Skip to content
Back to search

pi2dsh

Bridge the Pi and DeepSeek Harness ecosystems: one Pi Host ABI runs unmodified Pi extensions as native DSH plugins. 打通 Pi 与 DSH 生态。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/weijiafu14--pi2dsh/badge.svg)](/listings/weijiafu14--pi2dsh)

HTML

<a href="/listings/weijiafu14--pi2dsh"><img src="/api/listings/weijiafu14--pi2dsh/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

One engine, then whatever plugins you want:

dsh plugin --profile web add pi2dsh
dsh plugin --profile web add pi-mcp-adapter

Then **restart `dsh`** — plugins mount at startup.

> **A profile needs a surface bundle.** DSH's built-in templates are `web` and > `headless`. A custom profile is valid when its product installs a surface — > for example `@deepseek-harness-tui/dsh-tui` in the `dsh-tui` profile. A bare > arbitrary profile has no surface and can start with nothing to drive it, so > add the intended surface to `dsh.profile.bundles` first.

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 instance: one model directory, one login, one credential store, one upgrade unit.

Day-to-day:

| Task | Command | |---|---| | Add a plugin | `dsh plugin add <pkg>` (then restart dsh) | | Remove a plugin | `dsh plugin remove <pkg>` — remove plugins before removing the engine | | Upgrade a plugin | `dsh plugin add <pkg>@latest` — the engine is untouched | | Upgrade the engine | `dsh plugin add pi2dsh@latest` — your plugins are untouched | | Check a plugin before upgrading | `npx pi2dsh inspect <pkg>@<version>` |

Two installer messages worth knowing:

- **`ERR_PNPM_IGNORED_BUILDS`** — pnpm blocks dependency build scripts by default. Run `pnpm approve-builds` inside `$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 — pnpm's `minimumReleaseAge` skips versions published very recently. Pin it: `dsh plugin add pi2dsh@<version>`.

Requires Node.js 22.19+ and DeepSeek Harness.

Engine configuration

The engine reads one `config` block from its plugin row. Today it takes a single opt-in:

# $DSH_HOME/profiles/<profile>/cordis.patch.yml
- id: pi2dsh
  config:
    serveNativeSubagents: true

`serveNativeSubagents` (default: **off**) serves DSH-native subagents with the profile's Pi packages. With it on, a child agent DSH spawns through its own subagent delegation (one whose session carries the subagent origin) receives every discovered Pi package mounted on its own agent scope — the package's tools, commands and prompt sections appear for that child only, and every contribution unwinds when the child ends. With it off, such children run as plain DSH agents, exactly as before.

The mount is guaranteed for the child's **first** turn: prompt assembly and tool execution wait for it, so even a child that runs a single turn sees the full tool set. Each child is served exactly once, whichever path DSH created it through — children the agent registry reports as runtime roots are served by the engine's root mount path, and the subagent path serves the rest; the two never overlap. Pi subagent-bridge children are unaffected either way: they already receive the creator package's own per-spawn loader mount, and the bridge recognizes them by the `pi2dsh-sub-` session-id prefix (stable across a persisted resume), so no child is ever mounted twice.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 531 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # pi2dsh
  2. **English** | [中文](README.zh.md)
  3. **Move a Pi setup to DeepSeek Harness without rebuilding it.** The
  4. extensions, MCP manager, subagents, memory and background tasks you use on Pi
  5. install on DSH as the same npm packages and run unmodified — web, terminal
  6. and headless.
  7. ```sh
  8. dsh plugin add pi2dsh@next # DSH 0.2.2-alpha.3; once
  9. dsh plugin add pi-mcp-adapter # then the Pi packages you already use, straight from npm
  10. ```
  11. MCP is the deepest-verified path: the full protocol surface — OAuth,
  12. resources, prompts, MCP Apps, elicitation, sampling, cancellation — runs
  13. through DSH's own approval and rendering
  14. ([evidence matrix](docs/mcp-compatibility.md)). What has been verified end to
  15. end is listed in [What actually works today](#what-actually-works-today);
  16. nothing outside that table is claimed.
  17. Version support is explicit:
  18. | pi2dsh | DSH host | Maintenance |
  19. |---|---|---|
  20. | 0.28.0-next.1 (`next`) | 0.2.2-alpha.3 | Pi 1.4 preview: [acceptance and limits](community/release-0.28.0-next.1/README.md) |
  21. | 0.27.1 | 0.2.1-rc.2 / 0.2.1-rc.3 | [Acceptance and release status](community/release-0.27.1/README.md) |
  22. | 0.27.0 | 0.2.1-rc.2 | [Acceptance and release status](community/release-0.27.0/README.md) |
  23. | 0.26.0 | 0.2.0-rc.2 | [Release verification](community/release-0.26.0/README.md) |
  24. | 0.25.2 | 0.1.5-rc.2 | Frozen checkpoint: [release evidence](community/release-0.25.2/README.md) |
  25. Published 0.27.x uses Pi 0.84.1; the 0.28 candidate targets Pi 1.4.0 with explicitly
  26. documented capability limits. New engine releases target the
  27. validated current DSH line; historical fixes start from their release tag when
  28. needed. DSH owns stored-session format migration. An untested host version is
  29. not included in the compatibility declaration.
  30. For the **0.27.x / DSH 0.2.1** line, the validated terminal packages are
  31. `@deepseek-harness-tui/dsh-tui@0.17.0` and `@xmoon76/dsh-pi-tui@0.5.3`.
  32. The older dsh-pi-tui 0.5.1 still references removed host components; upgrade
  33. that terminal rather than bypassing compatibility checks with `allow-version`.
  34. For DSH 0.2.2-alpha.3, use `pi2dsh@next` (or Web suite `dsh-work-x@next`)
  35. with Node.js 24.9+. The published third-party terminals checked in this preview
  36. do not declare support for this host; Web and headless are independently tested.
  37. Stay on `pi2dsh@0.27.1` / `dsh-work-x@0.6.1` for DSH 0.2.1-rc.2 or rc.3.
  38. ## Why this exists
  39. [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) is built
  40. on ideas worth betting on — a durable, reconstructable session log, a clean
  41. service composition, an agent loop you can actually reason about. Its plugin
  42. ecosystem is young. [Pi](https://pi.dev/) has a mature one: hundreds of
  43. published packages, many with real users.
  44. pi2dsh is one compatibility layer that implements Pi's public extension ABI on
  45. top of DSH's native services, so a Pi package runs on DSH **as published** —
  46. no fork, no patch, no per-package adapter. For a Pi user or team that means
  47. switching hosts without rebuilding the toolchain; for a Pi plugin author it
  48. means a second host with no port to maintain. To the user everything looks
  49. like DSH; to the plugin everything looks like Pi.
  50. At the same time, pi2dsh is an ongoing, full-surface, real-world test of DSH's
  51. architecture. Instead of patching individual plugins, it asks whether the
  52. models, tools, sessions, interaction, resources and client capabilities that Pi
  53. plugins rely on can preserve their logic and lifecycle using only DSH's public
  54. services and extension seams. If they can, that is strong evidence that DSH's
  55. architectural goals for building agents and an agent-plugin ecosystem have been
  56. achieved, at least along this dimension. Wherever the bridge must bypass,
  57. degrade or cannot express a capability, it pinpoints an architectural gap that
  58. remains.
  59. ## Install
  60. One engine, then whatever plugins you want:
  61. ```sh
  62. dsh plugin --profile web add pi2dsh@next
  63. dsh plugin --profile web add pi-mcp-adapter
  64. ```
  65. Then **restart `dsh`** — plugins mount at startup.
  66. > **A profile needs a surface bundle.** DSH's built-in templates are `web` and
  67. > `headless`. A custom profile is valid when its product installs a surface —
  68. > for example `@deepseek-harness-tui/dsh-tui` in the `dsh-tui` profile. A bare
  69. > arbitrary profile has no surface and can start with nothing to drive it, so
  70. > add the intended surface to `dsh.profile.bundles` first.
  71. That is the whole model. There is no conversion step, no generated bundle, no
  72. build. The engine discovers the Pi packages in your profile (every one is
  73. something you explicitly added) and mounts them through a single bridge
  74. instance: one model directory, one login, one credential store, one upgrade
  75. unit.
  76. Day-to-day:
  77. | Task | Command |
  78. |---|---|
  79. | Add a plugin | `dsh plugin add <pkg>` (then restart dsh) |
  80. | Remove a plugin | `dsh plugin remove <pkg>` — remove plugins before removing the engine |
  81. | Upgrade a plugin | `dsh plugin add <pkg>@latest` — the engine is untouched |
  82. | Upgrade the preview engine | `dsh plugin add pi2dsh@next` — your plugins are untouched; `latest` remains the older host line |
  83. | Check a plugin before upgrading | `npx pi2dsh inspect <pkg>@<version>` |
  84. Two installer messages worth knowing:
  85. - **`ERR_PNPM_IGNORED_BUILDS`** — pnpm blocks dependency build scripts by
  86. default. Run `pnpm approve-builds` inside
  87. `$DSH_HOME/profiles/web`, or set the listed packages to `true`
  88. under `allowBuilds` in that profile's `pnpm-workspace.yaml`. Then re-run the
  89. add. (This is your call to make, so the bridge does not work around it.)
  90. - **An add silently installs an older version** right after a release —
  91. pnpm's `minimumReleaseAge` skips versions published very recently. Pin it:
  92. `dsh plugin add pi2dsh@<version>`.
  93. This development line requires Node.js 24.9+ and DSH 0.2.2-alpha.3.
  94. The published 0.27.x line retains its Node.js 22.19+ / DSH 0.2.1 requirements.
  95. ### Engine configuration
  96. The engine reads one `config` block from its plugin row. Today it takes a
  97. single opt-in:
  98. ```yaml
  99. # $DSH_HOME/profiles/<profile>/cordis.patch.yml
  100. - id: pi2dsh
  101. config:
  102. serveNativeSubagents: true
  103. ```
  104. `serveNativeSubagents` (default: **off**) serves DSH-native subagents with
  105. the profile's Pi packages. With it on, a child agent DSH spawns through its
  106. own subagent delegation (one whose session carries the subagent origin)
  107. receives every discovered Pi package mounted on its own agent scope — the
  108. package's tools, commands and prompt sections appear for that child only,
  109. and every contribution unwinds when the child ends. With it off, such
  110. children run as plain DSH agents, exactly as before.
  111. The mount is guaranteed for the child's **first** turn: prompt assembly and
  112. tool execution wait for it, so even a child that runs a single turn sees the
  113. full tool set. Each child is served exactly once, whichever path DSH created
  114. it through — children the agent registry reports as runtime roots are served
  115. by the engine's root mount path, and the subagent path serves the rest; the
  116. two never overlap. Pi subagent-bridge children are unaffected either way:
  117. they already receive the creator package's own per-spawn loader mount, and
  118. the bridge recognizes them by the `pi2dsh-sub-` session-id prefix (stable
  119. across a persisted resume), so no child is ever mounted twice.
  120. ## Walkthrough: advanced MCP in your terminal
  121. The clearest example of what the bridge buys you. dsh-TUI ships a native
  122. `/mcp` command for DSH's official MCP client — it works, and it stays
  123. untouched. The Pi ecosystem has a much richer MCP power tool: a full-screen
  124. server manager, lazy tool discovery, one proxy tool instead of flooding the
  125. model context with dozens of tools, JavaScript orchestration of multiple MCP
  126. calls, OAuth logins, resources and prompts. With the bridge, that package runs
  127. unmodified.
  128. ### 1. Install
  129. ```sh
  130. dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui # skip if the profile exists
  131. dsh plugin --profile dsh-tui add pi2dsh
  132. dsh plugin --profile dsh-tui add pi-mcp-adapter
  133. ```
  134. The alternative [`dsh-pi-tui` example](examples/pi-tui-ecosystem/) is a
  135. historical DSH 0.2.0-rc.2 / pi2dsh 0.26.0 checkpoint, not an alternative
  136. installation for the current 0.2.1 host. Its upstream terminal needs an update.
  137. Then restart `dsh` — plugins mount at startup.
  138. ### 2. Configure your MCP servers
  139. Inside dsh-TUI, run:
  140. ```text
  141. /pi-mcp setup
  142. ```
  143. The setup flow can adopt MCP server definitions from host configs you already
  144. have into the adapter's own standard `mcp.json`. No bridge-specific
  145. configuration exists — everything you touch is the package's own surface.
  146. ### 3. Use it
  147. ```text
  148. /pi-mcp
  149. ```
  150. opens the full-screen interactive server manager — its footer documents the
  151. keys for enable/disable, reconnect and OAuth login. The model receives the
  152. adapter's `mcp` and `mcpScript` tools through DSH's normal tool registry, and
  153. each agent (`/new` included) gets its own fully connected instance.
  154. dsh-TUI's native command remains separate, and both stay available:
  155. ```text
  156. /mcp # native DSH MCP-client status
  157. /pi-mcp # the installed Pi adapter's manager
  158. ```
  159. What is verified behind this walkthrough: 16 host-influenced capabilities
  160. end to end on the stock npm stack — three real transports, discovery, proxy
  161. and hot-loaded direct tools, `mcpScript`, resources, prompts, images becoming
  162. real DSH attachments, MCP Apps, tool approval through DSH questions,
  163. elicitation, sampling against the real DSH model runtime, cancellation and
  164. session restart. The full evidence matrix:
  165. [`docs/mcp-compatibility.md`](docs/mcp-compatibility.md).
  166. Full runnable version: [`examples/tui-mcp`](examples/tui-mcp/).
  167. ## What actually works today
  168. Two levels, and they are not the same claim.
  169. ### Level 1 — verified end to end, with a runnable example
  170. Someone sat down, used the plugin's real feature on a real DSH loop, and saw
  171. it work. **This is the list to trust.**
  172. | Plugin | What was exercised | Where | Example |
  173. |---|---|---|---|
  174. | [`@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/) |
  175. | [`@crazygit/pi-codex-image-gen`](https://www.npmjs.com/package/@crazygit/pi-codex-image-gen) | ChatGPT/Codex OAuth → `gpt-image-2` generation; local reference-image upload through DSH approval; image edit; native attachment storage and inline Web rendering | CLI + web | [`codex-image-gen`](examples/codex-image-gen/) |
  176. | [`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/) |
  177. | [`pi-powerline-footer`](https://www.npmjs.com/package/pi-powerline-footer) | A terminal status line — model, thinking level, project, context usage — drawn as a floating status pill in DSH web, colour included | web | [`presentation-surfaces`](examples/presentation-surfaces/) |
  178. | [`pi-mcp-adapter`](https://www.npmjs.com/package/pi-mcp-adapter) | Original full-screen manager; stdio/Streamable HTTP/SSE; discovery, direct/proxy/scripted calls, resources, prompts, images, structured content, MCP Apps, approval, elicitation, sampling, cancellation and restart through DSH runtimes | CLI + web + dsh-TUI | [`tui-mcp`](examples/tui-mcp/) · [`mcp-at-scale`](examples/mcp-at-scale/) · [`pi-tui-ecosystem`](examples/pi-tui-ecosystem/) · [evidence matrix](docs/mcp-compatibility.md) |
  179. | [`@tintinweb/pi-subagents`](https://www.npmjs.com/package/@tintinweb/pi-subagents) | The model delegates to autonomous subagents: spawn (with real host-native tools), background + completion notify, mid-run steer, wait-for-result, resume with memory, stop that stays stopped, interactive manager, and cross-restart reopen by archive identity — every child a native DSH session | CLI + dsh-TUI | [`subagents`](examples/subagents/) · [`pi-tui-ecosystem`](examples/pi-tui-ecosystem/) · [acceptance report](community/subagents-acceptance-report.md) |
  180. | [`pi-provider-alibaba`](https://www.npmjs.com/package/pi-provider-alibaba) | Alibaba Token Plan (CN) with its plan-specific key: live catalog, cold-start dynamic model, complete tool loop and restart. The package also declares Coding/API routes, but each requires its own non-interchangeable credential | CLI + web | [`alibaba-token-plan`](examples/alibaba-token-plan/) |
  181. | [`@ff-labs/pi-fff`](https://www.npmjs.com/package/@ff-labs/pi-fff) + [`pi-lens`](https://www.npmjs.com/package/pi-lens) | Code navigation for the model: `ffgrep` content search finds a marker that exists in exactly one file, and `lsp_diagnostics` reports a planted TS2322 through a real local `typescript-language-server` — both asserted from the tools’ own results in the session log | CLI + web | [`code-navigation`](examples/code-navigation/) |
  182. | [`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 | — |
  183. | [`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) | — |
  184. | [`pi-code`](https://www.npmjs.com/package/pi-code) | A repository's Claude Code configuration on DSH, unmodified: `settings.json` `env` and `PreToolUse` hooks, `CLAUDE.md` `@import` (text lands in the request's system prompt, not read by the model), `.claude/skills`, `.claude/rules` (always-on and `paths:`-scoped), output styles, `.mcp.json` servers through pi-code's own MCP client, `.claude/commands` as `/name` and via the `slash_command` tool; the first session answers "Trust this project?" in DSH's native question card. `Task` subagents from `.claude/agents` do not work (pi-code spawns the Pi CLI) | CLI + Web | [`claude-code-config`](examples/claude-code-config/) |
  185. | [`pi-hermes-memory`](https://www.npmjs.com/package/pi-hermes-memory) | Cross-session memory end to end: `memory_add` in one session, recalled in a second, fresh one (the codeword existed nowhere else); five tools, ten `/memory-*` commands, system-prompt memory injection | CLI | [`persistent-memory`](examples/persistent-memory/) |
  186. | [`pi-background-tasks`](https://www.npmjs.com/package/pi-background-tasks) | Background shell job started with `bg_run`, output read **mid-run** with `bg_logs`: the log result carries early ticks of a still-running 60-second job, with the final tick provably absent | CLI | [`background-tasks`](examples/background-tasks/) |
  187. Examples for the two remaining rows are still to be written; per this
  188. project's own rule they get re-verified from scratch before an example lands,
  189. so the table says plainly which have one today.
  190. ### Level 2 — mounts and its surface answers a probe
  191. The Pi catalog's **top 50 packages by monthly downloads**, each mounted in a
  192. real DSH runtime and then called through a black-box probe. Status as of
  193. 2026-08-14; per-package machine-readable evidence in
  194. [`community/`](community/).
  195. **47 of 50 exercised successfully · 1 with no probeable surface · 2 pending a
  196. re-run.**
  197. **What this level does not tell you:** that the plugin's actual feature works
  198. the way you would use it. A probe calls a registered surface with synthetic
  199. arguments; a user runs a workflow. `pi-btw` is the cautionary example — it
  200. graded "working" here for weeks while `/btw <question>` failed on a real
  201. session, because the feature needed two ABI gaps closed (Pi's settable
  202. `AgentState.messages`, and an input descriptor on bridged commands) that no
  203. probe exercised. Both are fixed in 0.11.0, and both were general fixes that
  204. unlock every plugin doing the same thing.
  205. So read the table below as **"the bridge covers what this plugin touches"**,
  206. not as "this plugin is known-good". When you try one, a report either way is
  207. useful.
  208. | Area | Packages |
  209. |---|---|
  210. | **MCP** | `pi-mcp-adapter` · `pi-mcp-extension` |
  211. | **Web search & fetch** | `pi-web-access` · `pi-deepseek-search` · `pi-web-search` · `@ollama/pi-web-search` · `@juicesharp/rpiv-web-tools` |
  212. | **Code navigation & editing** | `pi-lens` (ast-grep) · `@narumitw/pi-lsp` · `pi-readseek` · `@ff-labs/pi-fff` · `pi-landstrip` · `pi-hashline-edit-pro`¹ |
  213. | **Subagents & background work** | `@gotgenes/pi-subagents` · `@mjasnikovs/pi-task` |
  214. | **Memory** | `pi-hermes-memory` · `pi-goosedump` |
  215. | **Planning & goals** | `@narumitw/pi-goal` · `pi-goal-list-loop-audit` · `@narumitw/pi-plan-mode` · `@juicesharp/rpiv-todo` |
  216. | **Asking you / approvals** | `@juicesharp/rpiv-ask-user-question` · `pi-ask-user` · `@gotgenes/pi-permission-system` · `@juicesharp/rpiv-advisor` |
  217. | **Side conversations** | `pi-btw` · `@narumitw/pi-btw` |
  218. | **Models & providers** | `pi-provider-litellm` · `pi-llama-cpp` · `pi-prompt-template-model` · `@vigolium/piolium` |
  219. | **Images** | `@kassing/pi-vision` (see above) · `@amaster.ai/pi-image-gen` |
  220. | **External integrations** | `@llblab/pi-telegram` · `pi-cursor-sdk`² · `@howaboua/pi-codex-conversion` · `pi-agent-browser-native`² · `pi-harness-runtime` |
  221. | **Prompting & workflow** | `pi-simplify` · `pi-fabric`² · `mitsupi` · `pi-cc-extensions` · `pi-rtk-optimizer` · `pi-interview`¹ |
  222. | **Terminal decoration** | `pi-powerline-footer` · `@narumitw/pi-statusline` · `pi-zentui` |
  223. | **Voice** | `@juicesharp/rpiv-voice` |
  224. | **Usage reporting** | `@alexanderfortin/pi-deepseek-usage`³ |
  225. ¹ Mounts; the exercise run is pending a re-run (a harness-side failure, not a
  226. package or bridge gap). ² Ran its own business logic end to end and rejected
  227. the synthetic probe arguments — working, correctly validating.
  228. ³ A pure event-hook package: all subscriptions attach, but every handler is
  229. gated on a live DeepSeek billing session, so a black-box probe has nothing
  230. safely callable to assert.
  231. Packages outside the top 50 are not a separate case — the bridge has no
  232. per-package code. If one hits an ABI gap, fixing that gap unlocks every
  233. package that shares it.
  234. Level 1 grows by working through Level 2 one plugin at a time. The full
  235. verification ladder, with what each rung does and does not prove:
  236. [support matrix](docs/posting-kit/support-matrix.md).
  237. ## How it works
  238. Three layers, and nothing crosses them:
  239. ```
  240. ┌─ Pi plugin ─────────────────────────────────────────────────┐
  241. │ unmodified npm package. It sees a complete Pi host: the │
  242. │ three Pi runtime imports, registerX, ctx.*, 33 lifecycle │
  243. │ events. It never learns DSH exists. │
  244. └──────────────────────────┬──────────────────────────────────┘
  245. │ Pi's public ABI
  246. ┌──────────────────────────▼──────────────────────────────────┐
  247. │ pi2dsh — the translator, and the only place that knows both │
  248. │ vocabularies. Registry projection, event bridge, session & │
  249. │ subagent bridge, credentials, vendored Pi logic. │
  250. └──────────────────────────┬──────────────────────────────────┘
  251. │ ordinary DSH plugin + llm adapter
  252. ┌──────────────────────────▼──────────────────────────────────┐
  253. │ DeepSeek Harness. Sees a normal plugin. Never learns Pi │
  254. │ exists. │
  255. └─────────────────────────────────────────────────────────────┘
  256. ```
  257. DSH is two halves, and so is the bridge. The column above is the server; the
  258. browser shell has its own plugin surface, and a Pi capability that is a SHAPE
  259. rather than a behaviour lands there:
  260. ```
  261. ┌──────────── DSH server (cordis) ────────────┐ ┌──────── DSH browser shell ────────┐
  262. │ services · waterfalls · durable events │ │ dsh.client + exports "./client" │
  263. │ │ │ slot registry (ui-slots) │
  264. │ pi2dsh engine │ │ shell.overlay ← panel, pills │
  265. │ tools · commands · models · sessions │ │ session.header.utilities ← hdr │
  266. │ subagent bridge ─────────────┐ │ │ overlay ← widget pills/cards │
  267. │ browser-state registry │ │ │ composer.dock ← working/footer │
  268. │ GET /pi2dsh/browser-state ─┼── own route┼──┼─▶ all four seats, one poller │
  269. └────────────────────────────────┴────────────┘ └───────────────────────────────────┘
  270. ```
  271. The browser half's data rides **this package's own route**, not DSH's typed
  272. Remote system: that one is a first-party, code-generated contract, and an
  273. out-of-tree plugin talking to its own UI should carry its own channel. One
  274. payload per session serves every seat — the side-conversation panel, plus the
  275. Pi presentation surfaces (status, widget, header, footer, title and the
  276. working/thinking chrome), which are drawn in the host's own slot seats rather
  277. than re-implemented. Two host rules make the browser half load at all — the
  278. package must export `./package.json` (the host resolves the manifest by
  279. subpath), and the `./client` bundle is a closure-factory artifact, not plain
  280. ESM.
  281. The rules that keep it honest:
  282. - **Never a second bridge-owned implementation of something DSH already has.**
  283. Tools go to DSH's tool registry, models to DSH's llm configuration,
  284. configuration-only MCP servers to `dsh-mcp-client`, skills to
  285. `dsh-skill-filesystem`, and questions to DSH's user questions. An explicitly
  286. installed Pi capability package can retain behavior that it owns; the bridge
  287. maps its public surfaces and does not copy its transport.
  288. - **No bridge-private user world.** Normal configuration remains DSH-shaped:
  289. DSH settings, commands and credentials. When an installed capability package
  290. deliberately exposes its own manager, that surface remains recognizable and
  291. is namespaced on conflict — dsh-TUI keeps `/mcp`, while the Pi manager is
  292. `/pi-mcp`.
  293. - **No per-package special cases.** The core contains no
  294. `if (packageName === …)`. One ABI gap fixed unlocks every package that hits
  295. it.
  296. - **Never fake success.** A capability with no safe mapping is reported —
  297. once, per plugin, in plain language — instead of silently returning
  298. something invented. If a plugin needs one during startup, it is marked
  299. unusable with a removal hint rather than half-working.
  300. - **Verified, not asserted.** Every capability has a public-API contract test,
  301. and ships only after running end to end on every DSH surface it claims.
  302. ## What this is teaching us about DSH
  303. pi2dsh is also an executable stress test of DSH's plugin architecture. Pi gives
  304. that test a useful workload: a large, already-used public plugin ABI rather than
  305. a set of examples invented to fit the host.
  306. The result so far is specific, not a thumbs-up/thumbs-down verdict:
  307. - DSH's public seams successfully carry whole capabilities: tools, commands,
  308. model adapters, user questions, native child sessions and browser slots.
  309. - The pressure points appear when an out-of-repo plugin needs to extend an
  310. existing capability *from the inside*: add a durable session-event type,
  311. intercept the real provider request/response, control compaction before it
  312. happens, or participate in trust before project resources load.
  313. - A working pi2dsh sidecar or alternate adapter is useful product behaviour,
  314. but it is **not** counted as proof that the native DSH seam is complete.
  315. For example, a `pi-btw` answer is a real DSH child session — visible, resumable
  316. and continuable by the host. Pi custom entries are different: they still need a
  317. pi2dsh sidecar because an out-of-repo plugin cannot safely add a new event type
  318. to DSH's durable log. Likewise, a transport-owning Pi provider can register a
  319. native DSH route. Since DSH rc.8, a catalog-only provider also has a faithful
  320. official path: pi2dsh translates its endpoint, modalities, reasoning levels and
  321. the protocol-specific compat fields DSH offers into an `llm-pi-ai` profile, and
  322. DSH owns the request.
  323. The project follows one **[Pi → DSH architecture mapping standard](docs/architecture-mapping-standard.md)**.
  324. It is a reasoning method, not another runtime layer: concrete Pi interface →
  325. Pi capability contract → DSH carrying mechanism → public seam → real plugin
  326. run → five-grade result. The evolving branches live in the handwritten
  327. **[architecture model](docs/architecture-mapping-matrix.md)**, real runs in
  328. **[per-plugin validation records](docs/plugin-validation-matrix.md)**, and the
  329. three result classes in **[architecture conclusions](docs/dsh-architecture-conformance.md)**.
  330. Architecture classifications are deliberately not generated from a JSON ledger.
  331. The previously observed 111 Pi rule rows and 45 DSH subsystems are versioned
  332. snapshots, not fixed totals or proof of completeness. Four DSH gap IDs remain
  333. active; a fifth historical finding (`DSH-ARCH-002`) was fixed upstream in rc.8.
  334. These are confirmed findings, not a claim of complete coverage. Current
  335. upstream reports include
  336. [#2708 — durable events for out-of-repo plugins](https://github.com/deepseek-ai/deepseek-harness/discussions/2708)
  337. and
  338. [#3076 — provider compat fields dropped by `llm-pi-ai`](https://github.com/deepseek-ai/deepseek-harness/discussions/3076),
  339. now resolved by the rc.8 profile schema.
  340. ## Pi capabilities on DSH
  341. Tracked Pi extension surfaces, their DSH mappings and current limits. These tables are
  342. generated from the rules the bridge consults at runtime, so they cannot drift
  343. from the code.
  344. The generated catalog tracks the versioned runtime surfaces, not a claim of
  345. complete Pi support. The bridge also keeps one
  346. documented compatibility extension, `unregisterTool`; it appears on the tools
  347. detail page but is deliberately outside that total. Nested objects such as the
  348. session manager can expose several methods behind one row; the architecture
  349. audit states this boundary explicitly.
  350. <!-- capability-table:start -->
  351. | Area | Pi surfaces | Status |
  352. |---|---|---|
  353. | [Tools](docs/capabilities/tools.md) | 13 | 2 same semantics · 11 mapped, difference stated |
  354. | [Commands, flags, editor input](docs/capabilities/commands.md) | 13 | 13 mapped, difference stated |
  355. | [Messages, context, agent loop](docs/capabilities/conversation.md) | 23 | 8 same semantics · 13 mapped, difference stated · 2 not available |
  356. | [Sessions & side conversations](docs/capabilities/sessions.md) | 25 | 6 same semantics · 18 mapped, difference stated · 1 not available |
  357. | [Models, providers, credentials](docs/capabilities/models.md) | 19 | 2 same semantics · 13 mapped, difference stated · 4 not available |
  358. | [Asking the user, rendering](docs/capabilities/interaction.md) | 27 | 7 same semantics · 20 mapped, difference stated |
  359. | [Project environment & resources](docs/capabilities/environment.md) | 9 | 4 same semantics · 4 mapped, difference stated · 1 not available |
  360. | **Total** | **129** | **29 same semantics · 92 mapped, difference stated · 8 not available** |
  361. <!-- capability-table:end -->
  362. Plus **203 imported symbols** from Pi's three runtime packages
  363. (`pi-coding-agent`, `pi-tui`, `pi-ai`), served from vendored or headless
  364. shims — so a plugin's own Pi version pins never load. They are listed in
  365. [Imported Pi runtime symbols](docs/capabilities/imports.md).
  366. Each area page states the Pi capability contract, the theoretical DSH mechanism
  367. and public seam, and the current implementation for every surface. Adding a
  368. surface without a capability assignment or theoretical mapping fails the docs
  369. check.
  370. Start at the [capability index](docs/capabilities/README.md). Machine-readable:
  371. `pi2dsh matrix --json`.
  372. **Signing in with a subscription** works too: DSH ships static HTTP headers
  373. only, and the bridge adds the Pi ecosystem's interactive OAuth layer. Any Pi
  374. provider package that declares an `oauth` block gets a working
  375. `/login <provider>`, driven by the package's own protocol code — Pi's four
  376. official flows (OpenAI Codex, Anthropic, GitHub Copilot, Kimi Code) ship built
  377. in and are available immediately after installing the engine, even before the
  378. first community Pi package. Credentials persist with Pi's `auth.json` semantics and resolve per
  379. request through a standard `dsh-credentials` provider, so your subscription
  380. drives real calls on DSH's native llm path. Details in
  381. [models](docs/capabilities/models.md).
  382. **What is deliberately not available**, and why: runtime package installation
  383. and standalone model runtimes stay with the host and its security gates;
  384. provider payload/header/response interception belongs in a DSH llm adapter;
  385. project trust is a host decision. See
  386. [models](docs/capabilities/models.md) and
  387. [environment](docs/capabilities/environment.md).
  388. **The one gap we own:** plugin-drawn cards. Pi plugins can ship their own
  389. renderers; today those registrations are accepted but not invoked, so such a
  390. note appears as a native context-injection row — the content reaches you and
  391. the model, without the plugin's styling. The client half exists and takes four
  392. seats (side-conversation panel, header, floating widgets, working chrome) — the card
  393. renderers are what it does not draw yet.
  394. ## Examples
  395. Every verified capability ships as a complete, runnable example. Every command
  396. in one has actually been executed against a real DSH loop before landing.
  397. | Example | What you get |
  398. |---|---|
  399. | [`vision-bridge`](examples/vision-bridge/) | A text-only model answers questions about images — CLI and web, probe images included |
  400. | [`codex-image-gen`](examples/codex-image-gen/) | Generate and edit images with a ChatGPT/Codex subscription; DSH approval and inline result included |
  401. | [`side-conversation`](examples/side-conversation/) | `/btw <question>` runs a side thread in DSH's native subagent UI; your main conversation stays clean |
  402. | [`presentation-surfaces`](examples/presentation-surfaces/) | A real plugin's terminal chrome (`pi-powerline-footer`) in DSH's web seats, plus which of the top-50 Pi plugins draw at all |
  403. | [`subscription-login`](examples/subscription-login/) | Use a ChatGPT / Claude / Copilot / Kimi subscription as a DSH model: `/login`, then the route and credential appear on their own |
  404. | [`gateway-compat`](examples/gateway-compat/) | Private / domestic / proxy gateways that reject the `developer` role: how rc.8's official profile carries Pi compat declarations to the wire (passthrough recorder included) |
  405. | [`alibaba-token-plan`](examples/alibaba-token-plan/) | Use Alibaba Cloud Model Studio Plan routes through the original Pi provider; dynamic DeepSeek model, tool loop and restart included |
  406. | [`custom-gateways`](examples/custom-gateways/) | Add any OpenAI-compatible gateway the official DSH way, and every Pi plugin sees it |
  407. | [`code-navigation`](examples/code-navigation/) | Give the model real code-navigation tools — fuzzy content search and language-server diagnostics on a bundled sample project, CLI and web |
  408. | [`tui-mcp`](examples/tui-mcp/) | Keep dsh-TUI's native `/mcp`, add the Pi ecosystem manager as `/pi-mcp`, and exercise its complete host-influenced MCP surface through DSH runtimes |
  409. | [`mcp-at-scale`](examples/mcp-at-scale/) | A real 51-tool MCP server behind the adapter's two meta-tools: bounded tool surface, lazy discovery at scale, and a timeout budget that cuts a ~120 s tool to seconds — CLI and web |
  410. | [`claude-code-config`](examples/claude-code-config/) | pi-code reading a project's `.claude/` on DSH: trust question, settings env, PreToolUse hook, CLAUDE.md @import, skills — headless and web, both DSH lines |
  411. | [`persistent-memory`](examples/persistent-memory/) | pi-hermes-memory across two real sessions: save a fact in one, recall it in a fresh one — with the build-approval step (`better-sqlite3`) the install actually needs |
  412. | [`background-tasks`](examples/background-tasks/) | pi-background-tasks: start a long shell job in the background and read its output while it is still running — the live-tracking property asserted from the tool's own results |
  413. | [`subagents`](examples/subagents/) | The model runs a small team: delegate, background, steer mid-run, collect, resume with memory, stop for real, manage via `/pi-agents`, reopen across restarts |
  414. | [`pi-tui-ecosystem`](examples/pi-tui-ecosystem/) | Historical DSH 0.2.0-rc.2 proof; this terminal is currently incompatible with DSH 0.2.1-rc.2 |
  415. ## Other tools
  416. Beyond the engine, the CLI has a few helpers:
  417. ```sh
  418. npx pi2dsh inspect <pkg>@<version> # compatibility report before an upgrade
  419. npx pi2dsh matrix --json # the full capability matrix
  420. npx pi2dsh mcp-config # Pi mcpServers config → official DSH MCP entries
  421. ```
  422. ## Development
  423. ```sh
  424. pnpm verify # typecheck + contract tests + packaging
  425. pnpm audit:community # static screening over the top-50 corpus
  426. pnpm test:community # deep runtime + official plugin-manager + e2e
  427. DEEPSEEK_API_KEY=… pnpm test:live # real-model acceptance (key from env only)
  428. CODEX_AUTH_FILE=… pnpm test:codex-image # real OAuth generation + reference edit + Web pixels
  429. ```
  430. Acceptance evidence per capability: [docs/acceptance.md](docs/acceptance.md).
  431. Working standards: [CLAUDE.md](CLAUDE.md) and [docs/STANDARDS.md](docs/STANDARDS.md).
  432. ## License
  433. MIT. Vendored Pi sources retain their upstream MIT license
  434. (`src/compat/vendor/PI-LICENSE`); generated bundles retain copied upstream
  435. license and notice files.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.