@trycua/cua 0.2.0

package/dist/spaces/transport/session.d.ts

@@ -0,0 +1,120 @@
+/**
+ * `McpSession` — the MCP vocabulary, over any {@link Transport}.
+ *
+ * This is the piece that makes the seam worth having: it is the same code in
+ * Node, in a Tauri webview and in a browser, and the only thing that differs
+ * between them is which transport it was constructed with.
+ *
+ * It is deliberately small. It owns the handshake, id allocation, and the
+ * unwrapping of the `content` / `isError` envelope — and nothing else. The
+ * server on the other side is the Rust Spaces MCP server (`cua daemon mcp`,
+ * the daemon's `/mcp`, or the Tauri app's bridge); its tools are the Spaces
+ * contract (`libs/cua/spaces-contract/manifest.json`). Node code that can load
+ * the native binding uses `@trycua/cua/spaces` (typed) instead.
+ */
+import { type Json, type SendOptions, type Transport } from "./types.js";
+/** The MCP revision offered. The Rust server accepts 2025-06-18, 2025-03-26
+ * and 2024-11-05, and answers with the one it picked. */
+export declare const PROTOCOL_VERSION = "2025-06-18";
+export interface ClientInfo {
+    name: string;
+    version: string;
+}
+export interface ServerInfo {
+    name: string;
+    version: string;
+}
+/** One part of a tool result. `call_tool` passes through `image`,
+ * `audio` and `resource` parts from an in-space tool unchanged, so this is not
+ * only ever text. */
+export interface ContentPart {
+    type: string;
+    text?: string;
+    [key: string]: Json | undefined;
+}
+export interface ToolResult {
+    content: ContentPart[];
+    isError: boolean;
+    /** `structuredContent`, when the tool returned one (tool errors carry
+     * `{error: {kind, message}}` with a stable `kind`). */
+    structured?: Json;
+}
+export interface ToolDescriptor {
+    name: string;
+    description?: string;
+    inputSchema?: Json;
+}
+/**
+ * A tool that ran and failed.
+ *
+ * This is a separate type from {@link TransportError} on purpose. The server
+ * reports a failing tool as a *successful* JSON-RPC response carrying
+ * `isError: true` — the only JSON-RPC `error` objects it ever sends are
+ * `-32601` for an unknown method or tool. Collapsing the two would make
+ * "the sandbox refused this command" indistinguishable from "the control
+ * plane is not running", and those need different handling by every caller.
+ */
+export declare class ToolError extends Error {
+    readonly tag = "ToolError";
+    readonly tool: string;
+    readonly content: ContentPart[];
+    /** The server's stable error kind (`capability_missing`,
+     * `teleport_refused`, `not_found`, ...), when it sent one. */
+    readonly kind: string | undefined;
+    constructor(tool: string, content: ContentPart[], structured?: Json);
+}
+/** Concatenate the text parts, which is what almost every caller wants. */
+export declare function textOf(content: ContentPart[]): string;
+export interface SessionOptions {
+    clientInfo?: ClientInfo;
+}
+export declare class McpSession {
+    readonly transport: Transport;
+    private nextId;
+    private handshake;
+    private readonly clientInfo;
+    constructor(transport: Transport, options?: SessionOptions);
+    private allocateId;
+    private unwrap;
+    /**
+     * Perform the MCP handshake, at most once per session.
+     *
+     * The server does not require this — it builds its dispatch table before the
+     * read loop starts, so `tools/call` works cold. We do it anyway, and we
+     * memoize it: it is what makes this session usable against a *conforming*
+     * MCP server rather than only against this one, and the cost is a single
+     * round trip.
+     *
+     * The result is cached as a promise, not a value, so concurrent first calls
+     * share one handshake instead of racing two.
+     */
+    initialize(options?: SendOptions): Promise<ServerInfo | undefined>;
+    private performHandshake;
+    /** Sends a request after the handshake; re-initializes once when the
+     * server says the session expired (HTTP 404 from a restarted daemon). */
+    private request;
+    /** Every tool the server serves, with its input schema. */
+    listTools(options?: SendOptions): Promise<ToolDescriptor[]>;
+    /**
+     * Call a tool and return its envelope, including a failure.
+     *
+     * Use this when a caller wants to inspect `isError` itself — for instance a
+     * probe that treats "not available" as an answer rather than an exception.
+     * Most callers want {@link call}.
+     */
+    callRaw(name: string, args?: Record<string, Json>, options?: SendOptions): Promise<ToolResult>;
+    /** Call a tool, throwing {@link ToolError} if it failed. */
+    call(name: string, args?: Record<string, Json>, options?: SendOptions): Promise<ContentPart[]>;
+    /** Call a tool and return its text parts joined — the common case, since
+     * most of these tools answer with one text part. */
+    callText(name: string, args?: Record<string, Json>, options?: SendOptions): Promise<string>;
+    /**
+     * Call a tool whose text part is JSON, and parse it.
+     *
+     * Worth its own method because the parse failure needs to say which tool
+     * produced the unparsable text — without that, a server-side format change
+     * surfaces as a bare `SyntaxError` with no attribution.
+     */
+    callJson<T = Json>(name: string, args?: Record<string, Json>, options?: SendOptions): Promise<T>;
+    close(): Promise<void>;
+}

package/dist/spaces/transport/session.js

@@ -0,0 +1,188 @@
+/**
+ * `McpSession` — the MCP vocabulary, over any {@link Transport}.
+ *
+ * This is the piece that makes the seam worth having: it is the same code in
+ * Node, in a Tauri webview and in a browser, and the only thing that differs
+ * between them is which transport it was constructed with.
+ *
+ * It is deliberately small. It owns the handshake, id allocation, and the
+ * unwrapping of the `content` / `isError` envelope — and nothing else. The
+ * server on the other side is the Rust Spaces MCP server (`cua daemon mcp`,
+ * the daemon's `/mcp`, or the Tauri app's bridge); its tools are the Spaces
+ * contract (`libs/cua/spaces-contract/manifest.json`). Node code that can load
+ * the native binding uses `@trycua/cua/spaces` (typed) instead.
+ */
+import { TransportError, } from "./types.js";
+/** The MCP revision offered. The Rust server accepts 2025-06-18, 2025-03-26
+ * and 2024-11-05, and answers with the one it picked. */
+export const PROTOCOL_VERSION = "2025-06-18";
+/**
+ * A tool that ran and failed.
+ *
+ * This is a separate type from {@link TransportError} on purpose. The server
+ * reports a failing tool as a *successful* JSON-RPC response carrying
+ * `isError: true` — the only JSON-RPC `error` objects it ever sends are
+ * `-32601` for an unknown method or tool. Collapsing the two would make
+ * "the sandbox refused this command" indistinguishable from "the control
+ * plane is not running", and those need different handling by every caller.
+ */
+export class ToolError extends Error {
+    tag = "ToolError";
+    tool;
+    content;
+    /** The server's stable error kind (`capability_missing`,
+     * `teleport_refused`, `not_found`, ...), when it sent one. */
+    kind;
+    constructor(tool, content, structured) {
+        super(`${tool}: ${textOf(content) || "failed"}`);
+        this.name = "ToolError";
+        this.tool = tool;
+        this.content = content;
+        const error = structured?.error;
+        this.kind = typeof error?.kind === "string" ? error.kind : undefined;
+    }
+}
+/** Concatenate the text parts, which is what almost every caller wants. */
+export function textOf(content) {
+    return content
+        .filter((part) => part.type === "text" && typeof part.text === "string")
+        .map((part) => part.text)
+        .join("\n");
+}
+export class McpSession {
+    transport;
+    nextId = 1;
+    handshake;
+    clientInfo;
+    constructor(transport, options = {}) {
+        this.transport = transport;
+        this.clientInfo = options.clientInfo ?? { name: "@trycua/cua", version: "0.2.0" };
+    }
+    allocateId() {
+        return this.nextId++;
+    }
+    unwrap(response, method) {
+        if (response === null) {
+            throw new TransportError(`${method} expected a reply and got none`);
+        }
+        if (response.error) {
+            throw new TransportError(`${method}: ${response.error.message}`, response.error.code);
+        }
+        return response.result ?? null;
+    }
+    /**
+     * Perform the MCP handshake, at most once per session.
+     *
+     * The server does not require this — it builds its dispatch table before the
+     * read loop starts, so `tools/call` works cold. We do it anyway, and we
+     * memoize it: it is what makes this session usable against a *conforming*
+     * MCP server rather than only against this one, and the cost is a single
+     * round trip.
+     *
+     * The result is cached as a promise, not a value, so concurrent first calls
+     * share one handshake instead of racing two.
+     */
+    async initialize(options) {
+        if (!this.handshake) {
+            this.handshake = this.performHandshake(options).catch((error) => {
+                // A failed handshake must not poison the session forever; a later call
+                // should be free to try again against a restarted server.
+                this.handshake = undefined;
+                throw error;
+            });
+        }
+        return this.handshake;
+    }
+    async performHandshake(options) {
+        const result = this.unwrap(await this.transport.send({
+            jsonrpc: "2.0",
+            id: this.allocateId(),
+            method: "initialize",
+            params: {
+                protocolVersion: PROTOCOL_VERSION,
+                capabilities: {},
+                clientInfo: { ...this.clientInfo },
+            },
+        }, options), "initialize");
+        await this.transport.send({ jsonrpc: "2.0", method: "notifications/initialized" }, options);
+        const info = result?.serverInfo;
+        return info;
+    }
+    /** Sends a request after the handshake; re-initializes once when the
+     * server says the session expired (HTTP 404 from a restarted daemon). */
+    async request(method, params, options) {
+        for (let attempt = 0;; attempt++) {
+            await this.initialize(options);
+            try {
+                const message = params === undefined
+                    ? { jsonrpc: "2.0", id: this.allocateId(), method }
+                    : { jsonrpc: "2.0", id: this.allocateId(), method, params };
+                return this.unwrap(await this.transport.send(message, options), method);
+            }
+            catch (error) {
+                if (attempt === 0 && error instanceof TransportError && error.code === 404) {
+                    this.handshake = undefined;
+                    continue;
+                }
+                throw error;
+            }
+        }
+    }
+    /** Every tool the server serves, with its input schema. */
+    async listTools(options) {
+        const result = await this.request("tools/list", undefined, options);
+        const tools = result?.tools;
+        return Array.isArray(tools) ? tools : [];
+    }
+    /**
+     * Call a tool and return its envelope, including a failure.
+     *
+     * Use this when a caller wants to inspect `isError` itself — for instance a
+     * probe that treats "not available" as an answer rather than an exception.
+     * Most callers want {@link call}.
+     */
+    async callRaw(name, args = {}, options) {
+        const result = (await this.request("tools/call", { name, arguments: args }, options));
+        const content = Array.isArray(result?.content) ? result.content : [];
+        // `isError` is read as a field and never inferred from the shape of the
+        // content: a missing flag means the server did not say, and reading
+        // silence as success is how a failure becomes a wrong answer instead of an
+        // error. This server always sends it explicitly, including `false`.
+        const out = { content, isError: result?.isError === true };
+        if (result?.structuredContent !== undefined)
+            out.structured = result.structuredContent;
+        return out;
+    }
+    /** Call a tool, throwing {@link ToolError} if it failed. */
+    async call(name, args = {}, options) {
+        const result = await this.callRaw(name, args, options);
+        if (result.isError)
+            throw new ToolError(name, result.content, result.structured);
+        return result.content;
+    }
+    /** Call a tool and return its text parts joined — the common case, since
+     * most of these tools answer with one text part. */
+    async callText(name, args = {}, options) {
+        return textOf(await this.call(name, args, options));
+    }
+    /**
+     * Call a tool whose text part is JSON, and parse it.
+     *
+     * Worth its own method because the parse failure needs to say which tool
+     * produced the unparsable text — without that, a server-side format change
+     * surfaces as a bare `SyntaxError` with no attribution.
+     */
+    async callJson(name, args = {}, options) {
+        const text = await this.callText(name, args, options);
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new TransportError(`${name} did not return JSON: ${text.slice(0, 200)}`);
+        }
+    }
+    async close() {
+        this.handshake = undefined;
+        await this.transport.close();
+    }
+}

package/dist/spaces/transport/tauri.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `TauriTransport` — the conformer that makes this SDK usable from a webview.
+ *
+ * A Tauri frontend cannot load the package's N-API binding, so the root
+ * export cannot run there. What it *can* do is `invoke()` a Rust command
+ * that hands the JSON-RPC message to the Rust Spaces MCP server (in process
+ * via `cua_spaces::mcp::McpServer::handle`, or the daemon), and this class
+ * is the lines that carry a message across that call.
+ *
+ * Everything above it — `McpSession`, the handshake, the tool vocabulary, the
+ * `isError` unwrapping — is the same code a Node consumer runs. That is the
+ * claim the seam exists to make true.
+ *
+ * # Why `invoke` is injected rather than imported
+ *
+ * This package does not depend on `@tauri-apps/api`, and should not: a Node
+ * or browser consumer installing the Spaces SDK should not acquire a desktop
+ * framework. The host passes its own `invoke`, which also makes the transport
+ * trivially testable with a function that returns canned replies — the
+ * conformance test does exactly that.
+ */
+import { type RpcOutgoing, type RpcResponse, type SendOptions, type Transport } from "./types.js";
+/** The shape of Tauri's `invoke`, narrowed to what this needs. */
+export type InvokeFn = <T>(command: string, args?: Record<string, unknown>) => Promise<T>;
+export interface TauriOptions {
+    /** Usually `(await import("@tauri-apps/api/core")).invoke`. */
+    invoke: InvokeFn;
+    /** The Rust command name (default `spaces_mcp_request`). */
+    requestCommand?: string;
+    /** The Rust command that ends the session (default `spaces_mcp_shutdown`). */
+    shutdownCommand?: string;
+}
+export declare const DEFAULT_REQUEST_COMMAND = "spaces_mcp_request";
+export declare const DEFAULT_SHUTDOWN_COMMAND = "spaces_mcp_shutdown";
+export declare class TauriTransport implements Transport {
+    readonly kind = "tauri";
+    private readonly invoke;
+    private readonly requestCommand;
+    private readonly shutdownCommand;
+    constructor(options: TauriOptions);
+    send(message: RpcOutgoing, options?: SendOptions): Promise<RpcResponse | null>;
+    /**
+     * Ask the bridge to close the server's stdin.
+     *
+     * A failure here is swallowed: the transport is being torn down, the app may
+     * already be quitting, and turning "could not reach the bridge while closing"
+     * into an exception makes shutdown paths fragile for no gain.
+     */
+    close(): Promise<void>;
+}

package/dist/spaces/transport/tauri.js

@@ -0,0 +1,90 @@
+/**
+ * `TauriTransport` — the conformer that makes this SDK usable from a webview.
+ *
+ * A Tauri frontend cannot load the package's N-API binding, so the root
+ * export cannot run there. What it *can* do is `invoke()` a Rust command
+ * that hands the JSON-RPC message to the Rust Spaces MCP server (in process
+ * via `cua_spaces::mcp::McpServer::handle`, or the daemon), and this class
+ * is the lines that carry a message across that call.
+ *
+ * Everything above it — `McpSession`, the handshake, the tool vocabulary, the
+ * `isError` unwrapping — is the same code a Node consumer runs. That is the
+ * claim the seam exists to make true.
+ *
+ * # Why `invoke` is injected rather than imported
+ *
+ * This package does not depend on `@tauri-apps/api`, and should not: a Node
+ * or browser consumer installing the Spaces SDK should not acquire a desktop
+ * framework. The host passes its own `invoke`, which also makes the transport
+ * trivially testable with a function that returns canned replies — the
+ * conformance test does exactly that.
+ */
+import { TransportError, } from "./types.js";
+export const DEFAULT_REQUEST_COMMAND = "spaces_mcp_request";
+export const DEFAULT_SHUTDOWN_COMMAND = "spaces_mcp_shutdown";
+export class TauriTransport {
+    kind = "tauri";
+    invoke;
+    requestCommand;
+    shutdownCommand;
+    constructor(options) {
+        this.invoke = options.invoke;
+        this.requestCommand = options.requestCommand ?? DEFAULT_REQUEST_COMMAND;
+        this.shutdownCommand = options.shutdownCommand ?? DEFAULT_SHUTDOWN_COMMAND;
+    }
+    async send(message, options = {}) {
+        if (options.signal?.aborted) {
+            throw new TransportError(`${message.method} was aborted`);
+        }
+        // The Rust side owns the wait, including the timeout, because it owns the
+        // pending-reply map: a deadline enforced only here would leave the bridge
+        // holding a waiter for a reply nobody wants any more.
+        const call = this.invoke(this.requestCommand, {
+            message: message,
+            timeoutSecs: options.timeoutSeconds ?? null,
+        });
+        const value = options.signal ? await race(call, options.signal, message.method) : await call;
+        // A notification gets no reply, and the bridge answers `null` for it
+        // rather than inventing one.
+        if (value === null || value === undefined)
+            return null;
+        if (typeof value !== "object" || Array.isArray(value)) {
+            throw new TransportError(`${message.method}: the bridge returned a non-object reply`);
+        }
+        return value;
+    }
+    /**
+     * Ask the bridge to close the server's stdin.
+     *
+     * A failure here is swallowed: the transport is being torn down, the app may
+     * already be quitting, and turning "could not reach the bridge while closing"
+     * into an exception makes shutdown paths fragile for no gain.
+     */
+    async close() {
+        try {
+            await this.invoke(this.shutdownCommand);
+        }
+        catch {
+            /* the bridge is gone, which is the state we wanted */
+        }
+    }
+}
+/**
+ * Abort support for a call we cannot actually cancel.
+ *
+ * The server has no `notifications/cancelled` handling and is strictly
+ * sequential, so aborting abandons the reply — the work still runs to
+ * completion. This is honest about that rather than implying a cancel: the
+ * promise rejects, the bridge's waiter is left to its own timeout.
+ */
+async function race(promise, signal, method) {
+    return await Promise.race([
+        promise,
+        new Promise((_resolve, reject) => {
+            const onAbort = () => reject(new TransportError(`${method} was abandoned`));
+            if (signal.aborted)
+                return onAbort();
+            signal.addEventListener("abort", onAbort, { once: true });
+        }),
+    ]);
+}

package/dist/spaces/transport/types.d.ts

@@ -0,0 +1,123 @@
+/**
+ * The transport seam.
+ *
+ * # Why a seam at all
+ *
+ * The Spaces control plane is the Rust MCP server (`cua daemon mcp` over
+ * stdio, the daemon's `/mcp` over HTTP). Three of the four places this SDK
+ * has to run cannot spawn a subprocess:
+ *
+ * | host | can spawn a subprocess? | can load the N-API binding? |
+ * |---|---|---|
+ * | Node | yes | yes |
+ * | Tauri webview (`apps/cua-spaces`) | no | no |
+ * | browser | no | no |
+ * | React Native | no | yes, via UBRN |
+ *
+ * So a TypeScript SDK that owns its own stdio transport can only ever run in
+ * Node, and "the TypeScript SDK" would not be the thing our own app uses. The
+ * transport is what has to be pluggable for the same API to be true
+ * everywhere; everything above it — the handshake, the tool vocabulary, the
+ * error shape — is identical whatever carries the bytes.
+ *
+ * # Where the seam falls, and why it is not at the byte level
+ *
+ * A `Transport` exchanges **whole JSON-RPC messages**, not bytes. That is the
+ * load-bearing choice.
+ *
+ * Line framing is protocol. It is the bug the architecture document calls §1
+ * — a framer that dropped every byte after the first newline in a chunk — and
+ * it is invisible until it is catastrophic. If the seam were a byte stream,
+ * every host would re-implement that framer, and the whole argument for one
+ * Rust core would be conceded at exactly the layer that has already been got
+ * wrong once.
+ *
+ * At the message level the framer lives wherever the server lives: in the
+ * Rust `cua_spaces::mcp::stdio` framer, the daemon's HTTP endpoint, or the
+ * Tauri app's Rust side. None of them is the renderer's problem.
+ *
+ * # Nothing in this file imports the native binding
+ *
+ * This module and everything under `src/transport/` is dependency-free,
+ * platform-free TypeScript. It is exported from `@trycua/cua/spaces/transport`
+ * rather than the package root precisely so a webview bundle can import it
+ * without dragging in `@ubjs/node`, which would fail to resolve and take the
+ * whole bundle with it.
+ */
+/** A JSON value, as it crosses the wire. */
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/** JSON-RPC 2.0 ids: this SDK only ever sends numbers, but a reply echoes
+ * whatever it was given, and a conforming peer may use a string. */
+export type RpcId = number | string;
+export interface RpcRequest {
+    jsonrpc: "2.0";
+    id: RpcId;
+    method: string;
+    params?: Json;
+}
+/** A message with no `id`. It gets no reply, and a transport must resolve
+ * `null` for it rather than inventing one. */
+export interface RpcNotification {
+    jsonrpc: "2.0";
+    method: string;
+    params?: Json;
+}
+export interface RpcError {
+    code: number;
+    message: string;
+    data?: Json;
+}
+export interface RpcResponse {
+    jsonrpc: "2.0";
+    id: RpcId;
+    result?: Json;
+    error?: RpcError;
+}
+export type RpcOutgoing = RpcRequest | RpcNotification;
+export interface SendOptions {
+    /**
+     * Seconds to wait for a reply.
+     *
+     * The default is deliberately long. `teleport_app` and provisioning run with
+     * `timeout=900` server-side, and the agent-CLI registration this server
+     * ships with sets `requestTimeoutMs: 900000`. A transport that imposed a
+     * short deadline would silently break the app's slowest and most valuable
+     * operations, so a conformer must not shorten this on its own initiative.
+     */
+    timeoutSeconds?: number;
+    /** Aborts the wait. A transport should still expect the server to finish the
+     * work: this server has no `notifications/cancelled` handling, so aborting
+     * abandons the reply rather than stopping the call. */
+    signal?: AbortSignal;
+}
+/**
+ * The one interface a host has to implement.
+ *
+ * Implementations must:
+ * - resolve the reply whose `id` matches the request's, and not some other
+ *   reply that happened to arrive first;
+ * - resolve `null` for a notification;
+ * - reject every in-flight call if the peer dies, rather than leaving callers
+ *   hanging on a reply that is never coming;
+ * - be safe to call again after `close()`, either by restarting or by
+ *   rejecting clearly.
+ */
+export interface Transport {
+    /** A short name for diagnostics — `"stdio"`, `"tauri"`. */
+    readonly kind: string;
+    /** Send one message; resolve its reply, or `null` for a notification. */
+    send(message: RpcOutgoing, options?: SendOptions): Promise<RpcResponse | null>;
+    /** Release the peer. Idempotent. */
+    close(): Promise<void>;
+}
+/** Thrown for anything that goes wrong beneath the tool call: a dead peer, a
+ * timeout, a JSON-RPC `error` object. A failing *tool* is not this — see
+ * `ToolError`, because this server reports tool failure as a successful
+ * response carrying `isError: true`. */
+export declare class TransportError extends Error {
+    readonly tag = "TransportError";
+    readonly code: number | undefined;
+    constructor(message: string, code?: number);
+}

package/dist/spaces/transport/types.js

@@ -0,0 +1,59 @@
+/**
+ * The transport seam.
+ *
+ * # Why a seam at all
+ *
+ * The Spaces control plane is the Rust MCP server (`cua daemon mcp` over
+ * stdio, the daemon's `/mcp` over HTTP). Three of the four places this SDK
+ * has to run cannot spawn a subprocess:
+ *
+ * | host | can spawn a subprocess? | can load the N-API binding? |
+ * |---|---|---|
+ * | Node | yes | yes |
+ * | Tauri webview (`apps/cua-spaces`) | no | no |
+ * | browser | no | no |
+ * | React Native | no | yes, via UBRN |
+ *
+ * So a TypeScript SDK that owns its own stdio transport can only ever run in
+ * Node, and "the TypeScript SDK" would not be the thing our own app uses. The
+ * transport is what has to be pluggable for the same API to be true
+ * everywhere; everything above it — the handshake, the tool vocabulary, the
+ * error shape — is identical whatever carries the bytes.
+ *
+ * # Where the seam falls, and why it is not at the byte level
+ *
+ * A `Transport` exchanges **whole JSON-RPC messages**, not bytes. That is the
+ * load-bearing choice.
+ *
+ * Line framing is protocol. It is the bug the architecture document calls §1
+ * — a framer that dropped every byte after the first newline in a chunk — and
+ * it is invisible until it is catastrophic. If the seam were a byte stream,
+ * every host would re-implement that framer, and the whole argument for one
+ * Rust core would be conceded at exactly the layer that has already been got
+ * wrong once.
+ *
+ * At the message level the framer lives wherever the server lives: in the
+ * Rust `cua_spaces::mcp::stdio` framer, the daemon's HTTP endpoint, or the
+ * Tauri app's Rust side. None of them is the renderer's problem.
+ *
+ * # Nothing in this file imports the native binding
+ *
+ * This module and everything under `src/transport/` is dependency-free,
+ * platform-free TypeScript. It is exported from `@trycua/cua/spaces/transport`
+ * rather than the package root precisely so a webview bundle can import it
+ * without dragging in `@ubjs/node`, which would fail to resolve and take the
+ * whole bundle with it.
+ */
+/** Thrown for anything that goes wrong beneath the tool call: a dead peer, a
+ * timeout, a JSON-RPC `error` object. A failing *tool* is not this — see
+ * `ToolError`, because this server reports tool failure as a successful
+ * response carrying `isError: true`. */
+export class TransportError extends Error {
+    tag = "TransportError";
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "TransportError";
+        this.code = code;
+    }
+}

package/dist/teleport/controller.d.ts

@@ -0,0 +1,34 @@
+/**
+ * {@link TeleportPickerController}: the headless state machine bound to a
+ * {@link TeleportHost}. Frameworks subscribe to it (React:
+ * `useSyncExternalStore(c.subscribe, () => c.state)`; the web component
+ * re-renders on each change).
+ */
+import { type CatalogEntry, type PickerEvent, type PickerState, type TeleportHost } from "./model.js";
+export interface ControllerOptions {
+    spaceName: string;
+    /** Jump straight to the options for this app (a drop or window drag). */
+    preselect?: {
+        entry: CatalogEntry;
+        files?: string[];
+    };
+}
+export declare class TeleportPickerController {
+    #private;
+    readonly host: TeleportHost;
+    constructor(host: TeleportHost, options: ControllerOptions);
+    get state(): PickerState;
+    /** Subscribe to changes; returns the unsubscribe. */
+    subscribe: (listener: () => void) => (() => void);
+    dispatch: (event: PickerEvent) => void;
+    /** Loads (or reloads) the catalog. */
+    load(): Promise<void>;
+    /** Opens the options for the selected (or given) app. */
+    choose(id?: string): void;
+    /** Opens the native chooser and adds what the user picked. */
+    chooseFiles(): Promise<void>;
+    /** Builds the plan (sizes, installs, consent items). */
+    plan(): Promise<void>;
+    /** Runs the approved plan with the user's consent. */
+    confirm(): Promise<void>;
+}