@inhuman.tools/harness-client 0.0.0-stage → 0.2.0

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright 2026 Merkle Bonsai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# `@inhuman.tools/harness-client`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed client for the inhuman harness daemon, generated from
+[`@inhuman.tools/harness-contract`](https://www.npmjs.com/package/@inhuman.tools/harness-contract).
+It works over any transport that implements the four-member `Transport` interface.
+
+```sh
+npm install @inhuman.tools/harness-client
+npm install ws   # only for the Node entry point
+```
+
+## Node, over the daemon's unix socket
+
+```ts
+import { createHarnessClient } from "@inhuman.tools/harness-client";
+import { connectUnixSocket } from "@inhuman.tools/harness-client/node";
+
+const transport = await connectUnixSocket({
+  socketPath: "<kernel>/daemon.sock",
+  target: { host: "session", sessionId },
+});
+const client = createHarnessClient({ transport, onPark: (form) => ui.answer(form) });
+await client.session.kv.set({ key: "model", value: "m", scope: "session" });
+```
+
+## Browser or React Native
+
+Use `connectWebSocket(url)` from the main entry. `harnessUpgradePath(target)`
+builds the path part of the URL.
+
+## Notes
+
+- A method that can park returns a UI form instead of its result. `onPark`
+  receives it; see the contract's spec for `ui/resolve`.
+- Aborting a call with an `AbortSignal` rejects locally. There is no wire
+  cancel, so the daemon keeps working on it.
+
+The full wire description is in the
+[contract spec](https://github.com/here-build/inhuman-harness/tree/main/packages/harness-contract/spec).
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,33 @@
+import type { HarnessContract, UiForm } from "@inhuman.tools/harness-contract";
+import { type Client } from "@orpc/client";
+import type { ContractRouterClient } from "@orpc/contract";
+import { type ParkHandler } from "./link.js";
+import type { Transport } from "./transport.js";
+/**
+ * The typed client. A parking method's declared output is `result | UiForm`;
+ * the client either resolves the park (`onPark`) or rejects with
+ * `HarnessParkError`, so a call never returns the form and the type drops it.
+ */
+type WithoutPark<R> = R extends Client<infer C, infer I, infer O, infer E> ? Client<C, I, Exclude<O, UiForm>, E> : {
+    [K in keyof R]: WithoutPark<R[K]>;
+};
+export type HarnessClient = WithoutPark<ContractRouterClient<HarnessContract>>;
+export interface HarnessClientOptions {
+    readonly transport: Transport;
+    /**
+     * Called when a method parks for UI. Return the answer to resume the call
+     * (its result is what the original call resolves with). Without it a park
+     * rejects the call with `HarnessParkError`.
+     */
+    readonly onPark?: ParkHandler;
+}
+/**
+ * Typed client over one connection. The connection decides the host: a session
+ * socket also reaches kernel methods (the daemon falls through), a kernel socket
+ * does not reach session methods. Close the transport to dispose the client.
+ *
+ * Inputs and outputs are not re-validated here; the daemon validates both.
+ */
+export declare function createHarnessClient(options: HarnessClientOptions): HarnessClient;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAC;AAC/E,OAAO,EAAoB,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3D,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;GAIG;AACH,KAAK,WAAW,CAAC,CAAC,IAChB,CAAC,SAAS,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GAChD,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,GACnC;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC;AAE5C,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,oBAAoB,CAAC,eAAe,CAAC,CAAC,CAAC;AAE/E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAGhF"}

package/dist/client.js

@@ -0,0 +1,14 @@
+import { createORPCClient } from "@orpc/client";
+import { JsonRpcLink } from "./link.js";
+/**
+ * Typed client over one connection. The connection decides the host: a session
+ * socket also reaches kernel methods (the daemon falls through), a kernel socket
+ * does not reach session methods. Close the transport to dispose the client.
+ *
+ * Inputs and outputs are not re-validated here; the daemon validates both.
+ */
+export function createHarnessClient(options) {
+    const link = new JsonRpcLink(options.transport, options.onPark);
+    return createORPCClient(link);
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAe,MAAM,cAAc,CAAC;AAG7D,OAAO,EAAE,WAAW,EAAoB,MAAM,WAAW,CAAC;AAyB1D;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAA6B;IAC/D,MAAM,IAAI,GAAG,IAAI,WAAW,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAChE,OAAO,gBAAgB,CAAC,IAAI,CAAkB,CAAC;AACjD,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,19 @@
+import type { UiForm } from "@inhuman.tools/harness-contract";
+/** A JSON-RPC error reply. `code` is the JSON-RPC code (-32602 invalid params, -32603 internal, ...). */
+export declare class HarnessRpcError extends Error {
+    readonly code: number;
+    readonly data: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
+/** The method parked for UI and the client has no `onPark` handler. The park stays open on the daemon until the socket closes. */
+export declare class HarnessParkError extends Error {
+    readonly form: UiForm;
+    constructor(form: UiForm);
+}
+/** The connection ended (or was closed) before the call was answered. */
+export declare class HarnessClosedError extends Error {
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAC;AAE9D,yGAAyG;AACzG,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;gBAEX,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;CAM1D;AAED,kIAAkI;AAClI,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM;CAKzB;AAED,yEAAyE;AACzE,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,SAAsB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAIzE"}

package/dist/errors.js

@@ -0,0 +1,28 @@
+/** A JSON-RPC error reply. `code` is the JSON-RPC code (-32602 invalid params, -32603 internal, ...). */
+export class HarnessRpcError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.name = "HarnessRpcError";
+        this.code = code;
+        this.data = data;
+    }
+}
+/** The method parked for UI and the client has no `onPark` handler. The park stays open on the daemon until the socket closes. */
+export class HarnessParkError extends Error {
+    form;
+    constructor(form) {
+        super("the call parked for UI and no onPark handler is set");
+        this.name = "HarnessParkError";
+        this.form = form;
+    }
+}
+/** The connection ended (or was closed) before the call was answered. */
+export class HarnessClosedError extends Error {
+    constructor(message = "connection closed", options) {
+        super(message, options);
+        this.name = "HarnessClosedError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA,yGAAyG;AACzG,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,IAAI,CAAS;IACb,IAAI,CAAU;IAEvB,YAAY,IAAY,EAAE,OAAe,EAAE,IAAc;QACvD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,kIAAkI;AAClI,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,IAAI,CAAS;IAEtB,YAAY,IAAY;QACtB,KAAK,CAAC,qDAAqD,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,yEAAyE;AACzE,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAO,GAAG,mBAAmB,EAAE,OAA6B;QACtE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./client.js";
+export * from "./errors.js";
+export type { ParkHandler } from "./link.js";
+export * from "./transport.js";
+export { connectWebSocket, webSocketTransport, whenOpen, type WebSocketLike } from "./websocket.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./client.js";
+export * from "./errors.js";
+export * from "./transport.js";
+export { connectWebSocket, webSocketTransport, whenOpen } from "./websocket.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAE5B,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,QAAQ,EAAsB,MAAM,gBAAgB,CAAC"}

package/dist/link.d.ts

@@ -0,0 +1,18 @@
+import { type UiAnswer, type UiForm } from "@inhuman.tools/harness-contract";
+import type { ClientLink, ClientOptions } from "@orpc/client";
+import type { Transport } from "./transport.js";
+/**
+ * Answers a parked UI form. Returning resumes the parked call with the answer
+ * (`ui/resolve`); throwing cancels the park and rejects the original call.
+ */
+export type ParkHandler = (form: UiForm) => UiAnswer | Promise<UiAnswer>;
+/**
+ * oRPC `ClientLink` that speaks the daemon's JSON-RPC wire. A procedure's tree
+ * path is mapped to its wire name through the contract (`meta.method`).
+ */
+export declare class JsonRpcLink implements ClientLink<Record<never, never>> {
+    #private;
+    constructor(transport: Transport, onPark?: ParkHandler);
+    call(path: readonly string[], input: unknown, options: ClientOptions<Record<never, never>>): Promise<unknown>;
+}
+//# sourceMappingURL=link.d.ts.map

package/dist/link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../src/link.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,QAAQ,EACb,KAAK,MAAM,EACZ,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAOzE;;;GAGG;AACH,qBAAa,WAAY,YAAW,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;;gBAOtD,SAAS,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,WAAW;IAOhD,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;CA8EpH"}

package/dist/link.js

@@ -0,0 +1,107 @@
+import { encodeJsonRpcRequest, isUiForm, jsonRpcResponse, methodForPath, } from "@inhuman.tools/harness-contract";
+import { HarnessClosedError, HarnessParkError, HarnessRpcError } from "./errors.js";
+/**
+ * oRPC `ClientLink` that speaks the daemon's JSON-RPC wire. A procedure's tree
+ * path is mapped to its wire name through the contract (`meta.method`).
+ */
+export class JsonRpcLink {
+    #transport;
+    #onPark;
+    #waiters = new Map();
+    #nextId = 1;
+    #closed;
+    constructor(transport, onPark) {
+        this.#transport = transport;
+        this.#onPark = onPark;
+        transport.onMessage((text) => this.#deliver(text));
+        transport.onClose((cause) => this.#fail(new HarnessClosedError("connection closed", { cause })));
+    }
+    async call(path, input, options) {
+        const method = methodForPath(path);
+        if (method === undefined)
+            throw new Error(`not a procedure of the harness contract: ${path.join(".")}`);
+        let result = await this.#request(method, input ?? {}, options.signal);
+        while (isUiForm(result)) {
+            const form = result;
+            if (this.#onPark === undefined)
+                throw new HarnessParkError(form);
+            let answer;
+            try {
+                answer = await this.#onPark(form);
+            }
+            catch (error) {
+                // Free the parked call on the daemon rather than leave it until the socket closes.
+                await this.#request("ui/resolve", { pending: form.pending, kind: "cancel" }, options.signal).catch(() => undefined);
+                throw error;
+            }
+            result = await this.#request("ui/resolve", { pending: form.pending, ...answer }, options.signal);
+        }
+        return result;
+    }
+    #request(method, params, signal) {
+        if (this.#closed !== undefined)
+            return Promise.reject(this.#closed);
+        if (signal?.aborted === true)
+            return Promise.reject(abortReason(signal));
+        const id = this.#nextId++;
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                this.#waiters.delete(id);
+                reject(abortReason(signal));
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+            this.#waiters.set(id, {
+                resolve: (value) => {
+                    signal?.removeEventListener("abort", onAbort);
+                    resolve(value);
+                },
+                reject: (error) => {
+                    signal?.removeEventListener("abort", onAbort);
+                    reject(error);
+                },
+            });
+            try {
+                this.#transport.send(encodeJsonRpcRequest(id, method, params));
+            }
+            catch (error) {
+                this.#waiters.delete(id);
+                signal?.removeEventListener("abort", onAbort);
+                reject(error);
+            }
+        });
+    }
+    #deliver(text) {
+        let raw;
+        try {
+            raw = JSON.parse(text);
+        }
+        catch {
+            return;
+        }
+        const parsed = jsonRpcResponse.safeParse(raw);
+        if (!parsed.success || typeof parsed.data.id !== "number")
+            return;
+        const waiter = this.#waiters.get(parsed.data.id);
+        if (waiter === undefined)
+            return;
+        this.#waiters.delete(parsed.data.id);
+        if ("error" in parsed.data) {
+            const { code, message, data } = parsed.data.error;
+            waiter.reject(new HarnessRpcError(code, message, data));
+        }
+        else {
+            waiter.resolve(parsed.data.result);
+        }
+    }
+    #fail(error) {
+        this.#closed ??= error;
+        const waiters = [...this.#waiters.values()];
+        this.#waiters.clear();
+        for (const waiter of waiters)
+            waiter.reject(error);
+    }
+}
+function abortReason(signal) {
+    return signal?.reason ?? new DOMException("This operation was aborted", "AbortError");
+}
+//# sourceMappingURL=link.js.map

package/dist/link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link.js","sourceRoot":"","sources":["../src/link.ts"],"names":[],"mappings":"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"}

package/dist/node.d.ts

@@ -0,0 +1,12 @@
+import { type HarnessTarget, type Transport } from "./transport.js";
+export interface UnixSocketOptions {
+    /** Absolute path of the daemon socket, `<root>/daemon.sock`. */
+    readonly socketPath: string;
+    readonly target: HarnessTarget;
+}
+/**
+ * Connect to the daemon's unix socket from Node, using the `ws` package
+ * (an optional peer dependency, loaded only from this entry point).
+ */
+export declare function connectUnixSocket(options: UnixSocketOptions): Promise<Transport>;
+//# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAEA,OAAO,EAAsB,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGxF,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,CAGhF"}

package/dist/node.js

@@ -0,0 +1,12 @@
+import { WebSocket } from "ws";
+import { harnessUpgradePath } from "./transport.js";
+import { whenOpen } from "./websocket.js";
+/**
+ * Connect to the daemon's unix socket from Node, using the `ws` package
+ * (an optional peer dependency, loaded only from this entry point).
+ */
+export function connectUnixSocket(options) {
+    const socket = new WebSocket(`ws+unix://${options.socketPath}:${harnessUpgradePath(options.target)}`);
+    return whenOpen(socket);
+}
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAE/B,OAAO,EAAE,kBAAkB,EAAsC,MAAM,gBAAgB,CAAC;AACxF,OAAO,EAAE,QAAQ,EAAsB,MAAM,gBAAgB,CAAC;AAQ9D;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAA0B;IAC1D,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,aAAa,OAAO,CAAC,UAAU,IAAI,kBAAkB,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACtG,OAAO,QAAQ,CAAC,MAAkC,CAAC,CAAC;AACtD,CAAC"}

package/dist/transport.d.ts

@@ -0,0 +1,35 @@
+/**
+ * What the client needs from a connection: JSON-RPC text frames in and out.
+ * Binary frames (Yjs sync on the same socket) are not the client's business;
+ * a transport must not deliver them to `onMessage`.
+ */
+export interface Transport {
+    /** Send one JSON-RPC text frame. Throws if the connection is not open. */
+    send(text: string): void;
+    /** Subscribe to text frames. Returns the unsubscribe function. */
+    onMessage(listener: (text: string) => void): () => void;
+    /** Subscribe to the connection ending, with the cause when known. Returns the unsubscribe function. */
+    onClose(listener: (cause?: Error) => void): () => void;
+    /** Close the connection. Calls in flight reject with {@link HarnessClosedError}. */
+    close(): void;
+}
+/** Which daemon an upgrade reaches. See `packages/harness-contract/spec/README.md` for routing and fall-through. */
+export type HarnessTarget = {
+    readonly host: "kernel";
+} | {
+    readonly host: "project";
+    readonly path: string;
+} | {
+    readonly host: "session";
+    readonly sessionId: string;
+    readonly path?: string;
+} | {
+    readonly host: "session";
+    readonly path: string;
+    readonly sessionId?: string;
+};
+/** The WebSocket upgrade path (with query) for a target, e.g. `/session?sessionId=s1`. */
+export declare function harnessUpgradePath(target: HarnessTarget): string;
+/** Full upgrade URL on a base such as `ws://localhost:8080`, for bridges that expose the daemon over TCP. */
+export declare function harnessUpgradeUrl(base: string, target: HarnessTarget): string;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,0EAA0E;IAC1E,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,kEAAkE;IAClE,SAAS,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACxD,uGAAuG;IACvG,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACvD,oFAAoF;IACpF,KAAK,IAAI,IAAI,CAAC;CACf;AAED,oHAAoH;AACpH,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAChF;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAErF,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAMhE;AAED,6GAA6G;AAC7G,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,MAAM,CAE7E"}

package/dist/transport.js

@@ -0,0 +1,16 @@
+/** The WebSocket upgrade path (with query) for a target, e.g. `/session?sessionId=s1`. */
+export function harnessUpgradePath(target) {
+    if (target.host === "kernel")
+        return "/kernel";
+    const query = new URLSearchParams();
+    if (target.path !== undefined)
+        query.set("path", target.path);
+    if (target.host === "session" && target.sessionId !== undefined)
+        query.set("sessionId", target.sessionId);
+    return `/${target.host}?${query.toString()}`;
+}
+/** Full upgrade URL on a base such as `ws://localhost:8080`, for bridges that expose the daemon over TCP. */
+export function harnessUpgradeUrl(base, target) {
+    return `${base.replace(/\/+$/, "")}${harnessUpgradePath(target)}`;
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAuBA,0FAA0F;AAC1F,MAAM,UAAU,kBAAkB,CAAC,MAAqB;IACtD,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC/C,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAC;IACpC,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS;QAAE,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IAC9D,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS;QAAE,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;IAC1G,OAAO,IAAI,MAAM,CAAC,IAAI,IAAI,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC;AAC/C,CAAC;AAED,6GAA6G;AAC7G,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,MAAqB;IACnE,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC;AACpE,CAAC"}

package/dist/websocket.d.ts

@@ -0,0 +1,28 @@
+import type { Transport } from "./transport.js";
+/**
+ * The slice of the WHATWG `WebSocket` the transport uses. Browsers, React
+ * Native, Node's global `WebSocket` and the `ws` package all satisfy it.
+ */
+export interface WebSocketLike {
+    readonly readyState: number;
+    send(data: string): void;
+    close(): void;
+    addEventListener(type: "message", listener: (event: {
+        readonly data: unknown;
+    }) => void): void;
+    addEventListener(type: "close", listener: (event: {
+        readonly reason?: string;
+    }) => void): void;
+    addEventListener(type: "error", listener: (event: unknown) => void): void;
+    addEventListener(type: "open", listener: () => void): void;
+}
+/** Wrap an already open socket. Only string (text) frames are delivered; binary frames are ignored. */
+export declare function webSocketTransport(socket: WebSocketLike): Transport;
+/** Resolve once an open socket is ready, reject if it fails to open. */
+export declare function whenOpen(socket: WebSocketLike): Promise<Transport>;
+/**
+ * Connect with the platform `WebSocket` (browser, React Native, Node 22+).
+ * `url` is the full upgrade URL, see `harnessUpgradeUrl`.
+ */
+export declare function connectWebSocket(url: string): Promise<Transport>;
+//# sourceMappingURL=websocket.d.ts.map

package/dist/websocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../src/websocket.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,IAAI,IAAI,CAAC;IACd,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAC/F,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAC/F,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;IAC1E,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAC5D;AAID,uGAAuG;AACvG,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,CAqCnE;AAED,wEAAwE;AACxE,wBAAgB,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC,CAUlE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAEhE"}

package/dist/websocket.js

@@ -0,0 +1,66 @@
+import { HarnessClosedError } from "./errors.js";
+const OPEN = 1;
+/** Wrap an already open socket. Only string (text) frames are delivered; binary frames are ignored. */
+export function webSocketTransport(socket) {
+    const messages = new Set();
+    const closes = new Set();
+    let ended = false;
+    const end = (cause) => {
+        if (ended)
+            return;
+        ended = true;
+        for (const listener of closes)
+            listener(cause);
+    };
+    socket.addEventListener("message", (event) => {
+        if (typeof event.data !== "string")
+            return;
+        for (const listener of messages)
+            listener(event.data);
+    });
+    socket.addEventListener("close", (event) => {
+        end(event.reason === undefined || event.reason === "" ? undefined : new Error(event.reason));
+    });
+    socket.addEventListener("error", () => {
+        end(new Error("websocket error"));
+    });
+    return {
+        send(text) {
+            if (ended || socket.readyState !== OPEN)
+                throw new HarnessClosedError("websocket is not open");
+            socket.send(text);
+        },
+        onMessage(listener) {
+            messages.add(listener);
+            return () => messages.delete(listener);
+        },
+        onClose(listener) {
+            closes.add(listener);
+            return () => closes.delete(listener);
+        },
+        close() {
+            socket.close();
+            end();
+        },
+    };
+}
+/** Resolve once an open socket is ready, reject if it fails to open. */
+export function whenOpen(socket) {
+    return new Promise((resolve, reject) => {
+        if (socket.readyState === OPEN) {
+            resolve(webSocketTransport(socket));
+            return;
+        }
+        socket.addEventListener("open", () => resolve(webSocketTransport(socket)));
+        socket.addEventListener("error", () => reject(new HarnessClosedError("websocket failed to open")));
+        socket.addEventListener("close", () => reject(new HarnessClosedError("websocket closed before it opened")));
+    });
+}
+/**
+ * Connect with the platform `WebSocket` (browser, React Native, Node 22+).
+ * `url` is the full upgrade URL, see `harnessUpgradeUrl`.
+ */
+export function connectWebSocket(url) {
+    return whenOpen(new WebSocket(url));
+}
+//# sourceMappingURL=websocket.js.map

package/dist/websocket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.js","sourceRoot":"","sources":["../src/websocket.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@inhuman.tools/harness-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Transport-agnostic typed client for the harness daemon, built on the harness-contract.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js",
+      "default": "./dist/node.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!**/__tests__"
+  ],
+  "sideEffects": false,
+  "browserslist": [
+    "last 2 chrome versions",
+    "last 2 firefox versions",
+    "last 2 safari versions",
+    "ios_saf >= 16.4",
+    "node >= 22"
+  ],
+  "dependencies": {
+    "@orpc/client": "1.15.7",
+    "@orpc/contract": "1.15.7",
+    "@inhuman.tools/harness-contract": "^0.2.0"
+  },
+  "peerDependencies": {
+    "ws": "^8.18.3"
+  },
+  "peerDependenciesMeta": {
+    "ws": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/ws": "8.18.1",
+    "eslint": "9.39.2",
+    "typescript": "6.0.2",
+    "vitest": "4.1.0",
+    "ws": "8.18.3",
+    "@-internal-/eslint-configs": "0.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/here-build/inhuman-harness.git",
+    "directory": "packages/harness-client"
+  },
+  "author": "Merkle Bonsai",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsc -p tsconfig.json --noEmit && vitest run"
+  }
 }

package/src/client.ts

@@ -0,0 +1,40 @@
+import type { HarnessContract, UiForm } from "@inhuman.tools/harness-contract";
+import { createORPCClient, type Client } from "@orpc/client";
+import type { ContractRouterClient } from "@orpc/contract";
+
+import { JsonRpcLink, type ParkHandler } from "./link.js";
+import type { Transport } from "./transport.js";
+
+/**
+ * The typed client. A parking method's declared output is `result | UiForm`;
+ * the client either resolves the park (`onPark`) or rejects with
+ * `HarnessParkError`, so a call never returns the form and the type drops it.
+ */
+type WithoutPark<R> =
+  R extends Client<infer C, infer I, infer O, infer E>
+    ? Client<C, I, Exclude<O, UiForm>, E>
+    : { [K in keyof R]: WithoutPark<R[K]> };
+
+export type HarnessClient = WithoutPark<ContractRouterClient<HarnessContract>>;
+
+export interface HarnessClientOptions {
+  readonly transport: Transport;
+  /**
+   * Called when a method parks for UI. Return the answer to resume the call
+   * (its result is what the original call resolves with). Without it a park
+   * rejects the call with `HarnessParkError`.
+   */
+  readonly onPark?: ParkHandler;
+}
+
+/**
+ * Typed client over one connection. The connection decides the host: a session
+ * socket also reaches kernel methods (the daemon falls through), a kernel socket
+ * does not reach session methods. Close the transport to dispose the client.
+ *
+ * Inputs and outputs are not re-validated here; the daemon validates both.
+ */
+export function createHarnessClient(options: HarnessClientOptions): HarnessClient {
+  const link = new JsonRpcLink(options.transport, options.onPark);
+  return createORPCClient(link) as HarnessClient;
+}

package/src/errors.ts

@@ -0,0 +1,33 @@
+import type { UiForm } from "@inhuman.tools/harness-contract";
+
+/** A JSON-RPC error reply. `code` is the JSON-RPC code (-32602 invalid params, -32603 internal, ...). */
+export class HarnessRpcError extends Error {
+  readonly code: number;
+  readonly data: unknown;
+
+  constructor(code: number, message: string, data?: unknown) {
+    super(message);
+    this.name = "HarnessRpcError";
+    this.code = code;
+    this.data = data;
+  }
+}
+
+/** The method parked for UI and the client has no `onPark` handler. The park stays open on the daemon until the socket closes. */
+export class HarnessParkError extends Error {
+  readonly form: UiForm;
+
+  constructor(form: UiForm) {
+    super("the call parked for UI and no onPark handler is set");
+    this.name = "HarnessParkError";
+    this.form = form;
+  }
+}
+
+/** The connection ended (or was closed) before the call was answered. */
+export class HarnessClosedError extends Error {
+  constructor(message = "connection closed", options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "HarnessClosedError";
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./client.js";
+export * from "./errors.js";
+export type { ParkHandler } from "./link.js";
+export * from "./transport.js";
+export { connectWebSocket, webSocketTransport, whenOpen, type WebSocketLike } from "./websocket.js";

package/src/link.ts

@@ -0,0 +1,125 @@
+import {
+  encodeJsonRpcRequest,
+  isUiForm,
+  jsonRpcResponse,
+  methodForPath,
+  type UiAnswer,
+  type UiForm,
+} from "@inhuman.tools/harness-contract";
+import type { ClientLink, ClientOptions } from "@orpc/client";
+
+import { HarnessClosedError, HarnessParkError, HarnessRpcError } from "./errors.js";
+import type { Transport } from "./transport.js";
+
+/**
+ * Answers a parked UI form. Returning resumes the parked call with the answer
+ * (`ui/resolve`); throwing cancels the park and rejects the original call.
+ */
+export type ParkHandler = (form: UiForm) => UiAnswer | Promise<UiAnswer>;
+
+interface Waiter {
+  readonly resolve: (value: unknown) => void;
+  readonly reject: (error: unknown) => void;
+}
+
+/**
+ * oRPC `ClientLink` that speaks the daemon's JSON-RPC wire. A procedure's tree
+ * path is mapped to its wire name through the contract (`meta.method`).
+ */
+export class JsonRpcLink implements ClientLink<Record<never, never>> {
+  readonly #transport: Transport;
+  readonly #onPark: ParkHandler | undefined;
+  readonly #waiters = new Map<number, Waiter>();
+  #nextId = 1;
+  #closed: HarnessClosedError | undefined;
+
+  constructor(transport: Transport, onPark?: ParkHandler) {
+    this.#transport = transport;
+    this.#onPark = onPark;
+    transport.onMessage((text) => this.#deliver(text));
+    transport.onClose((cause) => this.#fail(new HarnessClosedError("connection closed", { cause })));
+  }
+
+  async call(path: readonly string[], input: unknown, options: ClientOptions<Record<never, never>>): Promise<unknown> {
+    const method = methodForPath(path);
+    if (method === undefined) throw new Error(`not a procedure of the harness contract: ${path.join(".")}`);
+    let result = await this.#request(method, input ?? {}, options.signal);
+    while (isUiForm(result)) {
+      const form = result;
+      if (this.#onPark === undefined) throw new HarnessParkError(form);
+      let answer: UiAnswer;
+      try {
+        answer = await this.#onPark(form);
+      } catch (error) {
+        // Free the parked call on the daemon rather than leave it until the socket closes.
+        await this.#request("ui/resolve", { pending: form.pending, kind: "cancel" }, options.signal).catch(
+          () => undefined,
+        );
+        throw error;
+      }
+      result = await this.#request("ui/resolve", { pending: form.pending, ...answer }, options.signal);
+    }
+    return result;
+  }
+
+  #request(method: string, params: unknown, signal: AbortSignal | undefined): Promise<unknown> {
+    if (this.#closed !== undefined) return Promise.reject(this.#closed);
+    if (signal?.aborted === true) return Promise.reject(abortReason(signal));
+    const id = this.#nextId++;
+    return new Promise<unknown>((resolve, reject) => {
+      const onAbort = (): void => {
+        this.#waiters.delete(id);
+        reject(abortReason(signal));
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+      this.#waiters.set(id, {
+        resolve: (value) => {
+          signal?.removeEventListener("abort", onAbort);
+          resolve(value);
+        },
+        reject: (error) => {
+          signal?.removeEventListener("abort", onAbort);
+          reject(error);
+        },
+      });
+      try {
+        this.#transport.send(encodeJsonRpcRequest(id, method, params));
+      } catch (error) {
+        this.#waiters.delete(id);
+        signal?.removeEventListener("abort", onAbort);
+        reject(error);
+      }
+    });
+  }
+
+  #deliver(text: string): void {
+    let raw: unknown;
+    try {
+      raw = JSON.parse(text);
+    } catch {
+      return;
+    }
+    const parsed = jsonRpcResponse.safeParse(raw);
+    if (!parsed.success || typeof parsed.data.id !== "number") return;
+    const waiter = this.#waiters.get(parsed.data.id);
+    if (waiter === undefined) return;
+    this.#waiters.delete(parsed.data.id);
+    if ("error" in parsed.data) {
+      const { code, message, data } = parsed.data.error;
+      waiter.reject(new HarnessRpcError(code, message, data));
+    } else {
+      waiter.resolve(parsed.data.result);
+    }
+  }
+
+  #fail(error: HarnessClosedError): void {
+    this.#closed ??= error;
+    const waiters = [...this.#waiters.values()];
+    this.#waiters.clear();
+    for (const waiter of waiters) waiter.reject(error);
+  }
+}
+
+function abortReason(signal: AbortSignal | undefined): unknown {
+  return signal?.reason ?? new DOMException("This operation was aborted", "AbortError");
+}

package/src/node.ts

@@ -0,0 +1,19 @@
+import { WebSocket } from "ws";
+
+import { harnessUpgradePath, type HarnessTarget, type Transport } from "./transport.js";
+import { whenOpen, type WebSocketLike } from "./websocket.js";
+
+export interface UnixSocketOptions {
+  /** Absolute path of the daemon socket, `<root>/daemon.sock`. */
+  readonly socketPath: string;
+  readonly target: HarnessTarget;
+}
+
+/**
+ * Connect to the daemon's unix socket from Node, using the `ws` package
+ * (an optional peer dependency, loaded only from this entry point).
+ */
+export function connectUnixSocket(options: UnixSocketOptions): Promise<Transport> {
+  const socket = new WebSocket(`ws+unix://${options.socketPath}:${harnessUpgradePath(options.target)}`);
+  return whenOpen(socket as unknown as WebSocketLike);
+}

package/src/transport.ts

@@ -0,0 +1,36 @@
+/**
+ * What the client needs from a connection: JSON-RPC text frames in and out.
+ * Binary frames (Yjs sync on the same socket) are not the client's business;
+ * a transport must not deliver them to `onMessage`.
+ */
+export interface Transport {
+  /** Send one JSON-RPC text frame. Throws if the connection is not open. */
+  send(text: string): void;
+  /** Subscribe to text frames. Returns the unsubscribe function. */
+  onMessage(listener: (text: string) => void): () => void;
+  /** Subscribe to the connection ending, with the cause when known. Returns the unsubscribe function. */
+  onClose(listener: (cause?: Error) => void): () => void;
+  /** Close the connection. Calls in flight reject with {@link HarnessClosedError}. */
+  close(): void;
+}
+
+/** Which daemon an upgrade reaches. See `packages/harness-contract/spec/README.md` for routing and fall-through. */
+export type HarnessTarget =
+  | { readonly host: "kernel" }
+  | { readonly host: "project"; readonly path: string }
+  | { readonly host: "session"; readonly sessionId: string; readonly path?: string }
+  | { readonly host: "session"; readonly path: string; readonly sessionId?: string };
+
+/** The WebSocket upgrade path (with query) for a target, e.g. `/session?sessionId=s1`. */
+export function harnessUpgradePath(target: HarnessTarget): string {
+  if (target.host === "kernel") return "/kernel";
+  const query = new URLSearchParams();
+  if (target.path !== undefined) query.set("path", target.path);
+  if (target.host === "session" && target.sessionId !== undefined) query.set("sessionId", target.sessionId);
+  return `/${target.host}?${query.toString()}`;
+}
+
+/** Full upgrade URL on a base such as `ws://localhost:8080`, for bridges that expose the daemon over TCP. */
+export function harnessUpgradeUrl(base: string, target: HarnessTarget): string {
+  return `${base.replace(/\/+$/, "")}${harnessUpgradePath(target)}`;
+}

package/src/websocket.ts

@@ -0,0 +1,79 @@
+import { HarnessClosedError } from "./errors.js";
+import type { Transport } from "./transport.js";
+
+/**
+ * The slice of the WHATWG `WebSocket` the transport uses. Browsers, React
+ * Native, Node's global `WebSocket` and the `ws` package all satisfy it.
+ */
+export interface WebSocketLike {
+  readonly readyState: number;
+  send(data: string): void;
+  close(): void;
+  addEventListener(type: "message", listener: (event: { readonly data: unknown }) => void): void;
+  addEventListener(type: "close", listener: (event: { readonly reason?: string }) => void): void;
+  addEventListener(type: "error", listener: (event: unknown) => void): void;
+  addEventListener(type: "open", listener: () => void): void;
+}
+
+const OPEN = 1;
+
+/** Wrap an already open socket. Only string (text) frames are delivered; binary frames are ignored. */
+export function webSocketTransport(socket: WebSocketLike): Transport {
+  const messages = new Set<(text: string) => void>();
+  const closes = new Set<(cause?: Error) => void>();
+  let ended = false;
+  const end = (cause?: Error): void => {
+    if (ended) return;
+    ended = true;
+    for (const listener of closes) listener(cause);
+  };
+  socket.addEventListener("message", (event) => {
+    if (typeof event.data !== "string") return;
+    for (const listener of messages) listener(event.data);
+  });
+  socket.addEventListener("close", (event) => {
+    end(event.reason === undefined || event.reason === "" ? undefined : new Error(event.reason));
+  });
+  socket.addEventListener("error", () => {
+    end(new Error("websocket error"));
+  });
+  return {
+    send(text) {
+      if (ended || socket.readyState !== OPEN) throw new HarnessClosedError("websocket is not open");
+      socket.send(text);
+    },
+    onMessage(listener) {
+      messages.add(listener);
+      return () => messages.delete(listener);
+    },
+    onClose(listener) {
+      closes.add(listener);
+      return () => closes.delete(listener);
+    },
+    close() {
+      socket.close();
+      end();
+    },
+  };
+}
+
+/** Resolve once an open socket is ready, reject if it fails to open. */
+export function whenOpen(socket: WebSocketLike): Promise<Transport> {
+  return new Promise<Transport>((resolve, reject) => {
+    if (socket.readyState === OPEN) {
+      resolve(webSocketTransport(socket));
+      return;
+    }
+    socket.addEventListener("open", () => resolve(webSocketTransport(socket)));
+    socket.addEventListener("error", () => reject(new HarnessClosedError("websocket failed to open")));
+    socket.addEventListener("close", () => reject(new HarnessClosedError("websocket closed before it opened")));
+  });
+}
+
+/**
+ * Connect with the platform `WebSocket` (browser, React Native, Node 22+).
+ * `url` is the full upgrade URL, see `harnessUpgradeUrl`.
+ */
+export function connectWebSocket(url: string): Promise<Transport> {
+  return whenOpen(new WebSocket(url) as unknown as WebSocketLike);
+}