dsh-pi-extension-bridge

Readme

# dsh-pi-extension-bridge

[English](README.md) | [简体中文](README.zh-CN.md)

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.

```bash
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

```bash
# 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](docs/ARCHITECTURE.md) 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`](COMPATIBILITY_MATRIX.md)
- [`STATE.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:

```bash
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:

```bash
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.