pi2dsh

English | 中文

Run the Pi ecosystem's plugins on DeepSeek Harness, unmodified.

dsh plugin add pi2dsh          # once
dsh plugin add <any-pi-plugin> # then any Pi plugin, straight from npm

Why this exists

DeepSeek Harness is built on ideas worth betting on — a durable, reconstructable session log, a clean service composition, an agent loop you can actually reason about. What it does not have yet is a large plugin ecosystem: it is early, and the plugins people want on day one — web search, memory, code navigation, subagents, vision — are mostly not written for it yet.

Pi has that ecosystem already, and it is mature: hundreds of published packages, many with real users.

pi2dsh is one compatibility layer that implements Pi's public extension ABI on top of DSH's native services, so a Pi package runs on DSH as published — no fork, no patch, no per-package adapter. You install a Pi plugin the same way you install anything else in DSH, and it works.

At the same time, pi2dsh is an ongoing, full-surface, real-world test of DSH's architecture. Instead of patching individual plugins, it asks whether the models, tools, sessions, interaction, resources and client capabilities that Pi plugins rely on can preserve their logic and lifecycle using only DSH's public services and extension seams. If they can, that is strong evidence that DSH's architectural goals for building agents and an agent-plugin ecosystem have been achieved, at least along this dimension. Wherever the bridge must bypass, degrade or cannot express a capability, it pinpoints an architectural gap that remains.

Install

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:

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.

Walkthrough: advanced MCP in your terminal

The clearest example of what the bridge buys you. dsh-TUI ships a native /mcp command for DSH's official MCP client — it works, and it stays untouched. The Pi ecosystem has a much richer MCP power tool: a full-screen server manager, lazy tool discovery, one proxy tool instead of flooding the model context with dozens of tools, JavaScript orchestration of multiple MCP calls, OAuth logins, resources and prompts. With the bridge, that package runs unmodified.

1. Install

dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui   # skip if the profile exists
dsh plugin --profile dsh-tui add pi2dsh
dsh plugin --profile dsh-tui add pi-mcp-adapter

Then restart dsh — plugins mount at startup.

2. Configure your MCP servers

Inside dsh-TUI, run:

/pi-mcp setup

The setup flow can adopt MCP server definitions from host configs you already have into the adapter's own standard mcp.json. No bridge-specific configuration exists — everything you touch is the package's own surface.

3. Use it

/pi-mcp

opens the full-screen interactive server manager — its footer documents the keys for enable/disable, reconnect and OAuth login. The model receives the adapter's mcp and mcpScript tools through DSH's normal tool registry, and each agent (/new included) gets its own fully connected instance.

dsh-TUI's native command remains separate, and both stay available:

/mcp       # native DSH MCP-client status
/pi-mcp    # the installed Pi adapter's manager

What is verified behind this walkthrough: 16 host-influenced capabilities end to end on the stock npm stack — three real transports, discovery, proxy and hot-loaded direct tools, mcpScript, resources, prompts, images becoming real DSH attachments, MCP Apps, tool approval through DSH questions, elicitation, sampling against the real DSH model runtime, cancellation and session restart. The full evidence matrix: [docs/mcp-compatibility.md](docs/mcp-compatibility.md).

Full runnable version: [examples/tui-mcp](examples/tui-mcp/).

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.

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.

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.

¹ Mounts; the exercise run is pending a re-run (a harness-side failure, not a package or bridge gap). ² Ran its own business logic end to end and rejected the synthetic probe arguments — working, correctly validating. ³ A pure event-hook package: all subscriptions attach, but every handler is gated on a live DeepSeek billing session, so a black-box probe has nothing safely callable to assert.

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:

┌─ Pi plugin ─────────────────────────────────────────────────┐
│ unmodified npm package. It sees a complete Pi host: the     │
│ three Pi runtime imports, registerX, ctx.*, 33 lifecycle    │
│ events. It never learns DSH exists.                         │
└──────────────────────────┬──────────────────────────────────┘
                           │  Pi's public ABI
┌──────────────────────────▼──────────────────────────────────┐
│ pi2dsh — the translator, and the only place that knows both │
│ vocabularies. Registry projection, event bridge, session &  │
│ subagent bridge, credentials, vendored Pi logic.            │
└──────────────────────────┬──────────────────────────────────┘
                           │  ordinary DSH plugin + llm adapter
┌──────────────────────────▼──────────────────────────────────┐
│ DeepSeek Harness. Sees a normal plugin. Never learns Pi     │
│ exists.                                                     │
└─────────────────────────────────────────────────────────────┘

DSH is two halves, and so is the bridge. The column above is the server; the browser shell has its own plugin surface, and a Pi capability that is a SHAPE rather than a behaviour lands there:

┌──────────── DSH server (cordis) ────────────┐  ┌──────── DSH browser shell ────────┐
│ services · waterfalls · durable events      │  │ dsh.client + exports "./client"   │
│                                             │  │ slot registry (ui-slots)          │
│ pi2dsh engine                               │  │   shell.overlay  ← panel, pills   │
│   tools · commands · models · sessions      │  │   session.header.utilities ← hdr  │
│   subagent bridge ─────────────┐            │  │   input.dock ← widgets            │
│   browser-state registry       │            │  │   composer.dock ← working/footer  │
│     GET /pi2dsh/browser-state ─┼── own route┼──┼─▶ all four seats, one poller      │
└────────────────────────────────┴────────────┘  └───────────────────────────────────┘

The browser half's data rides this package's own route, not DSH's typed Remote system: that one is a first-party, code-generated contract, and an out-of-tree plugin talking to its own UI should carry its own channel. One payload per session serves every seat — the side-conversation panel, plus the Pi presentation surfaces (status, widget, header, footer, title and the working/thinking chrome), which are drawn in the host's own slot seats rather than re-implemented. Two host rules make the browser half load at all — the package must export ./package.json (the host resolves the manifest by subpath), and the ./client bundle is a closure-factory artifact, not plain ESM.

The rules that keep it honest:

• Never a second bridge-owned implementation of something DSH already has.

Tools go to DSH's tool registry, models to DSH's llm configuration, configuration-only MCP servers to dsh-mcp-client, skills to dsh-skill-filesystem, and questions to DSH's user questions. An explicitly installed Pi capability package can retain behavior that it owns; the bridge maps its public surfaces and does not copy its transport.

• No bridge-private user world. Normal configuration remains DSH-shaped:

DSH settings, commands and credentials. When an installed capability package deliberately exposes its own manager, that surface remains recognizable and is namespaced on conflict — dsh-TUI keeps /mcp, while the Pi manager is /pi-mcp.

• No per-package special cases. The core contains no

if (packageName === …). One ABI gap fixed unlocks every package that hits it.

• Never fake success. A capability with no safe mapping is reported —

once, per plugin, in plain language — instead of silently returning something invented. If a plugin needs one during startup, it is marked unusable with a removal hint rather than half-working.

• Verified, not asserted. Every capability has a public-API contract test,

and ships only after running end to end on every DSH surface it claims.

What this is teaching us about DSH

pi2dsh is also an executable stress test of DSH's plugin architecture. Pi gives that test a useful workload: a large, already-used public plugin ABI rather than a set of examples invented to fit the host.

The result so far is specific, not a thumbs-up/thumbs-down verdict:

• DSH's public seams successfully carry whole capabilities: tools, commands,

model adapters, user questions, native child sessions and browser slots.

• The pressure points appear when an out-of-repo plugin needs to extend an

existing capability from the inside: add a durable session-event type, intercept the real provider request/response, control compaction before it happens, or participate in trust before project resources load.

• A working pi2dsh sidecar or alternate adapter is useful product behaviour,

but it is not counted as proof that the native DSH seam is complete.

For example, a pi-btw answer is a real DSH child session — visible, resumable and continuable by the host. Pi custom entries are different: they still need a pi2dsh sidecar because an out-of-repo plugin cannot safely add a new event type to DSH's durable log. Likewise, a transport-owning Pi provider can register a native DSH route. Since DSH rc.8, a catalog-only provider also has a faithful official path: pi2dsh translates its endpoint, modalities, reasoning levels and the protocol-specific compat fields DSH offers into an llm-pi-ai profile, and DSH owns the request.

The project follows one [Pi → DSH architecture mapping standard](docs/architecture-mapping-standard.md). It is a reasoning method, not another runtime layer: concrete Pi interface → Pi capability contract → DSH carrying mechanism → public seam → real plugin run → five-grade result. The evolving branches live in the handwritten [architecture model](docs/architecture-mapping-matrix.md), real runs in [per-plugin validation records](docs/plugin-validation-matrix.md), and the three result classes in [architecture conclusions](docs/dsh-architecture-conformance.md). Architecture classifications are deliberately not generated from a JSON ledger. The previously observed 111 Pi rule rows and 45 DSH subsystems are versioned snapshots, not fixed totals or proof of completeness. Four DSH gap IDs remain active; a fifth historical finding (DSH-ARCH-002) was fixed upstream in rc.8. These are confirmed findings, not a claim of complete coverage. Current upstream reports include #2708 — durable events for out-of-repo plugins and #3076 — provider compat fields dropped by llm-pi-ai, now resolved by the rc.8 profile schema.

Pi capabilities on DSH

Every surface a Pi package can touch, and what it maps onto. These tables are generated from the rules the bridge consults at runtime, so they cannot drift from the code.

For pinned Pi 0.84.1, the generated catalog has 111 upstream-shaped rule rows. The bridge also keeps one documented compatibility extension, unregisterTool; it appears on the tools detail page but is deliberately outside that total. Nested objects such as the session manager can expose several methods behind one row; the architecture audit states this boundary explicitly.

<!-- capability-table:start -->

…