@ai-matrx/desktop-protocol 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,181 @@
+import { BackoffOptions } from '@ai-matrx/realtime';
+export { RECONNECT_ALARM_ATTEMPTS } from '@ai-matrx/realtime';
+import { z } from 'zod';
+import { W as Welcome, D as DesktopProtocolError, O as OpName, a as OpParams, b as OpResult, c as OPS, S as StreamMeta, E as EndReason, d as EVENTS, C as ClientType } from './registry-DTcTGycI.js';
+export { i as isDesktopProtocolError } from './registry-DTcTGycI.js';
+import { FrameHeader } from './frame.js';
+
+/** The subset of the WHATWG WebSocket the client uses — browser, React Native, `ws` and Workers all fit. */
+interface WebSocketLike {
+    readonly readyState: number;
+    binaryType: string;
+    send(data: string | ArrayBuffer | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((event: {
+        code: number;
+        reason: string;
+    }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+}
+type WebSocketFactory = (url: string, protocols: string[]) => WebSocketLike;
+interface ClientTimers {
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+    now(): number;
+}
+type DesktopClientStatus = 
+/** Constructed, connect() not called yet. */
+"idle"
+/** Socket opening. */
+ | "connecting"
+/** Socket open, hello sent, waiting for Welcome. */
+ | "handshaking"
+/** Welcome received — requests flow. */
+ | "open"
+/** Dropped; a reconnect is scheduled (see `retryInMs`). */
+ | "reconnecting"
+/** Closed for good: close() was called, or the device/server refused us (see `lastError`). */
+ | "closed";
+interface DesktopClientState {
+    status: DesktopClientStatus;
+    welcome: Welcome | null;
+    /** Consecutive failed connection attempts since the last stable connection. */
+    attempts: number;
+    /** Delay before the scheduled reconnect, while `status === "reconnecting"`. */
+    retryInMs: number | null;
+    lastError: DesktopProtocolError | null;
+    lastCloseCode: number | null;
+}
+type DesktopClientDiagnostic = {
+    kind: "malformed_message";
+    detail: string;
+} | {
+    kind: "unknown_request";
+    id: string;
+    type: string;
+} | {
+    kind: "unknown_stream";
+    sid: number;
+} | {
+    kind: "seq_gap";
+    id: string;
+    expected: number;
+    received: number;
+} | {
+    kind: "heartbeat_timeout";
+    silentMs: number;
+} | {
+    kind: "reconnect_alarm";
+    attempts: number;
+} | {
+    kind: "reattach_failed";
+    resourceId: string;
+    error: DesktopProtocolError;
+} | {
+    kind: "reauth_failed";
+    error: unknown;
+} | {
+    kind: "handler_threw";
+    where: string;
+    error: unknown;
+};
+interface DesktopClientOptions {
+    /** wss://relay…/v1/devices/{id}/connect, or ws://127.0.0.1:2214x for the localhost transport. */
+    url: string | (() => string | Promise<string>);
+    /**
+     * WebSocket subprotocols, re-read on EVERY (re)connect so a refreshed token is used — e.g.
+     * `["matrx.v1", \`bearer.${jwt}\`]`. Browser tokens ride the subprotocol, never the URL.
+     */
+    protocols?: () => string[] | Promise<string[]>;
+    clientType: ClientType;
+    clientVersion: string;
+    /** Default: this package's PROTOCOL_MAJOR.PROTOCOL_MINOR. */
+    protocolVersion?: string;
+    /** Default: `globalThis.WebSocket`. */
+    webSocket?: WebSocketFactory;
+    /** Reconnect ladder — the shared @ai-matrx/realtime backoff (stability reset + jitter). */
+    backoff?: Omit<BackoffOptions, "now">;
+    /** Heartbeat interval (PING_TEXT). Two silent intervals = reconnect. Default 25 000. */
+    heartbeatMs?: number;
+    /** Unary request timeout. Default 70 000 (the relay's call default). */
+    requestTimeoutMs?: number;
+    /** Fresh access token for `relay.reauth` when the relay sends `relay.auth_expiring`. */
+    getToken?: () => Promise<string>;
+    /** Background problems — loud by contract; default logs to console.warn. */
+    onDiagnostic?: (diagnostic: DesktopClientDiagnostic) => void;
+    timers?: ClientTimers;
+}
+interface RequestOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+type StreamOpName = {
+    [N in OpName]: (typeof OPS)[N]["kind"] extends "unary" ? never : N;
+}[OpName];
+type EventName = keyof typeof EVENTS;
+type EventPayload<E extends EventName> = z.output<(typeof EVENTS)[E]>;
+type EventHandler<E extends EventName> = (payload: EventPayload<E>, resourceId: string | undefined) => void;
+interface StreamHandlers {
+    /** DATA / STDERR bytes. Credit is granted only after this returns (or its promise settles) — backpressure. */
+    onData?: (payload: Uint8Array, header: FrameHeader) => void | Promise<void>;
+    /** SNAPSHOT bytes (a serialized screen after a gap). */
+    onSnapshot?: (payload: Uint8Array, header: FrameHeader) => void | Promise<void>;
+    /** open / gap / snapshot announcements, including the ones after a reattach. */
+    onMeta?: (meta: StreamMeta) => void;
+    /** Called after a transparent reattach (the stream is live again on a new sid). */
+    onReattached?: () => void;
+}
+interface StreamOptions extends RequestOptions {
+    /** Receive window in payload bytes (default: the core's limits.default_window_bytes). */
+    windowBytes?: number;
+    /** Reattach mode for resource streams. Default "control". */
+    mode?: "control" | "read_only";
+}
+interface DesktopStream<N extends StreamOpName> {
+    /** The CURRENT request id carrying this stream (changes on reattach). */
+    readonly id: string;
+    /** The unary result that precedes the stream (PtyInfo, FsReadStreamResult, ResourceInfo…). */
+    readonly result: Promise<OpResult<N>>;
+    /** Settles when the stream ends for good: resolves with the end reason, rejects on error. */
+    readonly done: Promise<EndReason>;
+    /** The resource this stream belongs to (pty_…/watch_…), once known. Resource streams survive reconnects. */
+    readonly resourceId: string | null;
+    /** Seq of the last DATA frame delivered to onData — sent as since_seq on reattach. */
+    readonly lastSeq: number;
+    /** Send STDIN bytes (UTF-8 for strings), chunked and credit-gated. */
+    write(data: Uint8Array | string): void;
+    /** Cancel the request (core ends the stream with reason "cancelled"). */
+    cancel(): void;
+    /** Leave the resource running on the device and stop following it (session.detach). */
+    detach(): Promise<void>;
+}
+interface DesktopClient {
+    connect(): void;
+    /** Close for good (no reconnect). Pending work rejects with CANCELLED. */
+    close(): void;
+    getState(): DesktopClientState;
+    /** useSyncExternalStore-shaped. */
+    subscribe(listener: () => void): () => void;
+    /** Resolves with the Welcome once open (immediately if already open). */
+    ready(options?: RequestOptions): Promise<Welcome>;
+    request<N extends OpName>(op: N, params: OpParams<N>, options?: RequestOptions): Promise<OpResult<N>>;
+    stream<N extends StreamOpName>(op: N, params: OpParams<N>, handlers?: StreamHandlers, options?: StreamOptions): DesktopStream<N>;
+    on<E extends EventName>(name: E, handler: EventHandler<E>): () => void;
+    /** Hand the relay a fresh token without dropping the socket. */
+    reauth(token: string): void;
+}
+
+/**
+ * The reconnecting desktop-protocol client: hello → requests, streams with credit-based
+ * backpressure, events, transparent reattach of resource streams (terminals, watches) after a
+ * drop, heartbeat, and relay reauth. One instance per device connection. All state lives in the
+ * closure — no module-level state (dual ESM/CJS graphs would split it).
+ */
+
+declare function createDesktopClient(options: DesktopClientOptions): DesktopClient;
+
+export { type ClientTimers, type DesktopClient, type DesktopClientDiagnostic, type DesktopClientOptions, type DesktopClientState, type DesktopClientStatus, DesktopProtocolError, type DesktopStream, type EventHandler, type EventName, type EventPayload, OpName, OpParams, OpResult, type RequestOptions, type StreamHandlers, type StreamOpName, type StreamOptions, type WebSocketFactory, type WebSocketLike, createDesktopClient };