pi2dsh 0.10.0 → 0.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +262 -151
- package/README.zh.md +224 -133
- package/dist/host.mjs +1 -1
- package/dist/index.mjs +1 -1
- package/dist/{runtime-Ce3PTbWU.mjs → runtime-DFD6u4NO.mjs} +132 -7
- package/dist/runtime-DFD6u4NO.mjs.map +1 -0
- package/dist/runtime.d.mts.map +1 -1
- package/dist/runtime.mjs +1 -1
- package/package.json +4 -2
- package/dist/runtime-Ce3PTbWU.mjs.map +0 -1
package/README.md
CHANGED
|
@@ -2,205 +2,316 @@
|
|
|
2
2
|
|
|
3
3
|
**English** | [中文](README.zh.md)
|
|
4
4
|
|
|
5
|
-
**
|
|
5
|
+
**Run the Pi ecosystem's plugins on DeepSeek Harness, unmodified.**
|
|
6
6
|
|
|
7
7
|
```sh
|
|
8
|
-
|
|
9
|
-
dsh plugin
|
|
10
|
-
dsh plugin --profile headless add @kassing/pi-vision
|
|
11
|
-
dsh plugin --profile headless add pi-vision-tool
|
|
8
|
+
dsh plugin add pi2dsh # once
|
|
9
|
+
dsh plugin add <any-pi-plugin> # then any Pi plugin, straight from npm
|
|
12
10
|
```
|
|
13
11
|
|
|
14
|
-
|
|
15
|
-
package you added to the profile and mounts them all through one bridge
|
|
16
|
-
instance. Mounting happens at startup — **restart `dsh` after adding or
|
|
17
|
-
removing plugins**. Remove a plugin with `dsh plugin remove <pkg>` (remove
|
|
18
|
-
plugins before removing the engine, or they sit unmounted); upgrade the
|
|
19
|
-
engine with `dsh plugin add pi2dsh@latest` (your plugins are untouched),
|
|
20
|
-
upgrade a plugin with `dsh plugin add <pkg>@latest` (the engine is
|
|
21
|
-
untouched).
|
|
12
|
+
## Why this exists
|
|
22
13
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
14
|
+
[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) is built
|
|
15
|
+
on ideas worth betting on — a durable, reconstructable session log, a clean
|
|
16
|
+
service composition, an agent loop you can actually reason about. What it does
|
|
17
|
+
not have yet is a large plugin ecosystem: it is early, and the plugins people
|
|
18
|
+
want on day one — web search, memory, code navigation, subagents, vision — are
|
|
19
|
+
mostly not written for it yet.
|
|
27
20
|
|
|
28
|
-
|
|
21
|
+
[Pi](https://pi.dev/) has that ecosystem already, and it is mature: hundreds
|
|
22
|
+
of published packages, many with real users.
|
|
29
23
|
|
|
30
|
-
|
|
24
|
+
pi2dsh is one compatibility layer that implements Pi's public extension ABI on
|
|
25
|
+
top of DSH's native services, so a Pi package runs on DSH **as published** —
|
|
26
|
+
no fork, no patch, no per-package adapter. You install a Pi plugin the same
|
|
27
|
+
way you install anything else in DSH, and it works.
|
|
31
28
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
│ pi-tui / pi-coding-agent / pi-ai imports → vendored/headless │
|
|
45
|
-
│ shims (width/keys/session math byte-identical to Pi, MIT) │
|
|
46
|
-
│ setModel / setThinkingLevel → agent/request seam overrides │
|
|
47
|
-
└────────────────────────────────────────────────────────────────┘
|
|
48
|
-
▼
|
|
49
|
-
DeepSeek Harness native services (Cordis composition)
|
|
29
|
+
This is deliberately a bridge, not a destination. Every capability you reach
|
|
30
|
+
through pi2dsh is a capability DSH's own ecosystem will eventually offer
|
|
31
|
+
natively — and when a better native plugin shows up for something you use
|
|
32
|
+
here, you should switch to it. That would be the bridge doing its job.
|
|
33
|
+
|
|
34
|
+
## Install
|
|
35
|
+
|
|
36
|
+
One engine, then whatever plugins you want:
|
|
37
|
+
|
|
38
|
+
```sh
|
|
39
|
+
dsh plugin --profile <your-profile> add pi2dsh
|
|
40
|
+
dsh plugin --profile <your-profile> add @kassing/pi-vision
|
|
50
41
|
```
|
|
51
42
|
|
|
52
|
-
|
|
43
|
+
Then **restart `dsh`** — plugins mount at startup.
|
|
53
44
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
| **MCP config translation** | Pi's six `mcpServers` layers → official `@deepseek-ai/dsh-mcp-client` patch entries. The Pi MCP adapter's code never runs; `$VAR` becomes `!!js process.env.VAR`, literal secrets are warned about |
|
|
60
|
-
|
|
61
|
-
Engine config (optional, in the profile's `cordis.patch.yml`): `packages:
|
|
62
|
-
[a, b]` mounts exactly that list instead of discovering; `exclude: [c]`
|
|
63
|
-
skips individual dependencies; `visionCompanions: false` turns off the
|
|
64
|
-
automatic `<route>-vision` image-admission companions that every text-only
|
|
65
|
-
model route gets by default (an explicit `{route: [modelIds]}` map narrows
|
|
66
|
-
them instead).
|
|
67
|
-
|
|
68
|
-
**Plugin upgrades and compatibility.** Installed plugin versions are locked
|
|
69
|
-
by pnpm's lockfile — a plugin never upgrades behind your back; only an
|
|
70
|
-
explicit `dsh plugin add <pkg>@latest` moves it. Before upgrading, run
|
|
71
|
-
`pi2dsh inspect <pkg>@<version>` for the compatibility report. The bridge
|
|
72
|
-
intercepts the Pi runtime imports (`pi-coding-agent`/`pi-tui`/`pi-ai` are
|
|
73
|
-
served by its shims), so a plugin's own Pi dependency pins never load — the
|
|
74
|
-
only drift that can bite is a plugin adopting a Pi host API the bridge does
|
|
75
|
-
not cover yet, which the report shows and which fails loudly, package-
|
|
76
|
-
isolated, at runtime.
|
|
77
|
-
|
|
78
|
-
Three hard rules keep it general:
|
|
79
|
-
|
|
80
|
-
1. The core contains **no `if (packageName === …)`** branching.
|
|
81
|
-
2. Every capability has a **public-API contract test** (`pnpm test`, 55 tests); "some plugin loads" is never the success criterion.
|
|
82
|
-
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).
|
|
83
|
-
|
|
84
|
-
## Progress: Pi catalog top 50 by monthly downloads
|
|
85
|
-
|
|
86
|
-
Status as of 2026-08-14. Static analysis screens; the black-box run certifies. Full per-package machine-readable evidence in [community/](community/).
|
|
87
|
-
|
|
88
|
-
| Tier | Count | Meaning |
|
|
89
|
-
|---|---|---|
|
|
90
|
-
| ✅ **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 |
|
|
91
|
-
| 🟡 **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 |
|
|
92
|
-
| ❌ **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 |
|
|
93
|
-
| **Total mountable today** | **50 / 50** | 48 through convert/host bundles directly; 2 snapshot-limited packages through host mode ([evidence](community/host-mode-results.json)) |
|
|
45
|
+
That is the whole model. There is no conversion step, no generated bundle, no
|
|
46
|
+
build. The engine discovers the Pi packages in your profile (every one is
|
|
47
|
+
something you explicitly added) and mounts them through a single bridge
|
|
48
|
+
instance: one model directory, one login, one credential store, one upgrade
|
|
49
|
+
unit.
|
|
94
50
|
|
|
95
|
-
|
|
51
|
+
Day-to-day:
|
|
96
52
|
|
|
97
|
-
|
|
53
|
+
| Task | Command |
|
|
54
|
+
|---|---|
|
|
55
|
+
| Add a plugin | `dsh plugin add <pkg>` (then restart dsh) |
|
|
56
|
+
| Remove a plugin | `dsh plugin remove <pkg>` — remove plugins before removing the engine |
|
|
57
|
+
| Upgrade a plugin | `dsh plugin add <pkg>@latest` — the engine is untouched |
|
|
58
|
+
| Upgrade the engine | `dsh plugin add pi2dsh@latest` — your plugins are untouched |
|
|
59
|
+
| Check a plugin before upgrading | `npx pi2dsh inspect <pkg>@<version>` |
|
|
60
|
+
|
|
61
|
+
Two installer messages worth knowing:
|
|
62
|
+
|
|
63
|
+
- **`ERR_PNPM_IGNORED_BUILDS`** — pnpm blocks dependency build scripts by
|
|
64
|
+
default. Run `pnpm approve-builds` inside
|
|
65
|
+
`$DSH_HOME/profiles/<your-profile>`, or set the listed packages to `true`
|
|
66
|
+
under `allowBuilds` in that profile's `pnpm-workspace.yaml`. Then re-run the
|
|
67
|
+
add. (This is your call to make, so the bridge does not work around it.)
|
|
68
|
+
- **An add silently installs an older version** right after a release —
|
|
69
|
+
pnpm's `minimumReleaseAge` skips versions published very recently. Pin it:
|
|
70
|
+
`dsh plugin add pi2dsh@<version>`.
|
|
98
71
|
|
|
99
|
-
|
|
72
|
+
Requires Node.js 22.19+ and DeepSeek Harness.
|
|
100
73
|
|
|
101
|
-
|
|
74
|
+
## Walkthrough: give a text-only model eyes
|
|
102
75
|
|
|
103
|
-
|
|
76
|
+
The clearest example of what the bridge buys you. DeepSeek models are
|
|
77
|
+
text-only, so DSH cannot send them an image. The Pi ecosystem has a plugin for
|
|
78
|
+
exactly this — it hands the image to a vision model you choose and injects the
|
|
79
|
+
analysis back into the conversation.
|
|
104
80
|
|
|
105
|
-
|
|
81
|
+
### 1. Install the plugin
|
|
106
82
|
|
|
107
|
-
|
|
83
|
+
```sh
|
|
84
|
+
dsh plugin --profile <your-profile> add @kassing/pi-vision
|
|
85
|
+
```
|
|
108
86
|
|
|
109
|
-
|
|
110
|
-
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).
|
|
111
|
-
3. ✅ Done: all four Pi-internal-runtime packages bridged (see above) — every top-50 package mounts.
|
|
112
|
-
4. ✅ Done: the 2 snapshot-limited packages verified through host mode ([evidence](community/host-mode-results.json)).
|
|
113
|
-
5. ✅ Done: load-time vs lazy reachability screening landed; the five packages it unblocked all mount, four tested-working (see above).
|
|
87
|
+
### 2. Point it at a multimodal model
|
|
114
88
|
|
|
115
|
-
|
|
89
|
+
**This is the step to get right** — the plugin needs its own vision model, and
|
|
90
|
+
it is a different model from the one you chat with. Any OpenAI-compatible
|
|
91
|
+
vision endpoint works (OpenRouter, DashScope/Qwen-VL, a self-hosted vLLM, …).
|
|
116
92
|
|
|
117
|
-
|
|
93
|
+
The plugin reads its configuration from environment variables — the standard
|
|
94
|
+
way Pi plugins are configured, and a plain DSH-side action for you:
|
|
118
95
|
|
|
119
96
|
```sh
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
# Optional CLI (inspect / convert / host / mcp-config)
|
|
125
|
-
npx pi2dsh inspect @narumitw/pi-lsp # compatibility report
|
|
126
|
-
npx pi2dsh convert @narumitw/pi-lsp --out ./dsh-pi-lsp # vendored snapshot
|
|
127
|
-
npx pi2dsh host --packages 'pi-simplify' --out ./pi-host # pinned bundle
|
|
128
|
-
npx pi2dsh mcp-config # Pi mcpServers → DSH patch
|
|
97
|
+
export VISION_BRIDGE_BASE_URL=https://openrouter.ai/api/v1
|
|
98
|
+
export VISION_BRIDGE_MODEL=qwen/qwen2.5-vl-72b-instruct
|
|
99
|
+
export VISION_BRIDGE_API_KEY=$OPENROUTER_API_KEY
|
|
129
100
|
```
|
|
130
101
|
|
|
131
|
-
|
|
102
|
+
That is enough to work. If you would also like that vision model to appear in
|
|
103
|
+
DSH's own model picker (so you can chat with it directly), add it as a normal
|
|
104
|
+
DSH route as well — the `llm-pi-ai:` section of `$DSH_HOME/settings.yaml`:
|
|
132
105
|
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
106
|
+
```yaml
|
|
107
|
+
llm-pi-ai:
|
|
108
|
+
providers:
|
|
109
|
+
openrouter:
|
|
110
|
+
baseUrl: https://openrouter.ai/api/v1
|
|
111
|
+
apiKeyEnv: OPENROUTER_API_KEY
|
|
112
|
+
models:
|
|
113
|
+
- id: qwen/qwen2.5-vl-72b-instruct
|
|
114
|
+
```
|
|
138
115
|
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
| [`examples/vision-bridge`](examples/vision-bridge/) | A text-only model answers questions about images: mention an image path, a configured vision model reads it, the analysis is injected into the conversation (works in CLI and the DSH web app; probe images included) |
|
|
142
|
-
| [`examples/custom-gateways`](examples/custom-gateways/) | Add any OpenAI-compatible gateway the official DSH way (the `llm-pi-ai:` section of DSH settings) — it appears in the DSH model picker, works as the main model, and every Pi plugin sees it through the bridge's registry projection; the bridge owns zero model configuration |
|
|
116
|
+
Both are ordinary DSH configuration. The bridge owns no model configuration of
|
|
117
|
+
its own, and there is no Pi-format file for you to write.
|
|
143
118
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
each one is re-verified end to end under the same bar.
|
|
119
|
+
Avoid GPT-5/o-family models as the vision backend: that generation rejects the
|
|
120
|
+
non-default `temperature` some vision plugins send.
|
|
147
121
|
|
|
148
|
-
|
|
122
|
+
### 3. Ask about an image
|
|
149
123
|
|
|
150
|
-
|
|
124
|
+
In the CLI, mention a path:
|
|
151
125
|
|
|
152
126
|
```sh
|
|
153
|
-
|
|
154
|
-
/login openai-codex # prints the authorization URL, spins up the localhost callback
|
|
155
|
-
# → approve in your browser; the credential lands in auth.json (0600)
|
|
127
|
+
dsh --profile <your-profile> "What color fills $PWD/photo.png ? One word."
|
|
156
128
|
```
|
|
157
129
|
|
|
158
|
-
|
|
130
|
+
In the web app, **just paste the image** — even though your main model is
|
|
131
|
+
text-only. DSH normally refuses image attachments for a text-only model, so
|
|
132
|
+
the engine registers an *image-admission companion* route for every text-only
|
|
133
|
+
route in your directory, named `<route>-vision`. Pick it in the model picker
|
|
134
|
+
(it shows up as a "+ Vision Bridge" group), paste, and ask.
|
|
159
135
|
|
|
160
|
-
|
|
136
|
+
What you will see: your image becomes guide text, a
|
|
137
|
+
`pi2dsh:@kassing/pi-vision` context-injection row carries the analysis, and
|
|
138
|
+
your text-only model answers about the picture. Pixels never reach the
|
|
139
|
+
text-only wire.
|
|
140
|
+
|
|
141
|
+
Companions are automatic. To turn them off, or narrow them to specific routes,
|
|
142
|
+
set `visionCompanions` in the engine's plugin config
|
|
143
|
+
(`$DSH_HOME/profiles/<your-profile>/cordis.patch.yml`):
|
|
161
144
|
|
|
162
145
|
```yaml
|
|
163
|
-
- id:
|
|
164
|
-
name: '@deepseek-ai/dsh-llm-pi-ai'
|
|
146
|
+
- id: pi2dsh
|
|
165
147
|
config:
|
|
166
|
-
|
|
167
|
-
openai-codex:
|
|
168
|
-
apiKeyEnv: PI2DSH_OAUTH_OPENAI_CODEX
|
|
169
|
-
models:
|
|
170
|
-
- id: gpt-5.6-luna
|
|
148
|
+
visionCompanions: false
|
|
171
149
|
```
|
|
172
150
|
|
|
173
|
-
|
|
151
|
+
Full runnable version, with probe images: [`examples/vision-bridge`](examples/vision-bridge/).
|
|
152
|
+
|
|
153
|
+
## What you can install today
|
|
154
|
+
|
|
155
|
+
The Pi catalog's **top 50 packages by monthly downloads**, all verified on a
|
|
156
|
+
real DSH runtime — mounted, then actually exercised. Status as of 2026-08-14;
|
|
157
|
+
per-package machine-readable evidence in [`community/`](community/).
|
|
158
|
+
|
|
159
|
+
**47 of 50 verified working · 1 with no probeable surface · 2 pending a re-run.**
|
|
160
|
+
|
|
161
|
+
| Area | Packages |
|
|
162
|
+
|---|---|
|
|
163
|
+
| **MCP** | `pi-mcp-adapter` · `pi-mcp-extension` |
|
|
164
|
+
| **Web search & fetch** | `pi-web-access` · `pi-deepseek-search` · `pi-web-search` · `@ollama/pi-web-search` · `@juicesharp/rpiv-web-tools` |
|
|
165
|
+
| **Code navigation & editing** | `pi-lens` (ast-grep) · `@narumitw/pi-lsp` · `pi-readseek` · `@ff-labs/pi-fff` · `pi-landstrip` · `pi-hashline-edit-pro`¹ |
|
|
166
|
+
| **Subagents & background work** | `@tintinweb/pi-subagents` · `@gotgenes/pi-subagents` · `pi-background-tasks`² · `@mjasnikovs/pi-task` |
|
|
167
|
+
| **Memory** | `pi-hermes-memory` · `pi-goosedump` |
|
|
168
|
+
| **Planning & goals** | `@narumitw/pi-goal` · `pi-goal-list-loop-audit` · `@narumitw/pi-plan-mode` · `@juicesharp/rpiv-todo` |
|
|
169
|
+
| **Asking you / approvals** | `@juicesharp/rpiv-ask-user-question` · `pi-ask-user` · `@gotgenes/pi-permission-system` · `@juicesharp/rpiv-advisor` |
|
|
170
|
+
| **Side conversations** | `pi-btw` · `@narumitw/pi-btw` |
|
|
171
|
+
| **Models & providers** | `pi-provider-litellm` · `pi-llama-cpp` · `pi-prompt-template-model` · `@vigolium/piolium` |
|
|
172
|
+
| **Images** | `@kassing/pi-vision` (see above) · `@amaster.ai/pi-image-gen` |
|
|
173
|
+
| **External integrations** | `@llblab/pi-telegram` · `pi-cursor-sdk`² · `@howaboua/pi-codex-conversion` · `pi-agent-browser-native`² · `pi-harness-runtime` |
|
|
174
|
+
| **Prompting & workflow** | `pi-simplify` · `pi-fabric`² · `mitsupi` · `pi-cc-extensions` · `pi-rtk-optimizer` · `pi-interview`¹ |
|
|
175
|
+
| **Terminal decoration** | `pi-powerline-footer` · `@narumitw/pi-statusline` · `pi-zentui` |
|
|
176
|
+
| **Voice** | `@juicesharp/rpiv-voice` |
|
|
177
|
+
| **Usage reporting** | `@alexanderfortin/pi-deepseek-usage`³ |
|
|
178
|
+
|
|
179
|
+
¹ Mounts; the exercise run is pending a re-run (a harness-side failure, not a
|
|
180
|
+
package or bridge gap). ² Ran its own business logic end to end and rejected
|
|
181
|
+
the synthetic probe arguments — working, correctly validating.
|
|
182
|
+
³ A pure event-hook package: all subscriptions attach, but every handler is
|
|
183
|
+
gated on a live DeepSeek billing session, so a black-box probe has nothing
|
|
184
|
+
safely callable to assert.
|
|
185
|
+
|
|
186
|
+
Packages outside the top 50 are not a separate case — the bridge has no
|
|
187
|
+
per-package code. If one hits an ABI gap, fixing that gap unlocks every
|
|
188
|
+
package that shares it.
|
|
189
|
+
|
|
190
|
+
## How it works
|
|
191
|
+
|
|
192
|
+
Three layers, and nothing crosses them:
|
|
193
|
+
|
|
194
|
+
```
|
|
195
|
+
┌─ Pi plugin ─────────────────────────────────────────────────┐
|
|
196
|
+
│ unmodified npm package. It sees a complete Pi host: the │
|
|
197
|
+
│ three Pi runtime imports, registerX, ctx.*, 33 lifecycle │
|
|
198
|
+
│ events. It never learns DSH exists. │
|
|
199
|
+
└──────────────────────────┬──────────────────────────────────┘
|
|
200
|
+
│ Pi's public ABI
|
|
201
|
+
┌──────────────────────────▼──────────────────────────────────┐
|
|
202
|
+
│ pi2dsh — the translator, and the only place that knows both │
|
|
203
|
+
│ vocabularies. Registry projection, event bridge, session & │
|
|
204
|
+
│ subagent bridge, credentials, vendored Pi logic. │
|
|
205
|
+
└──────────────────────────┬──────────────────────────────────┘
|
|
206
|
+
│ ordinary DSH plugin + llm adapter
|
|
207
|
+
┌──────────────────────────▼──────────────────────────────────┐
|
|
208
|
+
│ DeepSeek Harness. Sees a normal plugin. Never learns Pi │
|
|
209
|
+
│ exists. │
|
|
210
|
+
└─────────────────────────────────────────────────────────────┘
|
|
211
|
+
```
|
|
174
212
|
|
|
175
|
-
|
|
213
|
+
The rules that keep it honest:
|
|
214
|
+
|
|
215
|
+
- **Never a second implementation of something DSH already has.** Tools go to
|
|
216
|
+
DSH's tool registry, models to DSH's llm configuration, MCP to
|
|
217
|
+
`dsh-mcp-client`, skills to `dsh-skill-filesystem`, questions to DSH's user
|
|
218
|
+
questions. The bridge translates configuration; it does not build a parallel
|
|
219
|
+
runtime.
|
|
220
|
+
- **You never see Pi.** Everything you configure, read, or type is DSH-shaped:
|
|
221
|
+
DSH settings, DSH commands, DSH credentials. Pi vocabulary exists only
|
|
222
|
+
inside the plugin's view and the bridge's own internals.
|
|
223
|
+
- **No per-package special cases.** The core contains no
|
|
224
|
+
`if (packageName === …)`. One ABI gap fixed unlocks every package that hits
|
|
225
|
+
it.
|
|
226
|
+
- **Never fake success.** A capability with no safe mapping is reported —
|
|
227
|
+
once, per plugin, in plain language — instead of silently returning
|
|
228
|
+
something invented. If a plugin needs one during startup, it is marked
|
|
229
|
+
unusable with a removal hint rather than half-working.
|
|
230
|
+
- **Verified, not asserted.** Every capability has a public-API contract test,
|
|
231
|
+
and ships only after running end to end on a real DSH loop — CLI *and* web.
|
|
232
|
+
|
|
233
|
+
## Pi capabilities on DSH
|
|
234
|
+
|
|
235
|
+
Every surface a Pi package can touch, and what it maps onto. These tables are
|
|
236
|
+
generated from the rules the bridge consults at runtime, so they cannot drift
|
|
237
|
+
from the code.
|
|
238
|
+
|
|
239
|
+
| Area | Pi surfaces | Status |
|
|
240
|
+
|---|---|---|
|
|
241
|
+
| [Tools](docs/capabilities/tools.md) | 12 | 3 same semantics · 9 mapped, difference stated |
|
|
242
|
+
| [Commands, flags, editor input](docs/capabilities/commands.md) | 13 | 13 mapped, difference stated |
|
|
243
|
+
| [Messages, context, agent loop](docs/capabilities/conversation.md) | 20 | 7 same semantics · 13 mapped, difference stated |
|
|
244
|
+
| [Sessions & side conversations](docs/capabilities/sessions.md) | 24 | 4 same semantics · 20 mapped, difference stated |
|
|
245
|
+
| [Models, providers, credentials](docs/capabilities/models.md) | 15 | 12 mapped, difference stated · 3 not available |
|
|
246
|
+
| [Asking the user, rendering](docs/capabilities/interaction.md) | 24 | 4 same semantics · 20 mapped, difference stated |
|
|
247
|
+
| [Project environment & resources](docs/capabilities/environment.md) | 4 | 1 same semantics · 1 mapped · 2 not available |
|
|
248
|
+
| **Total** | **112** | **19 same · 88 mapped with stated differences · 5 not available** |
|
|
249
|
+
|
|
250
|
+
Plus **202 imported symbols** from Pi's three runtime packages
|
|
251
|
+
(`pi-coding-agent`, `pi-tui`, `pi-ai`), served from vendored or headless
|
|
252
|
+
shims — so a plugin's own Pi version pins never load.
|
|
253
|
+
|
|
254
|
+
Start at the [capability index](docs/capabilities/README.md). Machine-readable:
|
|
255
|
+
`pi2dsh matrix --json`.
|
|
256
|
+
|
|
257
|
+
**Signing in with a subscription** works too: DSH ships static HTTP headers
|
|
258
|
+
only, and the bridge adds the Pi ecosystem's interactive OAuth layer. Any Pi
|
|
259
|
+
provider package that declares an `oauth` block gets a working
|
|
260
|
+
`/login <provider>`, driven by the package's own protocol code — Pi's four
|
|
261
|
+
official flows (OpenAI Codex, Anthropic, GitHub Copilot, Kimi Code) ship built
|
|
262
|
+
in. Credentials persist with Pi's `auth.json` semantics and resolve per
|
|
263
|
+
request through a standard `dsh-credentials` provider, so your subscription
|
|
264
|
+
drives real calls on DSH's native llm path. Details in
|
|
265
|
+
[models](docs/capabilities/models.md).
|
|
266
|
+
|
|
267
|
+
**What is deliberately not available**, and why: runtime package installation
|
|
268
|
+
and standalone model runtimes stay with the host and its security gates;
|
|
269
|
+
provider payload/header/response interception belongs in a DSH llm adapter;
|
|
270
|
+
project trust is a host decision. See
|
|
271
|
+
[models](docs/capabilities/models.md) and
|
|
272
|
+
[environment](docs/capabilities/environment.md).
|
|
273
|
+
|
|
274
|
+
**The one gap we own:** plugin-drawn cards. Pi plugins can ship their own
|
|
275
|
+
renderers; today those registrations are accepted but not invoked, so such a
|
|
276
|
+
note appears as a native context-injection row — the content reaches you and
|
|
277
|
+
the model, without the plugin's styling. DSH has the machinery for this; we
|
|
278
|
+
have not built our client half yet.
|
|
279
|
+
|
|
280
|
+
## Examples
|
|
281
|
+
|
|
282
|
+
Every verified capability ships as a complete, runnable example. Every command
|
|
283
|
+
in one has actually been executed against a real DSH loop before landing.
|
|
176
284
|
|
|
177
|
-
|
|
|
285
|
+
| Example | What you get |
|
|
178
286
|
|---|---|
|
|
179
|
-
|
|
|
180
|
-
|
|
|
181
|
-
|
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
| Session control | REAL on DSH's own surfaces: `newSession` creates a DSH session with lineage, `fork` uses DSH's official prefix-fork (landing on completed-turn boundaries), `navigateTree` forks at the target with an optional vendored branch summary, `switchSession` targets live sessions. The DSH tree lives *between* sessions (fork lineage); which session the surface shows stays a host choice |
|
|
185
|
-
| Compaction & summaries | `ctx.compact()` triggers DSH's official manual compaction; Pi's `generateSummary`/`generateBranchSummary`/`findCutPoint` are vendored with model calls on the DSH llm bridge |
|
|
186
|
-
| shutdown / reload | `shutdown` is absorbed (Pi defines its behavior as host-provided; the user owns DSH process exit); `reload` really remounts extension entries — skills/prompts/themes reload with dsh itself |
|
|
187
|
-
| Host-owned capabilities | `ModelRuntime` and `DefaultPackageManager` stay unavailable **by design** (the host owns model configuration and package install with its security gates). Importing them is flagged at startup; constructing them throws a structured error, and doing so during plugin startup marks the plugin unusable with a clear removal hint. Every capability gap is reported to you once per plugin — never a silent failure, never a fake success. **Known plugins unusable for this reason: none so far** (this list will name any we find) |
|
|
188
|
-
| Terminal decoration | footer/statusline/shortcuts register but never fire — matching Pi's own non-TUI modes |
|
|
287
|
+
| [`vision-bridge`](examples/vision-bridge/) | A text-only model answers questions about images — CLI and web, probe images included |
|
|
288
|
+
| [`side-conversation`](examples/side-conversation/) | `/btw <question>` runs a side thread in DSH's native subagent UI; your main conversation stays clean |
|
|
289
|
+
| [`custom-gateways`](examples/custom-gateways/) | Add any OpenAI-compatible gateway the official DSH way, and every Pi plugin sees it |
|
|
290
|
+
|
|
291
|
+
## Other tools
|
|
189
292
|
|
|
190
|
-
|
|
293
|
+
Beyond the engine, the CLI has a few helpers:
|
|
191
294
|
|
|
192
|
-
|
|
295
|
+
```sh
|
|
296
|
+
npx pi2dsh inspect <pkg>@<version> # compatibility report before an upgrade
|
|
297
|
+
npx pi2dsh matrix --json # the full capability matrix
|
|
298
|
+
npx pi2dsh mcp-config # Pi mcpServers config → official DSH MCP entries
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
## Development
|
|
193
302
|
|
|
194
303
|
```sh
|
|
195
|
-
pnpm verify
|
|
196
|
-
pnpm audit:community
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
# credentialed probes and real child-pi dispatch (keys from env only)
|
|
200
|
-
pnpm test:community # deep runtime + official manager + host e2e
|
|
201
|
-
DEEPSEEK_API_KEY=… pnpm test:live # real-model acceptance (key from env only)
|
|
304
|
+
pnpm verify # typecheck + contract tests + packaging
|
|
305
|
+
pnpm audit:community # static screening over the top-50 corpus
|
|
306
|
+
pnpm test:community # deep runtime + official plugin-manager + e2e
|
|
307
|
+
DEEPSEEK_API_KEY=… pnpm test:live # real-model acceptance (key from env only)
|
|
202
308
|
```
|
|
203
309
|
|
|
310
|
+
Acceptance evidence per capability: [docs/acceptance.md](docs/acceptance.md).
|
|
311
|
+
Working standards: [CLAUDE.md](CLAUDE.md) and [docs/STANDARDS.md](docs/STANDARDS.md).
|
|
312
|
+
|
|
204
313
|
## License
|
|
205
314
|
|
|
206
|
-
MIT. Vendored Pi sources retain their upstream MIT license
|
|
315
|
+
MIT. Vendored Pi sources retain their upstream MIT license
|
|
316
|
+
(`src/compat/vendor/PI-LICENSE`); generated bundles retain copied upstream
|
|
317
|
+
license and notice files.
|