dsh-connect-trae 3.4.1 → 3.4.2

package/CHANGELOG.md

@@ -1,5 +1,109 @@
 # 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 不提供此模型」。**

package/README.en.md

@@ -138,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`
@@ -232,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

@@ -143,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 写一行，界面上表现为「插件凭空消失」。
 
@@ -242,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"];
@@ -295,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 = {
@@ -351,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;
@@ -359,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;
@@ -2116,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. */
@@ -2333,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
@@ -322,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";
@@ -405,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({
@@ -424,7 +761,7 @@ function createTraeAdapter(options) {
 				}
 			} },
 			models: buildModels(),
-			api: openAICompletionsApi()
+			api: withContextAdaptation(openAICompletionsApi(), generation)
 		}),
 		getModels: () => buildModels()
 	};
@@ -5804,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({
@@ -5877,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.1",
+  "version": "3.4.2",
   "author": "dingminhua",
   "copyright": "Copyright (c) 2026 LaoDing",
   "license": "MIT",