dsh-pi-extension-bridge

dsh-pi-extension-bridge

English | 简体中文

A TypeScript compatibility bridge that adapts Pi Coding Agent extensions to DeepSeek DSH, including extension resources, tools, commands, lifecycle hooks, and Pi-style terminal UI rendering in the DSH Web client.

This project is an integration bridge, not a reimplementation of Pi or DSH. It prefers native host capabilities, maps semantics only where the correspondence is reliable, and fails explicitly when a lossless mapping is unavailable.

Highlights

• TypeScript-first source tree — src/ is authoritative; lib/index.js and lib/client.js are generated runtime bundles.
• Modular Host architecture — runtime/session adaptation, lifecycle hooks, resources/tools, message conversion, Typert protocol, UI registry, and terminal surface rendering are separated by responsibility.
• Pi extension loading — uses Pi's loader/runtime rather than maintaining a handwritten extension list.
• DSH-native integration — bridges scoped tools, commands, skills, prompt resources, model/thinking state, and lifecycle events without replacing DSH-native ownership where DSH already has the capability.
• Web terminal UI bridge — preserves ANSI frames, terminal-column width, overlays, custom TUI input, WTerm rendering, and Pi cursor metadata.
• Host-plane UI transport — the global Web Host owns the piExtensionUi Typert routes while Pi tools/commands stay session-scoped; revision-driven waitRevision() wakeups avoid recurring snapshot polling while the UI is static.
• Tool renderer bridge — Pi custom renderCall / renderResult output can render inside DSH tool views.
• Isolated regression workflow — Web validation is designed to run on a separate port without restarting the user's active DSH process.

Requirements

• Node.js 22+ (development has been validated with Node.js 24)
• DSH with the Web client/runtime services used by this bridge
• Pi Coding Agent installation/resources available to the Host

The bridge currently contains environment-oriented defaults for local Pi/DSH roots. Override them through bridge configuration when your installation paths differ.

Install for local DSH development

This repository is currently intended for local DSH plugin development rather than npm publication.

npm install
npm run typecheck
npm run build

The package keeps the runtime export contract:

• . → lib/index.js (Host)
• ./client → lib/client.js (Web Client)

Mount the package through your DSH/Cordis configuration or scoped preset. The current development setup intentionally keeps the bridge scoped to Pi-style sessions rather than globally changing every DSH session.

Development

# TypeScript correctness gate
npm run typecheck

# Build Host + Client bundles
npm run build

# Build one side only
npm run build:host
npm run build:client

# Syntax-check generated artifacts
node --check lib/index.js
node --check lib/client.js

Do not edit generated files under lib/ directly. Make changes under src/, then rebuild.

Architecture

Host composition is intentionally small; the large responsibilities live in dedicated modules:

Module	Responsibility
src/host/index.ts	Plugin composition, Host service registration, bridge assembly
src/host/runtime-bridge.ts	Pi runtime actions, model/thinking/session adaptation
src/host/ui-surface.ts	Terminal surfaces, overlays, ANSI/cursor projection, input routing
src/host/lifecycle.ts	Pi lifecycle hooks, prompt and command integration
src/host/resources.ts	Extension loading, resources, skills, tools and command adapters
src/host/messages.ts	DSH ↔ Pi message/replay conversion
src/host/ui-protocol.ts	piExtensionUi Typert wire descriptors
src/host/ui-registry.ts	Per-session UI bridge registry
src/host/config.ts	Configuration normalization
src/client/index.ts	DSH Client module composition and slot registration
src/client/terminal-layout.ts	Terminal metrics and overlay geometry
src/client/types.ts	Snapshot/frame types
src/client/errors.ts	Remote envelope and error decoding

See Architecture for the data flow and compatibility boundaries.

Pi UI contract

The browser side treats Pi UI output as terminal frames, not ordinary text:

• ANSI is preserved for WTerm; stripped lines are fallback/debug representation only.
• Width is measured in terminal columns using the actual browser monospace font metrics.
• Pi cursor markers are converted into cursor row/column metadata for hardware cursor and IME positioning.
• Focused custom components and overlays receive input before global extension shortcuts.
• Static UI produces no recurring /snapshot traffic; revision changes wake the Client and trigger the next snapshot fetch.

Compatibility and limitations

The project aims for explicit compatibility rather than pretending every Pi API has an exact DSH equivalent. Current implementation notes and historical validation evidence live in:

• COMPATIBILITY_MATRIX.md
• STATE.md

Some host-owned capabilities can only be partially mapped when DSH does not expose an equivalent public primitive. Those cases should remain explicit boundaries instead of being emulated with unsafe global state.

Regression testing

Never restart or replace a user's active DSH Web/TUI process just to test this bridge. Use an isolated port:

dsh --profile web --port 3081

At minimum, validate typecheck/build, generated bundle syntax, Web startup, ANSI styling, custom TUI input, cursor/IME positioning, overlay sizing, and extension shortcut routing.

Repository status

The TypeScript modularization is complete: the former monolithic Host source has been split by responsibility, the Host entry is now composition-oriented, the Client is TypeScript-based, and the current build/typecheck gates pass. STATE.md is the detailed engineering handoff record.

Contributing

Keep dependency direction simple: leaf protocol/config/conversion modules should not import the composition entry. Prefer a cohesive module over version-suffixed scratch files. Before submitting changes, run:

npm run typecheck && npm run build
node --check lib/index.js
node --check lib/client.js

License

No open-source license has been added yet. Public source visibility does not by itself grant reuse rights; add an explicit license if you want to permit redistribution or modification.