@ai-matrx/desktop-protocol 0.1.0

package/dist/react.d.ts

@@ -0,0 +1,924 @@
+import { ReactNode } from 'react';
+import { z } from 'zod';
+
+/**
+ * Zod-free type twins of the wire error shapes, for the zod-free entries (`./frame`, error.ts).
+ * schema/errors.ts asserts at compile time that these equal the zod-inferred types, so they can
+ * never drift (see the `_assert*` lines there).
+ */
+type ErrorCodeName = "AUTH_REQUIRED" | "AUTH_INVALID" | "AUTH_EXPIRED" | "AUTH_FORBIDDEN" | "AUTH_DEVICE_REVOKED" | "PERMISSION_DENIED_OS" | "NOT_FOUND" | "CONFLICT" | "INVALID_PARAMS" | "RESOURCE_BUSY" | "RESOURCE_GONE" | "CANCELLED" | "TIMEOUT" | "PLATFORM_UNSUPPORTED" | "RATE_LIMITED" | "INTERNAL" | "PROTOCOL_VERSION_UNSUPPORTED" | "PROTOCOL_ERROR" | "UNKNOWN_OPERATION" | "DEVICE_OFFLINE" | "PAYLOAD_TOO_LARGE";
+type ErrorReasonName = "not_a_directory" | "is_a_directory" | "directory_not_empty" | "already_exists" | "stale_write" | "binary_content" | "not_utf8_boundary" | "patch_no_match" | "patch_ambiguous" | "resource_exited" | "resource_expired" | "control_taken" | "window_exhausted";
+interface ErrorData {
+    reason?: ErrorReasonName | undefined;
+    cap?: string | undefined;
+    op?: string | undefined;
+    path?: string | undefined;
+    settings_url?: string | undefined;
+    retry_after_ms?: number | undefined;
+    limit_bytes?: number | undefined;
+    upgrade?: {
+        min_version: string;
+        max_version: string;
+        download_url?: string | undefined;
+    } | undefined;
+}
+
+/**
+ * The one error type every package entry throws. It carries the wire ErrorCode (SPEC §5), so a
+ * caller branches on `code`/`retryable`/`data.reason` and never parses a message. Zod-free on
+ * purpose: `./frame` (the relay hot path) throws it without pulling the schema graph.
+ */
+
+declare class DesktopProtocolError extends Error {
+    readonly code: ErrorCodeName;
+    readonly retryable: boolean;
+    readonly data: ErrorData | undefined;
+    constructor(code: ErrorCodeName, message: string, options?: {
+        retryable?: boolean;
+        data?: ErrorData;
+        cause?: unknown;
+    });
+    /** The wire body (ProtocolErrorBody) — what a core or relay sends for this error. */
+    toBody(): {
+        code: ErrorCodeName;
+        message: string;
+        retryable: boolean;
+        data?: ErrorData;
+    };
+}
+
+declare const FRAME_VERSION: 1;
+declare const FrameChannel: {
+    /** core→client: pty output, fs.read_stream bytes */
+    readonly DATA: 0;
+    /** core→client: stderr of a non-pty process (reserved for exec.spawn in v1.1) */
+    readonly STDERR: 1;
+    /** client→core: keystrokes / stdin to sid */
+    readonly STDIN: 2;
+    /** core→client: serialized terminal screen (attach when since_seq is outside the ring) */
+    readonly SNAPSHOT: 3;
+    /** relay↔device hop only: a JSON envelope carried inside a binary frame so the relay can route
+     *  by cid without parsing JSON. Never seen by clients. */
+    readonly ENVELOPE: 255;
+};
+type FrameChannelValue = (typeof FrameChannel)[keyof typeof FrameChannel];
+interface FrameHeader {
+    version: typeof FRAME_VERSION;
+    /** 0..3 — FrameFlag bits. */
+    flags: number;
+    channel: FrameChannelValue;
+    cid: number;
+    sid: number;
+    seq: number;
+}
+
+/** @ai-matrx/desktop-protocol — the JSON envelope (SPEC §4). Schema source: lint-enforced rules in scripts/check-schema-source.mjs. */
+
+declare const Welcome: z.ZodObject<{
+    protocol_version: z.ZodString;
+    session_id: z.ZodString;
+    client_id: z.ZodString;
+    device_id: z.ZodString;
+    device_name: z.ZodString;
+    app_version: z.ZodString;
+    platform: z.ZodEnum<{
+        darwin: "darwin";
+        win32: "win32";
+        linux: "linux";
+    }>;
+    ops: z.ZodArray<z.ZodObject<{
+        cap: z.ZodString;
+        op: z.ZodString;
+        since: z.ZodString;
+    }, z.core.$strict>>;
+    limits: z.ZodObject<{
+        max_message_bytes: z.ZodInt;
+        max_frame_payload_bytes: z.ZodInt;
+        default_window_bytes: z.ZodInt;
+        max_streams_per_client: z.ZodInt;
+        max_resources_per_user: z.ZodInt;
+    }, z.core.$strict>;
+    server_time_ms: z.ZodInt;
+}, z.core.$strict>;
+type Welcome = z.output<typeof Welcome>;
+declare const StreamMeta: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"open">;
+    sid: z.ZodInt;
+    window_bytes: z.ZodInt;
+    resource_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"snapshot">;
+    cols: z.ZodInt;
+    rows: z.ZodInt;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"gap">;
+    from_seq: z.ZodInt;
+    to_seq: z.ZodInt;
+}, z.core.$strict>], "kind">;
+type StreamMeta = z.output<typeof StreamMeta>;
+declare const EndReason: z.ZodEnum<{
+    error: "error";
+    resource_exited: "resource_exited";
+    completed: "completed";
+    cancelled: "cancelled";
+    detached: "detached";
+}>;
+type EndReason = z.output<typeof EndReason>;
+
+/** @ai-matrx/desktop-protocol — the op and event registries (Router, client and Python are generated from these). */
+
+declare const OPS: {
+    readonly "sysinfo.get": {
+        readonly params: z.ZodObject<{}, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            device_id: z.ZodString;
+            device_name: z.ZodString;
+            hostname: z.ZodString;
+            platform: z.ZodEnum<{
+                darwin: "darwin";
+                win32: "win32";
+                linux: "linux";
+            }>;
+            os_version: z.ZodString;
+            arch: z.ZodEnum<{
+                arm64: "arm64";
+                x64: "x64";
+            }>;
+            app_version: z.ZodString;
+            protocol_version: z.ZodString;
+            user: z.ZodObject<{
+                username: z.ZodString;
+                shell: z.ZodString;
+            }, z.core.$strict>;
+            paths: z.ZodObject<{
+                home: z.ZodString;
+                desktop: z.ZodString;
+                documents: z.ZodString;
+                downloads: z.ZodString;
+                app_data: z.ZodString;
+                temp: z.ZodString;
+            }, z.core.$strict>;
+            cpu: z.ZodObject<{
+                model: z.ZodString;
+                cores: z.ZodInt;
+            }, z.core.$strict>;
+            memory: z.ZodObject<{
+                total_bytes: z.ZodInt;
+                free_bytes: z.ZodInt;
+            }, z.core.$strict>;
+            uptime_seconds: z.ZodInt;
+            on_battery: z.ZodNullable<z.ZodBoolean>;
+            sleep_prevented: z.ZodBoolean;
+            permissions: z.ZodArray<z.ZodObject<{
+                name: z.ZodEnum<{
+                    full_disk_access: "full_disk_access";
+                    accessibility: "accessibility";
+                    screen_recording: "screen_recording";
+                    microphone: "microphone";
+                    camera: "camera";
+                    automation: "automation";
+                    contacts: "contacts";
+                    calendars: "calendars";
+                    photos: "photos";
+                    location: "location";
+                    local_network: "local_network";
+                    bluetooth: "bluetooth";
+                    notifications: "notifications";
+                }>;
+                state: z.ZodEnum<{
+                    granted: "granted";
+                    denied: "denied";
+                    not_determined: "not_determined";
+                    not_applicable: "not_applicable";
+                }>;
+                settings_url: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        readonly kind: "unary";
+        readonly since: "1.0";
+        readonly errors: readonly ["INTERNAL"];
+    };
+    readonly "fs.list": {
+        readonly params: z.ZodObject<{
+            path: z.ZodString;
+            recursive: z.ZodDefault<z.ZodBoolean>;
+            depth: z.ZodDefault<z.ZodInt>;
+            pattern: z.ZodOptional<z.ZodString>;
+            limit: z.ZodDefault<z.ZodInt>;
+            page_token: z.ZodOptional<z.ZodString>;
+            show_hidden: z.ZodDefault<z.ZodBoolean>;
+            sort: z.ZodDefault<z.ZodEnum<{
+                name: "name";
+                mtime: "mtime";
+                size: "size";
+                kind: "kind";
+            }>>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            entries: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                path: z.ZodString;
+                kind: z.ZodEnum<{
+                    file: "file";
+                    dir: "dir";
+                    symlink: "symlink";
+                }>;
+                size: z.ZodInt;
+                mtime: z.ZodNumber;
+                mtime_ms: z.ZodInt;
+                mode: z.ZodInt;
+                target: z.ZodNullable<z.ZodString>;
+                hidden: z.ZodBoolean;
+            }, z.core.$strict>>;
+            truncated: z.ZodBoolean;
+            next_page_token: z.ZodNullable<z.ZodString>;
+            scanned: z.ZodInt;
+        }, z.core.$strict>;
+        readonly kind: "unary";
+        readonly since: "1.0";
+        readonly errors: readonly ["NOT_FOUND", "PERMISSION_DENIED_OS", "INVALID_PARAMS", "RESOURCE_BUSY", "INTERNAL"];
+    };
+    readonly "fs.stat": {
+        readonly params: z.ZodObject<{
+            path: z.ZodString;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            name: z.ZodString;
+            path: z.ZodString;
+            kind: z.ZodEnum<{
+                file: "file";
+                dir: "dir";
+                symlink: "symlink";
+            }>;
+            size: z.ZodInt;
+            mtime: z.ZodNumber;
+            mtime_ms: z.ZodInt;
+            mode: z.ZodInt;
+            target: z.ZodNullable<z.ZodString>;
+            hidden: z.ZodBoolean;
+        }, z.core.$strict>;
+        readonly kind: "unary";
+        readonly since: "1.0";
+        readonly errors: readonly ["NOT_FOUND", "PERMISSION_DENIED_OS", "INVALID_PARAMS", "RESOURCE_BUSY", "INTERNAL"];
+    };
+    readonly "fs.read": {
+        readonly params: z.ZodObject<{
+            path: z.ZodString;
+            encoding: z.ZodDefault<z.ZodEnum<{
+                utf8: "utf8";
+                base64: "base64";
+            }>>;
+            offset: z.ZodDefault<z.ZodInt>;
+            limit: z.ZodDefault<z.ZodInt>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            content: z.ZodString;
+            encoding: z.ZodEnum<{
+                utf8: "utf8";
+                base64: "base64";
+            }>;
+            size: z.ZodInt;
+            offset: z.ZodInt;
+            next_offset: z.ZodInt;
+            truncated: z.ZodBoolean;
+            mime: z.ZodNullable<z.ZodString>;
+            mtime_ms: z.ZodInt;
+        }, z.core.$strict>;
+        readonly kind: "unary";
+        readonly since: "1.0";
+        readonly errors: readonly ["NOT_FOUND", "PERMISSION_DENIED_OS", "INVALID_PARAMS", "RESOURCE_BUSY", "INTERNAL", "PAYLOAD_TOO_LARGE"];
+    };
+    readonly "fs.read_stream": {
+        readonly params: z.ZodObject<{
+            path: z.ZodString;
+            offset: z.ZodDefault<z.ZodInt>;
+            length: z.ZodOptional<z.ZodInt>;
+            window_bytes: z.ZodOptional<z.ZodInt>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            size: z.ZodInt;
+            mime: z.ZodNullable<z.ZodString>;
+            mtime_ms: z.ZodInt;
+        }, z.core.$strict>;
+        readonly kind: "stream";
+        readonly since: "1.0";
+        readonly errors: readonly ["NOT_FOUND", "PERMISSION_DENIED_OS", "INVALID_PARAMS", "RESOURCE_BUSY", "INTERNAL", "CANCELLED"];
+    };
+    readonly "fs.write": {
+        readonly params: z.ZodObject<{
+            path: z.ZodString;
+            content: z.ZodString;
+            encoding: z.ZodDefault<z.ZodEnum<{
+                utf8: "utf8";
+                base64: "base64";
+            }>>;
+            mode: z.ZodOptional<z.ZodInt>;
+            create_parents: z.ZodDefault<z.ZodBoolean>;
+            if_match_mtime_ms: z.ZodOptional<z.ZodInt>;
+            exclusive: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            path: z.ZodString;
+            size: z.ZodInt;
+            mtime_ms: z.ZodInt;
+            created: z.ZodBoolean;
+        }, z.core.$strict>;
+        readonly kind: "unary";
+        readonly since: "1.0";
+        readonly errors: readonly ["NOT_FOUND", "PERMISSION_DENIED_OS", "INVALID_PARAMS", "RESOURCE_BUSY", "INTERNAL", "CONFLICT", "PAYLOAD_TOO_LARGE"];
+    };
+    readonly "fs.mkdir": {
+        readonly params: z.ZodObject<{
+            path: z.ZodString;
+            parents: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            path: z.ZodString;
+            created: z.ZodBoolean;
+        }, z.core.$strict>;
+        readonly kind: "unary";
+        readonly since: "1.0";
+        readonly errors: readonly ["NOT_FOUND", "PERMISSION_DENIED_OS", "INVALID_PARAMS", "RESOURCE_BUSY", "INTERNAL", "CONFLICT"];
+    };
+    readonly "fs.move": {
+        readonly params: z.ZodObject<{
+            from_path: z.ZodString;
+            to_path: z.ZodString;
+            overwrite: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            from_path: z.ZodString;
+            to_path: z.ZodString;
+        }, z.core.$strict>;
+        readonly kind: "unary";
+        readonly since: "1.0";
+        readonly errors: readonly ["NOT_FOUND", "PERMISSION_DENIED_OS", "INVALID_PARAMS", "RESOURCE_BUSY", "INTERNAL", "CONFLICT"];
+    };
+    readonly "fs.delete": {
+        readonly params: z.ZodObject<{
+            path: z.ZodString;
+            recursive: z.ZodDefault<z.ZodBoolean>;
+            to_trash: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            deleted: z.ZodLiteral<true>;
+            trashed_to: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+        readonly kind: "unary";
+        readonly since: "1.0";
+        readonly errors: readonly ["NOT_FOUND", "PERMISSION_DENIED_OS", "INVALID_PARAMS", "RESOURCE_BUSY", "INTERNAL"];
+    };
+    readonly "fs.watch": {
+        readonly params: z.ZodObject<{
+            path: z.ZodString;
+            recursive: z.ZodDefault<z.ZodBoolean>;
+            ignore: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            debounce_ms: z.ZodDefault<z.ZodInt>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            resource_id: z.ZodString;
+            path: z.ZodString;
+        }, z.core.$strict>;
+        readonly kind: "resource";
+        readonly since: "1.0";
+        readonly errors: readonly ["NOT_FOUND", "PERMISSION_DENIED_OS", "INVALID_PARAMS", "RESOURCE_BUSY", "INTERNAL", "RATE_LIMITED"];
+    };
+    readonly "fs.patch": {
+        readonly params: z.ZodObject<{
+            path: z.ZodString;
+            edits: z.ZodArray<z.ZodObject<{
+                old_text: z.ZodString;
+                new_text: z.ZodString;
+                replace_all: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strict>>;
+            create_if_missing: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            path: z.ZodString;
+            applied: z.ZodInt;
+            size: z.ZodInt;
+            mtime_ms: z.ZodInt;
+        }, z.core.$strict>;
+        readonly kind: "unary";
+        readonly since: "1.0";
+        readonly errors: readonly ["NOT_FOUND", "PERMISSION_DENIED_OS", "INVALID_PARAMS", "RESOURCE_BUSY", "INTERNAL", "CONFLICT"];
+    };
+    readonly "fs.search_paths": {
+        readonly params: z.ZodObject<{
+            pattern: z.ZodString;
+            cwd: z.ZodString;
+            hidden: z.ZodDefault<z.ZodBoolean>;
+            max_results: z.ZodDefault<z.ZodInt>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            paths: z.ZodArray<z.ZodString>;
+            truncated: z.ZodBoolean;
+        }, z.core.$strict>;
+        readonly kind: "unary";
+        readonly since: "1.0";
+        readonly errors: readonly ["NOT_FOUND", "PERMISSION_DENIED_OS", "INVALID_PARAMS", "RESOURCE_BUSY", "INTERNAL", "TIMEOUT"];
+    };
+    readonly "fs.search_content": {
+        readonly params: z.ZodObject<{
+            query: z.ZodString;
+            cwd: z.ZodString;
+            regex: z.ZodDefault<z.ZodBoolean>;
+            case_sensitive: z.ZodDefault<z.ZodBoolean>;
+            include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            max_results: z.ZodDefault<z.ZodInt>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            results: z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                lines: z.ZodString;
+                line_number: z.ZodInt;
+                submatches: z.ZodArray<z.ZodObject<{
+                    match: z.ZodString;
+                    start: z.ZodInt;
+                    end: z.ZodInt;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+            truncated: z.ZodBoolean;
+        }, z.core.$strict>;
+        readonly kind: "unary";
+        readonly since: "1.0";
+        readonly errors: readonly ["NOT_FOUND", "PERMISSION_DENIED_OS", "INVALID_PARAMS", "RESOURCE_BUSY", "INTERNAL", "TIMEOUT"];
+    };
+    readonly "exec.pty.start": {
+        readonly params: z.ZodObject<{
+            cols: z.ZodInt;
+            rows: z.ZodInt;
+            cwd: z.ZodOptional<z.ZodString>;
+            shell: z.ZodOptional<z.ZodString>;
+            args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            name: z.ZodOptional<z.ZodString>;
+            window_bytes: z.ZodOptional<z.ZodInt>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            resource_id: z.ZodString;
+            pid: z.ZodInt;
+            shell: z.ZodString;
+            cwd: z.ZodString;
+            title: z.ZodString;
+            name: z.ZodNullable<z.ZodString>;
+            cols: z.ZodInt;
+            rows: z.ZodInt;
+            state: z.ZodEnum<{
+                running: "running";
+                exited: "exited";
+            }>;
+            exit_code: z.ZodNullable<z.ZodInt>;
+            exit_signal: z.ZodNullable<z.ZodEnum<{
+                SIGINT: "SIGINT";
+                SIGTERM: "SIGTERM";
+                SIGKILL: "SIGKILL";
+                SIGHUP: "SIGHUP";
+                SIGQUIT: "SIGQUIT";
+                SIGTSTP: "SIGTSTP";
+                SIGCONT: "SIGCONT";
+                SIGUSR1: "SIGUSR1";
+                SIGUSR2: "SIGUSR2";
+            }>>;
+            last_seq: z.ZodInt;
+            created_at_ms: z.ZodInt;
+            controller_client_id: z.ZodNullable<z.ZodString>;
+            attached_clients: z.ZodInt;
+            orphan_expires_at_ms: z.ZodNullable<z.ZodInt>;
+        }, z.core.$strict>;
+        readonly kind: "resource";
+        readonly since: "1.0";
+        readonly errors: readonly ["INVALID_PARAMS", "NOT_FOUND", "RATE_LIMITED", "PLATFORM_UNSUPPORTED", "INTERNAL"];
+    };
+    readonly "exec.pty.write": {
+        readonly params: z.ZodObject<{
+            resource_id: z.ZodString;
+            data: z.ZodString;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            written: z.ZodInt;
+        }, z.core.$strict>;
+        readonly kind: "unary";
+        readonly since: "1.0";
+        readonly errors: readonly ["RESOURCE_GONE", "AUTH_FORBIDDEN", "INVALID_PARAMS"];
+    };
+    readonly "exec.pty.resize": {
+        readonly params: z.ZodObject<{
+            resource_id: z.ZodString;
+            cols: z.ZodInt;
+            rows: z.ZodInt;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            cols: z.ZodInt;
+            rows: z.ZodInt;
+        }, z.core.$strict>;
+        readonly kind: "unary";
+        readonly since: "1.0";
+        readonly errors: readonly ["RESOURCE_GONE", "AUTH_FORBIDDEN"];
+    };
+    readonly "exec.pty.signal": {
+        readonly params: z.ZodObject<{
+            resource_id: z.ZodString;
+            signal: z.ZodEnum<{
+                SIGINT: "SIGINT";
+                SIGTERM: "SIGTERM";
+                SIGKILL: "SIGKILL";
+                SIGHUP: "SIGHUP";
+                SIGQUIT: "SIGQUIT";
+                SIGTSTP: "SIGTSTP";
+                SIGCONT: "SIGCONT";
+                SIGUSR1: "SIGUSR1";
+                SIGUSR2: "SIGUSR2";
+            }>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            delivered: z.ZodBoolean;
+        }, z.core.$strict>;
+        readonly kind: "unary";
+        readonly since: "1.0";
+        readonly errors: readonly ["RESOURCE_GONE", "AUTH_FORBIDDEN", "PLATFORM_UNSUPPORTED"];
+    };
+    readonly "exec.pty.kill": {
+        readonly params: z.ZodObject<{
+            resource_id: z.ZodString;
+            grace_ms: z.ZodDefault<z.ZodInt>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            exit_code: z.ZodNullable<z.ZodInt>;
+            exit_signal: z.ZodNullable<z.ZodEnum<{
+                SIGINT: "SIGINT";
+                SIGTERM: "SIGTERM";
+                SIGKILL: "SIGKILL";
+                SIGHUP: "SIGHUP";
+                SIGQUIT: "SIGQUIT";
+                SIGTSTP: "SIGTSTP";
+                SIGCONT: "SIGCONT";
+                SIGUSR1: "SIGUSR1";
+                SIGUSR2: "SIGUSR2";
+            }>>;
+        }, z.core.$strict>;
+        readonly kind: "unary";
+        readonly since: "1.0";
+        readonly errors: readonly ["RESOURCE_GONE", "AUTH_FORBIDDEN"];
+    };
+    readonly "exec.list": {
+        readonly params: z.ZodObject<{}, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            sessions: z.ZodArray<z.ZodObject<{
+                resource_id: z.ZodString;
+                pid: z.ZodInt;
+                shell: z.ZodString;
+                cwd: z.ZodString;
+                title: z.ZodString;
+                name: z.ZodNullable<z.ZodString>;
+                cols: z.ZodInt;
+                rows: z.ZodInt;
+                state: z.ZodEnum<{
+                    running: "running";
+                    exited: "exited";
+                }>;
+                exit_code: z.ZodNullable<z.ZodInt>;
+                exit_signal: z.ZodNullable<z.ZodEnum<{
+                    SIGINT: "SIGINT";
+                    SIGTERM: "SIGTERM";
+                    SIGKILL: "SIGKILL";
+                    SIGHUP: "SIGHUP";
+                    SIGQUIT: "SIGQUIT";
+                    SIGTSTP: "SIGTSTP";
+                    SIGCONT: "SIGCONT";
+                    SIGUSR1: "SIGUSR1";
+                    SIGUSR2: "SIGUSR2";
+                }>>;
+                last_seq: z.ZodInt;
+                created_at_ms: z.ZodInt;
+                controller_client_id: z.ZodNullable<z.ZodString>;
+                attached_clients: z.ZodInt;
+                orphan_expires_at_ms: z.ZodNullable<z.ZodInt>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        readonly kind: "unary";
+        readonly since: "1.0";
+        readonly errors: readonly ["INTERNAL"];
+    };
+    readonly "exec.run": {
+        readonly params: z.ZodObject<{
+            command: z.ZodString;
+            cwd: z.ZodOptional<z.ZodString>;
+            cwd_key: z.ZodOptional<z.ZodString>;
+            env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            stdin: z.ZodOptional<z.ZodString>;
+            timeout: z.ZodDefault<z.ZodInt>;
+            max_output_bytes: z.ZodDefault<z.ZodInt>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            exit_code: z.ZodInt;
+            stdout: z.ZodString;
+            stderr: z.ZodString;
+            cwd: z.ZodString;
+            duration_ms: z.ZodInt;
+            timed_out: z.ZodBoolean;
+            output_truncated: z.ZodBoolean;
+        }, z.core.$strict>;
+        readonly kind: "unary";
+        readonly since: "1.0";
+        readonly errors: readonly ["INVALID_PARAMS", "NOT_FOUND", "TIMEOUT", "CANCELLED", "INTERNAL"];
+    };
+    readonly "session.attach": {
+        readonly params: z.ZodObject<{
+            resource_id: z.ZodString;
+            mode: z.ZodDefault<z.ZodEnum<{
+                control: "control";
+                read_only: "read_only";
+            }>>;
+            since_seq: z.ZodOptional<z.ZodInt>;
+            window_bytes: z.ZodOptional<z.ZodInt>;
+        }, z.core.$strict>;
+        readonly result: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"pty">;
+            pty: z.ZodObject<{
+                resource_id: z.ZodString;
+                pid: z.ZodInt;
+                shell: z.ZodString;
+                cwd: z.ZodString;
+                title: z.ZodString;
+                name: z.ZodNullable<z.ZodString>;
+                cols: z.ZodInt;
+                rows: z.ZodInt;
+                state: z.ZodEnum<{
+                    running: "running";
+                    exited: "exited";
+                }>;
+                exit_code: z.ZodNullable<z.ZodInt>;
+                exit_signal: z.ZodNullable<z.ZodEnum<{
+                    SIGINT: "SIGINT";
+                    SIGTERM: "SIGTERM";
+                    SIGKILL: "SIGKILL";
+                    SIGHUP: "SIGHUP";
+                    SIGQUIT: "SIGQUIT";
+                    SIGTSTP: "SIGTSTP";
+                    SIGCONT: "SIGCONT";
+                    SIGUSR1: "SIGUSR1";
+                    SIGUSR2: "SIGUSR2";
+                }>>;
+                last_seq: z.ZodInt;
+                created_at_ms: z.ZodInt;
+                controller_client_id: z.ZodNullable<z.ZodString>;
+                attached_clients: z.ZodInt;
+                orphan_expires_at_ms: z.ZodNullable<z.ZodInt>;
+            }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"watch">;
+            resource_id: z.ZodString;
+            path: z.ZodString;
+            orphan_expires_at_ms: z.ZodNullable<z.ZodInt>;
+        }, z.core.$strict>], "kind">;
+        readonly kind: "stream";
+        readonly since: "1.0";
+        readonly errors: readonly ["RESOURCE_GONE", "AUTH_FORBIDDEN", "RESOURCE_BUSY"];
+    };
+    readonly "session.detach": {
+        readonly params: z.ZodObject<{
+            resource_id: z.ZodString;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            orphan_expires_at_ms: z.ZodNullable<z.ZodInt>;
+        }, z.core.$strict>;
+        readonly kind: "unary";
+        readonly since: "1.0";
+        readonly errors: readonly ["RESOURCE_GONE"];
+    };
+    readonly "session.release": {
+        readonly params: z.ZodObject<{
+            resource_id: z.ZodString;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            released: z.ZodLiteral<true>;
+        }, z.core.$strict>;
+        readonly kind: "unary";
+        readonly since: "1.0";
+        readonly errors: readonly ["RESOURCE_GONE", "AUTH_FORBIDDEN"];
+    };
+    readonly "session.list": {
+        readonly params: z.ZodObject<{}, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            resources: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"pty">;
+                pty: z.ZodObject<{
+                    resource_id: z.ZodString;
+                    pid: z.ZodInt;
+                    shell: z.ZodString;
+                    cwd: z.ZodString;
+                    title: z.ZodString;
+                    name: z.ZodNullable<z.ZodString>;
+                    cols: z.ZodInt;
+                    rows: z.ZodInt;
+                    state: z.ZodEnum<{
+                        running: "running";
+                        exited: "exited";
+                    }>;
+                    exit_code: z.ZodNullable<z.ZodInt>;
+                    exit_signal: z.ZodNullable<z.ZodEnum<{
+                        SIGINT: "SIGINT";
+                        SIGTERM: "SIGTERM";
+                        SIGKILL: "SIGKILL";
+                        SIGHUP: "SIGHUP";
+                        SIGQUIT: "SIGQUIT";
+                        SIGTSTP: "SIGTSTP";
+                        SIGCONT: "SIGCONT";
+                        SIGUSR1: "SIGUSR1";
+                        SIGUSR2: "SIGUSR2";
+                    }>>;
+                    last_seq: z.ZodInt;
+                    created_at_ms: z.ZodInt;
+                    controller_client_id: z.ZodNullable<z.ZodString>;
+                    attached_clients: z.ZodInt;
+                    orphan_expires_at_ms: z.ZodNullable<z.ZodInt>;
+                }, z.core.$strict>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"watch">;
+                resource_id: z.ZodString;
+                path: z.ZodString;
+                orphan_expires_at_ms: z.ZodNullable<z.ZodInt>;
+            }, z.core.$strict>], "kind">>;
+        }, z.core.$strict>;
+        readonly kind: "unary";
+        readonly since: "1.0";
+        readonly errors: readonly ["INTERNAL"];
+    };
+};
+type OpName = keyof typeof OPS;
+type OpParams<N extends OpName> = z.input<(typeof OPS)[N]["params"]>;
+type OpResult<N extends OpName> = z.output<(typeof OPS)[N]["result"]>;
+declare const EVENTS: {
+    readonly "fs.changed": z.ZodObject<{
+        changes: z.ZodArray<z.ZodObject<{
+            type: z.ZodEnum<{
+                created: "created";
+                deleted: "deleted";
+                modified: "modified";
+                moved: "moved";
+            }>;
+            path: z.ZodString;
+            to_path: z.ZodOptional<z.ZodString>;
+            kind: z.ZodEnum<{
+                unknown: "unknown";
+                file: "file";
+                dir: "dir";
+                symlink: "symlink";
+            }>;
+        }, z.core.$strict>>;
+        overflow: z.ZodBoolean;
+    }, z.core.$strict>;
+    readonly "exec.exited": z.ZodObject<{
+        exit_code: z.ZodNullable<z.ZodInt>;
+        exit_signal: z.ZodNullable<z.ZodEnum<{
+            SIGINT: "SIGINT";
+            SIGTERM: "SIGTERM";
+            SIGKILL: "SIGKILL";
+            SIGHUP: "SIGHUP";
+            SIGQUIT: "SIGQUIT";
+            SIGTSTP: "SIGTSTP";
+            SIGCONT: "SIGCONT";
+            SIGUSR1: "SIGUSR1";
+            SIGUSR2: "SIGUSR2";
+        }>>;
+    }, z.core.$strict>;
+    readonly "exec.title": z.ZodObject<{
+        title: z.ZodString;
+    }, z.core.$strict>;
+    readonly "exec.cwd": z.ZodObject<{
+        cwd: z.ZodString;
+    }, z.core.$strict>;
+    readonly "session.control_changed": z.ZodObject<{
+        controller_client_id: z.ZodNullable<z.ZodString>;
+        your_mode: z.ZodEnum<{
+            control: "control";
+            read_only: "read_only";
+        }>;
+    }, z.core.$strict>;
+    readonly "relay.device_status": z.ZodObject<{
+        online: z.ZodBoolean;
+        since_ms: z.ZodInt;
+        app_version: z.ZodNullable<z.ZodString>;
+        protocol_version: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    readonly "relay.auth_expiring": z.ZodObject<{
+        expires_at_ms: z.ZodInt;
+    }, z.core.$strict>;
+};
+
+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;
+}
+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;
+}
+
+declare function DesktopClientProvider(props: {
+    client: DesktopClient;
+    children?: ReactNode;
+}): ReactNode;
+/** The client from the nearest provider (or the one passed in). Throws when there is neither. */
+declare function useDesktopClient(client?: DesktopClient): DesktopClient;
+/** Live connection state (status, welcome, attempts, retryInMs, lastError). Connects on mount when idle. */
+declare function useDesktopConnection(client?: DesktopClient): DesktopClientState;
+interface DesktopRequestState<N extends OpName> {
+    data: OpResult<N> | undefined;
+    error: DesktopProtocolError | undefined;
+    loading: boolean;
+    /** Re-run now; resolves with the fresh result. */
+    refetch: () => Promise<OpResult<N> | undefined>;
+}
+interface UseDesktopRequestOptions extends Omit<RequestOptions, "signal"> {
+    /** Default true. False = do not run until refetch() or enabled flips true. */
+    enabled?: boolean;
+    client?: DesktopClient;
+}
+/**
+ * Run a unary op and keep its latest result. Re-runs when `op` or the params' JSON changes, and
+ * after a reconnect if the last attempt failed with a retryable error. Aborts on unmount.
+ */
+declare function useDesktopRequest<N extends OpName>(op: N, params: OpParams<N>, options?: UseDesktopRequestOptions): DesktopRequestState<N>;
+/** Subscribe to one protocol event (fs.changed, exec.exited, relay.device_status, …) for the component's life. */
+declare function useDesktopEvent<E extends EventName>(name: E, handler: EventHandler<E>, options?: {
+    client?: DesktopClient;
+}): void;
+
+export { DesktopClientProvider, type DesktopRequestState, type UseDesktopRequestOptions, useDesktopClient, useDesktopConnection, useDesktopEvent, useDesktopRequest };