DSH Pi
Run trusted, unmodified Pi extensions inside DeepSeek Harness. This is a compatibility host, not a source-to-source converter: Pi's official loader and ExtensionRunner own Pi semantics, while this package adapts their observable surface to agent-scoped DSH tools, commands, messages, attachments, and lifecycle hooks.
The project currently targets Pi 0.80.x and DSH 0.1.0-rc.6. DSH is still a developer preview; the peer range is intentionally narrow.
Why a host instead of generated plugins
An extension factory is executable code with lifecycle and session state. Converting its source once cannot preserve tools registered during session_start, mutable active-tool sets, cancellation, providers, or per-agent state. The host therefore creates one Pi runtime per DSH agent and reconciles registrations into that agent's Cordis context.
flowchart LR
C["DSH bundle config"] --> R["Package / manifest resolver"]
R --> P["Pi loader + ExtensionRunner"]
P --> A["Agent-scoped adapter"]
A --> T["DSH tools"]
A --> M["DSH commands"]
A --> L["DSH lifecycle and messages"]
F["Existing Pi packages\nread-only fixtures"] --> R
Local development
pnpm install
pnpm check
PI_FIXTURE_WORKSPACE=/absolute/path/to/pi pnpm test
pnpm compat /absolute/path/to/pi
The repository at ../pi is only read. Compatibility tests inventory its packages/pi-* manifests and source API usage; representative smoke tests load built entries without calling paid tools.
Install as a DSH bundle
Install the published bundle and the Pi extensions you want in the same profile:
dsh plugin --profile demo add dsh-pi-host \
@amaster.ai/pi-image-gen \
@amaster.ai/pi-video-gen
dsh --profile demo --dump-config
For local development, replace dsh-pi-host with the path to this checkout, such as ./dsh-pi when running from its parent directory.
The selected Pi packages must be installed in the same DSH profile so bare package specifiers resolve from that profile. DSH may warn that they declare no dsh.bundle; that is expected because they are plain dependencies loaded by dsh-pi-host, not independent DSH layers. Install any other package named in extensions the same way.
Choose Pi extensions
Then override the bundle row in the profile's cordis.patch.yml. DSH replaces a row's complete config, so keep every field:
- id: dsh-pi
config:
extensions:
- '@amaster.ai/pi-image-gen'
- '@amaster.ai/pi-video-gen'
projectTrusted: false
allowLocalPaths: false
strict: false
flags: {}
strict: true fails agent composition when any selected Pi tool schema cannot be represented without widening it. With strict: false, those tools are skipped, excluded from the Pi-visible adapted active set, and retried only after their definition changes or they are reactivated; for the current pi-video-gen fixture this skips video_generate because DSH cannot enforce its numeric minimum, while the other three video tools still mount.
For local fixture packages, enable the explicit code-execution boundary:
- id: dsh-pi
config:
extensions:
- '/Users/me/Workspace/pi/packages/pi-image-gen'
projectTrusted: false
allowLocalPaths: true
strict: true
flags: {}
allowLocalPaths is off by default because Pi extensions are trusted Node.js code, not sandboxed plugins. projectTrusted is a separate switch: it controls whether extensions may consume project-local Pi settings and policies. The host loads only entries resolved from extensions; it never auto-discovers <cwd>/.pi/extensions.
Reload the profile after changing extensions, then run dsh --profile demo --dump-config to verify the effective list.
Configure Pi extensions
Keep Pi settings beside the DSH profile configuration and point PI_CODING_AGENT_DIR at that profile directory. Use Pi's established settings.json filename rather than a separate pi-settings.json compatibility format:
$DSH_HOME/profiles/demo/
├── cordis.patch.yml # selects Pi extensions
└── settings.json # configures those Pi extensions
For pi-image-gen, the minimum configuration selects a model and keeps the API key in the environment:
{
"pi-image-gen": {
"defaultModel": "nano-banana"
}
}
export DSH_HOME="$HOME/.dsh"
export PI_CODING_AGENT_DIR="$DSH_HOME/profiles/demo"
export GEMINI_API_KEY="..."
dsh --profile demo
The same settings file can configure multiple selected Pi extensions under their own top-level keys. Project-local <cwd>/.pi/settings.json remains available only when projectTrusted is enabled.
Pi API to DSH compatibility
Status:
- ✅ Supported — the observable Pi behavior has a DSH mapping.
- 🟡 Partial — useful behavior works, but some Pi semantics are missing.
- ❌ Unsupported — there is no faithful adapter yet; the host does not pretend it worked.
ExtensionAPI methods
| Pi ExtensionAPI | Closest DSH capability | Implemented here | Notes |
|---|
pi.on(...) | Cordis ctx.on(...) and DSH agent/session/tool events | 🟡 Partial | See the lifecycle-event table below. |
pi.registerTool(...) | agent.ctx.tools.register(...) | 🟡 Partial | Execution, strict schema projection (including disjoint TypeBox literal unions), prepareArguments, cancellation, sanitized errors, ordered updates, images, concurrency, active-tool changes and lifecycle-time registration/replacement work. Successful text is bounded to 50KB/2000 lines, oversized details are omitted, and images are checked against DSH attachment limits before decoding. Unrepresentable schemas are rejected; Pi TUI renderers and DSH live update cards do not. |
pi.registerCommand(...) | agent.ctx.commands.register(...) | 🟡 Partial | Command handlers, sanitized unexpected failures, and ctx.ui.notify text work. Pi completions and interactive ctx.ui dialogs do not. |
pi.registerShortcut(...) | No plugin-owned DSH keyboard-shortcut registry | ❌ Unsupported | Requires a separate client/UI plugin. |
pi.registerFlag(...) | DSH plugin config plus the embedded Pi flag store | ✅ Supported | Defaults and configured overrides use Pi's official runner. |
pi.getFlag(...) | Read the embedded Pi flag store | ✅ Supported | Preserves Pi flag lookup behavior. |
pi.registerMessageRenderer(...) | DSH replayable message projections/UI plugins | ❌ Unsupported | Pi TUI components cannot be replayed as DSH render intents. |
pi.registerEntryRenderer(...) | DSH session projections/UI plugins | ❌ Unsupported | Same renderer-model mismatch. |
pi.sendMessage(...) | agent.followup(), agent.steer(), agent.inject(), agent.send() | 🟡 Partial |
ExtensionContext and command context
| Pi context capability | Closest DSH capability | Implemented here | Notes |
|---|
ctx.ui.* | DSH command response and optional client UI plugins | 🟡 Partial | /command handlers capture ctx.ui.notify as response text. Dialogs and Pi TUI controls use Pi's no-op UI context. |
ctx.mode | Active host transport | 🟡 Partial | Reports the embedded Pi mode (rpc by default), not the connected DSH frontend. |
ctx.hasUI | Availability of dialog-capable UI | ✅ Supported | Correctly returns false; this host exposes no Pi dialogs. |
ctx.cwd | agent.session.header.cwd | ✅ Supported | Uses the DSH agent's working directory. |
ctx.sessionManager | DSH event-sourced session | 🟡 Partial | An in-memory Pi SessionManager is available, but DSH history is not projected into it. |
ctx.modelRegistry | DSH LLM adapter/catalog services | 🟡 Partial | Pi provider registrations are recorded; DSH adapters, credentials and model catalog are not exposed. |
ctx.model | Selected DSH provider/model | ❌ Unsupported | No Pi Model object is synthesized. |
ctx.isIdle() | agent.status | ✅ Supported | Reads the DSH agent's live status. |
ctx.isProjectTrusted() | projectTrusted config | ✅ Supported | Returns the explicit host trust decision. |
ctx.signal | DSH turn/tool AbortSignal | ✅ Supported | Invocation-scoped and safe for parallel Pi tools. |
ctx.abort() | agent.cancel(...) | ✅ Supported | Cancels the current DSH agent operation. |
|
Lifecycle events
| Pi event | Closest DSH event/capability | Implemented here |
|---|
project_trust | Deployment/plugin trust configuration | 🟡 Configured projectTrusted controls ctx.isProjectTrusted(); the interactive handler is not run. |
resources_discover | DSH skill and system-prompt registries | 🟡 Handler runs, but returned skill/prompt/theme paths are not mounted into DSH. |
session_start | agent/session-start | ✅ Per-agent and awaited before the first step. |
session_shutdown | agent/disposed / Cordis effect disposal | 🟡 Runs once and drains during agent or plugin teardown, but every DSH teardown is reported to Pi with reason quit. |
session_info_changed | DSH session-title projection | ❌ Not mapped. |
session_before_switch, session_before_fork | DSH session preparation/publication | ❌ No equivalent veto mapping yet. |
session_before_compact, session_compact | DSH compaction plugins/events | ❌ Different compaction contract; only reload-style startup is currently emitted after compact lifecycle changes. |
session_before_tree, session_tree | DSH event-sourced session history | ❌ Pi tree navigation has no direct DSH equivalent. |
input | First agent/pre-step of a DSH turn | 🟡 continue, handled, and text/image transforms run once for the initial claimed DSH message batch. Text is newline-joined, images are preserved, and a transform replaces the claimed batch with one new DSH message identity. |
before_agent_start | First agent/pre-step plus system-prompt/assemble | 🟡 Handler runs once per agent run; returned custom messages and system-prompt replacement are not applied yet. |
agent_start |
The host additionally provides Pi package-manifest discovery, dynamic extension selection through DSH config, one official Pi runtime per DSH agent, HMR-safe effect disposal, and invocation-scoped cancellation for parallel tools.
See the detailed compatibility matrix and the executable source of truth in src/capabilities.ts.
Publishing
Git installs need pnpm permission to run this package's prepare build. The npm package ships prebuilt lib/ and needs no install-time build permission. Maintainers publish by pushing a tag that exactly matches the package version, for example v0.1.0-rc.2; the release workflow validates, builds, tests, and publishes dsh-pi-host with the repository's NPM_TOKEN secret. Prereleases use npm's next tag and stable versions use latest.
