dsh-connect-trae 3.4.0 → 3.4.2

package/CHANGELOG.md

@@ -1,5 +1,153 @@
 # Changelog
 
+## 3.4.2 (2026-10-13)
+
+> **插件现在与它自己解析到的那份 `@earendil-works/pi-ai` 代数对齐了**——这是 [issue #27](https://github.com/dingminhua/dsh-connect-trae/issues/27)
+> 的修复。起因是报告人用任意模型都拿到 `PI_AI_ERROR / Cannot read properties of undefined (reading 'length')`，
+> 且 usage 恒为 0：崩溃发生在**请求发出之前**的本地 token 估算里，所以既与模型无关，也看不到任何 HTTP 痕迹。
+> 取证见 `docs/ISSUE27_DIAGNOSIS.md`。
+
+### 修复
+
+- **插件现在会在两种上下文形状之间双向适配，而不是把宿主的形状原样交给自己的 api**（issue #27）：
+  - **原行为**：`createTraeAdapter` 把 `openAICompletionsApi()` 直接交给 `createProvider`，没有任何适配层。
+    插件声明 pi-ai 为 peer（`>=0.85.1`），所以它解析到哪一份**由安装环境决定**，未必是宿主那一份。
+  - **为什么这是必崩**：pi-ai **0.86 起**在每个公开入口调一次 `normalizeContext()`，于是 provider 收到的是
+    *归一化 transcript*：`{ messages: [ { role:'system', content:<字符串>, toolsAdded }, … ] }`——系统提示与工具声明
+    **只**挂在这条 system 消息上，顶层 `systemPrompt` / `tools` 已被删除。而 ≤0.85 的 `estimateMessageTokens`
+    **没有 `role === 'system'` 分支**：它 `for (const block of message.content)` 迭代一个**字符串**，逐字符拿到
+    `block`，再读 `block.name.length` → `TypeError`。因为这一步位于 `buildBaseOptions` 内、早于任何 HTTP 构造，
+    所以现象就是「105ms 内本地崩溃 + usage 恒 0 + 换模型无效」。
+  - **两个方向都要修**，因为 **DSH 自己也横跨两代**（`dsh-llm-pi-ai` ≤0.2.0-rc.1 声明 `^0.85.1`，0.2.0-rc.2 起声明
+    `^0.87.1`，0.2.1-alpha.2 已到 `^1.0.2`），而本插件声明支持 `>=0.1.7-rc.1 <0.3.0-0`：
+    - **新宿主 + 旧库**（issue #27 本尊）：必崩。
+    - **旧宿主 + 新库**：不崩，但现代 api 只从 system 消息读提示与工具，顶层字段被**静默忽略** → 系统提示与
+      **全部工具声明**丢失（模型永远不会产生 toolCall）。只修前者会把一个响亮的故障换成一个安静的故障。
+  - **改后**：新增 `withContextAdaptation(api, generation)`，按**本插件自己解析到的那一代**决定折返方向；
+    两个适配函数都以**形状**做幂等短路（普通路径返回同一个对象，零分配）。
+    - `adaptLegacyPiAiContext`（transcript → 旧形状）：把 system 文本提升为 `systemPrompt`，并把
+      `toolsRemoved`/`toolsAdded` **按序回放**成顶层 `tools`——工具那一步不能省，`normalizeContext` 之后它是
+      工具声明的**唯一**载体。
+    - `adaptModernPiAiContext`（旧形状 → transcript）：把 `systemPrompt`/`tools` 提到一条首部 system 消息上，
+      并移除顶层字段，避免后续的形状判据误判。
+  - **提示文本的三条载体都要搬，`sections` 不能漏**：新代 `SystemMessage` 的提示文本有 `content` 与
+    `sections` 两条载体（`Record<string, string | null>`），库自己的 `getSystemMessageText` 是
+    「`content` + 全部非 null section」按空行连接。只读 `content` 会让以 section 形态到达的提示整体折成
+    `undefined`——与该适配器要防的「静默丢失」完全同类。现已逐字对齐库的语义（`content` 在前、
+    按声明顺序接 section、跳过 `null`）。
+  - **折上的语义与 `normalizeContext` 逐字对齐，包括「混合形状」**：当上下文**同时**带顶层字段和
+    system 消息时（部分归一化的宿主），pi-ai 自己的做法是**前插**（于是有两条 system 消息，provider 再按
+    空行折叠），本插件因此同样前插。实测该输出经真实 0.87.1 的 `resolveTranscript` 折叠后，与
+    `normalizeContext` 的结果**逐字相同**。早先版本在混合形状下直接原样返回，会静默丢掉顶层提示与其
+    工具——这条是评审的变异测试暴露的（见「测试」）。
+- **代际判据落在 0.86，不是 0.87**（issue #27）：
+  - 报告与兄弟插件的既有实现都按 `>= 0.87 → modern` 划分。实测**真实边界是 0.86.0**——
+    `dist/utils/transcript.js`、`normalizeContext`、估算器的 system 分支、以及「不再读 `systemPrompt`/`tools`」
+    四件事**同时**出现在 0.86.0。
+  - **为什么这个偏差有害**：若插件解析到 **0.86.x**，`>= 0.87` 的判据会把它当旧代而执行折返，而 0.86+ 的 api
+    根本不读顶层字段 → 系统提示与全部工具被静默丢弃。即「照抄现成实现」反而会引入一个新的静默故障。
+- **新增 `src/pi-ai-runtime.ts`：世代探测不依赖版本号字符串**（issue #27）：
+  - 主判据是解析到的那份包 manifest 的版本，用**数值**比较（`major > 0` 或 `minor >= 86` 即现代），
+    因此 `0.9.0` 不会被误判为高于 `0.86.0`，已发布的 `1.x` 也无需改动即可正确归类。
+  - 版本读不到时退化为**包布局**判据（`dist/utils/transcript.js` 是否存在）。
+  - **刻意不使用 `import.meta.resolve()` 做能力探测**：bundler 风格的解析器（vite，以及在它之上的 vitest）
+    会把 exports map 里的 `"./utils/*"` 通配符展开成路径**并直接返回，不检查文件是否存在**，于是对 0.85.1
+    也回答「有」——实测该假阳性会把 0.85.1 判成 modern，从而**在声称按能力判断的同时放过 issue #27**。
+    读包目录则不会被这样骗过。
+  - 解析不到 pi-ai（宿主外探测的市场安装）时取 `modern` 透传：每个做归一化的宿主都同时提供现代代，
+    且透传不可能破坏一个本来就正确的上下文。
+
+### 诊断
+
+- **启动时打印解析到的 pi-ai 版本与代数**（issue #27）：混代安装是「安静坏掉」的那一类，日志里一行
+  `dsh-connect-trae: pi-ai 0.85.1 (legacy generation)` 让它在下次出现时立刻可见，而不是只表现为一次崩溃。
+
+### 测试
+
+- **全仓 549 → 594（+45）**：
+  - `tests/pi-ai-context.spec.ts`（38 例）：代际判定（含 0.86/0.87 边界、数值排序、`1.x`、不可读版本）、
+    `decidePiAiGeneration` 的三条分支（含本机**永不可达**的「什么都没探测到」——市场安装的默认答案，
+    必须显式钉住）、折返（提示提升、**工具提升**、`toolsRemoved`/`toolsAdded` 顺序回放、既有顶层 `tools`
+    权威、空文本 system 消息只丢文本不丢工具、文本块、**`sections` 三条载体**、混合形状、畸形输入）、
+    折上（提升、移除顶层字段、幂等、空提示、**混合形状前插**）、
+    `withContextAdaptation`（两个入口都适配、同形状透传为**同一对象**、保留 `fetchDeferred` 等其余字段），
+    以及**对真实解析到的那份 pi-ai 的集成对拍**：`estimateContextTokens` 不抛错、`convertMessages` 后
+    `messages[0].role === 'system'` 且 `tools` 仍在。
+  - `tests/pi-ai-adapter-wiring.spec.ts`（7 例）：**接线层**用例。上面那批函数级用例在把适配层从工厂里删掉后
+    **依然全绿**（已用变异验证），正是「函数没问题、只是没人调用」这一原始缺陷的形状；本文件 mock 掉
+    `openai-completions.lazy`，经 `adapter.current() → piProvider → streamSimple` 走真实装配路径断言交付给
+    api 的形状。
+  - **变异验证 8 次，8 次全部被抓**（①–⑤ 为自查，⑥–⑧ 由独立评审提出）：
+    ① 工厂里移除适配层 → 5 例失败；② 折返只搬 prompt 不搬 tools → 6 例失败；③ 边界写成 `>= 87` →
+    1 例失败；④ 折上时不移除顶层字段 → 2 例失败；⑤ 折返不做幂等短路 → 5 例失败；
+    **⑥ 折返忽略 `sections` → 2 例失败**；**⑦ 折上跳过多 system 消息的混合形状 → 1 例失败**；
+    **⑧ 不可探测时默认 `legacy` → 1 例失败**。恢复后 57 文件 594 例全绿。
+  - 确认新增用例真的在跑：改动前基线 **549**、改动后 **594**，净增 45，与新增用例数一致。
+
+### 独立评审
+
+发布前由独立评审对 diff 做了对抗性复核（真实发布包 + 真实 api 模块），确认：双向四组合均不丢提示、
+不丢工具、不重复 system 消息；**0.86 边界**在 0.85.1/0.86.0/0.86.1/0.87.1/1.0.2 五个真实 tarball 上
+逐项复核成立；**`import.meta.resolve` 的假阳性被独立复现**（该模块在 0.85.1 磁盘上不存在，vite 仍返回
+其 URL）；接线层用例确实覆盖工厂路径。
+
+评审同时提出 **3 条有效缺陷**，均已修复并补上用例（即上表 ⑥⑦⑧）：`sections` 载体被漏读、
+混合形状下折上会静默丢弃顶层提示与工具、以及不可探测分支的默认值无任何用例约束。
+
+### 文档
+
+- `docs/ISSUE27_DIAGNOSIS.md`：对外部报告的逐条核验——链路 6 跳的取证、双向错配四组合矩阵的实测结果、
+  DSH 各版本与 pi-ai 代数对照，并明确指出该报告的 **3 处硬错误**（代际边界实为 0.86 而非 0.87；
+  CASE B 实测为 `{"tokens":25}` 而非 `15`；`undefined maxTokens` 实为 `NaN` 而非「夹回正整数」）
+  与 **2 处需修正的修复建议**（「收紧 peer 即可在安装期被拒」不成立——DSH 内核预检
+  `evaluatePluginCompatibility` 只覆盖 `@deepseek-ai/dsh*`，pi-ai 不在其中，报告引用的 `install-compat`
+  告警来自 dshmarket 社区插件且属只告警不阻止的 `soft-incompatible`；以及「升级 DSH」解决不了问题，
+  报告人本就在最新的 0.2.0-rc.2 上，而升级只会把他更牢地留在「新宿主」一侧）。
+
+## 3.4.1 (2026-10-12)
+
+> **`4011` 的含义改正了：它是 Trae 对 SOLO 通道的限流，不是「该 function 不提供此模型」。**
+> 起因是 [issue #33](https://github.com/dingminhua/dsh-connect-trae/issues/33)：报告人用 `GLM-5.3` 拿到
+> `Trae code 4011`，报文原文写着 `your requests have exceeded the rate limit`，而他额度充足、
+> Trae 客户端的 SOLO 里同一模型正常。**两边都没错**——Trae 把「额度」和「限流」分成两个码，
+> 插件此前把限流读成了「function 归属错误」，于是用一个与上游原文矛盾的结论来解释，用户只能来问。
+> 取证过程见 `docs/ISSUE33_DIAGNOSIS.md`。
+
+### 修复
+
+- **`4011` 的文案不再断言一个与上游原文矛盾的原因**（issue #33）：
+  - **原行为**：`TRAE_ERROR_HINTS[4011]` 写死为「Trae refused this model under the SOLO function the request used」，并把 Trae 自己的原文降级成 `· upstream:` 后缀。用户看到的主句是「模型/function 错了」，于是按那个方向去查。
+  - **为什么那个断言站不住**：本机 CN 实时凭据上跑 **22 个 function × 6 个模型**的最小请求矩阵，
+    「模型不在该 function 名单里」**无一例外回 `4001`**（`the param is invalid`）——22 个 function 全部如此，**没有一次回 4011**；而报告人用的 `glm-5.3` 归属的正是 `solo_work_remote`（插件本来就发这个 function），同一份请求体**正常出字**。也就是说「function 选错」这个条件已经被 `4001` 占用了，4011 不可能是它。
+  - **改后**：`4011` 如实描述为「Trae 限流了这条 SOLO 通道（是限流，不是余额）」，Trae 原文照旧附在后面。
+- **`4011` 的 HTTP 状态改为 `429`（`soft_rate`），让状态码、文案与内核判定三者一致**：
+  - **原行为**：4011 被归类为 `400 / client`（按本插件 `fallback-upstream.ts` 的语义，`client` 属于「可换通道重放」的一类，绝不是「等一下再来」的一类）。但内核 `@deepseek-ai/dsh-llm-pi-ai` 是**按消息文本**分类的（`/\b429\b|rate.?limit/i` → `RATE_LIMIT`），而 `RATE_LIMIT` 在 `DEFAULT_RETRYABLE_CODES` 里、`maxRetries = 5`。
+  - **后果（issue #33 截图逐项吻合）**：失败的 4011 被内核当限流重试——`已重试模型请求 (5/5)`、重试延迟 7328 毫秒、右侧 `RATE_LIMIT` 徽标；而同一行正文却说「该 function 不提供此模型」。**被限流的通道 8 秒内又挨了 5 发请求。**
+  - **改后**：4011 → `429 / soft_rate`，三处判定不再打架；`soft_rate` 也正是 `fallback-upstream` 拒绝换通道重放的类别（限流不是通道兼容性问题，是对的）。
+- **一键测试不再把「被限流」判成「上游不提供」**（issue #33）：
+  - `UNSUPPORTED_CODES` 此前是 `{4001, 4011}`，于是 4011 会得到 `unsupported`——卡片文案「上游不提供」，是一个**永久性的负面结论**。这与该模块自己写在文件头的原则直接冲突（「the verdict must never turn an inconclusive answer into "unavailable"」）。报告人用一键测试时会被告知一个能用的模型已经死了。
+  - **改后**：4011 归入 `rate_limited`（卡片「被限流」），`unsupported` 只由 `4001` 产生。
+  - **顺带把「一个码只能有一个 verdict」变成结构性约束**：原来每个 verdict 一个 `Set`，一个码同时出现在两个集合里时，结果取决于分支书写顺序——实测把 4011 加回「unsupported」集合**所有测试都过**。现在改成单一 `CODE_VERDICTS` 映射表 + 加载期唯一性断言，并补了交叉断言用例钉住它。
+- **登记两个此前不认识的错误码**：
+  - **`4008` = 额度/配额耗尽**（原文 `Your requests have exceeded the quota.`）。它与 `4011` **是两个不同的码**：Trae 把「额度用完」和「被限流」分开报，所以 issue #33 里「我额度还有很多」与「我被 4011 拦住」可以同时成立。只登记文案与分类，**不改它的既有语义**（仍 `400 / client`）。本机只在国际版账号上观察到（该账号当前对多数模型都回 4008），CN 未触发——属**未验证项**。
+  - **`4023` = 模型名不存在**（原文 `the model is unknown`）。
+  - 一键测试里 `4008` 归入 `unknown`：它是**账号级**状态，不能变成对某个**模型**的判决。
+
+### 测试
+
+- **全仓 541 → 549（+8）**：
+  - `tests/solo-bridge.spec.ts`：4011 文案改为「限流」并保留 Trae 原文、`4008` 与 `4011` 文案分开、`4023` 命名、未登记码回退；`bridgeTraeSoloStreamOrFail` 的 4011 用例改为断言 `429 / soft_rate`；`4008` 的既有用例改为断言新文案。
+  - `tests/model-probe.spec.ts`：4011 → `rate_limited`（含「消息里只有码、没有 429 状态」的路径与「流中拒绝」路径）、`4008` → `unknown`、`4001` → `unsupported`，以及一条**表级交叉断言**（每个已知码都只映射到一个 verdict）——它正是为上面那个「顺序依赖」缺陷加的。
+  - **变异验证 6 次，6 次全部被抓**：① 去掉 4011 的 429 映射 → 1 例失败；② 恢复旧 4011 文案 → 2 例失败；③ 把 4011 在映射表里改回 `unsupported` → 4 例失败（**这条在改造前是抓不到的**）；④ 去掉 4008 的 `unknown` 映射 → 2 例失败；⑤ 删除「表内唯一性」的交叉断言依赖的行为 → 2 例失败；⑥ 其余组合。恢复后 55 文件 549 例全绿。
+- 确认新增用例真的在跑：改动前基线 **541**、改动后 **549**，净增 8，与新增用例数一致。
+
+### 文档
+
+- `docs/ISSUE33_DIAGNOSIS.md`：完整取证——`4008`/`4011`/`4001`/`4023`/`1001`/`1005` 的码→语义对照、
+  22 function × 6 模型的调用矩阵、`glm-5.3` 的归属验证、本机 30 并发未触发限流的对照，以及内核
+  `dsh-llm-pi-ai` 按文本分类 + `DEFAULT_RETRYABLE_CODES` 的证据链（为什么截图里是 5/5 与 7328 毫秒）。
+  同时明确列出**未证实项**（4011 的粒度是「通道」还是「账号」、`4008` 的边界与恢复时间、CN 是否也用 4008）。
+
 ## 3.4.0 (2026-10-12)
 
 ### 新增

package/README.en.md

@@ -43,7 +43,8 @@ A [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) bund
 - **Account switching** — refreshes the token list and lets users select an account without storing tokens in DSH settings. **Your choice is remembered and stays in effect**: the plugin will never switch accounts on its own just because the bound one ran out of credit or another usable one was found (switching bills a different person). So when the bound account is exhausted the card **says so explicitly** and lists the other accounts on this machine that still have credit, with their balances, for you to switch to in one click — instead of showing an empty panel or quietly rebinding you. "Refresh accounts & tokens" now always reports what happened (how many accounts were found, who is still bound) instead of appearing to do nothing. The dropdown names the product (`Trae` / `TRAE SOLO` / international) so a credential left behind by an uninstalled app is recognisable.
 - **Read-only usage and model management** — Work/general credits on CN accounts, subscription/trial status on international ones; enable Trae models freely. Read-only queries consume nothing.
 - **Credit-near-expiry notices** — the remaining balance only says "how much is left", not "**which pack lapses first**". The notice escalates by urgency (7 days → 24 hours → already lapsed) and names the amount, the pack count and the soonest expiry, so a user watching only the total never silently loses the pack that expires first. Shown in both the usage card and the composer credits panel on the CN side (the international side is subscription-based and has no per-pack expiry).
-- **One-click test of the enabled models** — sends each **enabled** model one minimal message (a single `ping`, no tools) and reports whether it actually answers: **works** / **needs a higher plan** (Trae `1005`; your plan does not cover it) / **not served** (`4001`/`4011`; no SOLO function serves it) / **throttled** / **sign-in rejected** / **not determined**. The last one is a first-class outcome: a timeout, a dropped connection, a proxy or a 5xx is **never** reported as unusable — only an explicit upstream refusal is a negative verdict. This is the plugin's **only** operation that spends quota (check-in changes account state but spends nothing), it runs only when you click, and its results live in the current session rather than in your settings.
+- **One-click test of the enabled models** — sends each **enabled** model one minimal message (a single `ping`, no tools) and reports whether it actually answers: **works** / **needs a higher plan** (Trae `1005`; your plan does not cover it) / **not served** (`4001`; no SOLO function serves it) / **throttled** (`4011`; Trae rate-limited that route) / **sign-in rejected** / **not determined**. The last one is a first-class outcome: a timeout, a dropped connection, a proxy or a 5xx is **never** reported as unusable — only an explicit upstream refusal is a negative verdict. This is the plugin's **only** operation that spends quota (check-in changes account state but spends nothing), it runs only when you click, and its results live in the current session rather than in your settings.
+  > `4011` is a **rate limit**, not "this model is unavailable" (measured for issue #33): an exhausted balance reports a different code, `4008`, so "I still have plenty of credits" and "I got a 4011" are both true at once. A throttled model answers again after a short wait — do not delete it.
 - **One-click test of all models** — the same probe applied to **every visible model** of the current region, not just the enabled ones. Use it when you want to know whether the models you have switched off could still answer — after a plan change, or after Trae reshuffles its lineup.
 - **Daily check-in claiming (per account)** — on the CN card **every account row carries its own check-in button**, with the day's reward written on it (`Check in +150`). A row reads **Claimed** and disables itself once *that account* has been paid, and reads **Device used** and disables itself when *this machine* has already spent today's slot through some other account — the two are reported honestly, and the second is never dressed up as "claimed". This is the plugin's **only** operation that changes account state, and it runs only when you click; one click targets that one row's account and sends exactly one request. There is deliberately **no "claim for every account"**: Trae allows **one check-in per device per day** (switching accounts does not reset the slot), so a sweep could only manufacture a row of false failures. The international side has no check-in activity, so no button is shown there.
 - **Composer readout** — the composer tool row (between "Expert" and the model selector) shows a clickable readout, refreshing every 5 minutes. **Both regions show it, but they do not show the same quantity, and that is the data's doing**: the CN side is credit-based, so it reads "Trae CN · <general credits>"; the international side is subscription-based and its usage document carries no credit field at all, so it reads "Trae Global · <plan>" (e.g. `Pro` / `Free`). The whole readout is clickable and opens a panel showing a TABLE: one row per account in the region — general credits on CN, plan on international — where clicking a row SWITCHES accounts (through the same merged `accounts` write the card uses, so the other region's selection survives), with the manual refresh button in the panel. It appears **only while the session's selected model belongs to this plugin**, and renders nothing for any other provider — which is what keeps two connector plugins from competing for one shared row (the sidebar foot is a shared root row; the composer row is per-session and provider-scoped).
@@ -137,6 +138,25 @@ Restart the DSH process after install/update/uninstall.
 **Requires DSH 0.1.7-rc.1 and up** (since 2.3.0 the plugin no longer targets hosts older than 0.1.7; the peer dependency ranges are narrowed accordingly).
 **The peer upper bound is `<0.3.0-0`, so both the 0.1.7 and the 0.2 line are supported.**
 
+### Both pi-ai context generations are supported (since 3.4.2)
+
+DSH itself spans two generations of `@earendil-works/pi-ai`, and **which one this plugin resolves to is decided by your install**, not by the host — declaring it a peer is correct, but the two generations disagree on what a context looks like:
+
+| | legacy (≤0.85) | modern (0.86+) |
+| --- | --- | --- |
+| shape | `{ systemPrompt, tools, messages }` | `{ messages: [ {role:'system', content, toolsAdded}, … ] }` |
+| system prompt | top-level `systemPrompt` | **only** on that system message |
+| tool declarations | top-level `tools` | **only** on that system message's `toolsAdded` |
+
+A mismatch breaks **in both directions**, so since 3.4.2 the plugin adapts bidirectionally according to the generation it resolved (issue #27):
+
+- **Modern host + legacy library**: a guaranteed crash — the legacy token estimator has no `role === 'system'` branch, so it iterates a string and throws `Cannot read properties of undefined (reading 'length')`. This happens before the request is built, which is why it looks like "every model crashes, within milliseconds, with all-zero usage".
+- **Legacy host + modern library**: no crash, but the modern api reads only that system message and silently ignores the top-level fields — the system prompt and **every tool declaration** are lost, so the model can never emit a tool call. Quieter, and also fixed.
+
+The generation gate is the copy **this plugin resolved** (its manifest version; package layout when that is unreadable), **not the host version** — a nested older copy shadows a newer host copy and vice versa. Startup logs one line, `dsh-connect-trae: pi-ai <version> (<generation>)`; `legacy` means your install resolved to the ≤0.85 line.
+
+The boundary is **0.86**: `dist/utils/transcript.js`, `normalizeContext`, the estimator's system branch, and the switch away from the top-level fields all land in 0.86.0 together. Gating on `0.87` misclassifies 0.86.x as legacy and folds a context the modern api consumes natively, destroying the prompt and the tools.
+
 The 0.2.0 line breaks **no** contract this plugin consumes — a symbol-by-symbol check confirmed every API it imports is unchanged ([full 0.2.0-rc.1 impact check](https://github.com/dingminhua/dsh-connect-trae/blob/main/docs/DSH_0.2.0_RC1_IMPACT_CHECK.md)). But since 0.1.7 DSH enforces a **bundle-level peer gate**: a bundle whose peers are unsatisfied is skipped **whole**, with one line on stderr and nothing in the UI — the plugin simply disappears.
 
 ### Why the upper bound is not `<0.2.0`
@@ -231,7 +251,7 @@ pnpm run check   # typecheck + test + build
 Local dev via a `link:` install to the desktop profile (restart DSH Desktop after editing):
 
 ```sh
-dsh plugin --profile desktop add /Users/dmh2002/DshProject/dsh-connect-trae
+dsh plugin --profile desktop add /path/to/dsh-connect-trae
 ```
 
 ## Acknowledgements

package/README.md

@@ -44,7 +44,8 @@
 - **跟随 Trae 当前登录的账号** —— 你在 Trae 桌面端**退出并换登录**后，卡片会检测到「插件绑定的账号」与「Trae 现在登录的账号」不一致，并给出一行提示与**一键切换**（复用账号下拉的同一次写入，不引入第二条切换路径）。想让插件**自动跟随**，可打开设置卡片里的「跟随 Trae 当前登录的账号」开关：此后每次配置生效都会把 `accounts.<region>` 重绑到 App 当前登录的账号。**该开关默认关闭**——已有配置保持原来的严格绑定，自动换绑意味着换人计费，必须由你主动勾选；未勾选时上面那行提示就是你的手动通道。（issue #29）
 - **只读用量与模型管理** —— 国内版查看 Work 积分与通用积分，国际版查看订阅/试用状态；刷新/启用 Trae 模型；只读查询不消耗额度。
 - **积分临近到期会提醒** —— 剩余额度只回答「还有多少」，回答不了「**哪一笔先到期**」；提醒条按到期紧迫程度逐级加重（**7 天 → 24 小时 → 已过期**），写明金额、套餐数和最早到期时间，避免只盯总额时悄悄丢掉最先到期的额度。国内版在用量页与输入框积分面板两处都显示（国际版是订阅制，没有逐包到期数据）。
-- **一键测试启用模型** —— 给**已启用**的每个模型发一条最小消息（一句 `ping`、不带工具），逐个告诉你能不能真的应答：**可用** / **需要更高档位**（Trae `1005`，你的套餐不覆盖）/ **上游不提供**（`4001`/`4011`，SOLO 通道没有这个模型）/ **被限流** / **登录凭据被拒** / **本次未测出**。最后一项是一等公民：超时、断连、代理、5xx **一律不算「不可用」**——只有上游明确的拒绝才算负面结论。**这是插件里唯一消耗额度的操作**（签到改变的是账号状态，不消耗），只在你点击时运行，结果只留在当前会话里不写入设置。
+- **一键测试启用模型** —— 给**已启用**的每个模型发一条最小消息（一句 `ping`、不带工具），逐个告诉你能不能真的应答：**可用** / **需要更高档位**（Trae `1005`，你的套餐不覆盖）/ **上游不提供**（`4001`，SOLO 通道没有这个模型）/ **被限流**（`4011`，Trae 限了这条通道）/ **登录凭据被拒** / **本次未测出**。最后一项是一等公民：超时、断连、代理、5xx **一律不算「不可用」**——只有上游明确的拒绝才算负面结论。**这是插件里唯一消耗额度的操作**（签到改变的是账号状态，不消耗），只在你点击时运行，结果只留在当前会话里不写入设置。
+  > `4011` 是**限流**不是「模型不可用」（issue #33 实测）：它额度耗尽走的是另一个码 `4008`，所以「额度还有很多却报 4011」两句话可以同时成立。被限流的模型**等你一会儿再试**即可，不要删。
 - **一键测试所有模型** —— 同一套探测，作用于当前 region 的**全部可见模型**（不限于已启用的）。想知道「没启用的那些到底还能不能用」时用它——比如套餐降级后，或 Trae 调整了模型阵容之后。
 - **每日签到领取（逐账号）** —— 国内版**每个账号行各有一个签到按钮**，当日奖励直接写在按钮上（`签到 +150`）；该账号当天已领显示「已领取」并禁用，**本机今日名额已被别的账号用掉**时显示「本机已签」并禁用——如实区分「这个账号领了」和「这台设备领过了」，绝不把后者说成「已领取」。这是插件里**唯一会改变账号状态**的操作，由你主动点击触发；一次点击只针对该行账号、只发一次请求，**刻意没有「一键全签」**——Trae 的签到按「**每台设备每天一次**」计（换账号不会重置当天名额），批量只会酿成一排假失败。国际版没有签到活动，因此不显示该按钮。
 - **输入框读数** —— 在输入框工具栏（「专家」与模型选择器之间）显示一块可点击读数，5 分钟自动刷新。**两个区域都显示，但显示的东西不同，这是数据决定的**：国内版是积分制，显示「Trae CN · <通用积分>」；国际版是订阅制，它的用量文档里根本没有积分字段，所以显示「Trae 国际版 · <套餐>」（如 `Pro` / `Free`）。**整块可点击**，弹出浮层显示一张**表格**：本区域**每个账号一行**，国内版列**通用积分**、国际版列**套餐**，**点行即可切换账号**（写入与卡片相同的 `accounts` 字段、合并时不丢掉另一个区域的选择），并把手动刷新按钮放在浮层里。**只在当前会话选中的模型属于本插件时出现**——选其它供应商的模型时整块不渲染。这样两个连接器插件不会争同一个位置（侧边栏底部是共享的根级行，输入框工具栏是按会话、按供应商的）。
@@ -142,6 +143,33 @@ npm install dsh-connect-trae
 **要求 DSH 0.1.7-rc.1 及以上**（2.3.0 起不再支持 0.1.7 之前的宿主；peer 依赖范围已按此收窄）。
 **peer 上界为 `<0.3.0-0`：0.1.7 与 0.2 两条线均受支持。**
 
+### 同时支持 pi-ai 的两代上下文（3.4.2 起）
+
+DSH 自己横跨 `@earendil-works/pi-ai` 的两代，而**本插件解析到哪一代由你的安装环境决定**，
+未必是宿主那一代——插件声明它是 peer，这是对的，但两代对「上下文长什么样」的定义不同：
+
+| | 旧代（≤0.85） | 新代（0.86+） |
+| --- | --- | --- |
+| 形状 | `{ systemPrompt, tools, messages }` | `{ messages: [ {role:'system', content, toolsAdded}, … ] }` |
+| 系统提示 | 顶层 `systemPrompt` | **只**挂在那条 system 消息上 |
+| 工具声明 | 顶层 `tools` | **只**挂在那条 system 消息的 `toolsAdded` 上 |
+
+错配**两个方向都会坏**，所以 3.4.2 起插件会按自己解析到的那一代双向适配（issue #27）：
+
+- **新宿主 + 旧库**：必崩——旧代的 token 估算没有 `role === 'system'` 分支，会去迭代一个字符串并抛
+  `Cannot read properties of undefined (reading 'length')`。这一步在请求构造之前，所以表现为
+  「任意模型都崩、耗时极短、usage 恒为 0」。
+- **旧宿主 + 新库**：不崩，但现代 api 只读那条 system 消息，顶层字段被**静默忽略**——系统提示与
+  **全部工具声明**丢失（模型永远不会产生 toolCall）。这类故障更隐蔽，同样已修。
+
+代际判据是**本插件自己解析到的那份包**（读它的 manifest 版本；读不到时看包布局），
+**不是宿主版本**——因为嵌套的旧副本会盖过宿主的新副本，反之亦然。启动时日志里会有一行
+`dsh-connect-trae: pi-ai <版本> (<代数>)`，`legacy` 表示你这份安装解析到了 ≤0.85 的旧代。
+
+分界线是 **0.86**：`dist/utils/transcript.js`、`normalizeContext`、估算器的 system 分支、
+以及「不再读顶层字段」这四件事同时出现在 0.86.0。按 `0.87` 划分会把 0.86.x 误判成旧代而错误折返，
+反而丢掉提示与工具。
+
 0.2.0 线对本插件**没有契约破坏**——逐符号核对确认插件消费的 API 全部未变（[完整的 0.2.0-rc.1 影响面核对](https://github.com/dingminhua/dsh-connect-trae/blob/main/docs/DSH_0.2.0_RC1_IMPACT_CHECK.md)）。但 0.1.7 起 DSH 有一道**bundle 级 peer 门禁**：
 peer 范围不满足的 bundle 会被**整体跳过**，只往 stderr 写一行，界面上表现为「插件凭空消失」。
 
@@ -241,7 +269,7 @@ pnpm run check   # typecheck + test + build
 本地开发用 `link:` 安装到 desktop profile（改码后重启 DSH Desktop 生效）：
 
 ```sh
-dsh plugin --profile desktop add /Users/dmh2002/DshProject/dsh-connect-trae
+dsh plugin --profile desktop add /path/to/dsh-connect-trae
 ```
 
 ## 致谢

package/lib/index.d.ts

@@ -1,6 +1,7 @@
 import z from "@deepseek-ai/schemastery";
+import { Context, ProviderStreams } from "@earendil-works/pi-ai";
 import { PiAiAdapter } from "@deepseek-ai/dsh-llm-pi-ai";
-import { Context } from "@deepseek-ai/cordis";
+import { Context as Context$1 } from "@deepseek-ai/cordis";
 import { AttachmentStore } from "@deepseek-ai/dsh-attachment";
 //#region src/reasoning.d.ts
 declare const TRAE_REASONING_EFFORTS: readonly ["minimal", "low", "medium", "high", "xhigh"];
@@ -237,9 +238,10 @@ interface TraeWireModel {
  * their own Trae IDE offers. The row therefore ships, and its call fails
  * honestly: the bridge now translates the in-stream refusal into a readable
  * error (`4001` → "Trae does not serve this model under the SOLO function the
- * request used", `4011` → "Trae refused this model under the SOLO function the
- * request used"), so a user who picks an unusable model is told why instead of
- * seeing nothing. This reverses the 2026-08-30 note about `Doubao-Seed-Code`,
+ * request used", `4011` → "Trae throttled the SOLO channel for this account",
+ * the second one corrected by issue #33 — 4011 is a rate limit, see
+ * src/solo-bridge.ts), so a user who picks an unusable model is told why instead
+ * of seeing nothing. This reverses the 2026-08-30 note about `Doubao-Seed-Code`,
  * which later turned out to be callable under `chat_v3`.
  *
  * Credit multiplier precedence: the wire's `display_contact_config` rate wins
@@ -294,6 +296,113 @@ declare class TraeCatalog {
   set(models: readonly TraeModelInfo[]): void;
 }
 //#endregion
+//#region src/pi-ai-runtime.d.ts
+/**
+ * Which `@earendil-works/pi-ai` copy THIS plugin resolves at runtime, and which
+ * context shape that copy consumes (issue #27).
+ *
+ * WHY THIS EXISTS. The plugin declares pi-ai as a peer, so the module it
+ * imports is whatever the install provides — and the two generations consume
+ * DIFFERENT context shapes:
+ *
+ * - **modern** (0.86+): every public entry point calls `normalizeContext()`
+ *   once, so what reaches a provider is a normalized *transcript*:
+ *   `{ messages: [ { role: 'system', content, toolsAdded }, … ] }`. The system
+ *   prompt and the tool declarations live ONLY on that leading system message;
+ *   the top-level `systemPrompt` / `tools` fields are gone, and the api never
+ *   reads them back.
+ * - **legacy** (≤0.85): expects `{ systemPrompt, tools, messages }` and has no
+ *   branch for a `system` message inside `messages` at all. Its token estimator
+ *   crashes on one — `estimateMessageTokens` iterates the string `content`
+ *   character by character and reads `.name` off a character — and its wire
+ *   converter silently drops it.
+ *
+ * The mismatch is reachable in BOTH directions, because DSH itself spans both
+ * generations (`dsh-llm-pi-ai` ≤0.2.0-rc.1 declares `^0.85.1`; 0.2.0-rc.2 and
+ * later declare `^0.87.1`, 0.2.1-alpha.2 declares `^1.0.2`), while this plugin
+ * accepts the whole range (`>=0.1.7-rc.1 <0.3.0-0`). Whichever side is newer,
+ * the other one is wrong:
+ *
+ * | host | resolved api | outcome |
+ * |---|---|---|
+ * | legacy | legacy | fine |
+ * | legacy | modern | no crash, but prompt + tools silently LOST |
+ * | modern | legacy | CRASH: `Cannot read properties of undefined (reading 'length')` |
+ * | modern | modern | fine |
+ *
+ * THE BOUNDARY IS 0.86, NOT 0.87. Checked against the published tarballs:
+ * `dist/utils/transcript.js` — and with it `normalizeContext`, the
+ * `role === 'system'` estimator branch, and the switch away from reading
+ * `systemPrompt`/`tools` — first appears in **0.86.0**. A `>= 0.87` gate
+ * misclassifies 0.86.x as legacy and folds a context the modern api consumes
+ * natively, which deletes the only carrier of the prompt and the tools.
+ *
+ * HOW the generation is decided, in order:
+ *
+ * 1. **The manifest version** of the copy this plugin resolved. Numeric semver
+ *    comparison (`minor >= 86`), so `0.86.0` and the already-shipped `1.x` line
+ *    both land on modern, and `0.9.0` correctly sorts below `0.86.0`.
+ * 2. **The package's own layout**, when no version could be read: the transcript
+ *    module sits at `dist/utils/transcript.js` (the exports map's
+ *    `"./utils/*" → "./dist/utils/*.js"` convention is identical in every
+ *    published generation, 0.82 through 1.x).
+ *
+ * Both checks are deliberately resolver-independent. `import.meta.resolve()` is
+ * NOT used to answer this question: bundler-style resolvers (vite, and equally
+ * `vitest` under it) expand the `"./utils/*"` wildcard to a path and return it
+ * WITHOUT checking that the file exists, so a probe built on it answers "modern"
+ * for 0.85.1 — the exact false positive that would leave issue #27 unfixed while
+ * claiming to be capability-based. Reading the package directory cannot be
+ * fooled that way.
+ *
+ * The version is therefore the primary signal, and it also keeps the gate
+ * forward-compatible for free: a future 2.x needs no change here, whereas a
+ * file-name check alone would have to know about it.
+ *
+ * @module dsh-connect-trae/pi-ai-runtime
+ */
+/** The context generation a resolved pi-ai api module speaks. */
+type PiAiGeneration = 'legacy' | 'modern';
+/** What {@link piAiRuntimeInfo} reports about the resolved pi-ai copy. */
+interface PiAiRuntimeInfo {
+  /** `modern` (0.86+: consumes normalized transcripts) or `legacy` (≤0.85 shape). */
+  generation: PiAiGeneration;
+  /** Version of the resolved copy, when the manifest could be read. */
+  version: string | undefined;
+  /** Package directory of the resolved copy, when it could be located. */
+  resolvedFrom: string | undefined;
+  /**
+   * Whether the copy could be inspected at all. `false` means pi-ai does not
+   * resolve from this plugin — the normal state of a market install probed
+   * OUTSIDE the DSH host, where the host supplies the module at plugin runtime.
+   * Inside DSH the copy is always inspectable: a nested one shadows host
+   * injection, and without a nested one the host supplies its own.
+   */
+  inspected: boolean;
+}
+/** Resolve (once) which pi-ai copy this plugin runs against. */
+declare function piAiRuntimeInfo(): PiAiRuntimeInfo;
+/**
+ * The generation decision table, exported so every branch is pinned by tests
+ * rather than by a comment here — including the two this development tree can
+ * never reach (no local copy, and a copy with no readable version), which are
+ * exactly the states a market install founds its gate on.
+ *
+ * @param version - manifest version of the resolved copy, if readable.
+ * @param transcriptPresent - whether that copy actually ships
+ *   `dist/utils/transcript.js`; `undefined` when nothing was inspected.
+ */
+declare function decidePiAiGeneration(version: string | undefined, transcriptPresent: boolean | undefined): PiAiGeneration;
+/**
+ * The generation a version string belongs to, or `undefined` when the string
+ * cannot be read as a version at all.
+ *
+ * Only the minor of the `0.x` line matters for the boundary, and `major >= 1`
+ * is modern by definition (1.0.x is already in use by `dsh-llm-pi-ai@0.2.1-alpha.2`
+ * and consumes transcripts natively).
+ */
+declare function generationOf(version: string | undefined): PiAiGeneration | undefined;
+//#endregion
 //#region src/upstream.d.ts
 type TraeUpstreamErrorKind = 'authentication' | 'hard_credit' | 'soft_rate' | 'not_found' | 'server' | 'client' | 'unconfigured';
 type TraeChatResult = {
@@ -350,6 +459,67 @@ declare const TRAE_PROVIDER_DISPLAY_NAMES: Readonly<Record<TraeRegion, string>>;
 /** Region a provider route id belongs to. */
 declare function regionOfTraeProvider(provider: string): TraeRegion | undefined;
 declare const TRAE_STREAM_IDLE_TIMEOUT_MS = 300000;
+/**
+ * Fold a NORMALIZED transcript back into the `{ systemPrompt, tools, messages }`
+ * shape a LEGACY (≤0.85) api consumes — issue #27's crash and its two silent
+ * siblings.
+ *
+ * WHY (issue #27). 0.86+ normalizes at every public entry point, and DSH's host
+ * calls `Models.streamSimple()`, so on a modern host the context arriving here
+ * ALWAYS carries its prompt and its tool declarations on a leading system
+ * message — the top-level fields are gone. A legacy api has no branch for that
+ * message: `estimateMessageTokens` iterates the string `content` character by
+ * character and reads `.name` off a character, throwing
+ * `Cannot read properties of undefined (reading 'length')` before the request
+ * is even built. That is what surfaced as `PI_AI_ERROR` with all-zero usage.
+ *
+ * The fold must carry MORE than the prompt. `toolsAdded` is the ONLY remaining
+ * carrier of the tool declarations once `normalizeContext` has run, and a
+ * legacy api reads tools exclusively from `context.tools` — so lifting the text
+ * alone would trade a loud crash for a silent one: a model that can never emit
+ * a `toolCall` because the request declared no tools.
+ *
+ * Shape-guarded, not version-guarded: it asks "is there a system message inside
+ * `messages`?" rather than "which pi-ai is loaded?". A version test would be
+ * wrong the moment either side moves, and this predicate is an identity for the
+ * legacy shape, so the ordinary path stays byte-for-byte untouched. WHICH
+ * branch runs at all IS generation-gated — see {@link withContextAdaptation}.
+ *
+ * Returns the SAME object when there is nothing to fold, so a legacy host
+ * (which never normalizes) pays one `Array.some` and nothing else.
+ */
+declare function adaptLegacyPiAiContext(context: Context): Context;
+/**
+ * Lift the legacy `{ systemPrompt, tools, messages }` shape into the normalized
+ * transcript a MODERN (0.86+) api consumes — the reverse mismatch, and just as
+ * silent.
+ *
+ * WHY. DSH spans both generations (`dsh-llm-pi-ai` ≤0.2.0-rc.1 pins `^0.85.1`)
+ * while this plugin may resolve a newer copy than its host. A LEGACY host never
+ * normalizes, so it hands the api the legacy shape; a modern api reads the
+ * prompt from a leading system message and the tools from its `toolsAdded`, and
+ * never looks at the top-level fields — so both are dropped without a sound.
+ * Verified against the published tarballs: the request that reaches the wire
+ * carries no system turn and `tools: []`.
+ *
+ * Identity for anything already in transcript shape, and for a context with
+ * neither a prompt nor tools (pi-ai's own `createInitialSystemMessage` returns
+ * `undefined` there, keeping an empty transcript empty).
+ */
+declare function adaptModernPiAiContext(context: Context): Context;
+/**
+ * Wrap one pi-ai API module so BOTH stream entry points receive a context its
+ * own generation can consume.
+ *
+ * The gate is the copy THIS plugin resolved (see {@link piAiRuntimeInfo}) —
+ * what the host runs says nothing about it, because a nested copy on disk
+ * shadows host injection and vice versa. The wrapping is cheap and lazy: only
+ * `stream`/`streamSimple` are intercepted, the deferred-fetch entry points take
+ * no context and are passed through untouched, and each adapter function is an
+ * identity unless the context is actually the other generation's shape. So a
+ * healthy install does one `Array.some` per request.
+ */
+declare function withContextAdaptation(api: ProviderStreams, generation: PiAiGeneration): ProviderStreams;
 interface TraeAdapterOptions {
   shim: TraeShim;
   catalog: TraeCatalog;
@@ -358,6 +528,12 @@ interface TraeAdapterOptions {
   /** pi-ai provider name and profile display name; defaults to the CN name. */
   displayName?: string;
   resolveAttachments?: () => AttachmentStore | undefined;
+  /**
+   * Override the resolved pi-ai generation (see {@link withContextAdaptation});
+   * tests use it to exercise the combination this machine does not have
+   * installed.
+   */
+  piAiGeneration?: PiAiGeneration;
 }
 interface TraeAdapter {
   adapter: PiAiAdapter;
@@ -2115,7 +2291,7 @@ interface TraeUsageRouteOptions {
  */
 declare function traeWebUsage(deps: TraeUsageRouteOptions, region: TraeRegion): Promise<TraeWebUsage>;
 /** Mount the GET usage route on an optional webServer context. */
-declare function registerTraeUsageRoute(ctx: Context, deps: TraeUsageRouteOptions): void;
+declare function registerTraeUsageRoute(ctx: Context$1, deps: TraeUsageRouteOptions): void;
 //#endregion
 //#region src/model-probe.d.ts
 /** How one model answered. */
@@ -2332,6 +2508,6 @@ declare function regionEnabled(config: Config, region: TraeRegion): boolean;
  */
 declare function asVolatile<S>(schema: S): S;
 declare const Config: z<Config>;
-declare function apply(ctx: Context, config: Config): void;
+declare function apply(ctx: Context$1, config: Config): void;
 //#endregion
-export { Config, FALLBACK_TRAE_MODELS, FALLBACK_TRAE_MODELS_AI, REGION_GATEWAYS, type RawChatDelta, type RawChatMessage, type RawChatTool, SseDecoder, type SseEvent, TRAE_ACCOUNT_STATUS_PATH, TRAE_AI_PROVIDER, TRAE_CHECKIN_PATH, TRAE_CN_AGENT_TASK_PATH, TRAE_CN_TITLE_PATH, TRAE_MODELS_TEST_PATH, TRAE_MODEL_DETAIL_FUNCTIONS, TRAE_MODEL_DETAIL_PATH, TRAE_PAY_BASE, TRAE_PROBE_TIMEOUT_MS, TRAE_PROVIDER, TRAE_PROVIDERS, TRAE_PROVIDER_DISPLAY_NAMES, TRAE_RAW_CHAT_V1_PATH, TRAE_RAW_CHAT_V2_PATH, TRAE_REASONING_EFFORTS, TRAE_REGIONS, TRAE_REGION_PARAM, TRAE_SETTINGS_NS, TRAE_SOLO_CHAT_PATH, TRAE_SOLO_FUNCTION, TRAE_SOLO_MODELS_PATH, TRAE_SOLO_REMOTE_BASE, TRAE_STATE_DB_FILENAME, TRAE_STREAM_IDLE_TIMEOUT_MS, TRAE_USAGE_PATH, TRAE_VERSION_CODE_FALLBACK, type TraeActivityRule, type TraeAdapter, type TraeCachedModelConfig, TraeCatalog, type TraeChatResult, type TraeCheckinClaim, type TraeCheckinStatus, type TraeContextBudget, type TraeCredential, TraeCredentialStore, TraeDelegatingUpstreamClient, type TraeDiscoveredModel, type TraeDiscoveredReasoning, type TraeEdition, TraeFallbackUpstreamClient, type TraeFallbackUpstreamOptions, type TraeFusionRawChatEnvelope, TraeGatedUpstreamClient, type TraeGatedUpstreamOptions, type TraeIdentity, type TraeInputModality, type TraeModelDetailRequest, type TraeModelInfo, type TraeModelProbeVerdict, type TraeModelsTestResponse, type TraeObservedModelConfig, type TraeProbeResult, type TraeProbeVerdict, TraeRawCapabilityController, type TraeRawCapabilityControllerOptions, type TraeRawCapabilitySnapshot, TraeRawCapabilityState, type TraeRawChatBehaviorConfig, type TraeRawChatCapability, type TraeRawChatClientOptions, type TraeRawChatConfig, type TraeRawChatFailureReason, type TraeRawChatRuntimeConfig, TraeRawChatUpstreamClient, type TraeRawDiagnostic, type TraeRawDiagnosticState, type TraeRawGateway, type TraeRawGatewayOptions, type TraeRawResolverResult, type TraeReasoningCapability, type TraeReasoningEffort, type TraeRefreshDevice, type TraeRegion, type TraeRegionGateways, TraeRegionState, type TraeShim, TraeSoloBridge, type TraeSoloClientOptions, TraeSoloRemoteCatalogClient, type TraeSoloRemoteCatalogOptions, TraeSoloUpstreamClient, type TraeStorageCandidate, type TraeStreamEvent, type TraeUpstreamClient, TraeUsageClient, type TraeUsageOptions, type TraeUsagePack, type TraeUsageRouteOptions, type TraeUsageSnapshot, type TraeUsageSummary, type TraeUsageView, type TraeWebAccountState, type TraeWebActivity, type TraeWebAppLogin, type TraeWebCheckin, type TraeWebCheckinClaim, type TraeWebCredits, type TraeWebUsage, type TraeWireModel, UnconfiguredTraeUpstreamClient, apply, applyContextBudgets, applyImageSelection, applyReasoningEffort, asVolatile, bridgeTraeSoloStream, buildTraeAgentTaskBody, buildTraeCnHeaders, buildTraeFusionRawChatEnvelope, buildTraeModelDetailRequest, buildTraeRawChatDraft, buildTraeRawChatRuntimeConfig, classifyProbeError, classifyProbeResult, classifyTraeRawChatFailure, configuredAccountsOf, createTraeAdapter, createTraeRawGateway, createTraeShim, decodeRawChatChunk, decodeTraeEvent, decryptTraeStorageValue, deriveCatalog, describeIdShape, describeNameShape, discoveredCatalog, fallbackModelsFor, followAppLoginEnabled, hashTraeRawChatArg, identityHeaders, inject, legacyTraeOwnAuthPath, maskUserPath, mergeTraeModelSources, name, nextRegionEnabled, nextRegionSlots, normalizeTraeCredential, normalizeTraeVersionCode, parseObservedModelConfig, parseReasoningCapability, parseTraeAuthValue, parseTraeCachedModel, parseTraeModelExtraConfigLogLine, parseTraeRawChatBehaviorConfig, parseTraeRemoteModel, parseTraeStorageDocument, pickTraeStorageIdentity, prepareSoloBody, probeBody, probeModelsSequentially, probeOneModel, probeTraeRawChatCapability, rawCapabilityDiagnostic, rawCapabilityFingerprint, readTraeCachedModel, readTraeCliIdentity, readTraeIdentity, refreshTraeCredential, regionEnabled, regionEnabledOf, regionOfCredential, regionOfEdition, regionOfHost, regionOfTraeProvider, regionOfTraeStatusUrl, regionOfUserRegion, regionStateOf, registerTraeUsageRoute, resolveTraeIdentity, resolveTraeRawRuntime, sanitizeCatalog, settingsNamespaceOf, traeEndpoint, traeInputModalities, traeModelDisplayName, traeOwnAuthPath, traeRawChatExtraInfo, traeStateDatabaseCandidates, traeStorageCandidates, traeWebUsage, traeWindowsAppNames, unwrapVolatile, unwrapVolatileDeep, withTraeRegion };
+export { Config, FALLBACK_TRAE_MODELS, FALLBACK_TRAE_MODELS_AI, type PiAiGeneration, type PiAiRuntimeInfo, REGION_GATEWAYS, type RawChatDelta, type RawChatMessage, type RawChatTool, SseDecoder, type SseEvent, TRAE_ACCOUNT_STATUS_PATH, TRAE_AI_PROVIDER, TRAE_CHECKIN_PATH, TRAE_CN_AGENT_TASK_PATH, TRAE_CN_TITLE_PATH, TRAE_MODELS_TEST_PATH, TRAE_MODEL_DETAIL_FUNCTIONS, TRAE_MODEL_DETAIL_PATH, TRAE_PAY_BASE, TRAE_PROBE_TIMEOUT_MS, TRAE_PROVIDER, TRAE_PROVIDERS, TRAE_PROVIDER_DISPLAY_NAMES, TRAE_RAW_CHAT_V1_PATH, TRAE_RAW_CHAT_V2_PATH, TRAE_REASONING_EFFORTS, TRAE_REGIONS, TRAE_REGION_PARAM, TRAE_SETTINGS_NS, TRAE_SOLO_CHAT_PATH, TRAE_SOLO_FUNCTION, TRAE_SOLO_MODELS_PATH, TRAE_SOLO_REMOTE_BASE, TRAE_STATE_DB_FILENAME, TRAE_STREAM_IDLE_TIMEOUT_MS, TRAE_USAGE_PATH, TRAE_VERSION_CODE_FALLBACK, type TraeActivityRule, type TraeAdapter, type TraeCachedModelConfig, TraeCatalog, type TraeChatResult, type TraeCheckinClaim, type TraeCheckinStatus, type TraeContextBudget, type TraeCredential, TraeCredentialStore, TraeDelegatingUpstreamClient, type TraeDiscoveredModel, type TraeDiscoveredReasoning, type TraeEdition, TraeFallbackUpstreamClient, type TraeFallbackUpstreamOptions, type TraeFusionRawChatEnvelope, TraeGatedUpstreamClient, type TraeGatedUpstreamOptions, type TraeIdentity, type TraeInputModality, type TraeModelDetailRequest, type TraeModelInfo, type TraeModelProbeVerdict, type TraeModelsTestResponse, type TraeObservedModelConfig, type TraeProbeResult, type TraeProbeVerdict, TraeRawCapabilityController, type TraeRawCapabilityControllerOptions, type TraeRawCapabilitySnapshot, TraeRawCapabilityState, type TraeRawChatBehaviorConfig, type TraeRawChatCapability, type TraeRawChatClientOptions, type TraeRawChatConfig, type TraeRawChatFailureReason, type TraeRawChatRuntimeConfig, TraeRawChatUpstreamClient, type TraeRawDiagnostic, type TraeRawDiagnosticState, type TraeRawGateway, type TraeRawGatewayOptions, type TraeRawResolverResult, type TraeReasoningCapability, type TraeReasoningEffort, type TraeRefreshDevice, type TraeRegion, type TraeRegionGateways, TraeRegionState, type TraeShim, TraeSoloBridge, type TraeSoloClientOptions, TraeSoloRemoteCatalogClient, type TraeSoloRemoteCatalogOptions, TraeSoloUpstreamClient, type TraeStorageCandidate, type TraeStreamEvent, type TraeUpstreamClient, TraeUsageClient, type TraeUsageOptions, type TraeUsagePack, type TraeUsageRouteOptions, type TraeUsageSnapshot, type TraeUsageSummary, type TraeUsageView, type TraeWebAccountState, type TraeWebActivity, type TraeWebAppLogin, type TraeWebCheckin, type TraeWebCheckinClaim, type TraeWebCredits, type TraeWebUsage, type TraeWireModel, UnconfiguredTraeUpstreamClient, adaptLegacyPiAiContext, adaptModernPiAiContext, apply, applyContextBudgets, applyImageSelection, applyReasoningEffort, asVolatile, bridgeTraeSoloStream, buildTraeAgentTaskBody, buildTraeCnHeaders, buildTraeFusionRawChatEnvelope, buildTraeModelDetailRequest, buildTraeRawChatDraft, buildTraeRawChatRuntimeConfig, classifyProbeError, classifyProbeResult, classifyTraeRawChatFailure, configuredAccountsOf, createTraeAdapter, createTraeRawGateway, createTraeShim, decidePiAiGeneration, decodeRawChatChunk, decodeTraeEvent, decryptTraeStorageValue, deriveCatalog, describeIdShape, describeNameShape, discoveredCatalog, fallbackModelsFor, followAppLoginEnabled, generationOf, hashTraeRawChatArg, identityHeaders, inject, legacyTraeOwnAuthPath, maskUserPath, mergeTraeModelSources, name, nextRegionEnabled, nextRegionSlots, normalizeTraeCredential, normalizeTraeVersionCode, parseObservedModelConfig, parseReasoningCapability, parseTraeAuthValue, parseTraeCachedModel, parseTraeModelExtraConfigLogLine, parseTraeRawChatBehaviorConfig, parseTraeRemoteModel, parseTraeStorageDocument, piAiRuntimeInfo, pickTraeStorageIdentity, prepareSoloBody, probeBody, probeModelsSequentially, probeOneModel, probeTraeRawChatCapability, rawCapabilityDiagnostic, rawCapabilityFingerprint, readTraeCachedModel, readTraeCliIdentity, readTraeIdentity, refreshTraeCredential, regionEnabled, regionEnabledOf, regionOfCredential, regionOfEdition, regionOfHost, regionOfTraeProvider, regionOfTraeStatusUrl, regionOfUserRegion, regionStateOf, registerTraeUsageRoute, resolveTraeIdentity, resolveTraeRawRuntime, sanitizeCatalog, settingsNamespaceOf, traeEndpoint, traeInputModalities, traeModelDisplayName, traeOwnAuthPath, traeRawChatExtraInfo, traeStateDatabaseCandidates, traeStorageCandidates, traeWebUsage, traeWindowsAppNames, unwrapVolatile, unwrapVolatileDeep, withContextAdaptation, withTraeRegion };

package/lib/index.js

@@ -3,9 +3,11 @@ import { createProvider } from "@earendil-works/pi-ai";
 import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
 import { resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
 import { PiAiAdapter } from "@deepseek-ai/dsh-llm-pi-ai";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { readFile, rm, stat } from "node:fs/promises";
 import { createDecipheriv, createHash, randomBytes, randomUUID, sign, timingSafeEqual } from "node:crypto";
-import { dirname, join } from "node:path";
 import { withFileLock, writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
 import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
 import { cpus, homedir, hostname, release, userInfo } from "node:os";
@@ -13,7 +15,6 @@ import { createServer } from "node:http";
 import { Readable } from "node:stream";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { existsSync } from "node:fs";
 //#region src/catalog.ts
 /**
 * Bootstrap catalog: identity only where current Trae metadata has not been
@@ -197,9 +198,10 @@ function displayKey(name) {
 * their own Trae IDE offers. The row therefore ships, and its call fails
 * honestly: the bridge now translates the in-stream refusal into a readable
 * error (`4001` → "Trae does not serve this model under the SOLO function the
-* request used", `4011` → "Trae refused this model under the SOLO function the
-* request used"), so a user who picks an unusable model is told why instead of
-* seeing nothing. This reverses the 2026-08-30 note about `Doubao-Seed-Code`,
+* request used", `4011` → "Trae throttled the SOLO channel for this account",
+* the second one corrected by issue #33 — 4011 is a rate limit, see
+* src/solo-bridge.ts), so a user who picks an unusable model is told why instead
+* of seeing nothing. This reverses the 2026-08-30 note about `Doubao-Seed-Code`,
 * which later turned out to be callable under `chat_v3`.
 *
 * Credit multiplier precedence: the wire's `display_contact_config` rate wins
@@ -321,6 +323,179 @@ var TraeCatalog = class {
 	}
 };
 //#endregion
+//#region src/pi-ai-runtime.ts
+/**
+* Which `@earendil-works/pi-ai` copy THIS plugin resolves at runtime, and which
+* context shape that copy consumes (issue #27).
+*
+* WHY THIS EXISTS. The plugin declares pi-ai as a peer, so the module it
+* imports is whatever the install provides — and the two generations consume
+* DIFFERENT context shapes:
+*
+* - **modern** (0.86+): every public entry point calls `normalizeContext()`
+*   once, so what reaches a provider is a normalized *transcript*:
+*   `{ messages: [ { role: 'system', content, toolsAdded }, … ] }`. The system
+*   prompt and the tool declarations live ONLY on that leading system message;
+*   the top-level `systemPrompt` / `tools` fields are gone, and the api never
+*   reads them back.
+* - **legacy** (≤0.85): expects `{ systemPrompt, tools, messages }` and has no
+*   branch for a `system` message inside `messages` at all. Its token estimator
+*   crashes on one — `estimateMessageTokens` iterates the string `content`
+*   character by character and reads `.name` off a character — and its wire
+*   converter silently drops it.
+*
+* The mismatch is reachable in BOTH directions, because DSH itself spans both
+* generations (`dsh-llm-pi-ai` ≤0.2.0-rc.1 declares `^0.85.1`; 0.2.0-rc.2 and
+* later declare `^0.87.1`, 0.2.1-alpha.2 declares `^1.0.2`), while this plugin
+* accepts the whole range (`>=0.1.7-rc.1 <0.3.0-0`). Whichever side is newer,
+* the other one is wrong:
+*
+* | host | resolved api | outcome |
+* |---|---|---|
+* | legacy | legacy | fine |
+* | legacy | modern | no crash, but prompt + tools silently LOST |
+* | modern | legacy | CRASH: `Cannot read properties of undefined (reading 'length')` |
+* | modern | modern | fine |
+*
+* THE BOUNDARY IS 0.86, NOT 0.87. Checked against the published tarballs:
+* `dist/utils/transcript.js` — and with it `normalizeContext`, the
+* `role === 'system'` estimator branch, and the switch away from reading
+* `systemPrompt`/`tools` — first appears in **0.86.0**. A `>= 0.87` gate
+* misclassifies 0.86.x as legacy and folds a context the modern api consumes
+* natively, which deletes the only carrier of the prompt and the tools.
+*
+* HOW the generation is decided, in order:
+*
+* 1. **The manifest version** of the copy this plugin resolved. Numeric semver
+*    comparison (`minor >= 86`), so `0.86.0` and the already-shipped `1.x` line
+*    both land on modern, and `0.9.0` correctly sorts below `0.86.0`.
+* 2. **The package's own layout**, when no version could be read: the transcript
+*    module sits at `dist/utils/transcript.js` (the exports map's
+*    `"./utils/*" → "./dist/utils/*.js"` convention is identical in every
+*    published generation, 0.82 through 1.x).
+*
+* Both checks are deliberately resolver-independent. `import.meta.resolve()` is
+* NOT used to answer this question: bundler-style resolvers (vite, and equally
+* `vitest` under it) expand the `"./utils/*"` wildcard to a path and return it
+* WITHOUT checking that the file exists, so a probe built on it answers "modern"
+* for 0.85.1 — the exact false positive that would leave issue #27 unfixed while
+* claiming to be capability-based. Reading the package directory cannot be
+* fooled that way.
+*
+* The version is therefore the primary signal, and it also keeps the gate
+* forward-compatible for free: a future 2.x needs no change here, whereas a
+* file-name check alone would have to know about it.
+*
+* @module dsh-connect-trae/pi-ai-runtime
+*/
+let cached;
+/** Resolve (once) which pi-ai copy this plugin runs against. */
+function piAiRuntimeInfo() {
+	cached ??= inspectResolvedPiAi();
+	return cached;
+}
+function inspectResolvedPiAi() {
+	const entry = resolveModuleFile();
+	const root = entry === void 0 ? void 0 : findPackageRoot(entry);
+	const version = root === void 0 ? void 0 : readVersion(root);
+	return {
+		generation: decidePiAiGeneration(version, root === void 0 ? void 0 : hasTranscriptModule(root)),
+		version,
+		resolvedFrom: root,
+		inspected: root !== void 0
+	};
+}
+/**
+* The generation decision table, exported so every branch is pinned by tests
+* rather than by a comment here — including the two this development tree can
+* never reach (no local copy, and a copy with no readable version), which are
+* exactly the states a market install founds its gate on.
+*
+* @param version - manifest version of the resolved copy, if readable.
+* @param transcriptPresent - whether that copy actually ships
+*   `dist/utils/transcript.js`; `undefined` when nothing was inspected.
+*/
+function decidePiAiGeneration(version, transcriptPresent) {
+	const byVersion = generationOf(version);
+	if (byVersion !== void 0) return byVersion;
+	if (transcriptPresent === true) return "modern";
+	if (transcriptPresent === false) return "legacy";
+	return "modern";
+}
+/**
+* The generation a version string belongs to, or `undefined` when the string
+* cannot be read as a version at all.
+*
+* Only the minor of the `0.x` line matters for the boundary, and `major >= 1`
+* is modern by definition (1.0.x is already in use by `dsh-llm-pi-ai@0.2.1-alpha.2`
+* and consumes transcripts natively).
+*/
+function generationOf(version) {
+	if (version === void 0) return void 0;
+	const match = /^(\d+)\.(\d+)\./u.exec(version);
+	if (match === null) return void 0;
+	const major = Number(match[1]);
+	const minor = Number(match[2]);
+	if (major > 0) return "modern";
+	return minor >= 86 ? "modern" : "legacy";
+}
+/**
+* Whether the resolved package actually contains the transcript module.
+*
+* `dist/utils/transcript.js` is the file every modern generation ships and no
+* legacy one has (checked: absent in 0.82.1 and 0.85.1; present in 0.86.0,
+* 0.86.1, 0.87.1 and 1.0.2). Landing on the file directly, rather than asking a
+* resolver to find it, is what keeps this honest under bundler-style resolution
+* — see the module docstring.
+*/
+function hasTranscriptModule(packageRoot) {
+	return existsSync(join(packageRoot, "dist", "utils", "transcript.js"));
+}
+/**
+* The file the main entry resolved to; undefined when resolution itself fails.
+*
+* `import.meta.resolve` (not `require.resolve`): pi-ai's exports map exposes
+* "." under the `import` condition only, so the CJS resolver refuses the bare
+* specifier outright — the ESM resolver is the one this plugin actually imports
+* with, so it is also the one whose answer is meaningful here. Only the package
+* LOCATION is taken from it; the generation question is answered from disk.
+*/
+function resolveModuleFile() {
+	try {
+		return fileURLToPath(import.meta.resolve("@earendil-works/pi-ai"));
+	} catch {
+		return;
+	}
+}
+/**
+* The package directory owning `moduleFile`: `dist/index.js` sits directly
+* inside the package, so walking up from the entry finds its manifest. The
+* manifest is claimed only when its `name` matches, so a same-named ancestor (a
+* pnpm virtual-store parent, for instance) cannot be misread.
+*/
+function findPackageRoot(moduleFile) {
+	let directory = dirname(moduleFile);
+	for (let depth = 0; depth < 4; depth++) {
+		if (readManifest(directory)?.name === "@earendil-works/pi-ai") return directory;
+		const parent = dirname(directory);
+		if (parent === directory) return void 0;
+		directory = parent;
+	}
+}
+/** Version from the manifest already located by {@link findPackageRoot}. */
+function readVersion(packageRoot) {
+	const version = readManifest(packageRoot)?.version;
+	return typeof version === "string" ? version : void 0;
+}
+function readManifest(directory) {
+	try {
+		const parsed = JSON.parse(readFileSync(join(directory, "package.json"), "utf8"));
+		return typeof parsed === "object" && parsed !== null ? parsed : void 0;
+	} catch {
+		return;
+	}
+}
+//#endregion
 //#region src/adapter.ts
 /** Provider route this bundle owns for the domestic (CN) gateway. */
 const TRAE_PROVIDER = "trae";
@@ -404,9 +579,172 @@ function toPiModel(info, baseUrl, providerId) {
 		compat: { supportsReasoningEffort: info.reasoningEfforts !== void 0 }
 	};
 }
+function isSystemMessage(message) {
+	return typeof message === "object" && message !== null && message.role === "system";
+}
+/**
+* The text of one system message: its `content` (a string, as
+* `normalizeContext` writes, or text blocks, which a provider may send back)
+* followed by its named `sections` — exactly the join pi-ai's own
+* `getSystemMessageText` performs.
+*
+* `sections` is not decoration: it is the modern transcript's second carrier of
+* prompt text ("named, ordered prompt sections rendered verbatim after
+* content"). Folding `content` alone would silently drop a prompt that arrives
+* section-shaped, which is the same asymmetric-loss failure this adapter exists
+* to prevent.
+*/
+function systemTextOf(message) {
+	const parts = [contentTextOf(message.content)];
+	const sections = message.sections;
+	if (typeof sections === "object" && sections !== null && !Array.isArray(sections)) {
+		for (const text of Object.values(sections)) if (typeof text === "string") parts.push(text);
+	}
+	return parts.filter((part) => part.length > 0).join("\n\n");
+}
+function contentTextOf(content) {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	const texts = [];
+	for (const block of content) {
+		if (typeof block !== "object" || block === null) continue;
+		const candidate = block;
+		if (candidate.type === "text" && typeof candidate.text === "string") texts.push(candidate.text);
+	}
+	return texts.join("\n\n");
+}
+/**
+* Replay one transcript system message's tool deltas into `state`, the same
+* merge pi-ai's own `getCurrentTools` performs: removals first, then additions,
+* keyed by name so a mid-conversation redeclaration replaces the original.
+*/
+function replayToolState(message, state) {
+	const removed = message.toolsRemoved;
+	if (Array.isArray(removed)) for (const tool of removed) {
+		const name = tool?.name;
+		if (typeof name === "string") state.delete(name);
+	}
+	const added = message.toolsAdded;
+	if (Array.isArray(added)) for (const tool of added) {
+		const name = tool?.name;
+		if (typeof name === "string") state.set(name, tool);
+	}
+}
+/**
+* Fold a NORMALIZED transcript back into the `{ systemPrompt, tools, messages }`
+* shape a LEGACY (≤0.85) api consumes — issue #27's crash and its two silent
+* siblings.
+*
+* WHY (issue #27). 0.86+ normalizes at every public entry point, and DSH's host
+* calls `Models.streamSimple()`, so on a modern host the context arriving here
+* ALWAYS carries its prompt and its tool declarations on a leading system
+* message — the top-level fields are gone. A legacy api has no branch for that
+* message: `estimateMessageTokens` iterates the string `content` character by
+* character and reads `.name` off a character, throwing
+* `Cannot read properties of undefined (reading 'length')` before the request
+* is even built. That is what surfaced as `PI_AI_ERROR` with all-zero usage.
+*
+* The fold must carry MORE than the prompt. `toolsAdded` is the ONLY remaining
+* carrier of the tool declarations once `normalizeContext` has run, and a
+* legacy api reads tools exclusively from `context.tools` — so lifting the text
+* alone would trade a loud crash for a silent one: a model that can never emit
+* a `toolCall` because the request declared no tools.
+*
+* Shape-guarded, not version-guarded: it asks "is there a system message inside
+* `messages`?" rather than "which pi-ai is loaded?". A version test would be
+* wrong the moment either side moves, and this predicate is an identity for the
+* legacy shape, so the ordinary path stays byte-for-byte untouched. WHICH
+* branch runs at all IS generation-gated — see {@link withContextAdaptation}.
+*
+* Returns the SAME object when there is nothing to fold, so a legacy host
+* (which never normalizes) pays one `Array.some` and nothing else.
+*/
+function adaptLegacyPiAiContext(context) {
+	if (context === null || typeof context !== "object") return context;
+	const messages = Array.isArray(context.messages) ? context.messages : void 0;
+	if (messages === void 0) return context;
+	if (!messages.some(isSystemMessage)) return context;
+	const systemTexts = [];
+	const rest = [];
+	const toolState = /* @__PURE__ */ new Map();
+	for (const message of messages) {
+		if (!isSystemMessage(message)) {
+			rest.push(message);
+			continue;
+		}
+		const text = systemTextOf(message);
+		if (text !== "") systemTexts.push(text);
+		replayToolState(message, toolState);
+	}
+	const texts = [...context.systemPrompt === void 0 || context.systemPrompt === "" ? [] : [context.systemPrompt], ...systemTexts];
+	const systemPrompt = texts.length > 0 ? texts.join("\n\n") : void 0;
+	const promoted = Array.isArray(context.tools) ? void 0 : [...toolState.values()];
+	return {
+		...context,
+		...systemPrompt === void 0 ? {} : { systemPrompt },
+		...promoted === void 0 || promoted.length === 0 ? {} : { tools: promoted },
+		messages: rest
+	};
+}
+/**
+* Lift the legacy `{ systemPrompt, tools, messages }` shape into the normalized
+* transcript a MODERN (0.86+) api consumes — the reverse mismatch, and just as
+* silent.
+*
+* WHY. DSH spans both generations (`dsh-llm-pi-ai` ≤0.2.0-rc.1 pins `^0.85.1`)
+* while this plugin may resolve a newer copy than its host. A LEGACY host never
+* normalizes, so it hands the api the legacy shape; a modern api reads the
+* prompt from a leading system message and the tools from its `toolsAdded`, and
+* never looks at the top-level fields — so both are dropped without a sound.
+* Verified against the published tarballs: the request that reaches the wire
+* carries no system turn and `tools: []`.
+*
+* Identity for anything already in transcript shape, and for a context with
+* neither a prompt nor tools (pi-ai's own `createInitialSystemMessage` returns
+* `undefined` there, keeping an empty transcript empty).
+*/
+function adaptModernPiAiContext(context) {
+	if (context === null || typeof context !== "object") return context;
+	const messages = Array.isArray(context.messages) ? context.messages : void 0;
+	if (messages === void 0) return context;
+	const prompt = context.systemPrompt;
+	const tools = Array.isArray(context.tools) && context.tools.length > 0 ? context.tools : void 0;
+	if (!(typeof prompt === "string" && prompt.length > 0) && tools === void 0) return context;
+	const head = {
+		role: "system",
+		content: prompt ?? "",
+		...tools === void 0 ? {} : { toolsAdded: tools }
+	};
+	const { systemPrompt: _lifted, tools: _liftedTools, ...rest } = context;
+	return {
+		...rest,
+		messages: [head, ...messages]
+	};
+}
+/**
+* Wrap one pi-ai API module so BOTH stream entry points receive a context its
+* own generation can consume.
+*
+* The gate is the copy THIS plugin resolved (see {@link piAiRuntimeInfo}) —
+* what the host runs says nothing about it, because a nested copy on disk
+* shadows host injection and vice versa. The wrapping is cheap and lazy: only
+* `stream`/`streamSimple` are intercepted, the deferred-fetch entry points take
+* no context and are passed through untouched, and each adapter function is an
+* identity unless the context is actually the other generation's shape. So a
+* healthy install does one `Array.some` per request.
+*/
+function withContextAdaptation(api, generation) {
+	const adapt = generation === "modern" ? adaptModernPiAiContext : adaptLegacyPiAiContext;
+	return {
+		...api,
+		stream: (model, context, options) => api.stream(model, adapt(context), options),
+		streamSimple: (model, context, options) => api.streamSimple(model, adapt(context), options)
+	};
+}
 function createTraeAdapter(options) {
 	const providerId = options.provider ?? "trae";
 	const providerName = options.displayName ?? "Trae";
+	const generation = options.piAiGeneration ?? piAiRuntimeInfo().generation;
 	const buildModels = () => options.catalog.current().map((info) => toPiModel(info, `${options.shim.baseUrl()}/v1`, providerId));
 	const provider = {
 		...createProvider({
@@ -423,7 +761,7 @@ function createTraeAdapter(options) {
 				}
 			} },
 			models: buildModels(),
-			api: openAICompletionsApi()
+			api: withContextAdaptation(openAICompletionsApi(), generation)
 		}),
 		getModels: () => buildModels()
 	};
@@ -2407,9 +2745,14 @@ const TRAE_SOLO_FUNCTION = "solo_work_lite";
 * live SG credential, issue #19): it is a Remote-agent roster function, not a
 * chat function. Every model sent with `function: "solo_agent"` — `gpt-5.4`,
 * `gpt-5.6-sol`, `gpt-6-astra`, `glm-5.2`, `kimi-k2.7-code` — answered
-* `event:error {"code":4011}` (message says "rate limit", it is really "not
-* served here"), while the same model with the same body answered normally
-* under `solo_work_remote` / `solo_work_lite` / `solo_agent_remote`.
+* `event:error {"code":4011}`, while the same model with the same body answered
+* normally under `solo_work_remote` / `solo_work_lite` / `solo_agent_remote`.
+* Issue #33 corrected the reading of that code: `4011` is Trae's rate limit on
+* the route that was asked (its own text says so, and issue #33's reporter hit
+* it on the CORRECT function), and the "this route does not serve that model"
+* condition is `4001` — measured on all 22 functions of a live CN credential.
+* The conclusion for this list is unchanged either way: a route that refuses
+* chat is not a chat route, so `solo_agent` stays out.
 *
 * Note `get_detail_param` DOES answer `solo_agent` with a 43-entry list, so
 * asking it looks helpful while making 8 of the 10 exposed ai-region models
@@ -2809,22 +3152,38 @@ function decodeTraeEvent(event) {
 //#endregion
 //#region src/solo-bridge.ts
 /**
-* What Trae's in-stream error codes mean. Measured 2026-10-01 on a live SG
-* credential (issue #19), by sending the same body to several functions:
+* What Trae's in-stream error codes mean. Measured 2026-10-01 on live
+* credentials (issue #19), and re-measured 2026-10-12 on a live CN credential
+* (issue #33) with a 22-function × 6-model chat matrix:
 *
 *  - `1005` — the model needs a paid plan. Trae answers HTTP 200 with
 *    `event:error {"code":1005,"message":"","extra":"{\"plan\":1}"}`, so the
 *    gate is only visible in `extra.plan`; `gpt-6-sol` returned it under both
 *    `solo_work_remote` and `solo_agent_remote` on a free account.
-*  - `4011` — the function the request named does not serve that model. Its
-*    message claims "exceeded the rate limit", which is misleading: the same
-*    model answers normally when sent under `solo_work_remote`.
+*  - `4011` — Trae throttled the SOLO route for this account. Trae's own text
+*    is `your requests have exceeded the rate limit. Please wait and try again
+*    later.`, and issue #33 is why that text is now taken at face value: the
+*    earlier reading of 4011 as "this function does not serve that model" is
+*    contradicted by measurement. On CN that condition is `4001`, and all 22
+*    functions answered `4001` — never `4011` — for a model absent from their
+*    roster, while `glm-5.3` streamed normally under its own function. Rate
+*    limiting is per account, route and moment, which is exactly the shape of
+*    that report: the same model through the same function was fine for days
+*    and then failed, with Trae's own text saying "rate limit".
 *  - `4001` — `config_name` is not one this function serves.
+*  - `4008` — the account's SOLO quota is exhausted. Deliberately a different
+*    code from `4011`: Trae words this one `your requests have exceeded the
+*    quota`, so "I still have plenty of credits" and "I am being throttled" are
+*    two different statements, and a user hits the second without touching the
+*    first (issue #33).
+*  - `4023` — the model name is unknown on the route that was asked.
 */
 const TRAE_ERROR_HINTS = {
 	1005: "Trae requires a paid plan for this model; the current account's plan does not cover it",
 	4001: "Trae does not serve this model under the SOLO function the request used (config_name rejected)",
-	4011: "Trae refused this model under the SOLO function the request used"
+	4008: "Trae reports the account's SOLO quota is exhausted for this request",
+	4011: "Trae throttled the SOLO channel for this account (a rate limit, not the credit balance)",
+	4023: "Trae does not recognise this model name on the SOLO route that was asked"
 };
 /** `extra` is a JSON *string* on the wire; unwrap it to read `plan`. */
 function traeErrorPlan(extra) {
@@ -2854,13 +3213,30 @@ function describeTraeFailure(failure) {
 * answer with a real error instead of a truncated 200 stream.
 *
 * `1005` is a subscription gate: 402 is what makes clients stop rather than
-* retry, and it is truthful. Everything else is a client-side rejection.
+* retry, and it is truthful.
+*
+* `4011` is a rate limit and is reported as one — `429` / `soft_rate` (issue
+* #33). It previously answered `400` / `client`, which contradicted both its own
+* message and the client's own behaviour: pi-ai classifies an error by its text
+* (`/\b429\b|rate.?limit/i` → `RATE_LIMIT`), and `RATE_LIMIT` is retryable, so
+* the kernel retried five times with backoff while this function called the same
+* failure a non-retryable client error. Reporting the real status makes all
+* three agree, and `soft_rate` is already what `fallback-upstream` refuses to
+* replay — correct, since a throttled route is not a route-compatibility
+* problem.
+*
+* Everything else stays a client-side rejection.
 */
 function classifyTraeFailure(failure) {
-	return failure.code === 1005 ? {
+	if (failure.code === 1005) return {
 		status: 402,
 		kind: "hard_credit"
-	} : {
+	};
+	if (failure.code === 4011) return {
+		status: 429,
+		kind: "soft_rate"
+	};
+	return {
 		status: 400,
 		kind: "client"
 	};
@@ -3934,9 +4310,41 @@ var TraeDelegatingUpstreamClient = class {
 * beyond this the answer is not worth waiting for and is reported as unknown.
 */
 const TRAE_PROBE_TIMEOUT_MS = 3e4;
-/** Upstream error codes the probe recognises, and what they mean. */
-const GATE_CODES = /* @__PURE__ */ new Set([1005]);
-const UNSUPPORTED_CODES = /* @__PURE__ */ new Set([4001, 4011]);
+/**
+* Every upstream code the probe recognises, mapped to the verdict it implies.
+*
+* ONE table, not a set per verdict: with separate sets the outcome depended on
+* the order the branches happened to be written in, so a code left in two sets
+* was silently decided by whichever line ran first (measured: re-adding `4011`
+* to the "unsupported" set passed every test). A single map makes a code mean
+* exactly one thing, and {@link assertCodesAreDistinct} pins that down at
+* module load.
+*
+*  - `1005` — the plan does not cover this model (`extra.plan` carries the
+*    tier). A paying account may pass, so it is a gate, not a dead model.
+*  - `4001` — this function's roster does not contain that `config_name`. The
+*    ONLY code that may produce `unsupported`, measured on all 22 functions of
+*    a live CN credential (issue #33).
+*  - `4011` — Trae throttled the route; its own text says the rate limit was
+*    exceeded. Issue #33 moved this here from `unsupported`: reporting a
+*    throttle as "the channel does not serve it" told users a working model was
+*    dead.
+*  - `4008` — the ACCOUNT's SOLO quota is exhausted. It says nothing about any
+*    one model, so it must not become a model verdict; it stays inconclusive
+*    and carries the upstream text, so the user retests once the quota is back.
+*/
+const CODE_VERDICTS = {
+	1005: "gated",
+	4001: "unsupported",
+	4008: "unknown",
+	4011: "rate_limited"
+};
+/** A code that maps to two verdicts would make the table order-dependent. */
+function assertCodesAreDistinct(table) {
+	const codes = Object.keys(table);
+	if (new Set(codes).size !== codes.length) throw new Error("dsh-connect-trae: a Trae probe code maps to more than one verdict");
+}
+assertCodesAreDistinct(CODE_VERDICTS);
 /** Pull `Trae code N` out of an already-translated failure message. */
 function codeOf(message) {
 	const match = /Trae code (\d+)/u.exec(message);
@@ -3992,12 +4400,9 @@ function classifyProbeResult(result, outputSeen) {
 		detail: message
 	};
 	const code = codeOf(message);
-	if (code !== void 0 && GATE_CODES.has(code)) return {
-		verdict: "gated",
-		detail: message
-	};
-	if (code !== void 0 && UNSUPPORTED_CODES.has(code)) return {
-		verdict: "unsupported",
+	const mapped = code === void 0 ? void 0 : CODE_VERDICTS[code];
+	if (mapped !== void 0) return {
+		verdict: mapped,
 		detail: message
 	};
 	if (result.kind === "client" && result.status >= 400 && result.status < 500) return {
@@ -5736,6 +6141,8 @@ function apply(ctx, config) {
 	Promise.all(REGION_KEYS.map((region) => stacks[region].shim.ready)).then(async () => {
 		if (stopped) return;
 		try {
+			const piAi = piAiRuntimeInfo();
+			ctx.logger.info(`dsh-connect-trae: pi-ai ${piAi.version ?? "unknown"} (${piAi.generation} generation)${piAi.inspected ? "" : " — not resolved locally, the host supplies it"}`);
 			for (const region of REGION_KEYS) {
 				const stack = stacks[region];
 				const trae = createTraeAdapter({
@@ -5809,4 +6216,4 @@ function apply(ctx, config) {
 	});
 }
 //#endregion
-export { Config, FALLBACK_TRAE_MODELS, FALLBACK_TRAE_MODELS_AI, REGION_GATEWAYS, SseDecoder, TRAE_ACCOUNT_STATUS_PATH, TRAE_AI_PROVIDER, TRAE_CHECKIN_PATH, TRAE_CN_AGENT_TASK_PATH, TRAE_CN_TITLE_PATH, TRAE_MODELS_TEST_PATH, TRAE_MODEL_DETAIL_FUNCTIONS, TRAE_MODEL_DETAIL_PATH, TRAE_PAY_BASE, TRAE_PROBE_TIMEOUT_MS, TRAE_PROVIDER, TRAE_PROVIDERS, TRAE_PROVIDER_DISPLAY_NAMES, TRAE_RAW_CHAT_V1_PATH, TRAE_RAW_CHAT_V2_PATH, TRAE_REASONING_EFFORTS, TRAE_REGIONS, TRAE_REGION_PARAM, TRAE_SETTINGS_NS, TRAE_SOLO_CHAT_PATH, TRAE_SOLO_FUNCTION, TRAE_SOLO_MODELS_PATH, TRAE_SOLO_REMOTE_BASE, TRAE_STATE_DB_FILENAME, TRAE_STREAM_IDLE_TIMEOUT_MS, TRAE_USAGE_PATH, TRAE_VERSION_CODE_FALLBACK, TraeCatalog, TraeCredentialStore, TraeDelegatingUpstreamClient, TraeFallbackUpstreamClient, TraeGatedUpstreamClient, TraeRawCapabilityController, TraeRawCapabilityState, TraeRawChatUpstreamClient, TraeSoloBridge, TraeSoloRemoteCatalogClient, TraeSoloUpstreamClient, TraeUsageClient, UnconfiguredTraeUpstreamClient, apply, applyContextBudgets, applyImageSelection, applyReasoningEffort, asVolatile, bridgeTraeSoloStream, buildTraeAgentTaskBody, buildTraeCnHeaders, buildTraeFusionRawChatEnvelope, buildTraeModelDetailRequest, buildTraeRawChatDraft, buildTraeRawChatRuntimeConfig, classifyProbeError, classifyProbeResult, classifyTraeRawChatFailure, configuredAccountsOf, createTraeAdapter, createTraeRawGateway, createTraeShim, decodeRawChatChunk, decodeTraeEvent, decryptTraeStorageValue, deriveCatalog, describeIdShape, describeNameShape, discoveredCatalog, fallbackModelsFor, followAppLoginEnabled, hashTraeRawChatArg, identityHeaders, inject, legacyTraeOwnAuthPath, maskUserPath, mergeTraeModelSources, name, nextRegionEnabled, nextRegionSlots, normalizeTraeCredential, normalizeTraeVersionCode, parseObservedModelConfig, parseReasoningCapability, parseTraeAuthValue, parseTraeCachedModel, parseTraeModelExtraConfigLogLine, parseTraeRawChatBehaviorConfig, parseTraeRemoteModel, parseTraeStorageDocument, pickTraeStorageIdentity, prepareSoloBody, probeBody, probeModelsSequentially, probeOneModel, probeTraeRawChatCapability, rawCapabilityDiagnostic, rawCapabilityFingerprint, readTraeCachedModel, readTraeCliIdentity, readTraeIdentity, refreshTraeCredential, regionEnabled, regionEnabledOf, regionOfCredential, regionOfEdition, regionOfHost, regionOfTraeProvider, regionOfTraeStatusUrl, regionOfUserRegion, regionStateOf, registerTraeUsageRoute, resolveTraeIdentity, resolveTraeRawRuntime, sanitizeCatalog, settingsNamespaceOf, traeEndpoint, traeInputModalities, traeModelDisplayName, traeOwnAuthPath, traeRawChatExtraInfo, traeStateDatabaseCandidates, traeStorageCandidates, traeWebUsage, traeWindowsAppNames, unwrapVolatile, unwrapVolatileDeep, withTraeRegion };
+export { Config, FALLBACK_TRAE_MODELS, FALLBACK_TRAE_MODELS_AI, REGION_GATEWAYS, SseDecoder, TRAE_ACCOUNT_STATUS_PATH, TRAE_AI_PROVIDER, TRAE_CHECKIN_PATH, TRAE_CN_AGENT_TASK_PATH, TRAE_CN_TITLE_PATH, TRAE_MODELS_TEST_PATH, TRAE_MODEL_DETAIL_FUNCTIONS, TRAE_MODEL_DETAIL_PATH, TRAE_PAY_BASE, TRAE_PROBE_TIMEOUT_MS, TRAE_PROVIDER, TRAE_PROVIDERS, TRAE_PROVIDER_DISPLAY_NAMES, TRAE_RAW_CHAT_V1_PATH, TRAE_RAW_CHAT_V2_PATH, TRAE_REASONING_EFFORTS, TRAE_REGIONS, TRAE_REGION_PARAM, TRAE_SETTINGS_NS, TRAE_SOLO_CHAT_PATH, TRAE_SOLO_FUNCTION, TRAE_SOLO_MODELS_PATH, TRAE_SOLO_REMOTE_BASE, TRAE_STATE_DB_FILENAME, TRAE_STREAM_IDLE_TIMEOUT_MS, TRAE_USAGE_PATH, TRAE_VERSION_CODE_FALLBACK, TraeCatalog, TraeCredentialStore, TraeDelegatingUpstreamClient, TraeFallbackUpstreamClient, TraeGatedUpstreamClient, TraeRawCapabilityController, TraeRawCapabilityState, TraeRawChatUpstreamClient, TraeSoloBridge, TraeSoloRemoteCatalogClient, TraeSoloUpstreamClient, TraeUsageClient, UnconfiguredTraeUpstreamClient, adaptLegacyPiAiContext, adaptModernPiAiContext, apply, applyContextBudgets, applyImageSelection, applyReasoningEffort, asVolatile, bridgeTraeSoloStream, buildTraeAgentTaskBody, buildTraeCnHeaders, buildTraeFusionRawChatEnvelope, buildTraeModelDetailRequest, buildTraeRawChatDraft, buildTraeRawChatRuntimeConfig, classifyProbeError, classifyProbeResult, classifyTraeRawChatFailure, configuredAccountsOf, createTraeAdapter, createTraeRawGateway, createTraeShim, decidePiAiGeneration, decodeRawChatChunk, decodeTraeEvent, decryptTraeStorageValue, deriveCatalog, describeIdShape, describeNameShape, discoveredCatalog, fallbackModelsFor, followAppLoginEnabled, generationOf, hashTraeRawChatArg, identityHeaders, inject, legacyTraeOwnAuthPath, maskUserPath, mergeTraeModelSources, name, nextRegionEnabled, nextRegionSlots, normalizeTraeCredential, normalizeTraeVersionCode, parseObservedModelConfig, parseReasoningCapability, parseTraeAuthValue, parseTraeCachedModel, parseTraeModelExtraConfigLogLine, parseTraeRawChatBehaviorConfig, parseTraeRemoteModel, parseTraeStorageDocument, piAiRuntimeInfo, pickTraeStorageIdentity, prepareSoloBody, probeBody, probeModelsSequentially, probeOneModel, probeTraeRawChatCapability, rawCapabilityDiagnostic, rawCapabilityFingerprint, readTraeCachedModel, readTraeCliIdentity, readTraeIdentity, refreshTraeCredential, regionEnabled, regionEnabledOf, regionOfCredential, regionOfEdition, regionOfHost, regionOfTraeProvider, regionOfTraeStatusUrl, regionOfUserRegion, regionStateOf, registerTraeUsageRoute, resolveTraeIdentity, resolveTraeRawRuntime, sanitizeCatalog, settingsNamespaceOf, traeEndpoint, traeInputModalities, traeModelDisplayName, traeOwnAuthPath, traeRawChatExtraInfo, traeStateDatabaseCandidates, traeStorageCandidates, traeWebUsage, traeWindowsAppNames, unwrapVolatile, unwrapVolatileDeep, withContextAdaptation, withTraeRegion };

package/package.json

@@ -2,7 +2,7 @@
   "name": "dsh-connect-trae",
   "displayName": "DSH Connect Trae",
   "description": "把本机登录的 Trae 模型接入 DeepSeek Harness：国内版与国际版双供应商并行，提供用量/积分概览与每日签到领取。",
-  "version": "3.4.0",
+  "version": "3.4.2",
   "author": "dingminhua",
   "copyright": "Copyright (c) 2026 LaoDing",
   "license": "MIT",