@rynx-ai/remote-runtime-client 0.1.9 → 0.1.10-beta.2

package/dist/browser-inspect-client.d.ts

@@ -0,0 +1,26 @@
+import { type RuntimeBrowserInspectClosedReason, type RuntimeBrowserInspectMessage, type RuntimeBrowserInspectTarget } from "@rynx-ai/protocol/runtime-browser-inspect";
+import { DirectRuntimeClientError } from "./errors.js";
+export interface DirectRuntimeBrowserInspectClientOptions {
+    timeoutMs?: number;
+    /** Cancels only the connect/authenticate/open barrier. */
+    signal?: AbortSignal;
+    liveness?: {
+        pingIntervalMs?: number;
+        inactivityTimeoutMs?: number;
+    };
+}
+export interface DirectRuntimeBrowserInspectConnection extends AsyncIterable<RuntimeBrowserInspectMessage> {
+    readonly target: RuntimeBrowserInspectTarget;
+    readonly daemonInstanceId: string;
+    /** Resolves after local or remote transport closure. */
+    readonly closed: Promise<void>;
+    send(message: RuntimeBrowserInspectMessage): Promise<void>;
+    /** Idempotently close this dedicated attachment. */
+    close(): Promise<void>;
+}
+export declare class DirectRuntimeBrowserInspectError extends DirectRuntimeClientError {
+    readonly reason: RuntimeBrowserInspectClosedReason;
+    constructor(reason: RuntimeBrowserInspectClosedReason, message: string);
+}
+/** Authenticate a fresh V5 socket and open exactly one semantic page target. */
+export declare function openDirectRuntimeBrowserInspect(untrustedCredential: unknown, untrustedTarget: unknown, options?: DirectRuntimeBrowserInspectClientOptions): Promise<DirectRuntimeBrowserInspectConnection>;

package/dist/browser-inspect-client.js

@@ -0,0 +1,731 @@
+import { createHash, createPublicKey, randomBytes, sign, verify, } from "node:crypto";
+import { decodeDirectRuntimeFrame, DIRECT_RUNTIME_BROWSER_INSPECT_BINDING_PROTOCOL, DIRECT_RUNTIME_BROWSER_INSPECT_PATH, DIRECT_RUNTIME_CLOSE_CODE, DIRECT_RUNTIME_MAX_HANDSHAKE_FRAME_BYTES, encodeClientAuthenticateCanonical, encodeClientAuthenticateProofPayload, encodeDirectRuntimeFrame, encodeServerAcceptedProofPayload, encodeServerHelloCanonical, encodeServerHelloProofPayload, } from "@rynx-ai/protocol/direct-runtime";
+import { encodeRuntimeBrowserInspectOpenFrame, parseRuntimeBrowserInspectMessage, parseRuntimeBrowserInspectServerFrame, parseRuntimeBrowserInspectTarget, RUNTIME_BROWSER_INSPECT_MAX_CONTROL_FRAME_BYTES, RUNTIME_BROWSER_INSPECT_MAX_MESSAGE_BYTES, } from "@rynx-ai/protocol/runtime-browser-inspect";
+import { REMOTE_RUNTIME_CORE_PROTOCOL } from "@rynx-ai/protocol/remote-runtime";
+import { DIRECT_RUNTIME_E2EE_MAX_ENVELOPE_BYTES, generateClientKeyExchange, } from "@rynx-ai/remote-runtime-e2ee";
+import WebSocket from "ws";
+import { parseDirectRuntimeClientIdentity, parseDirectRuntimeCredential, } from "./credential.js";
+import { clientError, DirectRuntimeClientError, } from "./errors.js";
+const DEFAULT_TIMEOUT_MS = 10_000;
+const MIN_TIMEOUT_MS = 100;
+const MAX_TIMEOUT_MS = 120_000;
+const DEFAULT_PING_INTERVAL_MS = 10_000;
+const DEFAULT_INACTIVITY_TIMEOUT_MS = 25_000;
+const MAX_LIVENESS_INTERVAL_MS = 5 * 60_000;
+const MAX_PRE_ACTIVATION_FRAMES = 4;
+const MAX_PRE_ACTIVATION_BYTES = 128 * 1024;
+const MAX_QUEUED_MESSAGE_BYTES = 32 * 1024 * 1024;
+const MAX_TRANSPORT_BUFFERED_BYTES = 32 * 1024 * 1024;
+export class DirectRuntimeBrowserInspectError extends DirectRuntimeClientError {
+    reason;
+    constructor(reason, message) {
+        super(inspectCloseErrorCode(reason), message);
+        this.reason = reason;
+        this.name = "DirectRuntimeBrowserInspectError";
+    }
+}
+/** Authenticate a fresh V5 socket and open exactly one semantic page target. */
+export async function openDirectRuntimeBrowserInspect(untrustedCredential, untrustedTarget, options = {}) {
+    if (options.signal?.aborted) {
+        throw clientError("closed", "Browser Inspect opening was cancelled");
+    }
+    const credential = parseDirectRuntimeCredential(untrustedCredential);
+    const identity = parseDirectRuntimeClientIdentity(credential, "authentication_failed");
+    const target = parseRuntimeBrowserInspectTarget(untrustedTarget);
+    const openFrame = {
+        type: "browser.inspect.open",
+        ...target,
+    };
+    const timeoutMs = parseTimeout(options.timeoutMs);
+    const socket = new BrowserInspectSocket(browserInspectEndpoint(credential.directEndpoint), timeoutMs, parseLiveness(options.liveness));
+    const abortOpening = () => {
+        socket.abort(clientError("closed", "Browser Inspect opening was cancelled"));
+    };
+    options.signal?.addEventListener("abort", abortOpening, { once: true });
+    const deadline = Date.now() + timeoutMs;
+    try {
+        await socket.open(remaining(deadline));
+        const keyExchange = generateClientKeyExchange(credential.serverEncryptionPublicKey);
+        await socket.startAuthentication(keyExchange.channel, encodeDirectRuntimeFrame(keyExchange.clientHello));
+        const ready = decodeHandshake(await socket.readAuthenticationFrame(remaining(deadline)), "e2ee.ready");
+        if (ready.type !== "e2ee.ready") {
+            throw clientError("protocol_error", "e2ee.ready must follow e2ee.client-hello");
+        }
+        const hello = decodeHandshake(await socket.readAuthenticationFrame(remaining(deadline)), "server.hello");
+        if (hello.type !== "server.hello") {
+            throw clientError("protocol_error", "Browser Inspect server.hello is missing");
+        }
+        assertInspectHello(hello, credential);
+        const helloFields = withoutSignature(hello);
+        const daemonPublicKey = createPublicKey({
+            key: Buffer.from(credential.identityPublicKey, "base64url"),
+            format: "der",
+            type: "spki",
+        });
+        if (!verify(null, encodeServerHelloProofPayload(keyExchange.channelBinding, helloFields), daemonPublicKey, Buffer.from(hello.signature, "base64url"))) {
+            throw clientError("authentication_failed", "Browser Inspect server.hello signature is invalid");
+        }
+        const authenticateFields = {
+            type: "client.authenticate",
+            mode: "connect",
+            role: "browser-inspect",
+            daemonId: hello.daemonId,
+            daemonInstanceId: hello.daemonInstanceId,
+            bindingProtocolVersion: DIRECT_RUNTIME_BROWSER_INSPECT_BINDING_PROTOCOL.currentVersion,
+            coreProtocolVersion: selectCoreProtocol(hello),
+            clientId: credential.clientId,
+            clientPublicKey: credential.clientPublicKey,
+            nonce: randomBytes(32).toString("base64url"),
+            grantId: credential.grantId,
+        };
+        const helloHash = sha256(encodeServerHelloCanonical(helloFields));
+        const authenticate = {
+            ...authenticateFields,
+            signature: sign(null, encodeClientAuthenticateProofPayload(keyExchange.channelBinding, helloHash, authenticateFields), identity.privateKey).toString("base64url"),
+        };
+        const authenticateHash = sha256(encodeClientAuthenticateCanonical(authenticateFields));
+        await socket.sendAuthenticationText(encodeDirectRuntimeFrame(authenticate));
+        const accepted = decodeHandshake(await socket.readAuthenticationFrame(remaining(deadline)), "server.accepted");
+        if (accepted.type !== "server.accepted") {
+            throw clientError("protocol_error", "Browser Inspect server.accepted is missing");
+        }
+        assertInspectAccepted(accepted, hello, authenticate, credential);
+        if (!verify(null, encodeServerAcceptedProofPayload(keyExchange.channelBinding, helloHash, authenticateHash, withoutSignature(accepted)), daemonPublicKey, Buffer.from(accepted.signature, "base64url"))) {
+            throw clientError("authentication_failed", "Browser Inspect server.accepted signature is invalid");
+        }
+        socket.activateInspect();
+        socket.markAuthenticated();
+        const connection = new BrowserInspectConnectionImpl(socket, target, hello.daemonInstanceId);
+        await socket.sendInspect({
+            binary: false,
+            data: encodeRuntimeBrowserInspectOpenFrame(openFrame),
+        });
+        await connection.waitUntilReady(remaining(deadline));
+        if (options.signal?.aborted) {
+            throw clientError("closed", "Browser Inspect opening was cancelled");
+        }
+        return connection;
+    }
+    catch (error) {
+        const normalized = normalizeError(error, "Browser Inspect handshake failed");
+        socket.abort(normalized);
+        await socket.close().catch(() => undefined);
+        throw normalized;
+    }
+    finally {
+        options.signal?.removeEventListener("abort", abortOpening);
+    }
+}
+class BrowserInspectConnectionImpl {
+    socket;
+    target;
+    daemonInstanceId;
+    closed;
+    readyPromise;
+    readyResolve;
+    readyReject;
+    closedResolve;
+    ready = false;
+    finished = false;
+    localClose = false;
+    terminal;
+    items = [];
+    queuedBytes = 0;
+    waiter;
+    constructor(socket, target, daemonInstanceId) {
+        this.socket = socket;
+        this.target = target;
+        this.daemonInstanceId = daemonInstanceId;
+        this.readyPromise = new Promise((resolve, reject) => {
+            this.readyResolve = resolve;
+            this.readyReject = reject;
+        });
+        this.closed = new Promise((resolve) => {
+            this.closedResolve = resolve;
+        });
+        socket.setInspectHandlers((message) => this.handleMessage(message), (error) => this.handleTerminal(error));
+    }
+    async waitUntilReady(timeoutMs) {
+        await withTimeout(this.readyPromise, timeoutMs, () => clientError("unreachable", "Browser Inspect ready barrier timed out"));
+    }
+    async send(untrustedMessage) {
+        if (this.finished) {
+            throw this.terminal ??
+                clientError("closed", "Browser Inspect connection is closed");
+        }
+        await this.socket.sendInspect(parseRuntimeBrowserInspectMessage(untrustedMessage));
+    }
+    async close() {
+        if (this.localClose)
+            return;
+        this.localClose = true;
+        this.finish();
+        await this.socket.close();
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => this.nextMessage(),
+            return: async () => {
+                await this.close();
+                return { done: true, value: undefined };
+            },
+        };
+    }
+    nextMessage() {
+        const item = this.items.shift();
+        if (item) {
+            this.queuedBytes -= item.bytes;
+            if (this.items.length === 0)
+                this.socket.resumeInspectInput();
+            return Promise.resolve({ done: false, value: item.message });
+        }
+        if (this.terminal)
+            return Promise.reject(this.terminal);
+        if (this.finished)
+            return Promise.resolve({ done: true, value: undefined });
+        if (this.waiter) {
+            return Promise.reject(clientError("protocol_error", "concurrent Browser Inspect iterator reads are not allowed"));
+        }
+        return new Promise((resolve, reject) => {
+            this.waiter = { resolve, reject };
+        });
+    }
+    handleMessage(message) {
+        try {
+            if (!this.ready) {
+                if (message.binary) {
+                    throw new Error("Browser Inspect binary data preceded ready");
+                }
+                if (Buffer.byteLength(message.data, "utf8") >
+                    RUNTIME_BROWSER_INSPECT_MAX_CONTROL_FRAME_BYTES) {
+                    throw new Error("Browser Inspect ready frame is too large");
+                }
+                const frame = parseRuntimeBrowserInspectServerFrame(JSON.parse(message.data));
+                if (frame.type === "browser.inspect.closed") {
+                    throw new DirectRuntimeBrowserInspectError(frame.reason, frame.message ?? `Browser Inspect closed: ${frame.reason}`);
+                }
+                this.ready = true;
+                this.readyResolve();
+                return;
+            }
+            this.enqueue(message);
+        }
+        catch (error) {
+            const normalized = error instanceof DirectRuntimeClientError
+                ? error
+                : clientError("protocol_error", "invalid Browser Inspect opening response", error);
+            this.socket.abort(normalized);
+            this.handleTerminal(normalized);
+        }
+    }
+    enqueue(message) {
+        if (this.finished)
+            return;
+        if (this.waiter) {
+            const waiter = this.waiter;
+            this.waiter = undefined;
+            waiter.resolve({ done: false, value: message });
+            return;
+        }
+        const bytes = messageBytes(message);
+        if (this.queuedBytes + bytes > MAX_QUEUED_MESSAGE_BYTES) {
+            throw new Error("Browser Inspect inbound queue is full");
+        }
+        this.items.push({ message, bytes });
+        this.queuedBytes += bytes;
+        if (this.items.length === 1)
+            this.socket.pauseInspectInput();
+    }
+    handleTerminal(error) {
+        if (this.finished)
+            return;
+        if (this.ready &&
+            error.code === "closed" &&
+            error.webSocketCloseCode === 1000) {
+            this.finish();
+            return;
+        }
+        this.terminal = error;
+        this.readyReject(error);
+        this.finish(error);
+    }
+    finish(error) {
+        if (this.finished)
+            return;
+        this.finished = true;
+        this.closedResolve();
+        if (!this.ready && !error) {
+            this.readyReject(clientError("closed", "Browser Inspect closed before ready"));
+        }
+        if (this.waiter) {
+            const waiter = this.waiter;
+            this.waiter = undefined;
+            if (error)
+                waiter.reject(error);
+            else
+                waiter.resolve({ done: true, value: undefined });
+        }
+    }
+}
+class BrowserInspectSocket {
+    liveness;
+    websocket;
+    opened;
+    openResolve;
+    openReject;
+    authenticationChannel;
+    inspectActive = false;
+    awaitingPlaintextReady = false;
+    authenticationQueue = [];
+    authenticationQueuedBytes = 0;
+    authenticationWaiter;
+    messageHandler;
+    terminalHandler;
+    terminal;
+    authenticated = false;
+    localClose = false;
+    livenessTimer;
+    lastInboundActivityAt = 0;
+    constructor(endpoint, timeoutMs, liveness) {
+        this.liveness = liveness;
+        this.opened = new Promise((resolve, reject) => {
+            this.openResolve = resolve;
+            this.openReject = reject;
+        });
+        this.websocket = new WebSocket(endpoint, {
+            rejectUnauthorized: true,
+            followRedirects: false,
+            handshakeTimeout: timeoutMs,
+            perMessageDeflate: false,
+            maxPayload: Math.max(DIRECT_RUNTIME_E2EE_MAX_ENVELOPE_BYTES, RUNTIME_BROWSER_INSPECT_MAX_MESSAGE_BYTES),
+        });
+        this.websocket.on("open", () => {
+            this.noteActivity();
+            this.startLiveness();
+            this.openResolve();
+        });
+        this.websocket.on("message", (data, isBinary) => {
+            this.noteActivity();
+            try {
+                this.handleWireRecord(rawDataBytes(data), isBinary);
+            }
+            catch (error) {
+                this.abort(clientError("protocol_error", "invalid Browser Inspect frame", error));
+            }
+        });
+        this.websocket.on("ping", () => this.noteActivity());
+        this.websocket.on("pong", () => this.noteActivity());
+        this.websocket.on("unexpected-response", (_request, response) => {
+            response.resume();
+            this.abort(clientError(response.statusCode === 401 || response.statusCode === 403
+                ? "authentication_failed"
+                : response.statusCode === 429 || response.statusCode === 503
+                    ? "unreachable"
+                    : "protocol_error", `Browser Inspect WebSocket upgrade failed with HTTP ${response.statusCode ?? "unknown"}`));
+        });
+        this.websocket.on("error", (error) => {
+            this.fail(this.authenticated ? closedError(error) : mapWebSocketError(error));
+        });
+        this.websocket.on("close", (code, reason) => {
+            const suffix = reason.length === 0
+                ? ""
+                : `: ${reason.toString("utf8").slice(0, 256)}`;
+            this.fail(webSocketCloseError(code, suffix, this.localClose));
+        });
+    }
+    async open(timeoutMs) {
+        await withTimeout(this.opened, timeoutMs, () => clientError("unreachable", "Browser Inspect WebSocket connection timed out"));
+    }
+    async startAuthentication(channel, clientHello) {
+        if (this.authenticationChannel) {
+            throw clientError("protocol_error", "E2EE is already initialized");
+        }
+        this.authenticationChannel = channel;
+        this.awaitingPlaintextReady = true;
+        await this.sendWire(clientHello, false);
+    }
+    async readAuthenticationFrame(timeoutMs) {
+        if (this.authenticationWaiter) {
+            throw clientError("protocol_error", "concurrent Browser Inspect handshake reads are not allowed");
+        }
+        const queued = this.authenticationQueue.shift();
+        if (queued) {
+            this.authenticationQueuedBytes -= queued.byteLength;
+            return queued;
+        }
+        if (this.terminal)
+            throw this.terminal;
+        return await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                if (this.authenticationWaiter?.timer !== timer)
+                    return;
+                this.authenticationWaiter = undefined;
+                reject(clientError("unreachable", "Browser Inspect handshake timed out"));
+            }, timeoutMs);
+            timer.unref?.();
+            this.authenticationWaiter = { resolve, reject, timer };
+        });
+    }
+    async sendAuthenticationText(plaintext) {
+        const channel = this.authenticationChannel;
+        if (!channel) {
+            throw clientError("protocol_error", "Browser Inspect authentication E2EE is unavailable");
+        }
+        await this.sendWire(channel.seal(plaintext), false);
+    }
+    activateInspect() {
+        if (this.authenticationWaiter || this.authenticationQueue.length > 0) {
+            throw clientError("protocol_error", "Browser Inspect handshake has unread frames");
+        }
+        this.inspectActive = true;
+        this.authenticationChannel = undefined;
+    }
+    markAuthenticated() {
+        this.authenticated = true;
+    }
+    setInspectHandlers(onMessage, onTerminal) {
+        if (this.messageHandler) {
+            throw clientError("protocol_error", "Browser Inspect socket is already active");
+        }
+        this.messageHandler = onMessage;
+        this.terminalHandler = onTerminal;
+        if (this.terminal)
+            onTerminal(this.terminal);
+    }
+    async sendInspect(untrustedMessage) {
+        const message = parseRuntimeBrowserInspectMessage(untrustedMessage);
+        if (this.terminal || this.websocket.readyState !== WebSocket.OPEN) {
+            throw this.terminal ??
+                clientError("closed", "Browser Inspect connection is not open");
+        }
+        if (!this.inspectActive) {
+            throw clientError("protocol_error", "Browser Inspect data stream is unavailable");
+        }
+        try {
+            await this.sendWire(message.data, message.binary);
+        }
+        catch (error) {
+            const normalized = normalizeError(error, "Browser Inspect send failed");
+            this.abort(normalized);
+            throw normalized;
+        }
+    }
+    pauseInspectInput() {
+        if (this.websocket.readyState === WebSocket.OPEN)
+            this.websocket.pause();
+    }
+    resumeInspectInput() {
+        if (this.websocket.readyState === WebSocket.OPEN)
+            this.websocket.resume();
+    }
+    abort(error) {
+        this.fail(error);
+        if (this.websocket.readyState !== WebSocket.CLOSED) {
+            this.websocket.terminate();
+        }
+    }
+    async close() {
+        this.stopLiveness();
+        if (this.websocket.readyState === WebSocket.CLOSED)
+            return;
+        this.localClose = true;
+        await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                if (this.websocket.readyState !== WebSocket.CLOSED) {
+                    this.websocket.terminate();
+                }
+                resolve();
+            }, 1_000);
+            timer.unref?.();
+            this.websocket.once("close", () => {
+                clearTimeout(timer);
+                resolve();
+            });
+            if (this.websocket.readyState === WebSocket.CONNECTING) {
+                this.websocket.terminate();
+            }
+            else {
+                this.websocket.close(1000, "client closed");
+            }
+        });
+    }
+    handleWireRecord(bytes, binary) {
+        if (this.inspectActive) {
+            this.messageHandler?.(binary
+                ? { binary: true, data: new Uint8Array(bytes) }
+                : { binary: false, data: decodeText(bytes) });
+            return;
+        }
+        if (binary) {
+            throw clientError("protocol_error", "binary traffic preceded Browser Inspect activation");
+        }
+        const authenticationChannel = this.authenticationChannel;
+        if (!authenticationChannel) {
+            throw clientError("protocol_error", "server traffic preceded Browser Inspect E2EE setup");
+        }
+        const plaintext = this.awaitingPlaintextReady
+            ? (this.awaitingPlaintextReady = false, bytes)
+            : Uint8Array.from(Buffer.from(authenticationChannel.open(decodeText(bytes)), "utf8"));
+        if (plaintext.byteLength > DIRECT_RUNTIME_MAX_HANDSHAKE_FRAME_BYTES) {
+            throw clientError("protocol_error", "Browser Inspect handshake frame is too large");
+        }
+        this.deliverAuthentication(plaintext);
+    }
+    deliverAuthentication(frame) {
+        if (this.authenticationWaiter) {
+            const waiter = this.authenticationWaiter;
+            this.authenticationWaiter = undefined;
+            clearTimeout(waiter.timer);
+            waiter.resolve(frame);
+            return;
+        }
+        if (this.authenticationQueue.length >= MAX_PRE_ACTIVATION_FRAMES ||
+            this.authenticationQueuedBytes + frame.byteLength > MAX_PRE_ACTIVATION_BYTES) {
+            throw clientError("protocol_error", "too many Browser Inspect handshake frames arrived");
+        }
+        this.authenticationQueue.push(frame);
+        this.authenticationQueuedBytes += frame.byteLength;
+    }
+    async sendWire(frame, binary) {
+        if (this.terminal || this.websocket.readyState !== WebSocket.OPEN) {
+            throw this.terminal ??
+                clientError("closed", "Browser Inspect connection is not open");
+        }
+        const bytes = typeof frame === "string"
+            ? Buffer.byteLength(frame, "utf8")
+            : frame.byteLength;
+        if (bytes > Math.max(DIRECT_RUNTIME_E2EE_MAX_ENVELOPE_BYTES, RUNTIME_BROWSER_INSPECT_MAX_MESSAGE_BYTES) ||
+            this.websocket.bufferedAmount + bytes > MAX_TRANSPORT_BUFFERED_BYTES) {
+            throw clientError("unreachable", "Browser Inspect output buffer is full");
+        }
+        await new Promise((resolve, reject) => {
+            try {
+                this.websocket.send(frame, { binary, compress: false }, (error) => {
+                    if (error) {
+                        reject(this.authenticated
+                            ? closedError(error)
+                            : mapWebSocketError(error));
+                    }
+                    else {
+                        resolve();
+                    }
+                });
+            }
+            catch (error) {
+                reject(this.authenticated ? closedError(error) : mapWebSocketError(error));
+            }
+        });
+    }
+    fail(error) {
+        if (this.terminal)
+            return;
+        this.terminal = error;
+        this.stopLiveness();
+        this.openReject(error);
+        if (this.authenticationWaiter) {
+            clearTimeout(this.authenticationWaiter.timer);
+            this.authenticationWaiter.reject(error);
+            this.authenticationWaiter = undefined;
+        }
+        this.terminalHandler?.(error);
+    }
+    noteActivity() {
+        this.lastInboundActivityAt = Date.now();
+    }
+    startLiveness() {
+        this.livenessTimer = setInterval(() => {
+            if (this.terminal)
+                return;
+            if (Date.now() - this.lastInboundActivityAt >
+                this.liveness.inactivityTimeoutMs) {
+                this.abort(clientError(this.authenticated ? "closed" : "unreachable", "Browser Inspect peer stopped responding"));
+                return;
+            }
+            if (this.websocket.readyState === WebSocket.OPEN)
+                this.websocket.ping();
+        }, this.liveness.pingIntervalMs);
+        this.livenessTimer.unref?.();
+    }
+    stopLiveness() {
+        if (this.livenessTimer)
+            clearInterval(this.livenessTimer);
+        this.livenessTimer = undefined;
+    }
+}
+function assertInspectHello(hello, credential) {
+    if (hello.role !== "browser-inspect") {
+        throw clientError("protocol_error", "Browser Inspect server.hello has the wrong role");
+    }
+    if (hello.daemonId !== credential.daemonId) {
+        throw clientError("identity_mismatch", "Browser Inspect daemonId differs from the pin");
+    }
+    if (hello.identityPublicKey !== credential.identityPublicKey) {
+        throw clientError("identity_mismatch", "Browser Inspect identity key differs from the pin");
+    }
+    if (hello.bindingProtocolVersion !==
+        DIRECT_RUNTIME_BROWSER_INSPECT_BINDING_PROTOCOL.currentVersion ||
+        hello.minimumCompatibleBindingVersion !==
+            DIRECT_RUNTIME_BROWSER_INSPECT_BINDING_PROTOCOL.minimumCompatibleVersion) {
+        throw clientError("incompatible", "Browser Inspect binding protocol is incompatible");
+    }
+}
+function assertInspectAccepted(accepted, hello, authenticate, credential) {
+    if (accepted.role !== "browser-inspect" ||
+        authenticate.role !== "browser-inspect" ||
+        accepted.daemonId !== hello.daemonId ||
+        accepted.daemonId !== credential.daemonId ||
+        accepted.daemonInstanceId !== hello.daemonInstanceId ||
+        accepted.bindingProtocolVersion !== authenticate.bindingProtocolVersion ||
+        accepted.coreProtocolVersion !== authenticate.coreProtocolVersion ||
+        accepted.clientId !== authenticate.clientId ||
+        accepted.grantId !== credential.grantId ||
+        accepted.authorities.length !== 1 ||
+        accepted.authorities[0] !== "daemon.full") {
+        throw clientError("authentication_failed", "Browser Inspect acceptance is inconsistent");
+    }
+}
+function selectCoreProtocol(hello) {
+    if (hello.minimumCompatibleCoreVersion >
+        REMOTE_RUNTIME_CORE_PROTOCOL.currentVersion ||
+        REMOTE_RUNTIME_CORE_PROTOCOL.minimumCompatibleVersion >
+            hello.coreProtocolVersion) {
+        throw clientError("incompatible", "Remote Runtime Core protocol ranges do not overlap");
+    }
+    return Math.min(hello.coreProtocolVersion, REMOTE_RUNTIME_CORE_PROTOCOL.currentVersion);
+}
+function decodeHandshake(frame, expected) {
+    try {
+        return decodeDirectRuntimeFrame(frame);
+    }
+    catch (error) {
+        throw clientError("protocol_error", `invalid Browser Inspect ${expected} frame`, error);
+    }
+}
+function browserInspectEndpoint(directEndpoint) {
+    const url = new URL(directEndpoint);
+    url.pathname = DIRECT_RUNTIME_BROWSER_INSPECT_PATH;
+    url.search = "";
+    url.hash = "";
+    return url.toString();
+}
+function withoutSignature(value) {
+    const { signature: _signature, ...fields } = value;
+    return fields;
+}
+function sha256(value) {
+    return Uint8Array.from(createHash("sha256").update(value).digest());
+}
+function parseTimeout(value) {
+    const timeout = value ?? DEFAULT_TIMEOUT_MS;
+    if (!Number.isSafeInteger(timeout) ||
+        timeout < MIN_TIMEOUT_MS ||
+        timeout > MAX_TIMEOUT_MS) {
+        throw clientError("protocol_error", `timeoutMs must be an integer between ${MIN_TIMEOUT_MS} and ${MAX_TIMEOUT_MS}`);
+    }
+    return timeout;
+}
+function parseLiveness(value) {
+    const pingIntervalMs = parseLivenessInterval(value?.pingIntervalMs, DEFAULT_PING_INTERVAL_MS, "liveness.pingIntervalMs");
+    const inactivityTimeoutMs = parseLivenessInterval(value?.inactivityTimeoutMs, DEFAULT_INACTIVITY_TIMEOUT_MS, "liveness.inactivityTimeoutMs");
+    if (inactivityTimeoutMs <= pingIntervalMs) {
+        throw clientError("protocol_error", "liveness timeout must exceed ping interval");
+    }
+    return { pingIntervalMs, inactivityTimeoutMs };
+}
+function parseLivenessInterval(value, fallback, field) {
+    const interval = value ?? fallback;
+    if (!Number.isSafeInteger(interval) ||
+        interval <= 0 ||
+        interval > MAX_LIVENESS_INTERVAL_MS) {
+        throw clientError("protocol_error", `${field} must be a bounded positive integer`);
+    }
+    return interval;
+}
+function remaining(deadline) {
+    return Math.max(1, deadline - Date.now());
+}
+function messageBytes(message) {
+    return message.binary
+        ? message.data.byteLength
+        : Buffer.byteLength(message.data, "utf8");
+}
+function rawDataBytes(data) {
+    if (Array.isArray(data))
+        return Uint8Array.from(Buffer.concat(data));
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data.slice(0));
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+}
+function decodeText(bytes) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch (error) {
+        throw clientError("protocol_error", "Browser Inspect frame must be valid UTF-8", error);
+    }
+}
+function normalizeError(error, message) {
+    return error instanceof DirectRuntimeClientError
+        ? error
+        : clientError("protocol_error", message, error);
+}
+function closedError(cause) {
+    return clientError("closed", "Browser Inspect connection was interrupted", cause);
+}
+function webSocketCloseError(closeCode, reasonSuffix, localClose) {
+    if (localClose) {
+        return clientError("closed", "Browser Inspect connection was closed", undefined, closeCode);
+    }
+    const code = closeCode === DIRECT_RUNTIME_CLOSE_CODE.unauthorized
+        ? "authentication_failed"
+        : closeCode === DIRECT_RUNTIME_CLOSE_CODE.badProtocol
+            ? "protocol_error"
+            : closeCode === DIRECT_RUNTIME_CLOSE_CODE.authenticationTimeout ||
+                closeCode === DIRECT_RUNTIME_CLOSE_CODE.capacity
+                ? "unreachable"
+                : "closed";
+    return clientError(code, `Browser Inspect connection closed (${closeCode})${reasonSuffix}`, undefined, closeCode);
+}
+function mapWebSocketError(error) {
+    const code = typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        typeof error.code === "string"
+        ? error.code
+        : "";
+    if (code.startsWith("ERR_TLS_") ||
+        code.startsWith("ERR_SSL_") ||
+        code.startsWith("CERT_") ||
+        [
+            "DEPTH_ZERO_SELF_SIGNED_CERT",
+            "SELF_SIGNED_CERT_IN_CHAIN",
+            "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+            "UNABLE_TO_GET_ISSUER_CERT",
+        ].includes(code)) {
+        return clientError("tls_error", "Browser Inspect TLS verification failed", error);
+    }
+    if (code === "WS_ERR_UNSUPPORTED_MESSAGE_LENGTH") {
+        return clientError("protocol_error", "Browser Inspect WebSocket frame is too large", error);
+    }
+    return clientError("unreachable", "Browser Inspect endpoint is unreachable", error);
+}
+function inspectCloseErrorCode(reason) {
+    if (reason === "unauthorized")
+        return "authentication_failed";
+    if (reason === "capacity")
+        return "unreachable";
+    return "closed";
+}
+async function withTimeout(promise, timeoutMs, timeoutError) {
+    return await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(timeoutError()), timeoutMs);
+        timer.unref?.();
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { connectDirectRuntime, pairDirectRuntime, type DirectRuntimeCallOptions, type DirectRuntimeClientOptions, type DirectRuntimeConnection, type DirectRuntimeSessionEventsOptions, type DirectRuntimeSessionEventsSubscription, type DirectRuntimeSessionTerminal, type DirectRuntimeSessionTerminalOptions, type DirectRuntimeEmulatorSurface, type DirectRuntimeEmulatorSurfaceOptions, type PairDirectRuntimeOptions, type PairDirectRuntimeResult, } from "./client.js";
 export { DirectRuntimeBrowserSurfaceError, openDirectRuntimeBrowserSurface, type DirectRuntimeBrowserSurfaceClientOptions, type DirectRuntimeBrowserSurfaceConnection, type DirectRuntimeBrowserSurfaceEvent, } from "./browser-surface-client.js";
+export { DirectRuntimeBrowserInspectError, openDirectRuntimeBrowserInspect, type DirectRuntimeBrowserInspectClientOptions, type DirectRuntimeBrowserInspectConnection, } from "./browser-inspect-client.js";
 export { generateDirectRuntimeClientIdentity, parseDirectRuntimeCredential, type DirectRuntimeClientIdentity, type DirectRuntimeCredential, type GenerateDirectRuntimeClientIdentityOptions, } from "./credential.js";
 export { DirectRuntimeCallTransportError, DirectRuntimeClientCapacityError, DirectRuntimeClientError, DirectRuntimeRpcError, DirectRuntimeSessionEventsError, DirectRuntimeSessionTerminalError, RemoteRuntimeClientError, RemoteRuntimeRpcCallError, type DirectRuntimeCallOutcome, type DirectRuntimeClientCapacity, type DirectRuntimeClientErrorCode, } from "./errors.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { connectDirectRuntime, pairDirectRuntime, } from "./client.js";
 export { DirectRuntimeBrowserSurfaceError, openDirectRuntimeBrowserSurface, } from "./browser-surface-client.js";
+export { DirectRuntimeBrowserInspectError, openDirectRuntimeBrowserInspect, } from "./browser-inspect-client.js";
 export { generateDirectRuntimeClientIdentity, parseDirectRuntimeCredential, } from "./credential.js";
 export { DirectRuntimeCallTransportError, DirectRuntimeClientCapacityError, DirectRuntimeClientError, DirectRuntimeRpcError, DirectRuntimeSessionEventsError, DirectRuntimeSessionTerminalError, RemoteRuntimeClientError, RemoteRuntimeRpcCallError, } from "./errors.js";

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@rynx-ai/remote-runtime-client",
-  "version": "0.1.9",
+  "version": "0.1.10-beta.2",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rynx-ai/rynx.git",
+    "directory": "packages/remote-runtime-client"
+  },
   "description": "Authenticated Node.js client for a Rynx Direct Remote Runtime.",
   "type": "module",
   "publishConfig": {
@@ -20,8 +25,8 @@
   },
   "dependencies": {
     "ws": "^8.21.0",
-    "@rynx-ai/protocol": "0.1.9",
-    "@rynx-ai/remote-runtime-e2ee": "0.1.9"
+    "@rynx-ai/remote-runtime-e2ee": "0.1.10-beta.2",
+    "@rynx-ai/protocol": "0.1.10-beta.2"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"