pi2dsh 0.3.1 → 0.3.2

package/README.md

@@ -45,7 +45,7 @@ Three delivery modes:
 Three hard rules keep it general:
 
 1. The core contains **no `if (packageName === …)`** branching.
-2. Every capability has a **public-API contract test** (`pnpm test`, 49 tests); "some plugin loads" is never the success criterion.
+2. Every capability has a **public-API contract test** (`pnpm test`, 55 tests); "some plugin loads" is never the success criterion.
 3. The top-50 corpus is verified **black-box only**: failures file public ABI gaps, and fixing one gap unlocks every package that hits it (e.g. one jiti subpath-alias fix unlocked 4 packages at once).
 
 ## Progress: Pi catalog top 50 by monthly downloads
@@ -54,28 +54,30 @@ Status as of 2026-08-14. Static analysis screens; the black-box run certifies. F
 
 | Tier | Count | Meaning |
 |---|---|---|
-| ✅ **Tested working** | **41 / 50** | Mounted in a real DSH runtime AND real execution verified: 35 returned success, 6 ran their business logic end-to-end and rejected the synthetic probe arguments (4 additionally passed deep verification: real LSP subprocess, web search/fetch, PNG generation, official `dsh plugin` add/activate/remove; 2 of the 41 verified through host mode) |
-| 🟡 **Mounts, not fully verified** | **9 / 50** | Loads and registers its tools/commands/skills in a real DSH runtime; full execution needs user credentials/services (3), exposes no safely-probeable callable surface — event-hook packages or tools whose names indicate shared-state mutation, which the harness never invokes (4), was still executing when the 20s probe timeout hit — it dispatches a child `pi` process the fixture environment cannot serve (1), or hit a test-harness limitation (1: strict live-agent identity checks in userQuestions — the same path passes in the deep-verification layer) |
+| ✅ **Tested working** | **49 / 50** | Mounted in a real DSH runtime AND real execution verified: 42 returned success, 7 ran their business logic end-to-end and rejected the synthetic probe arguments (2 of the 49 verified through host mode). Real-service coverage along the way: a real LSP subprocess, real web search/fetch, PNG generation, a real MCP stdio server bridged end-to-end, real child-`pi` dispatch answered by a live model, real DeepSeek search on user credentials, and the official `dsh plugin` add/activate/remove flow |
+| 🟡 **Mounts, not fully verified** | **1 / 50** | `@alexanderfortin/pi-deepseek-usage` — a pure event-hook package: all four lifecycle subscriptions attach, but every handler is gated on an active DeepSeek model session (it fetches billing usage and renders a footer), so a black-box probe has no safely-assertable callable surface. A harness limit, not a package or bridge gap |
 | ❌ **Not yet supported** | **0 / 50** | The last four Pi-internal-runtime packages are bridged: vendored built-in tool constructors, provider factories, a real-semantics `ExtensionRunner` facade, and `createAgentSession` driving genuine DSH child agents |
 | **Total mountable today** | **50 / 50** | 48 through convert/host bundles directly; 2 snapshot-limited packages through host mode ([evidence](community/host-mode-results.json)) |
 
+The v6 harness also hardened the probe methodology itself: the bridge's own host-native surface (e.g. the built-in `/login` command) is measured by mounting a zero-contribution fixture extension and subtracted from every probe, so a grade reflects the package's own increment only; unsafe-name screening is word-level (`litellm_skill_list` is not a "kill" tool); and the fixture environment serves a real MCP stdio server, a LiteLLM-gateway-shaped skills API, image-model settings under Pi's config-dir contract, and — opt-in via `PI2DSH_BLACKBOX_PI_BIN` + `DEEPSEEK_API_KEY` — real child-`pi` dispatch answered by a live model.
+
 Additional verified layers: a **host bundle** mounting two unmodified packages passed the official plugin-manager flow end-to-end; a **real model run** (`deepseek-v4-flash`) called a migrated Pi tool with the durable session log asserted and zero credential persistence ([evidence](community/live-deepseek-results.json)).
 
 ### How the last four internal-runtime packages were bridged
 
-Each landed as a reusable public-surface bridge, not a package patch: `pi-landstrip` and `pi-fabric` run on Pi's built-in tool constructors (bash/read/edit/write/grep/find/ls) vendored byte-identical with their pure-logic closure; `pi-provider-litellm` runs on the vendored pi-ai `createProvider` factory (model transports stay native to DSH llm); `pi-fabric` additionally hooks a real-semantics `ExtensionRunner` facade — patching `prototype.getAllRegisteredTools` genuinely filters the tool catalog, as under Pi; `@tintinweb/pi-subagents` runs on `createAgentSession` bridged to genuine DSH child agents through `ctx.agents` — the bridge owns no model loop, so compositions without one fail explicitly instead of simulating a subagent.
+Each landed as a reusable public-surface bridge, not a package patch: `pi-landstrip` and `pi-fabric` run on Pi's built-in tool constructors (bash/read/edit/write/grep/find/ls) vendored byte-identical with their pure-logic closure; `pi-provider-litellm` runs on the vendored pi-ai `createProvider` factory — providers key by `id` and the registry's `getProviderAuth` runs Pi's full credential chain (stored OAuth → stored key → the package's own env resolution), while model transports stay native to DSH llm; `pi-fabric` additionally hooks a real-semantics `ExtensionRunner` facade — patching `prototype.getAllRegisteredTools` genuinely filters the tool catalog, as under Pi; `@tintinweb/pi-subagents` runs on `createAgentSession` bridged to genuine DSH child agents through `ctx.agents` — the bridge owns no model loop, so compositions without one fail explicitly instead of simulating a subagent.
 
-### Correction: the "5 package defects" earlier versions reported
+### How the screener judges compatibility
 
-An earlier revision of this page (and our launch posts) attributed 5 blocked packages to upstream package defects. On re-verification **all five were faults in this project's own static screening, not in the packages** — high-download packages deserved that skepticism. Concretely: `bun:sqlite` is a host builtin of Pi's Bun-compiled distribution, and both `pi-hermes-memory` and `@mjasnikovs/pi-task` gate it behind runtime detection with proper Node fallbacks (better-sqlite3 / node:sqlite); `pi-harness-runtime`'s playwright and `mitsupi`'s googleapis/ws sit only on lazily-evaluated feature paths that never run at extension load; `pi-lens`'s out-of-tree skills path is skipped by Pi's own loader, and its bundler-stale worker URLs behave identically under Pi. The screener now models load-time vs lazy reachability, treats `bun:*` like `node:*`, and preserves published file layout — after which **all five mount, four grade tested-working, and no upstream issue was warranted**. The screening rules that produced the misjudgment are contract-tested against regressions.
+The screener models **load-time vs lazy reachability**: only an unresolvable dependency on the load-time static closure blocks a package — function-body dynamic imports, files reached only through dynamic import, and worker/data assets are lazy paths that behave identically under Pi and are graded as reviewable, never fatal. `bun:*` is treated like `node:*` (a host builtin of Pi's Bun-compiled distribution), and snapshots preserve the published file layout byte for byte. These rules are contract-tested; under them, packages that mix Bun-only branches, optional heavyweight dependencies, or bundler-generated worker paths — `pi-hermes-memory`, `@mjasnikovs/pi-task`, `pi-harness-runtime`, `mitsupi`, `pi-lens` — all mount and work as published, with no changes needed upstream.
 
 ### Roadmap
 
-1. Lift the 9 "mounts, not fully verified" to tested-working (credentialed fixtures, per-package probe arguments, a live-agent probe path for userQuestions).
+1. ✅ Done: the 9 "mounts, not fully verified" lifted — 8 grade tested-working (credentialed fixtures, a real MCP stdio server, a live-agent probe path for userQuestions, Pi-config-dir settings, real child-`pi` dispatch, and two registry-semantics fixes in the bridge: providers keyed by `id`, and `getProviderAuth` running Pi's full credential chain instead of OAuth only); the 1 remaining is a pure event-hook package graded honestly as having no probeable surface.
 2. ✅ Done: interactive OAuth host seam — Pi provider `oauth.login/refreshToken/getApiKey` flows run on DSH-native interaction, credentials persist with Pi's `auth.json` semantics with double-checked-lock refresh, and the four official Pi flows ship built in; verified end-to-end against a real ChatGPT Pro account (see "Interactive OAuth" above).
 3. ✅ Done: all four Pi-internal-runtime packages bridged (see above) — every top-50 package mounts.
 4. ✅ Done: the 2 snapshot-limited packages verified through host mode ([evidence](community/host-mode-results.json)).
-5. ✅ Done: re-verified the 5 packages we had wrongly reported as defective; corrected the screener and this page (see above).
+5. ✅ Done: load-time vs lazy reachability screening landed; the five packages it unblocked all mount, four tested-working (see above).
 
 ## Quick start
 
@@ -127,17 +129,20 @@ Both layers are verified against a real ChatGPT Pro account: browser authorizati
 | Sessions | Messages project from DSH's durable log; Pi custom entries/labels/names persist in a pi2dsh sidecar (DSH has no out-of-repo plugin-event channel yet) |
 | Pi TUI | Pure logic vendored byte-identical; components construct headlessly; `ui.custom` resolves `undefined` exactly like Pi's own rpc mode |
 | Providers/OAuth | Interactive OAuth is live: `/login <provider>` runs the package's own flow, credentials persist in Pi's `auth.json` with automatic refresh; model transports stay native to DSH `llm` |
+| Model runtime | `modelRegistry` projects the live DSH llm directory as Pi Model objects (refreshed on `llm/adapters-updated`); `ctx.model` reflects the agent's real route; `setModel`/`setThinkingLevel` switch the loop through the `agent/request` waterfall; pi-ai `complete()`/`stream()` run REAL calls through `ctx.llm.stream()` with two-way message conversion (verified against a live model: `scripts/verify-model-bridge-e2e.mjs`) |
 | Session tree writes | `fork`/`navigateTree`/`switchSession` fail explicitly (DSH lists pi-style entry trees as deferred) |
 | Terminal decoration | footer/statusline/shortcuts register but never fire — matching Pi's own non-TUI modes |
 
-Full machine-readable matrix: `pi2dsh matrix --json`. Capability-by-capability acceptance evidence: [docs/acceptance.md](docs/acceptance.md).
+Full machine-readable matrix: `pi2dsh matrix --json`. Capability-by-capability acceptance evidence: [docs/acceptance.md](docs/acceptance.md). The complete 114-item Pi-surface → DSH-semantics verdict (3 red / 21 yellow / ~90 green): [docs/pi-abi-coverage.md](docs/pi-abi-coverage.md).
 
 ## Development and verification
 
 ```sh
-pnpm verify                                   # typecheck + 49 contract tests + packaging
+pnpm verify                                   # typecheck + 55 contract tests + packaging
 pnpm audit:community                          # static screening, top 50
 node scripts/blackbox-community.mjs community/blackbox-results.json --exercise
+#   add DEEPSEEK_API_KEY=… PI2DSH_BLACKBOX_PI_BIN=$(command -v pi) for the
+#   credentialed probes and real child-pi dispatch (keys from env only)
 pnpm test:community                           # deep runtime + official manager + host e2e
 DEEPSEEK_API_KEY=… pnpm test:live             # real-model acceptance (key from env only)
 ```

package/README.zh.md

@@ -45,7 +45,7 @@ DeepSeek Harness 原生服务（Cordis 组合）
 保持通用性的三条硬规则：
 
 1. 核心**没有任何 `if (packageName === …)`** 包名分支。
-2. 每项能力有**公共 API 契约测试**（`pnpm test`，49 个）；"某个插件能加载"从不作为成功标准。
+2. 每项能力有**公共 API 契约测试**（`pnpm test`，55 个）；"某个插件能加载"从不作为成功标准。
 3. 前 50 只做**黑盒验收**：失败产生公共 ABI 缺口工单，修一个缺口、同类包一起解锁（例：一次 jiti 子路径 alias 修复同时解锁 4 个包）。
 
 ## 进度：Pi 官方目录下载量前 50
@@ -54,28 +54,30 @@ DeepSeek Harness 原生服务（Cordis 组合）
 
 | 档位 | 数量 | 含义 |
 |---|---|---|
-| ✅ **已测可用** | **41 / 50** | 在真实 DSH runtime 挂载且**真实执行**验证：35 个成功返回，6 个业务逻辑端到端真跑（拒绝了合成探针参数）；其中 4 个另通过深度验证：真 LSP 子进程、真搜索/抓取、PNG 真落盘、官方 `dsh plugin` 安装/激活/卸载全流程；41 个中有 2 个经 host 模式验证 |
-| 🟡 **能接入、未全测** | **9 / 50** | 在真实 DSH runtime 加载并注册出工具/命令/skill；完整执行还需用户凭证或外部服务（3 个）、没有可安全探测的调用面——纯事件钩子包或工具名表明会改共享状态、探针从不调用（4 个）、探针 20 秒超时时仍在执行——它要派发一个子 `pi` 进程，探针环境无法提供（1 个）、测试装置限制（1 个：userQuestions 严格校验 live agent 身份——同一链路在深度验证层已通过） |
+| ✅ **已测可用** | **49 / 50** | 在真实 DSH runtime 挂载且**真实执行**验证：42 个成功返回，7 个业务逻辑端到端真跑（拒绝了合成探针参数）；49 个中有 2 个经 host 模式验证。一路覆盖的真实服务包括：真 LSP 子进程、真搜索/抓取、PNG 真落盘、真 MCP stdio server 端到端桥接、真子 `pi` 进程派发并由真实模型应答、用真实凭证跑 DeepSeek 搜索、官方 `dsh plugin` 安装/激活/卸载全流程 |
+| 🟡 **能接入、未全测** | **1 / 50** | `@alexanderfortin/pi-deepseek-usage`——纯事件钩子包：4 个生命周期订阅全部接上，但每个 handler 都以"当前在 DeepSeek 模型会话中"为门槛（它拉计费用量并渲染 footer），黑盒探针没有可安全触发并断言的调用面。这是探针方法论的边界，不是包或桥的缺口 |
 | ❌ **尚未接入** | **0 / 50** | 最后 4 个 Pi 内部运行时包已全部桥接：内建工具构造器 vendored、provider 工厂、真语义 `ExtensionRunner` 门面、`createAgentSession` 驱动真实 DSH 子代理 |
 | **今天即可挂载** | **50 / 50** | 48 个经 convert/host bundle 直接挂载；2 个快照受限包经 host 模式（[证据](community/host-mode-results.json)） |
 
+v6 版黑盒装置同时强化了探测方法论本身：桥自带的宿主固有面（例如内建的 `/login` 命令）通过挂载一个零贡献 fixture 扩展测出，并从每个包的探测面里扣除——档位只反映包自己的增量；不安全工具名筛查改为分词级匹配（`litellm_skill_list` 不是 "kill" 工具）；fixture 环境提供真 MCP stdio server、LiteLLM 网关形状的 skills API、按 Pi config-dir 约定放置的图像模型配置，以及（经 `PI2DSH_BLACKBOX_PI_BIN` + `DEEPSEEK_API_KEY` 显式开启）由真实模型应答的子 `pi` 派发。
+
 另有两层验证：**host bundle** 合装两个原样 Pi 包走完官方插件管理器全流程；**真实模型**（deepseek-v4-flash）调用迁移后的 Pi 工具，durable 会话日志逐项断言、凭证零落盘（[证据](community/live-deepseek-results.json)）。
 
 ### 最后 4 个内部运行时包是怎么桥接的
 
-每个都落成了可复用的公共面桥，不是逐包补丁：`pi-landstrip` 与 `pi-fabric` 跑在 vendored 字节级的 Pi 内建工具构造器上（bash/read/edit/write/grep/find/ls 及其纯逻辑闭包）；`pi-provider-litellm` 跑在 vendored 的 pi-ai `createProvider` 工厂上（模型传输始终归 DSH llm 原生）；`pi-fabric` 另挂真语义 `ExtensionRunner` 门面——patch `prototype.getAllRegisteredTools` 能真实过滤工具目录，与 Pi 下行为一致；`@tintinweb/pi-subagents` 跑在 `createAgentSession` → 真实 DSH 子代理桥上（经 `ctx.agents` 走宿主 loop 工厂）——桥不自带模型循环，无 loop 的组合显式失败，绝不假装跑了子代理。
+每个都落成了可复用的公共面桥，不是逐包补丁：`pi-landstrip` 与 `pi-fabric` 跑在 vendored 字节级的 Pi 内建工具构造器上（bash/read/edit/write/grep/find/ls 及其纯逻辑闭包）；`pi-provider-litellm` 跑在 vendored 的 pi-ai `createProvider` 工厂上——provider 按 `id` 入注册表，注册表的 `getProviderAuth` 跑 Pi 完整凭证链（已存 OAuth → 已存 key → 包自己的环境变量解析），模型传输始终归 DSH llm 原生；`pi-fabric` 另挂真语义 `ExtensionRunner` 门面——patch `prototype.getAllRegisteredTools` 能真实过滤工具目录，与 Pi 下行为一致；`@tintinweb/pi-subagents` 跑在 `createAgentSession` → 真实 DSH 子代理桥上（经 `ctx.agents` 走宿主 loop 工厂）——桥不自带模型循环，无 loop 的组合显式失败，绝不假装跑了子代理。
 
-### 更正：早期版本报告的"5 个包缺陷"
+### 筛查器如何判定兼容性
 
-本页早期版本（以及我们的发布帖）曾把 5 个被挡的包归因为"包自身缺陷"。复查后确认：**五个全部是本项目静态筛查自己的判定问题，不是包的问题**——大下载量的包本就值得这份怀疑。具体：`bun:sqlite` 是 Pi 官方 Bun 编译发行版的宿主内建，`pi-hermes-memory` 与 `@mjasnikovs/pi-task` 都做了运行时检测并带正规 Node 回退（better-sqlite3 / node:sqlite）；`pi-harness-runtime` 的 playwright 和 `mitsupi` 的 googleapis/ws 只出现在惰性求值的功能路径上，扩展加载期根本不会执行；`pi-lens` 的越界 skills 路径 Pi 自己的 loader 也是跳过处理，其打包器残留的 worker 路径在 Pi 下行为完全相同。筛查器现已区分加载期与惰性可达、把 `bun:*` 与 `node:*` 同等对待、并原样保留发布文件布局——修正后**五个包全部可挂载、四个达到已测可用，无需向任何上游提 issue**。产生误判的判定规则已补契约测试防止回归。
+筛查器区分**加载期与惰性可达**：只有加载期静态闭包上解析不了的依赖才会阻断一个包——函数体内的动态 import、仅经动态 import 可达的文件、worker/数据资源都是惰性路径，与 Pi 下行为完全一致，只标记为可审阅、绝不判死。`bun:*` 与 `node:*` 同等对待（Pi 官方发行版是 Bun 编译二进制的宿主内建），快照逐字节保留发布文件布局。这些规则有契约测试钉着；在这套规则下，混用 Bun 分支、可选重依赖、打包器生成 worker 路径的包——`pi-hermes-memory`、`@mjasnikovs/pi-task`、`pi-harness-runtime`、`mitsupi`、`pi-lens`——全部按发布原样挂载可用，上游无需任何改动。
 
 ### 路线图
 
-1. 把 9 个"能接入、未全测"提升为"已测可用"（带凭证的 fixture、按包定制探针参数、给 userQuestions 补 live agent 探针链路）。
+1. ✅ 已完成：9 个"能接入、未全测"提级——8 个达到已测可用（带凭证的 fixture、真 MCP stdio server、userQuestions 的 live agent 探针链路、Pi config-dir 配置、真子 `pi` 派发，外加桥内两处注册表语义修正：provider 按 `id` 入表、`getProviderAuth` 跑 Pi 完整凭证链而非仅 OAuth）；剩下 1 个是纯事件钩子包，如实定档为无可探测面。
 2. ✅ 已完成：交互式 OAuth host seam——Pi provider 的 `oauth.login/refreshToken/getApiKey` 流跑在 DSH 原生交互上，凭证按 Pi `auth.json` 语义持久化并带双检锁刷新，四条官方流内建；已用真实 ChatGPT Pro 账号端到端验证（见上文"交互式 OAuth"）。
 3. ✅ 已完成：4 个 Pi 内部运行时包全部桥接（见上）——前 50 全部可挂载。
 4. ✅ 已完成：2 个快照受限包经 host 模式实测通过（[证据](community/host-mode-results.json)）。
-5. ✅ 已完成：复查曾被错误报告为"有缺陷"的 5 个包，修正筛查器与本页（见上）。
+5. ✅ 已完成：加载期/惰性可达筛查规则落地；由此解锁的 5 个包全部可挂载、4 个已测可用（见上）。
 
 ## 快速开始
 
@@ -127,17 +129,20 @@ DSH 原生只有静态 HTTP headers；pi2dsh 把 Pi 生态的交互式 OAuth 层
 | 会话 | 消息从 DSH durable 日志投影；Pi 自定义 entry/label/name 持久化在 pi2dsh sidecar（DSH 目前没有第三方插件事件通道） |
 | Pi TUI | 纯逻辑 vendored 字节一致；组件类同签名 headless 构造；`ui.custom` 与 Pi 官方 rpc 模式一样返回 undefined |
 | Provider/OAuth | 交互式 OAuth 已可用：`/login <provider>` 跑包自己的流程，凭证按 Pi `auth.json` 持久化并自动刷新；模型传输仍由 DSH `llm` 原生持有 |
+| 模型运行时 | `modelRegistry` 把 DSH llm 实时目录投影为 Pi Model 对象（`llm/adapters-updated` 时刷新）；`ctx.model` 反映 agent 真实路由；`setModel`/`setThinkingLevel` 经 `agent/request` waterfall 真切换 loop；pi-ai `complete()`/`stream()` 经 `ctx.llm.stream()` 发起**真实**模型调用并双向转换消息（已对真实模型验证：`scripts/verify-model-bridge-e2e.mjs`） |
 | 会话树写操作 | `fork`/`navigateTree`/`switchSession` 显式失败（DSH 官方将 pi 式 entry tree 列为 deferred） |
 | 终端装饰 | footer/statusline/快捷键注册成功但永不触发——与 Pi 自己的非 TUI 模式一致 |
 
-完整机器可读矩阵：`pi2dsh matrix --json`。十项能力逐项验收证据：[docs/acceptance.md](docs/acceptance.md)。
+完整机器可读矩阵：`pi2dsh matrix --json`。十项能力逐项验收证据：[docs/acceptance.md](docs/acceptance.md)。114 项 Pi 暴露面 → DSH 语义完整判决（红 3 / 黄 21 / 绿约 90）：[docs/pi-abi-coverage.md](docs/pi-abi-coverage.md)。
 
 ## 开发与验证
 
 ```sh
-pnpm verify                                   # 类型检查 + 49 契约测试 + 打包检查
+pnpm verify                                   # 类型检查 + 55 契约测试 + 打包检查
 pnpm audit:community                          # 前 50 静态筛查
 node scripts/blackbox-community.mjs community/blackbox-results.json --exercise
+#   前缀 DEEPSEEK_API_KEY=… PI2DSH_BLACKBOX_PI_BIN=$(command -v pi) 可开启
+#   带凭证探测与真子 pi 派发（key 仅从环境读）
 pnpm test:community                           # 深链路 + 官方插件管理器 + host e2e
 DEEPSEEK_API_KEY=… pnpm test:live             # 真实模型验收（key 仅从环境读）
 ```