cmux 0.3.6 → 0.4.0

package/README.md

@@ -1,73 +1,119 @@
-# cmux
+# cmux TypeScript Client
 
-Cloud VMs for development - spawn isolated dev environments instantly.
+The typed client library for cmux-tui frontends. It exposes every implemented
+command and event in protocol v10, transport-independent request handling,
+browser-safe attach streams, and Node.js Unix-socket defaults.
 
-## Installation
+## Install and build
 
 ```bash
-npm install -g cmux
+npm install cmux
+npm run build
 ```
 
-## Quick Start
-
-```bash
-# Login
-cmux login
+The package has no runtime dependencies. The Node entry requires Node 20 or
+newer. Browser bundles resolve the root `browser` export condition, and the
+same browser-safe surface is available explicitly from `cmux/browser`.
+
+## Building a frontend
+
+This example uses an existing xterm.js terminal and a cmux WebSocket endpoint.
+Attach payloads are decoded to `Uint8Array`, which xterm.js accepts directly.
+
+```ts
+import { Terminal } from "@xterm/xterm";
+import { CmuxClient, WebSocketTransport } from "cmux";
+const terminal = new Terminal();
+const transport = new WebSocketTransport("ws://127.0.0.1:9000/api/v1/ws", {
+  onPairingChallenge: ({ code }) => showCode(code),
+});
+const client = new CmuxClient({ transport });
+const info = await client.identify();
+console.log(`cmux protocol ${info.protocol}`);
+const tree = await client.listWorkspaces();
+const workspace = tree.workspaces.find(({ active }) => active);
+const screen = workspace?.screens.find(({ active }) => active);
+const pane = screen?.panes.find((item) => "tabs" in item);
+const surface = pane && "tabs" in pane ? pane.tabs[pane.active_tab]?.surface : undefined;
+if (surface === undefined) throw new Error("No active surface");
+const stream = await client.attachSurface(surface);
+void (async () => {
+  for await (const event of stream) {
+    if (event.event === "vt-state" || event.event === "output") terminal.write(event.data);
+  }
+})();
+await client.send(surface, { bytes: new TextEncoder().encode("ls\r") });
+```
 
-# Create a VM
-cmux start                     # Returns ID like cmux_abc123
+Without `authToken`, the transport requests a short-lived pairing code and
+holds protocol requests until a trusted TUI approves it. The approval issues a
+credential through `onPairingCredential` for reconnects. For automation, a
+server started with `--ws-token` accepts that static token instead:
 
-# Access the VM
-cmux code cmux_abc123          # Open VS Code in browser
-cmux ssh cmux_abc123           # SSH into VM
+```ts
+const transport = new WebSocketTransport("ws://127.0.0.1:7681", {
+  authToken: "replace-with-a-secret",
+});
+```
 
-# Run commands
-cmux exec cmux_abc123 "npm install"
+`WebSocketTransport` uses the browser's global `WebSocket`. In Node, inject any
+compatible constructor without adding a runtime dependency to this package:
 
-# Manage lifecycle
-cmux pause cmux_abc123         # Pause (preserves state)
-cmux resume cmux_abc123        # Resume
-cmux delete cmux_abc123        # Delete permanently
+```ts
+import WebSocket from "ws";
+import { CmuxClient, WebSocketTransport } from "cmux";
 
-# List all VMs
-cmux ls
+const client = new CmuxClient({
+  transport: new WebSocketTransport("ws://127.0.0.1:9000/api/v1/ws", WebSocket),
+});
 ```
 
-## Commands
+## Node Unix socket
 
-| Command | Description |
-|---------|-------------|
-| `cmux login` | Login via browser |
-| `cmux start [path]` | Create new VM, optionally sync directory |
-| `cmux ls` | List all VMs |
-| `cmux code <id>` | Open VS Code in browser |
-| `cmux vnc <id>` | Open VNC desktop in browser |
-| `cmux ssh <id>` | SSH into VM |
-| `cmux pty <id>` | Open interactive terminal |
-| `cmux exec <id> "cmd"` | Execute command |
-| `cmux sync <id> <path>` | Sync files to VM |
-| `cmux pause <id>` | Pause VM |
-| `cmux resume <id>` | Resume VM |
-| `cmux delete <id>` | Delete VM |
+The default Node entry preserves the original zero-argument API:
 
-## Browser Automation
+```ts
+import { CmuxClient } from "cmux/node";
 
-Control Chrome in the VNC desktop:
+const client = new CmuxClient();
+const created = await client.newWorkspace({ name: "sdk-demo", cols: 80, rows: 24 });
+await client.send(created.surface, { text: "echo hello\r" });
+console.log((await client.readScreen(created.surface)).text);
+await client.close();
+```
 
-```bash
-cmux computer open cmux_abc123 https://example.com
-cmux computer snapshot cmux_abc123       # Get interactive elements
-cmux computer click cmux_abc123 @e1      # Click element
-cmux computer type cmux_abc123 "hello"   # Type text
-cmux computer screenshot cmux_abc123     # Take screenshot
+`new CmuxClient()` uses `CMUX_TUI_SOCKET`, then legacy `CMUX_MUX_SOCKET`, then
+the default session socket. Unix subscribe and attach streams retain dedicated
+connections. An injected transport can multiplex attach streams and one
+subscription on its main connection; concurrent subscriptions require a
+`streamTransportFactory` because overflow events are terminal to one stream.
+Each stream retains at most 256 unread events, and each encoded attach payload
+is limited to 16 MiB by default. `maxBufferedEvents` and
+`maxAttachEncodedChars` may lower those limits for constrained clients.
+
+## Raw typed requests
+
+Every command method delegates to the same generic escape hatch:
+
+```ts
+const result = await client.request({ cmd: "copy", surface: 1, mode: "screen" });
 ```
 
-## Platform Support
+The `cmd` discriminator determines both required parameters and the successful
+response data type. `sendRaw()` remains available for untyped forward
+compatibility.
 
-- macOS (Apple Silicon & Intel)
-- Linux (x64 & ARM64)
-- Windows (x64)
+`clearHistory(surface, fallbackKey)` accepts a typed `TerminalKeyInput` and
+fails locally unless the server advertises `clear-history-key-v1`. It also
+rejects fallback `utf8` fields above the 4 KiB protocol limit before sending.
+`CmuxCommandError.delivery` exposes the server's `known-not-delivered` or
+`ambiguous` classification when present.
 
-## License
+## Verification
 
-MIT
+```bash
+npm ci
+npm run build
+npm test
+CMUX_TUI_SOCKET=/path/to/session.sock npm run e2e
+```

package/dist/src/base64.d.ts

@@ -0,0 +1,4 @@
+/** Decodes standard base64 without requiring Node's `Buffer`. */
+export declare function decodeBase64(value: string): Uint8Array;
+/** Encodes bytes as standard base64 without requiring Node's `Buffer`. */
+export declare function encodeBase64(value: Uint8Array): string;

package/dist/src/base64.js

@@ -0,0 +1,38 @@
+function nodeBuffer() {
+    return globalThis.Buffer;
+}
+/** Decodes standard base64 without requiring Node's `Buffer`. */
+export function decodeBase64(value) {
+    if (typeof globalThis.atob === "function") {
+        const decoded = globalThis.atob(value);
+        const bytes = new Uint8Array(decoded.length);
+        for (let index = 0; index < decoded.length; index += 1)
+            bytes[index] = decoded.charCodeAt(index);
+        return bytes;
+    }
+    const Buffer = nodeBuffer();
+    if (!Buffer)
+        throw new Error("base64 decoding is not available in this runtime");
+    const decoded = Buffer.from(value, "base64");
+    const bytes = new Uint8Array(decoded.length);
+    for (let index = 0; index < decoded.length; index += 1)
+        bytes[index] = decoded[index];
+    return bytes;
+}
+/** Encodes bytes as standard base64 without requiring Node's `Buffer`. */
+export function encodeBase64(value) {
+    if (typeof globalThis.btoa === "function") {
+        let binary = "";
+        const chunkSize = 0x8000;
+        for (let offset = 0; offset < value.length; offset += chunkSize) {
+            const chunk = value.subarray(offset, Math.min(offset + chunkSize, value.length));
+            for (const byte of chunk)
+                binary += String.fromCharCode(byte);
+        }
+        return globalThis.btoa(binary);
+    }
+    const Buffer = nodeBuffer();
+    if (!Buffer)
+        throw new Error("base64 encoding is not available in this runtime");
+    return Buffer.from(value).toString("base64");
+}

package/dist/src/browser.d.ts

@@ -0,0 +1,6 @@
+export { CmuxClient, CmuxStream, TERMINAL_KEY_TEXT_MAX_BYTES, type CmuxClientOptions, type CmuxClientOptions as ClientOptions, type AttachSurfaceOptions, type NewBrowserTabOptions, type NewPaneRightOptions, type NewScreenOptions, type NewTabOptions, type NewWorkspaceOptions, type ResizeTransactionOptions, type SelectOptions, type SelectTabOptions, type SendOptions, type SplitOptions, type SubscribeOptions, } from "./client.js";
+export * from "./base64.js";
+export * from "./errors.js";
+export * from "./protocol/index.js";
+export * from "./transport.js";
+export * from "./websocket-transport.js";

package/dist/src/browser.js

@@ -0,0 +1,6 @@
+export { CmuxClient, CmuxStream, TERMINAL_KEY_TEXT_MAX_BYTES, } from "./client.js";
+export * from "./base64.js";
+export * from "./errors.js";
+export * from "./protocol/index.js";
+export * from "./transport.js";
+export * from "./websocket-transport.js";

package/dist/src/client.d.ts

@@ -0,0 +1,202 @@
+import type { ApplyLayoutResult, CmuxCommand, CmuxRequest, CmuxRequestParams, CmuxResponse, CmuxResponseData, CmuxResponseDataFor, ColorHex, CopyMode, CopyResult, DecodedAttachEvent, EmptyResult, ExportLayoutResult, Id, IdKind, IdRef, IdsResult, IdentifyResult, JsonObject, ListAgentsResult, ListClientsResult, ListTerminalsResult, LayoutUndoResult, MoveTerminalResult, NotificationLevel, NotifyResult, PaneDirection, PaneNeighborResult, PingResult, ProcessInfoResult, ReadScrollbackResult, ReadScreenResult, ReloadConfigResult, ResizeSurfaceResult, ReportAgentResult, ResolveTerminalResult, RunResult, RenderAttachEvent, SidebarPluginResult, SplitDirection, SubscribeEvent, SurfaceResult, TerminalKeyInput, TerminalPlacement, TerminalEventsResult, Tree, WorkspacePlacement, WorkspaceMutation, VtStateResult, WaitForResult, ZoomPaneResult, AgentReportSource, AgentState, CloseTerminalResult, DeclarativeLayout, FocusDirectionResult } from "./protocol/index.js";
+import type { Transport } from "./transport.js";
+export interface CmuxClientOptions {
+    transport: Transport;
+    timeoutMs?: number;
+    allowProtocolV6Attach?: boolean;
+    /** Maximum events retained for a stream whose consumer falls behind. */
+    maxBufferedEvents?: number;
+    /** Maximum encoded characters per attach payload and retained bytes across buffered attach events. */
+    maxAttachEncodedChars?: number;
+    /** Creates dedicated subscribe/attach transports when supplied. */
+    streamTransportFactory?: () => Transport;
+}
+export declare const DEFAULT_MAX_BUFFERED_EVENTS = 256;
+export declare const DEFAULT_MAX_ATTACH_ENCODED_CHARS: number;
+export declare const TERMINAL_KEY_TEXT_MAX_BYTES: number;
+export interface ResizeTransactionOptions {
+    /** Reuse across one continuous drag, then choose a new value for the next drag. */
+    transaction?: number | null;
+}
+export type NewTabOptions = CmuxRequestParams<"new-tab">;
+export type NewBrowserTabOptions = Omit<CmuxRequestParams<"new-browser-tab">, "url">;
+export type NewWorkspaceOptions = CmuxRequestParams<"new-workspace">;
+export type CreateWorkspaceOptions = CmuxRequestParams<"create-workspace">;
+export type CreateTerminalOptions = CmuxRequestParams<"create-terminal">;
+export type CloseTerminalOptions = Omit<CmuxRequestParams<"close-terminal">, "terminal_id" | "terminal_incarnation">;
+export type CloseWorkspaceOptions = CmuxRequestParams<"close-workspace">;
+export type RenameWorkspaceOptions = CmuxRequestParams<"rename-workspace">;
+export type MoveWorkspaceOptions = CmuxRequestParams<"move-workspace">;
+export type NewScreenOptions = CmuxRequestParams<"new-screen">;
+export type NewPaneOptions = Omit<CmuxRequestParams<"new-pane">, "pane">;
+export type NewPaneRightOptions = Omit<CmuxRequestParams<"new-pane-right">, "pane">;
+export type SplitOptions = Omit<CmuxRequestParams<"split">, "pane" | "dir">;
+export type SelectOptions = CmuxRequestParams<"select-screen">;
+export type SelectTabOptions = CmuxRequestParams<"select-tab">;
+export interface SendOptions {
+    text?: string | null;
+    /** Standard base64-encoded raw bytes sent in the wire `bytes` field. */
+    base64?: string | null;
+    /** @deprecated Use `base64`, or pass text for UTF-8 input. */
+    bytes?: string | Uint8Array | null;
+    /** Request bracketed-paste wrapping when terminal mode 2004 is enabled. */
+    paste?: boolean;
+}
+export interface SubscribeOptions {
+    treeEvents?: "coarse" | "deltas";
+}
+export type AttachSurfaceOptions = {
+    mode?: "bytes" | "render";
+} & ({
+    cols: number;
+    rows: number;
+} | {
+    cols?: never;
+    rows?: never;
+});
+/** A closeable async event stream with optional per-read timeouts. */
+export declare class CmuxStream<T extends {
+    event: string;
+}> implements AsyncIterable<T> {
+    private readonly timeoutMs;
+    private readonly cleanup;
+    private readonly maxBufferedEvents;
+    private readonly maxBufferedBytes;
+    private readonly retainedBytes;
+    private readonly buffered;
+    private bufferedBytes;
+    private readonly waiters;
+    private closed;
+    private endsAfterDrain;
+    private terminalError;
+    constructor(timeoutMs: number, cleanup: () => void, maxBufferedEvents?: number, maxBufferedBytes?: number, retainedBytes?: (event: T) => number);
+    next(timeoutMs?: number): Promise<T>;
+    close(): void;
+    push(event: T, terminal?: boolean): void;
+    fail(error: Error): void;
+    get error(): Error | null;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    private finish;
+    private rejectWaiters;
+}
+/** Promise-based typed client for any cmux JSON transport. */
+export declare class CmuxClient {
+    readonly timeoutMs: number;
+    readonly allowProtocolV6Attach: boolean;
+    readonly maxBufferedEvents: number;
+    readonly maxAttachEncodedChars: number;
+    private readonly transport;
+    private readonly router;
+    private readonly streamTransportFactory?;
+    private nextRequestId;
+    private identifiedProtocol;
+    private identifiedCapabilities;
+    private sharedSubscriptionActive;
+    constructor(options: CmuxClientOptions);
+    close(): Promise<void>;
+    sendRaw(obj: JsonObject): Promise<CmuxResponse<unknown>>;
+    request<C extends CmuxRequest>(request: C): Promise<CmuxResponseData<C>>;
+    request<C extends CmuxCommand>(cmd: C, ...args: Record<string, never> extends CmuxRequestParams<C> ? [params?: CmuxRequestParams<C>] : [params: CmuxRequestParams<C>]): Promise<CmuxResponseDataFor<C>>;
+    identify(): Promise<IdentifyResult>;
+    /** The protocol reported by the latest `identify()`, or null before identification. */
+    get protocol(): number | null;
+    ping(): Promise<PingResult>;
+    setClientInfo(name?: string, kind?: string): Promise<EmptyResult>;
+    listClients(): Promise<ListClientsResult>;
+    detachClient(client: Id): Promise<EmptyResult>;
+    setClientSizing(surface: Id, client: Id, enabled: boolean): Promise<EmptyResult>;
+    useOnlyClientSizing(surface: Id, client: Id): Promise<EmptyResult>;
+    useAllClientSizing(surface: Id): Promise<EmptyResult>;
+    reloadConfig(): Promise<ReloadConfigResult>;
+    setWindowTitle(title: string): Promise<EmptyResult>;
+    clearWindowTitle(): Promise<EmptyResult>;
+    listWorkspaces(): Promise<Tree>;
+    listTerminals(): Promise<ListTerminalsResult>;
+    terminalEvents(afterRevision?: number): Promise<TerminalEventsResult>;
+    exportLayout(screen?: Id | null): Promise<ExportLayoutResult>;
+    applyLayout(layout: DeclarativeLayout, options?: Omit<CmuxRequestParams<"apply-layout">, "layout">): Promise<ApplyLayoutResult>;
+    send(surface: Id, options?: SendOptions): Promise<EmptyResult>;
+    clearHistory(surface: Id, fallbackKey?: TerminalKeyInput): Promise<EmptyResult>;
+    readScreen(surface: Id): Promise<ReadScreenResult>;
+    readScrollback(surface: Id, start: number, count: number): Promise<ReadScrollbackResult>;
+    sidebarPlugin(cols: number, rows: number, relaunch?: boolean | null): Promise<SidebarPluginResult>;
+    vtState(surface: Id): Promise<VtStateResult>;
+    resolveTerminal(terminalId: string): Promise<ResolveTerminalResult>;
+    closeTerminal(terminalId: string, terminalIncarnation?: string | null, options?: CloseTerminalOptions): Promise<CloseTerminalResult>;
+    newTab(options?: NewTabOptions): Promise<SurfaceResult>;
+    newBrowserTab(url: string, options?: NewBrowserTabOptions): Promise<SurfaceResult>;
+    newWorkspace(options?: NewWorkspaceOptions): Promise<SurfaceResult>;
+    createWorkspace(options?: CreateWorkspaceOptions): Promise<WorkspacePlacement>;
+    createTerminal(options: CreateTerminalOptions): Promise<TerminalPlacement>;
+    moveTerminal(terminalId: string, workspaceKey: string, options?: Omit<CmuxRequestParams<"move-terminal">, "terminal_id" | "workspace_key">): Promise<MoveTerminalResult>;
+    newScreen(options?: NewScreenOptions): Promise<SurfaceResult>;
+    newPane(pane: Id, options?: NewPaneOptions): Promise<SurfaceResult>;
+    newPaneRight(pane: Id, options?: NewPaneRightOptions): Promise<SurfaceResult>;
+    split(pane: Id, dir: SplitDirection, options?: SplitOptions): Promise<SurfaceResult>;
+    setRatio(pane: Id, dir: SplitDirection, ratio: number): Promise<EmptyResult>;
+    setSplitRatio(split: Id, ratio: number, options?: ResizeTransactionOptions): Promise<EmptyResult>;
+    setViewportPaneWidth(pane: Id, width: number, options?: ResizeTransactionOptions): Promise<EmptyResult>;
+    undoLayout(pane: Id, confirmationRevision?: number): Promise<LayoutUndoResult>;
+    paneNeighbor(pane: Id, dir: PaneDirection): Promise<PaneNeighborResult>;
+    focusDirection(dir: PaneDirection, pane?: Id | null): Promise<FocusDirectionResult>;
+    swapPane(params: CmuxRequestParams<"swap-pane">): Promise<EmptyResult>;
+    zoomPane(params?: CmuxRequestParams<"zoom-pane">): Promise<ZoomPaneResult>;
+    processInfo(surface: Id): Promise<ProcessInfoResult>;
+    setDefaultColors(fg?: ColorHex | null, bg?: ColorHex | null): Promise<EmptyResult>;
+    closeSurface(surface: Id): Promise<EmptyResult>;
+    closePane(pane: Id): Promise<EmptyResult>;
+    closeScreen(screen: Id): Promise<EmptyResult>;
+    closeWorkspace(workspace: Id): Promise<EmptyResult>;
+    closeWorkspaceRegistry(options: CloseWorkspaceOptions): Promise<WorkspaceMutation>;
+    renamePane(pane: Id, name: string): Promise<EmptyResult>;
+    renameSurface(surface: Id, name: string): Promise<EmptyResult>;
+    renameScreen(screen: Id, name: string): Promise<EmptyResult>;
+    renameWorkspace(workspace: Id, name: string): Promise<EmptyResult>;
+    renameWorkspaceRegistry(options: RenameWorkspaceOptions): Promise<WorkspaceMutation>;
+    resizeSurface(surface: Id, cols: number, rows: number): Promise<ResizeSurfaceResult>;
+    releaseSurfaceSize(surface: Id): Promise<EmptyResult>;
+    focusPane(pane: Id): Promise<EmptyResult>;
+    selectTab(options?: SelectTabOptions): Promise<EmptyResult>;
+    selectScreen(options?: SelectOptions): Promise<EmptyResult>;
+    selectWorkspace(options?: SelectOptions): Promise<EmptyResult>;
+    moveTab(surface: Id, pane: Id, index: number): Promise<EmptyResult>;
+    moveWorkspace(workspace: Id, index: number): Promise<EmptyResult>;
+    moveWorkspaceRegistry(options: MoveWorkspaceOptions): Promise<WorkspaceMutation>;
+    scrollSurface(surface: Id, delta: number): Promise<EmptyResult>;
+    subscribe(options?: SubscribeOptions): Promise<CmuxStream<SubscribeEvent>>;
+    attachSurface(surface: Id, options?: AttachSurfaceOptions & {
+        mode?: "bytes";
+    }): Promise<CmuxStream<DecodedAttachEvent>>;
+    attachSurface(surface: Id, options: AttachSurfaceOptions & {
+        mode: "render";
+    }): Promise<CmuxStream<RenderAttachEvent>>;
+    attachSurface(surface: Id, options: AttachSurfaceOptions): Promise<CmuxStream<DecodedAttachEvent> | CmuxStream<RenderAttachEvent>>;
+    private requireCapability;
+    private requireProtocol;
+    waitFor(surface: IdRef, pattern: string, timeoutMs: number): Promise<WaitForResult>;
+    run(options: CmuxRequestParams<"run">): Promise<RunResult>;
+    sendKey(surface: IdRef, keys: string[]): Promise<EmptyResult>;
+    copy(surface: IdRef, mode: CopyMode): Promise<CopyResult>;
+    ids(kind?: IdKind | null): Promise<IdsResult>;
+    notify(title: string, body: string, options?: {
+        level?: NotificationLevel | null;
+        surface?: IdRef | null;
+    }): Promise<NotifyResult>;
+    listAgents(options?: CmuxRequestParams<"list-agents">): Promise<ListAgentsResult>;
+    reportAgent(surface: IdRef, state: AgentState, source: AgentReportSource, session?: string | null): Promise<ReportAgentResult>;
+    private openStream;
+    private decodeAttachEvent;
+    private decodeAttachData;
+    private decodeBrowserFrame;
+    private validateFrameSequence;
+    private validateFrameCssDimension;
+    private validateFrameDimension;
+    private validateAttachEncodedData;
+    private attachEventRetainedBytes;
+    private matchesAttachEvent;
+    private isSurfaceOverflow;
+    private attachOnlyEvent;
+    private dropUndefined;
+    private securityLimit;
+    private nextId;
+}