@johnhenry/wsh 0.24.0 → 0.25.0

package/README.md

@@ -26,6 +26,7 @@ wsh is a pure-JS client library (with an optional Node server at `@johnhenry/wsh
 - [Quick Start](#quick-start)
 - [One-Shot Command Execution](#one-shot-command-execution)
 - [Node Server](#node-server)
+- [RPC channels (object mode)](#rpc-channels-object-mode)
 - [Attach and Resume](#attach-and-resume)
 - [Pinning a Self-Signed Certificate](#pinning-a-self-signed-certificate)
 - [API Overview](#api-overview)
@@ -545,6 +546,109 @@ the host to find it:
 | A client that primes anyway (older stock client, `primer` forced, other implementations) | `@johnhenry/wsh/server` | **The leading `0x00` is dropped:** if the first data on an exec stream is exactly one `0x00` byte it is discarded, never forwarded to the process's stdin. Only that first chunk is inspected; a later `0x00`, or a first chunk that is longer than one byte, is delivered untouched. The cost: a client whose genuine first stdin chunk is a lone NUL loses it. |
 | A client that neither announces nor primes (a third-party QMux client; the stock client always does one or the other) | `@johnhenry/wsh/server` | The host waits `bindTimeoutMs` (default 3000) for the stream, then drops the output and logs it. This cannot be fixed host-side: nothing about the stream has been sent, so there is nothing to bind. Such a client must send `QMuxStream.announce()` (an empty STREAM frame) or any first write -- a zero-length `write()` now does the same. |
 
+## RPC channels (object mode)
+
+An `rpc` channel is an ordinary QMux stream whose payload is a sequence of
+**objects**, not bytes -- wsh's counterpart of an SSH *subsystem*: SSH channels
+are byte streams, SFTP is a typed, id-correlated protocol layered inside one.
+Each message is one CBOR data item (a [CBOR sequence](https://www.rfc-editor.org/rfc/rfc8742),
+self-delimiting, no length prefix) shaped as JSON-RPC 2.0, so MCP maps 1:1 and
+binary values are native byte strings (`Uint8Array`). Stream-announce,
+backpressure and close/reset apply unchanged; the control plane, the Rust
+codegen and exec/pty byte streams do not change.
+
+```js
+// client
+const rpc = await client.openRpc('mcp', { timeoutMs: 30_000 });   // sugar over openSession({ type: 'rpc', protocol })
+const { tools } = await rpc.request('tools/list', {});            // rejects with RpcError
+rpc.notify('notifications/initialized');
+rpc.onRequest('sampling/createMessage', async (params, ctx) => ({ /* server -> client request */ }));
+const call = rpc.request('read', { path: 'big.bin' }, { onProgress: (chunk) => {} });   // $/progress chunks
+call.cancel();                                                    // $/cancel; rejects -32001 now, late answer dropped
+rpc.onProgress(call.id, (chunk) => {});                           // or attach to a request already in flight
+await rpc.close();
+
+// server
+import { createWshServer, mcpServerAdapter } from '@johnhenry/wsh/server';
+createWshServer({
+  auth, fs: { root: '/srv/files' },
+  rpc: {
+    'wsh-host': true,                       // host.info, host.ping
+    'wsh-fs': true,                         // the server's `fs`; or { root, readOnly, maxFileBytes }
+    mcp: mcpServerAdapter(mcpServer),       // any @modelcontextprotocol/sdk Server (or a factory for one per channel)
+    custom: (channel, ctx) => {             // anything else: a function run per opened channel
+      channel.onRequest('echo', (params, { signal, progress }) => params);
+    },
+  },
+});
+```
+
+**Negotiation.** The host advertises `rpc`, one `rpc-protocol:<name>` per
+protocol and `rpc-max-message:<bytes>` (default 1 MiB) in `ServerHello.features`.
+`openRpc()` / `openSession({ type: 'rpc', protocol })` refuse an unadvertised
+`rpc` or protocol with an `RpcError` (`code` -32000, `reason: 'UNSUPPORTED_PROTOCOL'`)
+**before sending any bytes**. `Open.command` carries the protocol name (the
+`Open` message has no other free field; `kind` is `'rpc'`).
+
+**Semantics.** `id` is unique per direction per channel and both sides may
+request. Responses are matched by `id` only (the class of bug behind #72).
+`$/cancel { id }` asks the callee to stop: it answers `-32001` at once, its
+`ctx.signal` aborts, and the caller drops any late result. `$/progress
+{ id, chunk }` notifications may precede the final response (file reads, logs).
+Closing the stream rejects every pending request with `-32001` / `reason:
+'channel-closed'`. Error codes: JSON-RPC's `-32700..-32603`, plus `-32000`
+unsupported protocol, `-32001` cancelled / timed out / closed, `-32002` too many
+requests in flight (`rpcMaxInflight`, default 64), `-32003` unauthorized.
+A message over the negotiated maximum is refused locally when sending and
+closes the channel when received.
+
+**Built-in protocols**
+
+| Protocol | Methods |
+|---|---|
+| `wsh-host` | `host.info` -> `{ version, protocol, features (this connection's ServerHello), hostFingerprint, user, rpc }`; `host.ping` -> `{ time }` |
+| `wsh-fs` | `stat`, `list`, `mkdir`, `remove`, `rename { path, newPath }`, `write { path, data, offset? }`, `upload { path, data, offset? }` (offset omitted/0 creates or truncates, later offsets continue in place: chunk big files), `read { path, offset?, length? }` and `download { path }` (the bytes arrive as `$/progress` chunks of at most 64 KiB; the result is `{ size, offset, length, eof }`). Same confinement as `fs`: no traversal or symlink escapes, `readOnly`, `maxFileBytes`; policy refusals are `-32003`. |
+| `mcp` | The MCP JSON-RPC surface verbatim; see below |
+
+When a host advertises `rpc-protocol:wsh-fs`, `fileStat` / `fileList` / `fileRead` /
+`fileWrite` / `fileRename` / `fileMkdir` / `fileRemove` use it (results keep the
+`FileResult` shape; `client.preferRpcFiles = false` opts out). The control-plane
+`FileOp`/`FileResult` path stays for hosts that do not advertise it.
+
+**MCP.** `mcpServerAdapter(server)` implements the official SDK's `Transport`
+interface over the channel, so any `Server` can be exposed (pass a factory
+`(ctx) => new Server(...)` for one per channel; an instance serves one channel
+at a time). On the other end, `mcpClientTransport(channel)` is a `Transport` for
+the SDK's `Client`:
+
+```js
+const channel = await client.openRpc('mcp');
+const mcp = new Client({ name: 'me', version: '1' }, { capabilities: {} });
+await mcp.connect(mcpClientTransport(channel));
+await mcp.callTool({ name: 'echo', arguments: { text: 'hi' } });
+```
+
+MCP is already JSON-RPC, so the adapter is a pass-through: request ids,
+results, errors and notifications (including `notifications/progress`) are
+forwarded verbatim. The one translation is cancellation: an MCP client abort
+(`notifications/cancelled`) becomes `$/cancel` on the wire, and an incoming
+`$/cancel` is delivered to the SDK as `notifications/cancelled`, so the tool
+handler's `signal` fires. The SDK is **not** imported by this package (the
+transport is structural); `@modelcontextprotocol/sdk` is an optional peer for
+whoever supplies the `Server`/`Client`, and the package root stays
+dependency-free and browser-safe.
+
+**Compatibility.** Purely additive. Old clients never open `rpc` sessions; an old
+host (or the Rust `wsh-server`, which has no `rpc` kind yet) does not advertise
+`rpc`, so a new client fails fast with `UNSUPPORTED_PROTOCOL` instead of waiting
+on an `OpenFail`. Only `@johnhenry/wsh/server` serves `rpc` today. Not goals: a
+replacement for byte streams (exec/pty are unchanged), a new transport (`rpc`
+rides WebSocket/QMux and WebTransport streams), or an auth change -- an `rpc`
+session is opened on an authenticated connection and per-method authorization is
+the handler's job (`-32003`; `ctx.user` / `ctx.fingerprint` identify the caller).
+Handlers run per channel, so register methods synchronously (or before the
+returned promise settles: inbound messages are held until it does).
+
 ## Attach and Resume
 
 Opening a PTY/exec session returns a session-scoped credential alongside the channel:
@@ -652,6 +756,8 @@ so options the platform gains later need no change here.
 | `WshKeyStore` | Ed25519 key management via IndexedDB + OPFS encrypted backup |
 | `WshFileTransfer` | File upload/download over dedicated streams |
 | `WshMcpBridge` | Remote MCP tool discovery and invocation |
+| `RpcChannel` / `RpcError` | Typed RPC channel (JSON-RPC 2.0 over a CBOR sequence): `client.openRpc(protocol)`; `RPC_FEATURE`, `rpcProtocolFeature(name)`, `RPC_ERROR`, `CborSequenceDecoder` |
+| `mcpClientTransport()` / `mcpServerAdapter()` (`/server`) | MCP SDK `Transport` over an `rpc` channel |
 | `SessionRecorder` | Record PTY I/O with timestamps (own schema, not asciicast v2) |
 | `SessionPlayer` | Replay recordings with original timing |
 | `generateKeyPair()` | Create Ed25519 key pair via Web Crypto |
@@ -714,6 +820,7 @@ than left to be found.
 | Remove a remote file | `WshClient.fileRemove()` | `file_transfer::remove()`, `wsh sftp`'s `rm` | **Wire-unified**: `FileOp`/`FileResult` (`op: "remove"`) -- refused today by every `wsh-server` release ("not yet implemented"), the same refusal on both sides |
 | Install an authorized key | `WshClient.addAuthorizedKey()` | `wsh_client::WshClient::add_authorized_key()`, `wsh copy-id` | **Wire-unified** (wsh #59): `AuthorizedKeyAdd`/`AuthorizedKeyResult`, replacing a Rust-CLI-only shell command with a message every implementation can send |
 | Host identity / TOFU | `WshKnownHosts` (localStorage-backed) | `KnownHosts`/`HostStatus` (`~/.wsh/known_hosts`-backed) | **Record unified, policy is not** (wsh #59): both pin `ServerHello.host_fingerprint`, which `@johnhenry/wsh/server` populates (with a proof of possession, [Host key](#host-key-fingerprint--tofu)) but no Rust `wsh-server` release does yet (see [Security](#security-model)). *When* to trust, prompt, or persist is deliberately left per-implementation -- a browser and a CLI have different UX for "first time seeing this host" |
+| Typed RPC channels (`openRpc`, `rpc` sessions; `wsh-host`, `wsh-fs`, `mcp`) | `WshClient.openRpc()`, `RpcChannel` | none yet (a Rust `wsh-server` does not advertise `rpc`; a JS client falls back to `FileOp` for files) | **JS server only, no wire change**: `Open { kind: 'rpc', command: <protocol> }` plus `rpc*` `ServerHello` features, negotiated so it fails fast elsewhere |
 | Interactive shell UI | none -- this SDK is a protocol client, not a terminal emulator; pair with xterm.js/ghostty-web | `wsh connect`, `wsh sftp` (line-oriented REPL) | **Deliberately not unified** -- a browser embeds a terminal widget the host page owns; a CLI process owns its own TTY |
 | Attach / resume | `attachSession()`, `resumeSession()`, `WshSession.seq` | `attach_session()`, `resume_session()` | **Wire-unified** (`Attach`/`Resume`/`Presence`); `seq` = cumulative output bytes. `@johnhenry/wsh/server` honours `last_seq` (bounded ring, gap errors) and answers Presence with `channel_id`/`seq`; the Rust `wsh-server` replays its whole ring and leaves them unset |
 | Reverse-connect / relay peer | `connectReverse()`, `trustRelayPeer()`; `@johnhenry/wsh/server`: `relay` option and `createReverseHost()` | `wsh reverse`, `wsh agent` (persistent, with startup-unit install) | **Wire-unified** (registration, discovery, signed peer records); **daemonization is CLI-only** -- a browser tab cannot be a background OS service. The Node relay is default-deny and bridges one operator per peer |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/wsh",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Web Shell \u2014 browser-native remote command execution over WebTransport and WebSocket with Ed25519 authentication",
   "type": "module",
   "main": "./src/index.mjs",
@@ -26,7 +26,8 @@
   "peerDependencies": {
     "@fails-components/webtransport": "^1.6.4",
     "@fails-components/webtransport-transport-http3-quiche": "^1.6.4",
-    "ws": "^8.0.0"
+    "ws": "^8.0.0",
+    "@modelcontextprotocol/sdk": "^1.17.0"
   },
   "peerDependenciesMeta": {
     "@fails-components/webtransport": {
@@ -37,6 +38,9 @@
     },
     "ws": {
       "optional": true
+    },
+    "@modelcontextprotocol/sdk": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -44,7 +48,8 @@
     "@fails-components/webtransport-transport-http3-quiche": "^1.6.4",
     "@johnhenry/browsermesh-primitives": "^0.2.0",
     "typescript": "^7.0.0",
-    "ws": "^8.21.0"
+    "ws": "^8.21.0",
+    "@modelcontextprotocol/sdk": "^1.17.0"
   },
   "scripts": {
     "test": "node --test test/*.test.mjs",
@@ -57,7 +62,8 @@
     "example:02": "node examples/02-tampered-challenge-fails-authentication.mjs",
     "example:03": "node examples/03-handshake-to-exec-over-in-process-pipe.mjs",
     "example:04": "node examples/04-recording-replays-with-original-timing.mjs",
-    "example:05": "node examples/05-remote-mcp-tools-called-through-bridge.mjs"
+    "example:05": "node examples/05-remote-mcp-tools-called-through-bridge.mjs",
+    "example:06": "node examples/06-rpc-requests-answered-out-of-order.mjs"
   },
   "keywords": [
     "wsh",

package/src/client.mjs

@@ -29,6 +29,7 @@ import {
   keyExchange as keyExchangeMsg,
   fileOp as fileOpMsg,
   fileChunk as fileChunkMsg,
+  fileResult as fileResultMsg,
   authorizedKeyAdd as authorizedKeyAddMsg,
   policyEval as policyEvalMsg, policyUpdate as policyUpdateMsg,
   detach as detachMsg,
@@ -40,6 +41,10 @@ import { signChallenge, exportPublicKeyRaw, signPeerRecord, verifyPeerRecord, im
 import { generateMlKemKeyPair, mlKemEncapsulate, mlKemDecapsulate } from './mlkem.mjs';
 import { WshSession } from './session.mjs';
 import { cborDecode } from './cbor.mjs';
+import {
+  RpcChannel, RpcError, RPC_ERROR, RPC_FEATURE, RPC_PROTOCOL_NAME_RE, RPC_DEFAULT_MAX_MESSAGE,
+  rpcProtocolFeature, parseRpcFeatures,
+} from './rpc.mjs';
 import {
   HostKeyError, newHostKeyNonce, hostKeyProofMessage, findHostKeyAdvert,
   HOST_KEY_NONCE_PREFIX,
@@ -58,6 +63,7 @@ const STATE_CLOSED        = 'closed';
 
 const DEFAULT_AUTH_TIMEOUT   = 10_000;  // ms
 const DEFAULT_OPEN_TIMEOUT   = 10_000;  // ms
+const FS_RPC_OPS = new Set(['stat', 'list', 'read', 'write', 'mkdir', 'remove', 'rename']);
 
 /**
  * ServerHello feature advertising that McpResult echoes McpCall's call_id.
@@ -677,10 +683,20 @@ export class WshClient {
    *   stream (without it they never bind the stream and drop all output).
    *   Skipped automatically against a host advertising `stream-announce`; pass
    *   `false` to never send it (e.g. a host that forwards stdin verbatim).
+   * @param {string} [opts.protocol] - For `type: 'rpc'` (wsh #85): the protocol to speak (`mcp`, `wsh-fs`,
+   *   `wsh-host`, or a host-defined name). Carried in `Open.command`. The session's data stream is a CBOR sequence
+   *   of JSON-RPC 2.0 messages -- use {@link WshClient#openRpc} to get an `RpcChannel` over it.
+   *   Throws `RpcError` (`UNSUPPORTED_PROTOCOL`) before sending anything if the host does not advertise it.
+   * @param {(session: WshSession) => void} [opts.attach] - Advanced: called synchronously the moment the data
+   *   stream is bound, before any received byte can be delivered (`openRpc` uses it to set `onData`).
    * @returns {Promise<WshSession>}
    */
-  async openSession({ type = 'pty', command, cols = 80, rows = 24, env, timeout = DEFAULT_OPEN_TIMEOUT, primer = true } = {}) {
+  async openSession({ type = 'pty', command, protocol, cols = 80, rows = 24, env, timeout = DEFAULT_OPEN_TIMEOUT, primer = true, attach } = {}) {
     this.#assertAuthenticated('openSession');
+    if (type === 'rpc') {
+      this.#assertRpcProtocol(protocol);
+      command = protocol;
+    }
     const requestedChannelId = this._nextChannelId();
 
     await this.#transport.sendControl(
@@ -696,6 +712,7 @@ export class WshClient {
         mode: 'session',
         kind: type,
         primer,
+        attach,
         requestedChannelId,
         resolve,
         reject,
@@ -709,6 +726,50 @@ export class WshClient {
     });
   }
 
+  /** Refuse an `rpc` open the host did not advertise, before any bytes are sent (wsh #85). */
+  #assertRpcProtocol(protocol) {
+    if (typeof protocol !== 'string' || !RPC_PROTOCOL_NAME_RE.test(protocol)) {
+      throw new RpcError(RPC_ERROR.INVALID_PARAMS, 'openSession({ type: "rpc" }) needs a protocol name', undefined, 'INVALID_PROTOCOL');
+    }
+    if (!this.hasFeature(RPC_FEATURE)) {
+      throw new RpcError(RPC_ERROR.UNSUPPORTED_PROTOCOL, `UNSUPPORTED_PROTOCOL: this host does not advertise "${RPC_FEATURE}" channels (cannot open "${protocol}")`, undefined, 'UNSUPPORTED_PROTOCOL');
+    }
+    if (!this.hasFeature(rpcProtocolFeature(protocol))) {
+      throw new RpcError(RPC_ERROR.UNSUPPORTED_PROTOCOL, `UNSUPPORTED_PROTOCOL: this host does not advertise the "${protocol}" rpc protocol`, undefined, 'UNSUPPORTED_PROTOCOL');
+    }
+  }
+
+  /**
+   * Open a typed (object-mode) RPC channel (wsh #85): sugar over `openSession({ type: 'rpc', protocol })` that
+   * returns an {@link RpcChannel} -- JSON-RPC 2.0 over a CBOR sequence on one QMux stream.
+   *
+   * @param {string} protocol - e.g. `'mcp'`, `'wsh-fs'`, `'wsh-host'`
+   * @param {object} [opts]
+   * @param {number} [opts.timeoutMs] - default timeout for every `request()` on the channel
+   * @param {number} [opts.openTimeout] - how long to wait for the host to open the channel
+   * @returns {Promise<RpcChannel>}
+   */
+  async openRpc(protocol, { timeoutMs, openTimeout = DEFAULT_OPEN_TIMEOUT } = {}) {
+    this.#assertAuthenticated('openRpc');
+    const { maxMessageBytes } = parseRpcFeatures(this.#serverFeatures);
+    let channel = null;
+    const session = await this.openSession({
+      type: 'rpc', protocol, timeout: openTimeout,
+      attach: (s) => {
+        channel = new RpcChannel({
+          maxMessageBytes: maxMessageBytes ?? RPC_DEFAULT_MAX_MESSAGE,
+          timeoutMs,
+          write: (bytes) => s.write(bytes),
+          close: () => s.close(),
+        });
+        s.onData = (bytes) => channel.feed(bytes);
+        s.onClose = (err) => channel.handleClose(err ? 'stream-error' : 'channel-closed');
+      },
+    });
+    channel.session = session;
+    return channel;
+  }
+
   /**
    * List locally tracked sessions with their current state.
    * @returns {Array<{channelId: number, kind: string, state: string}>}
@@ -1835,6 +1896,12 @@ export class WshClient {
    */
   async fileOperation(op, path, opts = {}, timeout = DEFAULT_OPEN_TIMEOUT) {
     this.#assertAuthenticated('fileOperation');
+    // wsh #85: a host that serves the `wsh-fs` rpc protocol is preferred over the FileOp/FileResult control path.
+    if (this.preferRpcFiles && FS_RPC_OPS.has(op) && this.hasFeature(rpcProtocolFeature('wsh-fs'))) {
+      let rpc = null;
+      try { rpc = await this.#fsChannel(); } catch { /* fall back to FileOp */ }
+      if (rpc) return this.#fileOperationRpc(rpc, op, path, opts, timeout);
+    }
     const channelId = this._nextChannelId();
     // FileOp and FileResult both carry channel_id; each call claims only the
     // result for its own id, so overlapping operations cannot swap replies (#72).
@@ -1880,6 +1947,77 @@ export class WshClient {
     );
   }
 
+  /**
+   * Use the `wsh-fs` rpc protocol for `fileStat`/`fileList`/`fileRead`/`fileWrite`/... when the host advertises it
+   * (default `true`); set `false` to always use the FileOp control path. Results keep the FileResult shape either way.
+   */
+  preferRpcFiles = true;
+  #fsRpc = null;
+
+  async #fsChannel() {
+    if (this.#fsRpc) {
+      const existing = await this.#fsRpc.catch(() => null);
+      if (existing && !existing.closed) return existing;
+      this.#fsRpc = null;
+    }
+    const opening = this.openRpc('wsh-fs');
+    this.#fsRpc = opening;
+    try { return await opening; } catch (err) { if (this.#fsRpc === opening) this.#fsRpc = null; throw err; }
+  }
+
+  /** `fileOperation` over `wsh-fs`, mapped back onto the FileResult shape the FileOp path returns. */
+  async #fileOperationRpc(rpc, op, path, opts, timeout) {
+    const channelId = this._nextChannelId();
+    const ok = (metadata = {}, entries = []) => fileResultMsg({ channelId, success: true, metadata, entries });
+    const timeoutMs = timeout;
+    try {
+      switch (op) {
+        case 'stat': return ok(await rpc.request('stat', { path }, { timeoutMs }));
+        case 'list': {
+          const r = await rpc.request('list', { path }, { timeoutMs });
+          return ok({ path: r.path }, r.entries);
+        }
+        case 'read': {
+          const parts = [];
+          const r = await rpc.request('read', { path, offset: opts.offset, length: opts.length ?? FILE_CHUNK_SIZE }, { timeoutMs, onProgress: (c) => { if (c instanceof Uint8Array) parts.push(c); } });
+          const data = new Uint8Array(parts.reduce((n, p) => n + p.byteLength, 0));
+          let at = 0;
+          for (const p of parts) { data.set(p, at); at += p.byteLength; }
+          return ok({ data, size: r.size });
+        }
+        case 'mkdir': case 'remove':
+          return ok(await rpc.request(op, { path }, { timeoutMs }));
+        case 'rename':
+          if (typeof opts.newPath !== 'string' || !opts.newPath) throw new TypeError('fileRename: newPath is required');
+          return ok(await rpc.request('rename', { path, newPath: opts.newPath }, { timeoutMs }));
+        case 'write': {
+          const data = typeof opts.data === 'string' ? new TextEncoder().encode(opts.data) : opts.data;
+          if (!(data instanceof Uint8Array)) throw new TypeError('fileWrite: data must be a string or Uint8Array');
+          const step = Math.max(256, Math.min(256 * 1024, rpc.maxMessageBytes - 1024));
+          const base = opts.offset === undefined || opts.offset === null ? undefined : Number(opts.offset);
+          let off = 0;
+          do {
+            const end = Math.min(off + step, data.byteLength);
+            const chunk = data.subarray(off, end);
+            // Whole-file replace streams as `upload` (offset 0 truncates, later offsets continue); an explicit
+            // offset writes in place chunk by chunk, never truncating.
+            if (base === undefined) await rpc.request('upload', { path, data: chunk, offset: off || undefined }, { timeoutMs });
+            else await rpc.request('write', { path, data: chunk, offset: base + off }, { timeoutMs });
+            off = end;
+          } while (off < data.byteLength);
+          return ok({ written: data.byteLength });
+        }
+        default: throw new Error(`unsupported file op ${op}`);
+      }
+    } catch (err) {
+      // Host-reported failures keep the FileResult contract (success: false); transport trouble still throws.
+      if (err instanceof RpcError && err.code !== RPC_ERROR.CANCELLED) {
+        return fileResultMsg({ channelId, success: false, errorMessage: err.message });
+      }
+      throw err;
+    }
+  }
+
   /** Stat a remote file. */
   async fileStat(path, timeout) { return this.fileOperation('stat', path, {}, timeout); }
   /** List a remote directory. */
@@ -2386,6 +2524,7 @@ export class WshClient {
 
       if (dataMode === 'virtual') {
         session._activateVirtual((m) => this.sendRelayControl(m));
+        pending.attach?.(session);
         pending.resolve(session);
         return;
       }
@@ -2397,6 +2536,7 @@ export class WshClient {
       this.#transport.openStream().then(
         async (stream) => {
           session._bind(stream.readable, stream.writable);
+          pending.attach?.(session);
           // The transport has already announced the stream, which is all a
           // current host needs. Older hosts only bind a stream on its first
           // byte, so exec (which has no stdin to send) writes a one-byte

package/src/index.d.ts

@@ -245,6 +245,146 @@ export const MCP_CALL_ID_FEATURE: 'mcp-call-id';
  */
 export const STREAM_ANNOUNCE_FEATURE: 'stream-announce';
 
+// ── Typed (object-mode) RPC channels -- wsh #85 ────────────────────────
+
+/** ServerHello feature: the host serves `rpc` sessions (`openSession({ type: 'rpc', protocol })`). */
+export const RPC_FEATURE: 'rpc';
+/** ServerHello feature prefix: one `rpc-protocol:<name>` per protocol the host serves. */
+export const RPC_PROTOCOL_PREFIX: 'rpc-protocol:';
+/** ServerHello feature prefix: `rpc-max-message:<bytes>`. */
+export const RPC_MAX_MESSAGE_PREFIX: 'rpc-max-message:';
+/** Largest single rpc message when the host does not say (1 MiB). */
+export const RPC_DEFAULT_MAX_MESSAGE: 1048576;
+/** Allowed protocol names. */
+export const RPC_PROTOCOL_NAME_RE: RegExp;
+/** `'rpc-protocol:' + name`. */
+export function rpcProtocolFeature(name: string): string;
+/** Read the rpc advertisement out of `ServerHello.features` (`client.features`). */
+export function parseRpcFeatures(features?: string[]): { enabled: boolean; protocols: string[]; maxMessageBytes: number };
+
+/** JSON-RPC's reserved error codes plus wsh's. */
+export const RPC_ERROR: Readonly<{
+  PARSE: -32700;
+  INVALID_REQUEST: -32600;
+  METHOD_NOT_FOUND: -32601;
+  INVALID_PARAMS: -32602;
+  INTERNAL: -32603;
+  /** The host does not serve the requested protocol. */
+  UNSUPPORTED_PROTOCOL: -32000;
+  /** Cancelled (`$/cancel`, a timeout, or the channel closing: see `RpcError.reason`). */
+  CANCELLED: -32001;
+  /** Too many requests in flight on the channel. */
+  STREAM_LIMIT: -32002;
+  /** Refused on policy grounds (confinement, read-only, a handler's own authorization). */
+  UNAUTHORIZED: -32003;
+}>;
+
+/** A JSON-RPC error: what `request()` rejects with, and what a handler throws to answer with one. */
+export class RpcError extends Error {
+  constructor(code: number, message: string, data?: unknown, reason?: string);
+  readonly code: number;
+  readonly data?: unknown;
+  /** A short machine-readable cause: `channel-closed`, `timeout`, `cancelled`, `aborted`, `message-too-large`, `UNSUPPORTED_PROTOCOL`. */
+  readonly reason?: string;
+  toJSON(): { code: number; message: string; data?: unknown };
+}
+
+/** Incremental decoder for a CBOR sequence (RFC 8742); feed bytes, get completed items. */
+export class CborSequenceDecoder {
+  constructor(opts?: { maxItemBytes?: number });
+  feed(chunk: Uint8Array): unknown[];
+  /** Bytes buffered towards an incomplete item. */
+  readonly pending: number;
+}
+
+/** What a request handler receives beside the params. */
+export interface RpcContext {
+  readonly id: string | number;
+  readonly method: string;
+  /** Aborts on `$/cancel` or channel close. */
+  readonly signal: AbortSignal;
+  readonly channel: RpcChannel;
+  /** Send a `$/progress` chunk for this request (resolves once written; no-op after cancel). */
+  progress(chunk: unknown): Promise<void>;
+}
+
+export interface RpcRequestOptions {
+  onProgress?: (chunk: any) => void;
+  signal?: AbortSignal;
+  /** Overrides the channel's default timeout; on expiry the request rejects with `-32001` / `timeout` and the callee is told. */
+  timeoutMs?: number;
+  /** Use this JSON-RPC id instead of the channel's counter (it must not be in flight). */
+  id?: string | number;
+}
+
+/** A pending request: a promise that also knows its id and can be cancelled. */
+export interface RpcRequestPromise<T = any> extends Promise<T> {
+  readonly id: string | number;
+  cancel(reason?: string): boolean;
+}
+
+export interface RpcChannelOptions {
+  write(bytes: Uint8Array): Promise<void> | void;
+  close?(): Promise<void> | void;
+  maxMessageBytes?: number;
+  timeoutMs?: number;
+  maxInflight?: number;
+}
+
+/**
+ * One end of a typed RPC channel: JSON-RPC 2.0 over a CBOR sequence on one QMux stream. Symmetric -- either side may
+ * request, notify and answer. Binary values are `Uint8Array`.
+ */
+export class RpcChannel {
+  constructor(opts: RpcChannelOptions);
+  /** The `WshSession` carrying this channel (client side, from `openRpc`). */
+  session?: WshSession;
+  readonly closed: boolean;
+  readonly closeReason: string | null;
+  readonly maxMessageBytes: number;
+  readonly pendingCount: number;
+  readonly inflightCount: number;
+  /** Called once when the channel ends. */
+  onClose: ((reason: string) => void) | null;
+
+  request<T = any>(method: string, params?: unknown, opts?: RpcRequestOptions): RpcRequestPromise<T>;
+  notify(method: string, params?: unknown): Promise<void>;
+  /** Cancel an outbound request: `$/cancel` to the callee, `-32001` locally, late responses dropped. */
+  cancel(id: string | number, reason?: string): boolean;
+  onRequest(method: string, handler: (params: any, ctx: RpcContext) => unknown): () => void;
+  onNotification(method: string, handler: (params: any) => void): () => void;
+  onProgress(id: string | number, fn: (chunk: any) => void): void;
+  setFallbackRequestHandler(fn: ((method: string, params: any, ctx: RpcContext) => unknown) | null): void;
+  setFallbackNotificationHandler(fn: ((method: string, params: any) => void) | null): void;
+  /** Pending requests reject with `-32001` / `channel-closed`; the stream is closed. */
+  close(reason?: string): Promise<void>;
+  /** Transport hooks. */
+  feed(bytes: Uint8Array): void;
+  handleClose(reason?: string): void;
+  hold(): void;
+  release(): void;
+}
+
+/**
+ * An MCP SDK `Transport` (structural -- the SDK is not imported) over an {@link RpcChannel}.
+ * `await mcpClient.connect(mcpClientTransport(await client.openRpc('mcp')))`.
+ */
+export class RpcMcpTransport {
+  constructor(channel: RpcChannel);
+  readonly channel: RpcChannel;
+  sessionId?: string;
+  onclose?: () => void;
+  onerror?: (error: Error) => void;
+  onmessage?: (message: any, extra?: any) => void;
+  start(): Promise<void>;
+  send(message: any, options?: any): Promise<void>;
+  close(): Promise<void>;
+}
+/** A transport for an MCP `Client` over a channel from `openRpc('mcp')`. */
+export function mcpClientTransport(channel: RpcChannel): RpcMcpTransport;
+/** A transport for an MCP `Server` over a server-side channel (`mcpServerAdapter` wraps this). */
+export function mcpServerTransport(channel: RpcChannel): RpcMcpTransport;
+
 /** A wsh protocol control message (all messages have a numeric `type`). */
 export interface WshMessage {
   type: number;
@@ -1633,8 +1773,15 @@ export interface WshConnectOptions extends WshHostKeyOptions {
 
 /** Options for WshClient.openSession(). */
 export interface WshOpenSessionOptions {
-  type?: 'pty' | 'exec';
+  type?: 'pty' | 'exec' | 'file' | 'rpc';
   command?: string;
+  /**
+   * `type: 'rpc'` only: the protocol to speak (`mcp`, `wsh-fs`, `wsh-host`, or a host-defined name). Throws
+   * `RpcError` (`UNSUPPORTED_PROTOCOL`) before sending anything if the host does not advertise it.
+   */
+  protocol?: string;
+  /** Advanced: called synchronously when the data stream binds, before any received byte is delivered. */
+  attach?: (session: WshSession) => void;
   cols?: number;
   rows?: number;
   env?: Record<string, string>;
@@ -1880,6 +2027,19 @@ export class WshClient {
    */
   openSession(opts?: WshOpenSessionOptions): Promise<WshSession>;
 
+  /**
+   * Open a typed (object-mode) RPC channel (wsh #85): JSON-RPC 2.0 over a CBOR sequence on one stream. Sugar over
+   * `openSession({ type: 'rpc', protocol })`. Throws `RpcError` (`UNSUPPORTED_PROTOCOL`) before sending any bytes
+   * if the host does not advertise `rpc` and `rpc-protocol:<protocol>`.
+   */
+  openRpc(protocol: string, opts?: { timeoutMs?: number; openTimeout?: number }): Promise<RpcChannel>;
+
+  /**
+   * Use the `wsh-fs` rpc protocol for `fileStat`/`fileList`/`fileRead`/`fileWrite`/... when the host advertises it
+   * (default `true`); `false` always uses the FileOp control path. Results keep the `FileResult` shape.
+   */
+  preferRpcFiles: boolean;
+
   /**
    * List locally tracked sessions with their current state.
    */

package/src/index.mjs

@@ -91,3 +91,10 @@ export { SessionRecorder, SessionPlayer } from './recording.mjs';
 
 // MCP bridge
 export { WshMcpBridge } from './mcp-bridge.mjs';
+
+// Typed (object-mode) RPC channels -- wsh #85
+export {
+  RpcChannel, RpcError, CborSequenceDecoder, RPC_ERROR, RPC_FEATURE, RPC_PROTOCOL_PREFIX, RPC_MAX_MESSAGE_PREFIX,
+  RPC_DEFAULT_MAX_MESSAGE, RPC_PROTOCOL_NAME_RE, rpcProtocolFeature, parseRpcFeatures,
+} from './rpc.mjs';
+export { RpcMcpTransport, mcpClientTransport, mcpServerTransport } from './rpc-mcp.mjs';