dsh-pi-adapter

Run pi coding-agent extensions (~/.pi/agent/extensions/*.ts) inside DeepSeek Harness (dsh).

A pi extension is export default (pi: ExtensionAPI) => void; every capability comes from the injected ExtensionAPI object. This project implements that contract on a cordis context so pi extensions run unmodified inside dsh.

How it works

pi extension (.ts factory)                  dsh (cordis)
┌────────────────────────────┐   jiti   ┌──────────────────────────────┐
│ export default (pi) => {   │ ───────► │ ExtensionBridge (PiCompat)   │
│   pi.registerTool({...})   │  alias   │   registerTool → ctx.tools   │
│   pi.registerCommand(...)  │  to pi   │   registerCommand → commands │
│   pi.on("tool_call", fn)   │  runtime │   on(event) → ctx.on(map)    │
│ }                          │          │   dispose() → unwind effects │
└────────────────────────────┘          └──────────────────────────────┘

• jiti loader loads extensions the same way pi does (TS, no build step).
• pi runtime aliases resolve @earendil-works/pi-ai / pi-tui / pi-coding-agent / typebox from the global pi install (npm root -g), since those packages only exist there.
• ExtensionBridge implements the full ExtensionAPI surface. Each method is one of:
  • [direct] shape matches a cordis seam one-to-one
  • [adapt] a compatibility adapter wraps the dsh surface
  • [degrade] a write-only sink with no dsh equivalent — logs loudly
  • [unsupported] no truthful answer exists — raises UnsupportedSeamError

The answer-truthfully rule

The bridge never fabricates a value an extension will act on. The split is by direction, not by importance:

• a seam the extension reads (its return value drives a decision) with no truthful dsh answer → throw, naming the extension and the seam
• a seam the extension only writes (notify, setStatus, widgets, shortcuts) → log and continue; nothing branches on it

The nuance is concrete: permission-gate.ts gates on ctx.ui.select(), and a headless dsh host has no user to ask. Two wrong answers were on the table. Silently returning undefined with nothing in the log hides the missing capability; quarantining the extension (the earlier behavior) kills the gate for the rest of the session — every later call denied with a misleading "unimplemented seam" reason, which is what a headless rc.2 smoke run actually produced. pi's own contract offers the honest middle: select/confirm resolve undefined/false on user-cancel, and correctly written extensions treat that as non-affirmative (the same branch they take under !ctx.hasUI). So an UNANSWERED ask resolves to that no-selection convention, with a loud log naming why nobody answered — a gate that blocks unless the answer is an explicit "Yes" (the real permission-gate shape) keeps gating with its own precise reason. A gate written to block only on an explicit "No" allows on no-selection — but that shape fails open on a plain Esc under real pi too. strictUi: true restores raise-and-quarantine for deployments that prefer it. Seams with no truthful answer at all (ctx.ui.editor(), ctx.isProjectTrusted()) still raise.

ctx.ui.theme moved the other way: pi's Theme is pure string decoration, so rendering each span as its own plain text is faithful for a host with no ANSI surface, not a degradation.

When an extension hits an unsupported seam

| where | what happens | |---|---| | its factory (mount) | partial registrations unwound, extension not mounted | | a tool_call gate | the call is denied, permanently — a gate that cannot run never becomes one that permits | | a tool_result handler | the tool's own result passes through unchanged | | a tool body / command | that invocation fails with the seam named | | any other handler | logged; the extension is quarantined |

Quarantine disables the extension without unsubscribing it, so its tool-call gates keep denying instead of vanishing. Both moments are also appended to the session log as log-only audit events — pi-adapter/quarantine (extension, seam, call site) and pi-adapter/gate-deny (extension, tool name, callId, reason) — so a replayed session tells the operator which extension was quarantined and which calls its broken gate went on to deny. In a multi-session host each event lands on the session of the agent whose call was denied (a dsh Agent exposes .session), falling back to the last observed session only when no agent context exists. The events never enter the model surface; the stderr log line remains the floor when no session has been observed yet.

One upstream limit, stated plainly: none of the adapter's plugin-owned event types — pi-adapter/quarantine, pi-adapter/gate-deny, and the existing pi/entry / pi/label from pi.appendEntry/setLabel — are in dsh session-persistence's KNOWN_SESSION_EVENT_TYPES, and Session.append() has no way to mark an appended event ignorable. A session containing any of them therefore cannot resume under a standard harness with session-persistence mounted: the read path refuses the unknown type with SessionFormatUnsupportedError (deliberately — an unrecognized log might belong to a newer harness, and dsh over-refuses rather than resuming a session it cannot interpret). A feature request has been filed upstream for a plugin-owned event registration surface; until it lands, the audit trail is exact for live sessions but costs resumability.

onUnsupported: 'fail' refuses to start instead of quarantining. It propagates wherever a caller exists (mount, tools, commands, the tool-call waterfall); a fire-and-forget event listener has no caller, so there it degrades to the same loud log.

Translation tiers

adapt-interactive sits between adapt and unsupported: the seam exists in dsh, but only behind a capability the HOST may or may not mount — when an interactive host mounted a user-questions provider the adapter asks the real human; when it has not, the adapter answers with pi's no-selection convention (undefined/false, loudly logged), which extensions already treat as non-affirmative — never an invented answer. strictUi: true turns an unanswered ask into a seam error instead.

| pi API | dsh seam | tier | |---|---|---| | pi.registerTool({parameters, execute}) | ctx.tools.register() with mandatory output {schema, render}; typebox → parameters JSON Schema (1.x's non-enumerable ~kind/~optional/~unsafe metadata is stripped — dsh requires lossless JSON and rejects the whole catalogue otherwise); execute(callId, args, signal) arg bridge | adapt | | pi.registerCommand(name, {handler}) | ctx.commands.register({name, description, handler(invocation)}); the registration window is cordis's own DI: a ctx.inject(['commands']) child flushes buffered registrations the moment the commands fiber goes ACTIVE (during boot that is after plugin mount, so a mount-time probe always loses — dsh's plan-mode registers commands the same hook). Load completion warns how many commands are still buffered; a host without dsh-commands is caught at the first session/created checkpoint, which degrades each buffered command by name without dropping it (a late-activating service still registers it) | adapt | | pi.registerFlag / getFlag | in-process registry | direct | | pi.on("tool_call") (block) | tools/pre-execute waterfall — block → {kind:'deny'}; non-block delegates next(); event.input is a mutable clone of dsh's frozen arguments, so in-place rewrites are dropped (dsh decisions can't rewrite args) instead of throwing | adapt | | pi.on("tool_result") | tools/post-execute waterfall — returned content → {kind:'accept', content} | adapt | | pi.on("turn_start/end") | session/event stream filtered to turn/start / turn/end | adapt | | pi.on("session_start/shutdown") | session/created / session/disposed | direct | | pi.on("agent_start/end") | agent/session-start / agent/settled (closest verified events; payload shapes differ) | adapt | | pi.on("input") | agent/prompt-submit waterfall — carries the claimed UserMessage, so event.text is real; {action:'transform'} → {kind:'allow', content}, {action:'handled'} → {kind:'block'}. A handler that cannot run delegates rather than blocking: this admits the USER's own prompt, so failing closed would wedge the session | adapt | | pi.on("before_agent_start") | agent/prompt-submit — pi's "prompt settled, turn about to open" is the same edge. event.systemPrompt is absent (dsh assembles it asynchronously later); result-side prompt/message replacement degrades | adapt | | pi.on("session_compact") | compact/end without error in the session/event stream. reason: 'manual' only when the owner turn is null (a standalone manual transaction); compactionEntry/fromExtension/willRetry are omitted, not invented | adapt | | pi.on("agent_settled") | agent/status reaching idle. NOT agent/settled: that fires per terminal turn and still flickers mid-retry, whereas idle means "parked, waiting for queued work" — pi's actual "no retry/compaction/follow-up pending" | adapt | | pi.events extension bus | cordis pi-ext/* namespaced events (and emit is real, not a silent no-op) | adapt | | ctx.isIdle | live agent.status read | direct | | ctx.hasPendingMessages | inbox depth tracked through agent/inbox/* lifecycle events | adapt | | ctx.abort() | agent.cancel({kind:'user'}) — pi's abort is a human interrupt | adapt | | ctx.compact() | ctx.compact.compactNow() with the agent's reserveTurnAdmission(); fire-and-forget, failed attempts stay durable in the log | adapt | | ctx.getContextUsage() | folded from the log: latest request/context window + latest assistant/message usage; usage before a compact/start is stale (pi's "null right after compaction") | adapt | | ctx.getSystemPrompt / pi.getAllTools / getActiveTools | the latest request's assembled request/header — the exact text/tool set the model saw | adapt | | pi.getCommands | ctx.commands.list(agent); source/sourceInfo omitted — dsh descriptors carry no pi provenance | adapt | | pi.exec() | ctx.shell ShellExecutor resolve() → run(); pi's argv words are shell-quoted, since dsh takes a shell string where pi never uses a shell | adapt | | pi.sendUserMessage() | agent.followup(), or agent.steer() for deliverAs: 'steer'. NOT inject(): dsh documents that as appending context without running the model, while pi's contract always opens a turn | adapt | | ctx.ui.notify / setStatus / setWidget / setFooter | logged; strictUi promotes these to unsupported too | degrade | | ctx.ui.theme | plain-text Theme — identity styling, correct for a host with no ANSI surface | direct | | ctx.ui.confirm / select / input | dsh's ctx.userQuestions service (@deepseek-ai/dsh-user-questions): when the host mounted a UI provider the adapter asks the real human (confirm → Yes/No question, select → option list, input → free-text form; a cancelled/skipped ask maps to pi's undefined/false, which is a real outcome, not a fabricated choice). The calling agent and the active call's abort signal are passed through, so dsh's live-caller boundary (CALLER_NOT_LIVE/DELEGATED_CALLER — an owned child agent has no human to ask) and cancellation apply. When the host is headless — no service, or the service answers NO_PROVIDER — the ask resolves to pi's cancel convention (undefined/false) with a loud log, instead of inventing the answer; strictUi: true raises instead | adapt-interactive | | ctx.hasUI | live probe of the ctx.userQuestions SERVICE: it reports that the service is mounted, not that a UI provider sits behind it — with no provider registered the interactive seams above answer no-selection (loudly logged) rather than asking a human | adapt | | ctx.ui.editor / custom / onTerminalInput | no dsh vocabulary exists for these richer interaction shapes | unsupported | | ctx.isProjectTrusted, ctx.sessionManager.getSessionFile, ctx.modelRegistry.*, pi.getThinkingLevel | no truthful dsh answer | unsupported | | setSessionName / getSessionName (dsh HAS ctx.sessionTitle, but the service would not register in any host wiring reachable from this repo's harness, so the bridge is unproven and therefore unclaimed) / setModel / setThinkingLevel / registerProvider / registerShortcut / register*Renderer | — | degrade (loud) | | pi.appendEntry / setLabel + ctx.sessionManager.getEntries / getBranch / getEntry / getLeafEntry / getLeafId / getLabel / getHeader | the dsh session log — pi/entry and pi/label plugin-owned events, projected back through SessionProjection. See that module for where the two models diverge (linear log, so getBranch() ≡ getEntries()) | adapt | | unmapped pi events (model_select, message_*, tool_execution_*, before_provider_*, …) | — | degrade (loud at subscribe time) |

Usage

Install via a plugin manager

The published lib/ bundle is self-contained (jiti/schemastery inlined; only cordis stays external, so the host instance keeps service identity) and the repo carries a dsh.plugin.json manifest, so dsh plugin managers can install it directly from git:

dshx install https://github.com/cyzlmh/dsh-pi-adapter.git   # marisa (dir|tgz|git-url)
# plugin-registry (dir / tarball):
git clone https://github.com/cyzlmh/dsh-pi-adapter.git && dsh plugin install ./dsh-pi-adapter

Build from source

pnpm install
pnpm build       # tsdown bundle -> lib/index.js + tsc types -> lib/types/ (lib/ is checked in for manager installs)
pnpm typecheck
pnpm test              # hermetic fixtures + real dsh registry integration (self-skips without a sibling dsh checkout)
PI_ADAPTER_REAL_EXT=1 pnpm test   # opt-in: also load real extensions from ~/.pi/agent/extensions

The integration suite imports the built dsh packages from a sibling npm installation of @deepseek-ai/dsh (../dsh-npm by default, override with DSH_REPO=/path/to/dsh-npm-installation) and runs registrations, tool execution, and the pre-execute waterfall veto against the real ToolRuntime / CommandRuntime.

Mount as a cordis plugin in a dsh cordis.yml (verified end-to-end with the headless-agent example — a live DeepSeek request called a bridged pi_echo tool and a real ~/.pi todo.ts extension):

# Plugin specifiers resolve against this file's location, so a relative path
# to the BUILT adapter entry works without publishing the package.
# NOTE the asymmetry: `extensions`/`scanDirs` entries below resolve against
# the HOST PROCESS cwd, not this file — prefer absolute paths in overlays.
- id: pi-adapter
  name: ../../../dsh-pi-adapter/lib/index.js
  config:
    extensions:
      - ../dsh-pi-adapter/test/fixtures   # resolved against process cwd
    includePiHome: false     # set true to also scan ~/.pi/agent/extensions
    toolPrefix: 'pi_'        # avoid collisions with built-in tools
    strictUi: false
    onUnsupported: disable   # 'fail' refuses to start unless every extension fits

Run it (from the dsh repo root, needs DEEPSEEK_API_KEY via $DSH_HOME/.env):

node --import tsx packages/examples/cli-demo/src/bin.ts \
  --config examples/headless-agent/your-overlay.yml \
  "Use the pi_echo tool with text 'hello dsh' and report what it returned."

Layout

src/
  index.ts              # cordis plugin entry (apply + Config schema)
  compat/ExtensionApi.ts# ExtensionAPI bridge — full interface surface
  loader/jiti-loader.ts # jiti loading + pi-runtime alias resolution
test/
  fixtures/             # hermetic pi extensions (import-free factories)
  fixtures.test.ts      # loader tests (hermetic + opt-in real ~/.pi loading)
  bridge.test.ts        # unit tests against a contract-fake ctx (mirrors dsh's
                        # register() output validation, waterfall veto, frozen args)
  integration.test.ts   # ground truth against the real built dsh registry
  artifact.test.ts      # artifact plane: the published lib/index.js under plain
                        # Node (via scripts/artifact-smoke.mjs), guarding the
                        # bundled jiti's runtime babel.cjs
demo/                   # live E2E in a real dsh TUI session — see demo/README.md
scripts/
  copy-babel.mjs        # build step: ship jiti's dist/babel.cjs at package root
  artifact-smoke.mjs    # plain-Node smoke used by test/artifact.test.ts

Status

Working bridge for the core seams — tool/command registration and execution, tool_call/tool_result waterfalls, session/turn/agent lifecycle events, exec(), and loud degradation for everything else — verified against the real built dsh registry AND end-to-end through the dsh headless-agent example with live model calls (fixture pi_echo and a real ~/.pi todo.ts extension both executed). Remaining gaps: per-prompt agent_start (dsh has no exact equivalent), ctx.ui.editor/custom and other rich interaction shapes, provider/model bridging, pi's custom session-entry persistence, and event.input argument rewriting in tool_call (dsh pre-execute decisions cannot rewrite arguments).