pi2dsh 0.11.0 → 0.12.0

package/README.md

@@ -36,12 +36,20 @@ here, you should switch to it. That would be the bridge doing its job.
 One engine, then whatever plugins you want:
 
 ```sh
-dsh plugin --profile <your-profile> add pi2dsh
-dsh plugin --profile <your-profile> add @kassing/pi-vision
+dsh plugin --profile web add pi2dsh
+dsh plugin --profile web add @kassing/pi-vision
 ```
 
 Then **restart `dsh`** — plugins mount at startup.
 
+> **Use `web` or `headless` as the profile name.** DSH ships a template for
+> exactly those two, and each includes a surface (the web app / the one-shot
+> driver). `dsh plugin --profile <any-other-name>` creates a profile with no
+> surface at all, and that profile **starts up and then hangs with no
+> diagnostic** — nothing to do with pi2dsh, but easy to hit on your first
+> install. If you want a differently named profile, add the surface bundle to
+> its `dsh.profile.bundles` yourself.
+
 That is the whole model. There is no conversion step, no generated bundle, no
 build. The engine discovers the Pi packages in your profile (every one is
 something you explicitly added) and mounts them through a single bridge
@@ -62,7 +70,7 @@ Two installer messages worth knowing:
 
 - **`ERR_PNPM_IGNORED_BUILDS`** — pnpm blocks dependency build scripts by
   default. Run `pnpm approve-builds` inside
-  `$DSH_HOME/profiles/<your-profile>`, or set the listed packages to `true`
+  `$DSH_HOME/profiles/web`, or set the listed packages to `true`
   under `allowBuilds` in that profile's `pnpm-workspace.yaml`. Then re-run the
   add. (This is your call to make, so the bridge does not work around it.)
 - **An add silently installs an older version** right after a release —
@@ -81,7 +89,7 @@ analysis back into the conversation.
 ### 1. Install the plugin
 
 ```sh
-dsh plugin --profile <your-profile> add @kassing/pi-vision
+dsh plugin --profile web add @kassing/pi-vision
 ```
 
 ### 2. Point it at a multimodal model
@@ -124,7 +132,7 @@ non-default `temperature` some vision plugins send.
 In the CLI, mention a path:
 
 ```sh
-dsh --profile <your-profile> "What color fills $PWD/photo.png ? One word."
+dsh --profile web "What color fills $PWD/photo.png ? One word."
 ```
 
 In the web app, **just paste the image** — even though your main model is
@@ -140,7 +148,7 @@ text-only wire.
 
 Companions are automatic. To turn them off, or narrow them to specific routes,
 set `visionCompanions` in the engine's plugin config
-(`$DSH_HOME/profiles/<your-profile>/cordis.patch.yml`):
+(`$DSH_HOME/profiles/web/cordis.patch.yml`):
 
 ```yaml
 - id: pi2dsh
@@ -150,13 +158,49 @@ set `visionCompanions` in the engine's plugin config
 
 Full runnable version, with probe images: [`examples/vision-bridge`](examples/vision-bridge/).
 
-## What you can install today
+## What actually works today
+
+Two levels, and they are not the same claim.
+
+### Level 1 — verified end to end, with a runnable example
+
+Someone sat down, used the plugin's real feature on a real DSH loop, and saw
+it work. **This is the list to trust.**
+
+| Plugin | What was exercised | Where | Example |
+|---|---|---|---|
+| [`@kassing/pi-vision`](https://www.npmjs.com/package/@kassing/pi-vision) | Image analysis delegated to a vision model; image-admission companion route; analysis injected into a text-only model's turn | CLI + web | [`vision-bridge`](examples/vision-bridge/) |
+| [`pi-btw`](https://www.npmjs.com/package/pi-btw) | `/btw <question>` as a real child session in DSH's subagent UI; `/btw-inject`; `/btw --save`; main thread stays clean | CLI + web | [`side-conversation`](examples/side-conversation/) |
+| [`pi-vision-tool`](https://www.npmjs.com/package/pi-vision-tool) | Tool registration through a JSON-Schema shape DSH had to convert (`anyOf` → `oneOf`) | CLI + web | — |
+| [`pi-approval-guardian`](https://www.npmjs.com/package/pi-approval-guardian) | Every tool call reviewed by a second model before execution; allow and deny both observed | CLI (bare env) | — |
+| [`pi-hermes-memory`](https://www.npmjs.com/package/pi-hermes-memory) | Cross-session memory: written in one process, read back in a second, fresh one | CLI | — |
 
-The Pi catalog's **top 50 packages by monthly downloads**, all verified on a
-real DSH runtime — mounted, then actually exercised. Status as of 2026-08-14;
-per-package machine-readable evidence in [`community/`](community/).
+Examples for the last three are still to be written; per this project's own
+rule they get re-verified from scratch before an example lands, so the table
+says plainly which have one today.
 
-**47 of 50 verified working · 1 with no probeable surface · 2 pending a re-run.**
+### Level 2 — mounts and its surface answers a probe
+
+The Pi catalog's **top 50 packages by monthly downloads**, each mounted in a
+real DSH runtime and then called through a black-box probe. Status as of
+2026-08-14; per-package machine-readable evidence in
+[`community/`](community/).
+
+**47 of 50 exercised successfully · 1 with no probeable surface · 2 pending a
+re-run.**
+
+**What this level does not tell you:** that the plugin's actual feature works
+the way you would use it. A probe calls a registered surface with synthetic
+arguments; a user runs a workflow. `pi-btw` is the cautionary example — it
+graded "working" here for weeks while `/btw <question>` failed on a real
+session, because the feature needed two ABI gaps closed (Pi's settable
+`AgentState.messages`, and an input descriptor on bridged commands) that no
+probe exercised. Both are fixed in 0.11.0, and both were general fixes that
+unlock every plugin doing the same thing.
+
+So read the table below as **"the bridge covers what this plugin touches"**,
+not as "this plugin is known-good". When you try one, a report either way is
+useful.
 
 | Area | Packages |
 |---|---|
@@ -187,6 +231,10 @@ Packages outside the top 50 are not a separate case — the bridge has no
 per-package code. If one hits an ABI gap, fixing that gap unlocks every
 package that shares it.
 
+Level 1 grows by working through Level 2 one plugin at a time. The full
+verification ladder, with what each rung does and does not prove:
+[support matrix](docs/posting-kit/support-matrix.md).
+
 ## How it works
 
 Three layers, and nothing crosses them:
@@ -286,6 +334,7 @@ in one has actually been executed against a real DSH loop before landing.
 |---|---|
 | [`vision-bridge`](examples/vision-bridge/) | A text-only model answers questions about images — CLI and web, probe images included |
 | [`side-conversation`](examples/side-conversation/) | `/btw <question>` runs a side thread in DSH's native subagent UI; your main conversation stays clean |
+| [`gateway-compat`](examples/gateway-compat/) | Private / domestic / proxy gateways that reject the `developer` role: why reasoning 400s, and how a Pi provider plugin gets past it (fake-endpoint probe included) |
 | [`custom-gateways`](examples/custom-gateways/) | Add any OpenAI-compatible gateway the official DSH way, and every Pi plugin sees it |
 
 ## Other tools

package/README.zh.md

@@ -30,12 +30,18 @@ DSH 插件一样装一个 Pi 插件，它就能用。
 一次引擎，之后想装谁装谁：
 
 ```sh
-dsh plugin --profile <你的 profile> add pi2dsh
-dsh plugin --profile <你的 profile> add @kassing/pi-vision
+dsh plugin --profile web add pi2dsh
+dsh plugin --profile web add @kassing/pi-vision
 ```
 
 然后**重启 `dsh`**——插件在启动时挂载。
 
+> **profile 名字请用 `web` 或 `headless`。** DSH 只为这两个名字内置了模板，
+> 每个都带一个界面层（网页应用 / 一次性执行器）。`dsh plugin --profile <别的
+> 名字>` 建出来的 profile **没有任何界面层**，起来之后会**直接挂住、不报任何
+> 错**——这跟 pi2dsh 无关，但第一次装的时候很容易撞上。确实想用别的名字，就
+> 自己往它的 `dsh.profile.bundles` 里加界面 bundle。
+
 就这一种方式。没有转换步骤，没有生成产物，不用构建。引擎会读出你 profile 里的
 Pi 包（每一个都是你显式装的），用同一个桥实例挂载它们：一个模型目录、一个登录、
 一个凭证存储、一个升级单元。
@@ -53,7 +59,7 @@ Pi 包（每一个都是你显式装的），用同一个桥实例挂载它们
 两条安装期提示值得提前知道：
 
 - **`ERR_PNPM_IGNORED_BUILDS`**：pnpm 默认拦截依赖的构建脚本。在
-  `$DSH_HOME/profiles/<你的 profile>` 里跑 `pnpm approve-builds`，或者把提示
+  `$DSH_HOME/profiles/web` 里跑 `pnpm approve-builds`，或者把提示
   里的包在该 profile 的 `pnpm-workspace.yaml` 的 `allowBuilds` 下设成 `true`，
   然后重跑 add。（这是你的决定权，桥不会绕过它。）
 - **刚发版后 add 装到了旧版本**：pnpm 的 `minimumReleaseAge` 会跳过刚发布不久
@@ -69,7 +75,7 @@ Pi 生态里正好有插件干这件事：把图片交给你指定的视觉模
 ### 1. 装插件
 
 ```sh
-dsh plugin --profile <你的 profile> add @kassing/pi-vision
+dsh plugin --profile web add @kassing/pi-vision
 ```
 
 ### 2. 给它配一个多模态模型
@@ -111,7 +117,7 @@ Pi 格式文件。
 CLI 里直接提路径：
 
 ```sh
-dsh --profile <你的 profile> "$PWD/photo.png 这张图是什么颜色？只答一个词。"
+dsh --profile web "$PWD/photo.png 这张图是什么颜色？只答一个词。"
 ```
 
 Web 里**直接粘图**——哪怕你的主模型是纯文本的。DSH 正常情况下会拒绝给纯文本模型
@@ -124,7 +130,7 @@ Web 里**直接粘图**——哪怕你的主模型是纯文本的。DSH 正常
 那条线。
 
 伴生路由是全自动的。想关掉、或者只给某些路由开，在引擎的插件配置里设
-`visionCompanions`（`$DSH_HOME/profiles/<你的 profile>/cordis.patch.yml`）：
+`visionCompanions`（`$DSH_HOME/profiles/web/cordis.patch.yml`）：
 
 ```yaml
 - id: pi2dsh
@@ -134,13 +140,42 @@ Web 里**直接粘图**——哪怕你的主模型是纯文本的。DSH 正常
 
 完整可跑版本（含纯色探针图）：[`examples/vision-bridge`](examples/vision-bridge/)。
 
-## 现在能装哪些插件
+## 现在到底哪些真能用
+
+分两级，这两件事不是一回事。
+
+### 第一级——端到端实测过，配可跑示例
+
+有人真坐下来，在真实 DSH loop 上用了这个插件的真功能，亲眼看到它工作。
+**要信就信这张表。**
+
+| 插件 | 验证了什么 | 在哪验的 | 示例 |
+|---|---|---|---|
+| [`@kassing/pi-vision`](https://www.npmjs.com/package/@kassing/pi-vision) | 图片委托给视觉模型；贴图伴生路由；分析结果注入纯文本模型的这一轮 | CLI + Web | [`vision-bridge`](examples/vision-bridge/) |
+| [`pi-btw`](https://www.npmjs.com/package/pi-btw) | `/btw <问题>` 跑成 DSH 子代理界面里的真子会话；`/btw-inject`；`/btw --save`；主会话保持干净 | CLI + Web | [`side-conversation`](examples/side-conversation/) |
+| [`pi-vision-tool`](https://www.npmjs.com/package/pi-vision-tool) | 工具注册，且带一个 DSH 需要转换的 JSON Schema 形状（`anyOf` → `oneOf`） | CLI + Web | — |
+| [`pi-approval-guardian`](https://www.npmjs.com/package/pi-approval-guardian) | 每次工具调用先由第二个模型审批；放行与拒绝两条路都看到了 | CLI（裸环境） | — |
+| [`pi-hermes-memory`](https://www.npmjs.com/package/pi-hermes-memory) | 跨会话记忆：一个进程写入，另一个全新进程读回 | CLI | — |
 
-Pi 目录里**月下载量前 50 的包**，全部在真实 DSH 运行时上验证过——先挂载，再真的
-调起来跑。状态截至 2026-08-14；逐包的机器可读证据在
-[`community/`](community/)。
+后三个的示例还没写。按本项目自己的规矩，补示例前必须重新端到端验证一遍，所以
+这张表如实标出今天谁有示例。
 
-**50 个里 47 个实测可用 · 1 个没有可探测面 · 2 个待复跑。**
+### 第二级——能挂载，且注册面能被探针调起来
+
+Pi 目录里**月下载量前 50 的包**，每个都在真实 DSH 运行时里挂载，然后用黑盒探针
+调用。状态截至 2026-08-14；逐包的机器可读证据在 [`community/`](community/)。
+
+**50 个里 47 个探针调用成功 · 1 个没有可探测面 · 2 个待复跑。**
+
+**这一级不能说明的事**：不能说明这个插件的真功能按你的用法能跑通。探针是拿合成
+参数去调一个注册面，用户跑的是一整条工作流。`pi-btw` 就是最好的反例——它在这张
+表里挂着"working"挂了好几周，而真实会话里 `/btw <问题>` 是直接失败的：这个功能
+需要补两个 ABI 缺口（Pi 公开可写的 `AgentState.messages`，以及给桥接命令声明输入
+描述符），而任何探针都不会碰到它们。两个缺口都在 0.11.0 修好了，而且都是通用修
+复——同样用法的插件一起解锁。
+
+所以下面这张表请读成**"桥覆盖了这个插件用到的面"**，而不是"这个插件已知可用"。
+你要是试了哪个，不管成没成，反馈回来都有用。
 
 | 能力 | 插件 |
 |---|---|
@@ -168,6 +203,9 @@ Pi 目录里**月下载量前 50 的包**，全部在真实 DSH 运行时上验
 前 50 之外的包不是另一类情况——桥里没有任何逐包代码。哪个包撞上 ABI 缺口，补上
 那个缺口，撞同一处的包一起解锁。
 
+第一级是靠一个一个啃第二级长出来的。完整的验证阶梯、以及每一级分别能证明什么、
+不能证明什么：[support matrix](docs/posting-kit/support-matrix.md)。
+
 ## 技术架构
 
 三层，谁也不跨谁：
@@ -251,6 +289,7 @@ loop 上实际跑过才会进来。
 |---|---|
 | [`vision-bridge`](examples/vision-bridge/) | 纯文本模型回答图片问题——CLI 与 Web 双端，附探针图 |
 | [`side-conversation`](examples/side-conversation/) | `/btw <问题>` 在 DSH 原生子代理界面里开一条侧边线程，主会话保持干净 |
+| [`gateway-compat`](examples/gateway-compat/) | 私有 / 国内 / 代理网关拒收 `developer` 角色：为什么一开推理就 400，以及用 Pi provider 插件怎么绕过去（附假端点探针） |
 | [`custom-gateways`](examples/custom-gateways/) | 按 DSH 官方方式接任何 OpenAI 兼容网关，每个 Pi 插件都能看到它 |
 
 ## 其它工具

package/dist/host.mjs

@@ -1,5 +1,5 @@
 
-import { r as registerVisionCompanions, t as applyPiPackage } from "./runtime-DFD6u4NO.mjs";
+import { r as registerVisionCompanions, t as applyPiPackage } from "./runtime-Bh5k4Kjt.mjs";
 import { t as resolvePiPackage } from "./source-0sA5z08z.mjs";
 import { createRequire } from "node:module";
 import { cp, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";

package/dist/index.mjs

@@ -1,5 +1,5 @@
 
-import { r as registerVisionCompanions } from "./runtime-DFD6u4NO.mjs";
+import { r as registerVisionCompanions } from "./runtime-Bh5k4Kjt.mjs";
 import { t as resolvePiPackage } from "./source-0sA5z08z.mjs";
 import { applyPiHost, generateHostBundle, manifestForInstalled } from "./host.mjs";
 import { a as CONTEXT_RULES, c as PI_AI_PACKAGES, d as UI_CONTEXT_RULES, f as ruleForApi, g as ruleForUiContextProperty, h as ruleForHostImport, i as API_RULES, l as PI_CODING_AGENT_PACKAGES, m as ruleForEvent, n as convertPiMcpConfig, o as EVENT_RULES, p as ruleForContextProperty, r as renderMcpPatch, s as HOST_IMPORT_RULES, t as collectPiMcpServers, u as PI_TUI_PACKAGES } from "./mcp-config-Cn5gWemZ.mjs";

package/dist/{runtime-DFD6u4NO.mjs → runtime-Bh5k4Kjt.mjs}

@@ -1,5 +1,5 @@
 
-import { F as AssistantMessageEventStream, a as builtinProviders, i as __setPiAiLlmBridge } from "./pi-ai-Dyg4zyLZ.mjs";
+import { F as AssistantMessageEventStream, a as builtinProviders, h as getSupportedThinkingLevels, i as __setPiAiLlmBridge } from "./pi-ai-Dyg4zyLZ.mjs";
 import { P as generateBranchSummary, Tn as PiCapabilityError, b as Theme, d as ExtensionRunner, w as __setSubagentSessionFactory, wn as CapabilityLedger } from "./pi-coding-agent-Ctw-BhoY.mjs";
 import { t as getAgentDir } from "./pi-config-shim-CZ1wFzqM.mjs";
 import { a as resolvePiProviderAuth, n as loginPiProvider, r as providerSupportsOAuth, t as FileCredentialStore } from "./oauth-bridge-CfyImWx4.mjs";
@@ -1279,6 +1279,33 @@ const PI_CARRIED_FIELDS = [
 	"compat",
 	"headers"
 ];
+/**
+* Pi's reasoning capability, in DSH's shape.
+*
+* The two sides say the same thing differently: Pi carries a `reasoning`
+* boolean plus a `thinkingLevelMap` whose `null` entries mark unsupported
+* levels, while DSH asks an adapter for the selectable efforts directly.
+* Translating is this layer's job — carrying Pi's boolean through under the
+* name `reasoning` would collide with DSH's `{efforts}` object, and carrying
+* nothing (what this bridge did before) leaves every package-registered route
+* with no selectable effort at all, so any reasoning request is rejected.
+*
+* The mapping is DSH's own: its native pi-ai adapter derives efforts from
+* `getSupportedThinkingLevels` and names them the same way, so a route a Pi
+* package registers offers exactly the efforts it would through the host's
+* own adapter. It belongs to the exact-route resolve, not the catalog listing
+* — `reasoning` is a resolved-model field in DSH's contract.
+* @param model - the Pi model descriptor as its package declared it.
+*/
+function reasoningProjection(model) {
+	if (model.reasoning !== true) return {};
+	const levels = getSupportedThinkingLevels(model);
+	if (levels.length === 0) return {};
+	return { reasoning: { efforts: levels.map((level) => ({
+		id: level,
+		name: `${level.charAt(0).toUpperCase()}${level.slice(1)}`
+	})) } };
+}
 function piCarriedFields(model) {
 	const carried = {};
 	for (const field of PI_CARRIED_FIELDS) if (model[field] !== void 0) carried[field] = model[field];
@@ -1306,6 +1333,7 @@ function piProviderDshAdapter(providerId, provider, host) {
 			const known = providerModels(provider).find((model) => model.id === modelId);
 			return {
 				...known === void 0 ? {} : piCarriedFields(known),
+				...known === void 0 ? {} : reasoningProjection(known),
 				provider: id,
 				id: modelId,
 				name: String(known?.name ?? modelId),
@@ -1327,7 +1355,8 @@ function piProviderDshAdapter(providerId, provider, host) {
 				...auth?.headers === void 0 ? {} : { headers: auth.headers },
 				...options.signal instanceof AbortSignal ? { signal: options.signal } : {},
 				...typeof options.maxTokens === "number" ? { maxTokens: options.maxTokens } : {},
-				...typeof options.temperature === "number" ? { temperature: options.temperature } : {}
+				...typeof options.temperature === "number" ? { temperature: options.temperature } : {},
+				...typeof options.reasoningEffort === "string" ? { reasoningEffort: options.reasoningEffort } : {}
 			};
 			yield* piEventsToDshChunks(provider.stream(model, piContext, piOptions));
 		}
@@ -3535,4 +3564,4 @@ const runtimeInternals = {
 //#endregion
 export { runtimeInternals as i, normalizeToolSchema as n, registerVisionCompanions as r, applyPiPackage as t };
 
-//# sourceMappingURL=runtime-DFD6u4NO.mjs.map
+//# sourceMappingURL=runtime-Bh5k4Kjt.mjs.map