ai-remote 0.4.8 → 0.4.9

package/dist/index.d.ts

@@ -1,13 +1,255 @@
 /**
- * The vocabulary every host of this stack shares.
- *
- * Deliberately no protocol engines: a Worker that only needs to know what a
- * host roster is should not pull noVNC or an RDP state machine into its
- * bundle. The engines live behind `@remotectl/core/protocols`.
- */
-export * from './shared/connection';
-export * from './shared/device';
-export * from './shared/hosts';
-export * from './shared/icons';
-export * from './shared/protocol';
-export * from './shared/signals';
+ * The vocabulary both halves of the gateway share.
+ *
+ * The Worker and the browser have to agree on what a "protocol" is, what ports
+ * they default to and how an RDP security layer is named, so those live here
+ * rather than being re-declared on each side and drifting apart.
+ */
+/** A remote-desktop protocol the session workspace can display. */
+export declare const REMOTE_PROTOCOLS: readonly ['vnc', 'rdp'];
+export type RemoteProtocol = (typeof REMOTE_PROTOCOLS)[number];
+/** Every protocol the gateway relays, including the terminal side panel. */
+export declare const TRANSPORT_PROTOCOLS: readonly ['vnc', 'rdp', 'ssh'];
+export type TransportProtocol = (typeof TRANSPORT_PROTOCOLS)[number];
+/**
+ * The RDP security layer. `auto` negotiates with the host, which is right for
+ * anything that answers honestly; the rest are for hosts that do not.
+ */
+export declare const RDP_SECURITY_MODES: readonly ['auto', 'nla', 'tls', 'rdp'];
+export type RdpSecurity = (typeof RDP_SECURITY_MODES)[number];
+export declare const DEFAULT_PORTS: Record<TransportProtocol, number>;
+export declare const DEFAULT_SSH_PORT: number;
+/** Max time allowed before command start output is detected. */
+export declare const COMMAND_START_MS = 15000;
+/** Max idle silence allowed during command execution. */
+export declare const COMMAND_IDLE_MS: number;
+export declare function isRemoteProtocol(value: unknown): value is RemoteProtocol;
+export declare function isRdpSecurity(value: unknown): value is RdpSecurity;
+/** Coerce anything to a protocol, falling back to what the caller opens on. */
+export declare function toRemoteProtocol(value: unknown, fallback?: RemoteProtocol): RemoteProtocol;
+export declare function toRdpSecurity(value: unknown, fallback?: RdpSecurity): RdpSecurity;
+/** A port number, or the protocol's default when the value is not one. */
+export declare function toPort(value: unknown, fallback: number): number;
+/** A published Windows application launched instead of the full desktop. */
+export interface RemoteAppLaunch {
+    /** Alias (`||notepad`) or an executable path. */
+    program: string;
+    workingDir?: string;
+    arguments?: string;
+}
+/** The companion terminal offered beside a desktop. */
+export interface SshCompanion {
+    enabled: boolean;
+    port: number;
+    username: string;
+}
+/** Picture and input options. VNC negotiates them; RDP and SSH ignore what does not apply. */
+export interface DisplaySettings {
+    /** RFB quality level, 1 (smallest) to 9 (sharpest). */
+    quality: number;
+    /** RFB compression level, 0 (fastest) to 9 (smallest). */
+    compression: number;
+    /** Fit the remote desktop to the pane rather than scrolling it. */
+    scaling: boolean;
+    /** Watch without sending keyboard or pointer input. */
+    viewOnly: boolean;
+}
+/**
+ * Everything a session needs. `password` is the only field never persisted
+ * anywhere -- not in the device library on the gateway, not in localStorage.
+ */
+export interface ConnectionSettings {
+    /** Stable identity: protocol, address, port and program. See {@link connectionId}. */
+    id: string;
+    label: string;
+    protocol: RemoteProtocol;
+    host: string;
+    port: number;
+    username: string;
+    password: string;
+    /** Windows domain or computer name. RDP only. */
+    domain: string;
+    security: RdpSecurity;
+    remoteApp: RemoteAppLaunch | null;
+    display: DisplaySettings;
+    ssh: SshCompanion;
+    /** Open the terminal panel as soon as the desktop appears. */
+    openSshOnConnect: boolean;
+}
+export declare const DEFAULT_DISPLAY_SETTINGS: DisplaySettings;
+/**
+ * A connection's identity is what it points at, not when it was made. Editing
+ * the address therefore makes a different connection rather than silently
+ * repointing an existing card, which is the behaviour people expect from a
+ * list of machines.
+ */
+export declare function connectionId(input: Pick<ConnectionSettings, 'protocol' | 'host' | 'port'> & {
+    remoteApp?: RemoteAppLaunch | null;
+}): string;
+/** A blank connection, ready for the dialog to fill in. */
+export declare function emptyConnection(protocol?: RemoteProtocol): ConnectionSettings;
+export declare function normalizeDisplaySettings(value: unknown): DisplaySettings;
+/**
+ * Build a complete, valid connection out of whatever a caller happens to have.
+ * Partial input from a saved card, a host list entry, a URL or localStorage all
+ * arrive here, so the dialog never has to reason about missing fields.
+ */
+export declare function normalizeConnection(input: Partial<ConnectionSettings> & Record<string, unknown>): ConnectionSettings;
+/** What a connection is worth remembering by -- never the password. */
+export type PersistedConnection = Omit<ConnectionSettings, 'password'>;
+export declare function withoutPassword(settings: ConnectionSettings): PersistedConnection;
+/** A one-line description for the dialog's summary row and the status bar. */
+export declare function describeConnection(settings: ConnectionSettings): string;
+export interface SavedDevice {
+    id: string;
+    label: string;
+    host: string;
+    port: number;
+    protocol: RemoteProtocol;
+    domain?: string;
+    security?: RdpSecurity;
+    /** RemoteApp alias (`||notepad`) when this card launches an app, not a desktop. */
+    program?: string;
+    favorite?: boolean;
+    /** Milliseconds since the epoch; drives the "recent" ordering. */
+    lastUsed?: number;
+    createdAt?: number;
+    /** Set when a thumbnail exists, so the client can cache-bust its <img>. */
+    thumbnailAt?: number;
+}
+/** Optional SSH access to the same machine, which publishes a terminal for it. */
+export interface HostSshAccess {
+    port: number;
+    username?: string;
+}
+/** One machine as the gateway's configuration describes it. */
+export interface RemoteHostTarget {
+    id: string;
+    name: string;
+    host: string;
+    port: number;
+    protocol: RemoteProtocol;
+    /** Windows domain or computer name pre-filled in the connect dialog. */
+    domain?: string;
+    security?: RdpSecurity;
+    remoteApp?: RemoteAppLaunch;
+    ssh?: HostSshAccess;
+}
+/**
+ * Build the target list offered in the connect dialog. `VNC_HOSTS` and
+ * `RDP_HOSTS` are merged into one list; each entry may override its protocol,
+ * so a single list can carry both kinds of target.
+ */
+export declare function parseConfiguredHosts(options: {
+    vncHostsJson?: string;
+    rdpHostsJson?: string;
+    defaultHost?: string;
+    defaultPort?: string;
+    defaultRdpHost?: string;
+    defaultRdpPort?: string;
+}): RemoteHostTarget[];
+/** One allowed network, as a base address and a mask. */
+export interface Subnet {
+    base: number;
+    mask: number;
+}
+/** Dotted-quad to a 32-bit number, or null for anything that is not one. */
+export declare function ipv4ToInt(value: string): number | null;
+/**
+ * The networks this gateway may dial, beyond the machines named in the host
+ * lists. Written as `ALLOWED_SUBNETS`, comma-separated:
+ *
+ *   192.168.8.0/24    a CIDR block
+ *   192.168.8.*       the same thing, written the way people say it
+ *   192.168.8.67      a single address
+ *
+ * This is what lets a terminal open on a machine that was never listed. Keep it
+ * to networks you own: anything inside one can be reached on any port by anyone
+ * who gets past the gateway's login.
+ */
+export declare function parseAllowedSubnets(value?: string): Subnet[];
+/** Whether a dotted-quad address falls inside one of the allowed networks. */
+export declare function hostInAllowedSubnets(host: string, value?: string): boolean;
+/**
+ * Icon path data, shared by the server-rendered login page and the React app.
+ *
+ * Each value is the inside of a 24x24 stroked `<svg>`; the wrapper differs
+ * between the two (a string on the Worker, a component in the browser) but the
+ * geometry should not.
+ */
+export declare const ICON_PATHS: {
+    readonly monitor: '<rect x="2" y="3" width="20" height="14" rx="2"/><path d="M8 21h8M12 17v4"/>';
+    readonly link: '<path d="M9 17H7A5 5 0 0 1 7 7h2M15 7h2a5 5 0 1 1 0 10h-2M8 12h8"/>';
+    readonly power: '<path d="M12 2v10"/><path d="M18.4 6.6a9 9 0 1 1-12.8 0"/>';
+    readonly maximize: '<path d="M8 3H5a2 2 0 0 0-2 2v3M21 8V5a2 2 0 0 0-2-2h-3M3 16v3a2 2 0 0 0 2 2h3M16 21h3a2 2 0 0 0 2-2v-3"/>';
+    readonly minimize: '<path d="M8 3v3a2 2 0 0 1-2 2H3M21 8h-3a2 2 0 0 1-2-2V3M3 16h3a2 2 0 0 1 2 2v3M16 21v-3a2 2 0 0 1 2-2h3"/>';
+    readonly keyboard: '<rect x="2" y="4" width="20" height="16" rx="2"/><path d="M6 8h.01M10 8h.01M14 8h.01M18 8h.01M8 12h.01M12 12h.01M16 12h.01M7 16h10"/>';
+    readonly clipboard: '<rect x="8" y="2" width="8" height="4" rx="1"/><path d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2"/>';
+    readonly check: '<path d="m5 13 4 4 10-10"/>';
+    readonly camera: '<path d="M14.5 4h-5L7 7H4a2 2 0 0 0-2 2v9a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2V9a2 2 0 0 0-2-2h-3l-2.5-3z"/><circle cx="12" cy="13" r="3"/>';
+    readonly eye: '<path d="M2 12s3.5-6 10-6 10 6 10 6-3.5 6-10 6S2 12 2 12z"/><circle cx="12" cy="12" r="3"/>';
+    readonly sliders: '<path d="M4 21v-7M4 10V3M12 21v-9M12 8V3M20 21v-5M20 12V3M2 14h4M10 8h4M18 16h4"/>';
+    readonly expand: '<path d="M15 3h6v6M9 21H3v-6M21 3l-7 7M3 21l7-7"/>';
+    readonly shield: '<path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/>';
+    readonly chevron: '<path d="m6 9 6 6 6-6"/>';
+    readonly back: '<path d="m15 18-6-6 6-6"/>';
+    readonly zap: '<path d="M13 2 3 14h9l-1 8 10-12h-9l1-8z"/>';
+    readonly cube: '<path d="M21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16z"/><path d="m3.3 7 8.7 5 8.7-5M12 22V12"/>';
+    readonly logout: '<path d="M9 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h4M16 17l5-5-5-5M21 12H9"/>';
+    readonly clock: '<circle cx="12" cy="12" r="9"/><path d="M12 7v5l3.5 2"/>';
+    readonly activity: '<path d="M22 12h-4l-3 9L9 3l-3 9H2"/>';
+    readonly transfer: '<path d="m3 16 4 4 4-4M7 20V4M21 8l-4-4-4 4M17 4v16"/>';
+    readonly screen: '<rect x="2" y="5" width="20" height="13" rx="2"/><path d="M7 21h10"/>';
+    readonly command: '<path d="M15 6a3 3 0 1 1 3 3h-3zm0 0v12m0 0a3 3 0 1 0 3-3h-3zM9 6a3 3 0 1 0-3 3h3zm0 0v12m0 0a3 3 0 1 1-3-3h3z"/>';
+    readonly apps: '<rect x="3" y="3" width="7" height="7" rx="1"/><rect x="14" y="3" width="7" height="7" rx="1"/><rect x="3" y="14" width="7" height="7" rx="1"/><rect x="14" y="14" width="7" height="7" rx="1"/>';
+    readonly terminal: '<path d="m4 17 6-6-6-6M12 19h8"/>';
+    readonly folder: '<path d="M3 7h6l2 2h10v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/><path d="M3 7V6a2 2 0 0 1 2-2h4l2 3"/>';
+    readonly close: '<path d="M18 6 6 18M6 6l12 12"/>';
+    readonly sparkles: '<path d="m12 3 1.9 5.1L19 10l-5.1 1.9L12 17l-1.9-5.1L5 10l5.1-1.9L12 3z"/><path d="m19 15 .8 2.2 2.2.8-2.2.8L19 21l-.8-2.2-2.2-.8 2.2-.8z"/>';
+    readonly broom: '<path d="M10 10V4a2 2 0 0 1 4 0v6"/><path d="M6 10h12a2 2 0 0 1 2 2v2H4v-2a2 2 0 0 1 2-2Z"/><path d="m5 14-2 7h18l-2-7M9 18l-1 3M15 18l1 3"/>';
+    readonly panel: '<rect x="3" y="4" width="18" height="16" rx="2"/><path d="M14 4v16"/>';
+    readonly menu: '<path d="M4 7h16M4 12h16M4 17h16"/>';
+    readonly plus: '<path d="M12 5v14M5 12h14"/>';
+    readonly star: '<path d="m12 3 2.9 5.9 6.5.9-4.7 4.6 1.1 6.5L12 17.8 6.2 20.9l1.1-6.5L2.6 9.8l6.5-.9L12 3z"/>';
+    readonly trash: '<path d="M3 6h18M8 6V4a1 1 0 0 1 1-1h6a1 1 0 0 1 1 1v2M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/>';
+};
+export type IconName = keyof typeof ICON_PATHS;
+/** The tab icon: a monitor in Cloudflare orange. */
+export declare const FAVICON_DATA_URI = "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23f38020' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Crect x='2' y='3' width='20' height='14' rx='2'/%3E%3Cpath d='M8 21h8M12 17v4'/%3E%3C/svg%3E";
+/**
+ * Control frames the browser and the gateway exchange on the WebSocket that
+ * carries a remote-desktop stream.
+ *
+ * They are plain strings precisely so they can never be confused with the
+ * binary protocol payload flowing in either direction, and both sides import
+ * these same literals so the two halves cannot drift apart.
+ */
+/** Browser -> gateway: "my WebSocket is open, you may start reading the host". */
+export declare const GATEWAY_READY_SIGNAL = "VNC_GATEWAY_READY_v1";
+/**
+ * Browser -> gateway: keep the edge from idling out a silent session.
+ * Cloudflare closes a WebSocket with no traffic in either direction for 100s,
+ * and an untouched desktop transmits nothing at all.
+ */
+export declare const GATEWAY_KEEPALIVE_SIGNAL = "VNC_GATEWAY_KEEPALIVE_v1";
+/**
+ * How often the browser nudges the transport. Well inside the edge's 100s
+ * window, so a session that is merely being looked at is never torn down
+ * without a close frame -- which is what a bare WebSocket 1006 used to mean.
+ */
+export declare const KEEPALIVE_INTERVAL_MS = 25000;
+export declare const MAX_CLOSE_REASON_BYTES = 123;
+/** Whether a live desktop ended for a transient transport reason worth retrying. */
+export declare function isRetryableDisconnect(diagnostic: {
+    close: {
+        code: number;
+        reason: string;
+    } | null;
+    established: boolean;
+}): boolean;
+/** WebSocket close reasons are capped at 123 bytes; trim without splitting a code point. */
+export declare function websocketCloseReason(reason: string): string;
+/** 1005/1006/1015 are reserved and cannot be transmitted in a close frame. */
+export declare function sendableCloseCode(code: number): number;
+/** Normalize any WebSocket message payload to bytes. */
+export declare function messageToBytes(data: unknown): Promise<Uint8Array | null>;

package/dist/protocols.d.ts

@@ -0,0 +1,349 @@
+/**
+ * The vocabulary both halves of the gateway share.
+ *
+ * The Worker and the browser have to agree on what a "protocol" is, what ports
+ * they default to and how an RDP security layer is named, so those live here
+ * rather than being re-declared on each side and drifting apart.
+ */
+/** A remote-desktop protocol the session workspace can display. */
+declare const REMOTE_PROTOCOLS: readonly ['vnc', 'rdp'];
+type RemoteProtocol = (typeof REMOTE_PROTOCOLS)[number];
+/** Every protocol the gateway relays, including the terminal side panel. */
+declare const TRANSPORT_PROTOCOLS: readonly ['vnc', 'rdp', 'ssh'];
+type TransportProtocol = (typeof TRANSPORT_PROTOCOLS)[number];
+/**
+ * The RDP security layer. `auto` negotiates with the host, which is right for
+ * anything that answers honestly; the rest are for hosts that do not.
+ */
+declare const RDP_SECURITY_MODES: readonly ['auto', 'nla', 'tls', 'rdp'];
+type RdpSecurity = (typeof RDP_SECURITY_MODES)[number];
+declare const DEFAULT_PORTS: Record<TransportProtocol, number>;
+declare const DEFAULT_SSH_PORT: number;
+/**
+ * How patient `runCommand` is, in three different senses.
+ *
+ * A single deadline cannot tell "the shell ignored me" apart from "the
+ * installer is three minutes into a download", and a short one turns every
+ * real piece of work -- a package install, a build, a large copy -- into a
+ * false failure that also leaves the command running on the far side.
+ *
+ * So the wait is judged by what the shell is doing. It has START_MS to
+ * acknowledge the command at all; after that it may take as long as it likes
+ * as long as it keeps printing, and only silence longer than IDLE_MS, or a run
+ * longer than MAX_MS, is treated as stuck.
+ */
+export declare const COMMAND_START_MS = 20000;
+/** Max idle silence allowed during command execution. */
+export declare const COMMAND_IDLE_MS: number;
+declare function isRemoteProtocol(value: unknown): value is RemoteProtocol;
+declare function isRdpSecurity(value: unknown): value is RdpSecurity;
+/** Coerce anything to a protocol, falling back to what the caller opens on. */
+declare function toRemoteProtocol(value: unknown, fallback?: RemoteProtocol): RemoteProtocol;
+declare function toRdpSecurity(value: unknown, fallback?: RdpSecurity): RdpSecurity;
+/** A port number, or the protocol's default when the value is not one. */
+declare function toPort(value: unknown, fallback: number): number;
+/** A published Windows application launched instead of the full desktop. */
+interface RemoteAppLaunch {
+    /** Alias (`||notepad`) or an executable path. */
+    program: string;
+    workingDir?: string;
+    arguments?: string;
+}
+/** The companion terminal offered beside a desktop. */
+interface SshCompanion {
+    enabled: boolean;
+    port: number;
+    username: string;
+}
+/** Picture and input options. VNC negotiates them; RDP and SSH ignore what does not apply. */
+interface DisplaySettings {
+    /** RFB quality level, 1 (smallest) to 9 (sharpest). */
+    quality: number;
+    /** RFB compression level, 0 (fastest) to 9 (smallest). */
+    compression: number;
+    /** Fit the remote desktop to the pane rather than scrolling it. */
+    scaling: boolean;
+    /** Watch without sending keyboard or pointer input. */
+    viewOnly: boolean;
+}
+/**
+ * Everything a session needs. `password` is the only field never persisted
+ * anywhere -- not in the device library on the gateway, not in localStorage.
+ */
+interface ConnectionSettings {
+    /** Stable identity: protocol, address, port and program. See {@link connectionId}. */
+    id: string;
+    label: string;
+    protocol: RemoteProtocol;
+    host: string;
+    port: number;
+    username: string;
+    password: string;
+    /** Windows domain or computer name. RDP only. */
+    domain: string;
+    security: RdpSecurity;
+    remoteApp: RemoteAppLaunch | null;
+    display: DisplaySettings;
+    ssh: SshCompanion;
+    /** Open the terminal panel as soon as the desktop appears. */
+    openSshOnConnect: boolean;
+}
+declare const DEFAULT_DISPLAY_SETTINGS: DisplaySettings;
+/**
+ * A connection's identity is what it points at, not when it was made. Editing
+ * the address therefore makes a different connection rather than silently
+ * repointing an existing card, which is the behaviour people expect from a
+ * list of machines.
+ */
+declare function connectionId(input: Pick<ConnectionSettings, 'protocol' | 'host' | 'port'> & {
+    remoteApp?: RemoteAppLaunch | null;
+}): string;
+/** A blank connection, ready for the dialog to fill in. */
+declare function emptyConnection(protocol?: RemoteProtocol): ConnectionSettings;
+declare function normalizeDisplaySettings(value: unknown): DisplaySettings;
+/**
+ * Build a complete, valid connection out of whatever a caller happens to have.
+ * Partial input from a saved card, a host list entry, a URL or localStorage all
+ * arrive here, so the dialog never has to reason about missing fields.
+ */
+declare function normalizeConnection(input: Partial<ConnectionSettings> & Record<string, unknown>): ConnectionSettings;
+/** What a connection is worth remembering by -- never the password. */
+type PersistedConnection = Omit<ConnectionSettings, 'password'>;
+declare function withoutPassword(settings: ConnectionSettings): PersistedConnection;
+/** A one-line description for the dialog's summary row and the status bar. */
+declare function describeConnection(settings: ConnectionSettings): string;
+/** Where the pointer may go, in framebuffer pixels. */
+export interface ScreenGeometry {
+    width: number;
+    height: number;
+    viewport: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/** Mouse buttons, as the UI names them. */
+type PointerButton = 0 | 1 | 2;
+/** Wheel movement in discrete remote-protocol notches. Positive is right/down. */
+interface ScrollDelta {
+    x: number;
+    y: number;
+}
+/**
+ * A live session. Both drivers expose this, so the AI pane's screen tool and
+ * the toolbar never have to ask which protocol they are driving.
+ */
+export interface RemoteSession extends EventTarget {
+    readonly protocol: RemoteProtocol;
+    disconnect(): void;
+    /** True once the desktop has been reached. */
+    readonly connected: boolean;
+    /** Fit the remote desktop to the pane rather than scrolling it. */
+    scaleViewport: boolean;
+    /** Watch without sending keyboard or pointer input. */
+    viewOnly: boolean;
+    /** RFB quality level. RDP ignores it. */
+    qualityLevel?: number;
+    /** RFB compression level. RDP ignores it. */
+    compressionLevel?: number;
+    /** The transport the metrics rail instruments. Can appear a tick after construction. */
+    readonly socket?: WebSocket | null;
+    readonly screenGeometry: ScreenGeometry;
+    movePointer(x: number, y: number): boolean;
+    clickPointer(x: number, y: number, button?: PointerButton): boolean;
+    pointerButton(x: number, y: number, button?: PointerButton, pressed?: boolean): boolean;
+    scrollPointer(x: number, y: number, delta: ScrollDelta): boolean;
+    typeText(text: string): boolean;
+    /** Prefer the protocol clipboard for longer text when it can paste reliably. */
+    pasteText?(text: string): boolean | Promise<boolean>;
+    /** Press or release one key by keysym. */
+    sendKey(keysym: number, code: string | null, down?: boolean): void;
+    /** Send text to the host's clipboard, when the protocol carries one. */
+    sendClipboard?(text: string): void;
+    /**
+     * Stop taking keystrokes: the workspace has given the keyboard to something
+     * local, such as the terminal or the assistant's message box.
+     *
+     * Both protocols listen on the element they paint into, so a key only leaves
+     * for the host while that element holds focus. Handing focus back is the
+     * whole mechanism -- plus, for RDP, letting go of anything still held down,
+     * which would otherwise stay down on the far side.
+     */
+    releaseKeyboard?(): void;
+    /** Ask the host for a different desktop size, when the protocol allows it. */
+    requestDesktopSize?(width: number, height: number): void;
+    /** The canvas the session paints into, for screenshots and thumbnails. */
+    readonly canvas?: HTMLCanvasElement | null;
+}
+/** What the workspace hands a driver to open a session. */
+export interface SessionOptions {
+    credentials: {
+        username: string;
+        password: string;
+    };
+    domain: string;
+    security: RdpSecurity;
+    remoteApp: RemoteAppLaunch | null;
+    /** Desktop size to ask the host for. */
+    width: number;
+    height: number;
+    /** False on a phone, where resizing the host would make a portrait strip of it. */
+    allowRemoteResize: boolean;
+    scaleViewport: boolean;
+    viewOnly: boolean;
+    quality: number;
+    compression: number;
+    /** Shown in this driver's own log lines. */
+    hostLabel: string;
+}
+/** Wording for the one connect dialog, which is shared markup across protocols. */
+interface DialogCopy {
+    usernameLabel: string;
+    usernamePlaceholder: string;
+    usernameHelp: string;
+    passwordLabel: string;
+    passwordPlaceholder: string;
+    passwordHelp: string;
+    /** A VNC session needs some secret; RDP can sign in on the host's own screen. */
+    requiresPassword: boolean;
+}
+/** Everything the UI knows about a close, before anyone tries to explain it. */
+interface DisconnectContext {
+    code?: number;
+    reason: string;
+    /** Pre-rendered ` (WebSocket 1006: ...)` tail, so wording stays consistent. */
+    suffix: string;
+}
+/** One protocol implementation. */
+export interface ProtocolDriver {
+    readonly protocol: RemoteProtocol;
+    /** Used as the prefix of this driver's console lines. */
+    readonly label: string;
+    readonly defaultPort: number;
+    readonly dialog: DialogCopy;
+    /** The gateway endpoint for this connection, including any query it needs. */
+    buildUrl(origin: string, settings: ConnectionSettings): string;
+    createSession(container: HTMLElement, url: string, options: SessionOptions): RemoteSession;
+    /** Extra detail worth logging once the first server frame has been parsed. */
+    describeState(session: RemoteSession): Record<string, unknown>;
+    /** Protocol-specific wording for a close, or null to fall back to the shared text. */
+    describeDisconnect(context: DisconnectContext): string | null;
+}
+export declare const DEFAULT_PORT = 22;
+export declare const COMMAND_MAX_MS: number;
+/**
+ * The one line that runs `command` and marks where its output starts and ends.
+ *
+ * Each shell gets its own, because none of the three agree on how to print a
+ * string, run a command and read back its exit status.
+ */
+export declare function frameCommand(family: any, command: string, id: any): string;
+export declare class SshSession extends EventTarget {
+    #private;
+    /**
+     * @param {string} url          gateway WebSocket URL
+     * @param {object} options
+     * @param {string} options.username
+     * @param {string} [options.password]
+     * @param {SshIdentity[] | (() => Promise<SshIdentity[]>)} [options.identities]
+     * @param {'powershell'} [options.preferredShell]
+     * @param {(info: object) => Promise<boolean>} [options.verifyHost]
+     * @param {(prompt: object) => Promise<string>} [options.requestInput]
+     */
+    constructor(url: string, options?: {});
+    connect(): void;
+    disconnect(): void;
+    /** Send keystrokes, or anything else the terminal produces, to the shell. */
+    write(data: Uint8Array): void;
+    /**
+     * Run one command in this shell and return what it printed.
+     *
+     * Deliberately the *same* shell the user is looking at, not a second channel:
+     * a command the assistant runs inherits the working directory, the
+     * environment and the login the user already has, and it appears in their
+     * terminal as it happens. An agent acting on a machine invisibly is worse
+     * than an agent that is slower to read.
+     *
+     * The output is framed by markers rather than measured, because an
+     * interactive shell echoes its input and prints a prompt around it. The
+     * markers are assembled by the shell from two pieces, so the echoed command
+     * line -- which contains the pieces but not the joined marker -- never looks
+     * like the real boundary.
+     *
+     * A `command` event brackets the run so the terminal can label it, and the
+     * three deadlines above decide when a command is stuck rather than slow.
+     */
+    runCommand(command: string, { startMs, idleMs, maxMs, }?: {
+        idleMs?: number;
+        maxMs?: number;
+        startMs?: number;
+    }): Promise<unknown>;
+    /** Tell the shell its window changed, so full-screen programs redraw. */
+    resize(columns: number, rows: number): void;
+}
+export declare class SshTerminal {
+    constructor(container: any);
+    get columns(): any;
+    get rows(): any;
+    onData(handler: any): void;
+    onResize(handler: any): void;
+    write(data: Uint8Array): void;
+    /** Gateway-side notices, kept visually apart from what the host prints. */
+    notice(text: string, tone?: string): void;
+    clear(): void;
+    focus(): void;
+    /**
+     * Size the terminal to the panel, choosing the font so MIN_COLUMNS fit.
+     *
+     * The columns matter more than the type size here: the commands people run in
+     * a side panel -- `ls -l`, `top`, anything in PowerShell that prints a table
+     * -- are laid out for 80 columns, and a narrower grid wraps every row into an
+     * unreadable stack.
+     *
+     * `proposeDimensions()` reports the grid the current font size yields, and a
+     * monospace cell's width scales with its font size, so `fontSize * cols /
+     * MIN_COLUMNS` lands close to the size that gives MIN_COLUMNS. It is measured
+     * rather than assumed because the cell-width-to-font-size ratio belongs to
+     * whichever font the platform picked. A second pass settles the rounding.
+     * Changing the font resizes the element, which the ResizeObserver sees, so
+     * the guard keeps that from recursing.
+     */
+    fit(): void;
+    /** The grid the host is being told about, for a status line or a log. */
+    get geometry(): {
+        columns: any;
+        rows: any;
+        fontSize: any;
+    };
+    get selection(): any;
+    /**
+     * Read one line from the user, for a password or a one-time code the host
+     * asked for during authentication. The shell is not open yet, so the
+     * terminal is free to be a prompt.
+     */
+    readLine({ prompt, echo }?: {
+        echo?: boolean;
+        prompt?: string;
+    }): Promise<unknown>;
+    destroy(): void;
+}
+export declare const DRIVERS: Record<RemoteProtocol, ProtocolDriver>;
+/** Unknown names fall back to VNC, which is what the dialog opens on. */
+export declare function driverFor(protocol: string | undefined): ProtocolDriver;
+/** What the workspace knows about a session that has just ended. */
+export interface DisconnectDiagnostic {
+    protocol: RemoteProtocol;
+    /** The transport close, when one arrived. A 1006 means it did not. */
+    close: {
+        code: number;
+        reason: string;
+    } | null;
+    /** True once the session had reached the desktop. */
+    established: boolean;
+}
+/**
+ * Explain a disconnect in terms someone can act on. The protocol gets first
+ * say, then the close codes that mean the same thing either way.
+ */
+export declare function explainDisconnect(diagnostic: DisconnectDiagnostic, clean: boolean, protocolMessage: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-remote",
-  "version": "0.4.8",
+  "version": "0.4.9",
   "description": "RDP, VNC and SSH protocol engines that run in Node, a Worker or a browser -- plus `npx ai-remote`, a CLI that drives a machine and shows you what it is doing",
   "type": "module",
   "bin": {
@@ -54,12 +54,12 @@
       "default": "./dist/apple-dh.js"
     },
     "./protocols": {
-      "types": "./dist/protocols/index.d.ts",
+      "types": "./dist/protocols.d.ts",
       "import": "./dist/protocols.js",
       "default": "./dist/protocols.js"
     },
     "./protocols/*": {
-      "types": "./dist/protocols/index.d.ts",
+      "types": "./dist/protocols.d.ts",
       "import": "./dist/protocols.js",
       "default": "./dist/protocols.js"
     }

package/dist/protocols/index.d.ts

@@ -1,33 +0,0 @@
-/**
- * The protocol registry the workspace talks to.
- *
- * The UI owns the toolbar, the dialogs, the stats rail and the on-screen
- * keyboard, none of which care whether a session is VNC or RDP. Everything that
- * does differ -- the endpoint, how a client is constructed, the wording of a
- * failure, the labels in the connect dialog -- is looked up here instead of
- * branching at each site.
- */
-import type { ProtocolDriver } from './types';
-import type { RemoteProtocol } from '../shared/protocol';
-export type { ProtocolDriver, RemoteSession, SessionOptions, ScreenGeometry } from './types';
-export * from './ssh/session';
-export * from './ssh/terminal';
-export declare const DRIVERS: Record<RemoteProtocol, ProtocolDriver>;
-/** Unknown names fall back to VNC, which is what the dialog opens on. */
-export declare function driverFor(protocol: string | undefined): ProtocolDriver;
-/** What the workspace knows about a session that has just ended. */
-export interface DisconnectDiagnostic {
-    protocol: RemoteProtocol;
-    /** The transport close, when one arrived. A 1006 means it did not. */
-    close: {
-        code: number;
-        reason: string;
-    } | null;
-    /** True once the session had reached the desktop. */
-    established: boolean;
-}
-/**
- * Explain a disconnect in terms someone can act on. The protocol gets first
- * say, then the close codes that mean the same thing either way.
- */
-export declare function explainDisconnect(diagnostic: DisconnectDiagnostic, clean: boolean, protocolMessage: string): string;