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 /.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 /.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.