The Binding of DSH

English | 简体中文

A DSH plugin that enables bidirectional RPC between Host and Client through the native DSH Connection and Typert Gateway.

Features

• Targeted Host-to-Client calls for connected browser or Node peers.
• Symmetric Typert Gateway calls in both directions.
• Request correlation, cancellation, and connection lifecycle handling.
• Legacy hosts share the native events.host WebSocket for RPC and events.
• Modern hosts use Binding sockets for bidirectional RPC and native Gateway streams for events.

Connection owns peer addressing and lifecycle; Typert Gateway owns service descriptors, codecs, invocation, and errors.

Installation

npm install the-binding-of-dsh

The package declares its DSH client entrypoint and Harmony patches in package.json, so it can be enabled as a regular DSH plugin. Harmony 0.8.6 or newer derives the browser module dependency introduced by the Connection patch and orders the Binding module automatically.

Development

Requires Node.js 22.22.3 or newer.

npm install
npm run check

License

MIT

Browser events across DSH versions

BrowserPeerClient negotiates the event transport at connection opening. Legacy hosts retain onEvent() and its { channel, envelope: { rpcId, payload } } wire shape. The legacy decoder is bundled separately; modern installations do not need dsh-host-apiproxy. Domain payload types can be supplied to onEvent<T>() or BrowserPeerEvent<T> using the consumer's legacy DSH types.

On DSH 0.1.5/0.1.6, eventTransport is gateway-v1. Use subscribe(event, listener) for native notifications and handleEvent(event, handler) for waterfall requests. These preserve upstream event names and arguments; onEvent() does not synthesize legacy frames on modern hosts.

peer.subscribe('api-session/status', (...args) => refreshSessionStatus(args))
peer.handleEvent('approval/request', async ({ agentId, request, signal }) => {
  return await showApproval(agentId, request, signal)
})
await peer.connect()

Handlers receive eventId, agentId, the JSON request, and an AbortSignal. Return a result matching the upstream event contract; return undefined to continue to the next handler/Host, or throw to reject. Binding correlates and sends the response automatically. Host cancellation and disconnection abort the signal and suppress late results. Agent contexts are not reconstructed.

stream(endpoint, payload, signal) opens another native Gateway stream and returns an async iterable. Payloads use native wire arguments ({ args: ... }). Abort the signal or finish iteration to cancel that subscription.

connect() resolves only after the Gateway ready handshake. After a disconnect, call connect() again, or opt in to automatic retries with reconnectDelayMs. Event registrations survive reconnect; onState(true) should refetch application state and reopen business streams. Events are not replayed by Binding. close() stops retries, closes sockets, cancels requests and withdraws the remote contribution. Older clients requesting only legacy events still receive HTTP 409 from modern hosts.

Validation (2026-09-19): 31 tests pass with the legacy development baseline and Harmony 0.8.11. Isolated DSH 0.1.5-rc.2 and 0.1.6-alpha.2 Host tests pass forward/reverse RPC, lazy codecs, authentication refusal, Gateway notifications, waterfall result/delegation/rejection/cancellation and reconnect. Studio must consume these modern APIs before its event-driven UI can claim compatibility.

Run node test/upstream.e2e.mjs <isolated-dsh-root> <harmony-lib-bin-path> after building to repeat the modern Host test. It creates and removes an isolated profile, without model calls.