ai-remote 0.5.0 → 0.6.0

package/dist/computer.d.ts

@@ -0,0 +1,77 @@
+export type ComputerPoint = {
+    x: number;
+    y: number;
+};
+export type ComputerAction = ({
+    type: 'click';
+    button?: number;
+    count?: number;
+    intervalMs?: number;
+} & ComputerPoint) | ({
+    type: 'move';
+} & ComputerPoint) | ({
+    type: 'scroll';
+    dx?: number;
+    dy?: number;
+} & ComputerPoint) | {
+    type: 'type';
+    text: string;
+    chunkSize?: number;
+    intervalMs?: number;
+} | {
+    type: 'key';
+    chord: string;
+} | {
+    type: 'wait';
+    ms: number;
+} | {
+    type: 'drag';
+    path: ComputerPoint[];
+    button?: number;
+    intervalMs?: number;
+};
+export interface ObservationOptions {
+    region?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    maxEdge?: number;
+}
+export interface ComputerScreenshot {
+    base64: string;
+    width: number;
+    height: number;
+    desktopWidth: number;
+    desktopHeight: number;
+    viewport?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    generation: number;
+    changed: boolean;
+    quiet: boolean;
+    painted: boolean;
+    waitedMs: number;
+}
+export interface ComputerBatchResult {
+    actions: number;
+    clicks: number;
+    /** Input dispatch and requested pacing; not proof of application completion. */
+    dispatchMs: number;
+}
+/** Map a point in a returned image back to full-desktop coordinates. */
+export declare function desktopPoint(image: ComputerScreenshot, point: ComputerPoint): ComputerPoint;
+export declare class RemoteComputer {
+    readonly session: string;
+    constructor(session: string);
+    private call;
+    screenshot(options?: ObservationOptions): Promise<ComputerScreenshot>;
+    /** One IPC call, no reconnect or model invocation between actions. */
+    act(actions: ComputerAction[], options?: ObservationOptions): Promise<ComputerBatchResult & ComputerScreenshot>;
+    /** Explicitly skip observation for a known sequence; inspect when needed. */
+    dispatch(actions: ComputerAction[]): Promise<ComputerBatchResult>;
+}

package/dist/computer.js

@@ -0,0 +1,3 @@
+import g from"node:net";import{StringDecoder as f}from"node:string_decoder";function w(t,e){let r=new f("utf8"),n="";t.on("data",u=>{for(n+=r.write(u);;){let s=n.indexOf(`
+`);if(s===-1)return;let o=n.slice(0,s);if(n=n.slice(s+1),!!o.trim())try{e(JSON.parse(o))}catch{}}})}var x=(t,e)=>{t.write(`${JSON.stringify(e)}
+`)};function p(t,e,r={},n=12e4){return new Promise((u,s)=>{let o=g.connect(t),a=!1,c=(i,l)=>{a||(a=!0,clearTimeout(b),o.destroy(),i?s(i):u(l))},b=setTimeout(()=>c(new Error(`The session did not answer "${e}" in time.`)),n);o.on("connect",()=>x(o,{id:1,op:e,args:r})),o.on("error",i=>{c(Object.assign(i,{notRunning:i.code==="ENOENT"||i.code==="ECONNREFUSED"}))}),w(o,i=>c(null,i))})}import{homedir as y}from"node:os";import{join as m}from"node:path";var k=m(y(),".ai-remote"),P=m(k,"run");var h=t=>m(P,`${t}.sock`);function T(t,e){if(!Number.isFinite(e.x)||!Number.isFinite(e.y)||e.x<0||e.y<0||e.x>=t.width||e.y>=t.height)throw new Error("Point must be inside the screenshot.");let r=t.viewport??{x:0,y:0,width:t.desktopWidth,height:t.desktopHeight};return{x:Math.min(r.x+r.width-1,Math.floor(r.x+e.x*r.width/t.width)),y:Math.min(r.y+r.height-1,Math.floor(r.y+e.y*r.height/t.height))}}var d=class{session;constructor(e){if(!/^[\w.-]+$/.test(e)||e==="."||e==="..")throw new Error("Use a session name from ai-remote status --json.");this.session=e}async call(e,r){let n=await p(h(this.session),e,r);if(!n.ok)throw new Error(n.error??"Remote operation failed.");return n.result}screenshot(e={}){return this.call("shot",{...e})}act(e,r={}){return this.call("batch",{...r,actions:e})}dispatch(e){return this.call("batch",{actions:e,observe:!1})}};export{d as RemoteComputer,T as desktopPoint};

package/dist/index.d.ts

@@ -98,17 +98,72 @@ export declare function connectionId(input: Pick<ConnectionSettings, 'protocol'
 /** A blank connection, ready for the dialog to fill in. */
 export declare function emptyConnection(protocol?: RemoteProtocol): ConnectionSettings;
 export declare function normalizeDisplaySettings(value: unknown): DisplaySettings;
+/**
+ * Anything a caller might have.
+ *
+ * Every field is `unknown` on purpose. This is the function that a saved card,
+ * a URL, a host-list entry and a localStorage blob all arrive at, and none of
+ * those had their types checked by anyone. Declaring them as already the right
+ * shape would not make them so -- it would only move the guesswork from here,
+ * where each field is coerced deliberately, to the callers, where it is not.
+ */
+export type ConnectionInput = {
+    [K in keyof ConnectionSettings]?: unknown;
+} & Record<string, unknown>;
 /**
  * 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;
+export declare function normalizeConnection(input: ConnectionInput): 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;
+/**
+ * Carrying VNC credentials on the WebSocket handshake instead of in its URL.
+ *
+ * VNC is the one protocol whose authentication the gateway performs itself:
+ * macOS Screen Sharing needs the Apple Diffie-Hellman (type 30) exchange that
+ * noVNC does not implement, so the password has to reach the Worker. Where it
+ * travels decides who else gets to read it, and a query string is the one place
+ * it must not go -- request URLs are recorded by the platform's own request
+ * logging, which no amount of care in this codebase can redact.
+ *
+ * A browser cannot set headers on a WebSocket, so `Sec-WebSocket-Protocol` is
+ * the only field it controls. That is exactly how Kubernetes passes a bearer
+ * token to `exec`, and headers are not part of the logged request line.
+ *
+ * This is confidentiality against logging, not against the gateway: the Worker
+ * still sees the password, because Apple DH cannot be computed without it. RDP
+ * and SSH authenticate in the browser and never send one here at all.
+ */
+/** Subprotocol the byte relay actually speaks, and the one it echoes back. */
+export declare const WS_BINARY_SUBPROTOCOL = "binary";
+export interface VncCredentials {
+    username: string;
+    password: string;
+}
+/**
+ * The subprotocols a VNC WebSocket should offer: the real one first, so a
+ * gateway that ignores credentials entirely still negotiates a working session.
+ */
+export declare function websocketSubprotocols(credentials: Partial<VncCredentials>): string[];
+/**
+ * The credentials an offer list carries, or null when it carries none.
+ *
+ * A malformed offer is treated as absent rather than as an error: it is
+ * attacker-reachable input, and the handshake that follows will fail on its own
+ * terms with a message about authentication rather than about base64.
+ */
+export declare function readCredentialSubprotocol(header: string | null): VncCredentials | null;
+/**
+ * The subprotocol to accept, which is never the credential offer: echoing that
+ * back would put the password in the response headers, and in whatever the
+ * browser hands to `WebSocket.protocol`.
+ */
+export declare function selectSubprotocol(header: string | null): string | null;
 export interface SavedDevice {
     id: string;
     label: string;
@@ -262,3 +317,27 @@ export declare function websocketCloseReason(reason: string): string;
 export declare function sendableCloseCode(code: number): number;
 /** Normalize any WebSocket message payload to bytes. */
 export declare function messageToBytes(data: unknown): Promise<Uint8Array | null>;
+/**
+ * The part of a WebSocket the protocol engines actually use.
+ *
+ * The engines were written against a browser WebSocket pointed at the gateway's
+ * relay, and the CLI hands them a TCP socket wearing the same face (see
+ * `cli/transport.ts`). Naming that face is what lets both be passed without the
+ * engines being told which one they got -- and without the seam being an `any`,
+ * which is the same thing said less carefully.
+ */
+export interface ByteTransport extends EventTarget {
+    readonly readyState: number;
+    binaryType: string;
+    /** The full range a browser WebSocket takes, so a real one satisfies this. */
+    send(data: string | ArrayBufferLike | ArrayBufferView | Blob): void;
+    close(code?: number, reason?: string): void;
+}
+/**
+ * A `CustomEvent` whose detail this code knows the shape of.
+ *
+ * The engines communicate by dispatching events, so their consumers spend a lot
+ * of time reaching into `event.detail`. Saying which shape is expected at the
+ * point of listening is what keeps that from being unchecked.
+ */
+export type DetailListener<T> = (event: CustomEvent<T>) => void;

package/dist/index.js

@@ -1 +1 @@
-var A=["vnc","rdp"],k=["vnc","rdp","ssh"],P=["auto","nla","tls","rdp"],a={vnc:5900,rdp:3389,ssh:22},f=a.ssh,v=15e3,D=5*6e4;function C(t){return A.includes(t)}function g(t){return P.includes(t)}function h(t,e="vnc"){let n=String(t??"").toLowerCase();return C(n)?n:e}function M(t,e="auto"){let n=String(t??"").toLowerCase();return g(n)?n:e}function u(t,e){let n=typeof t=="number"?t:Number.parseInt(String(t??""),10);return Number.isInteger(n)&&n>0&&n<65536?n:e}var d={quality:6,compression:2,scaling:!0,viewOnly:!1,audio:!1};function E(t){let e=t.remoteApp?.program?.trim()??"",n=`${t.protocol||"vnc"}:${t.host.trim()}:${t.port||""}`;return(e?`${n}:${e}`:n).toLowerCase().slice(0,64)}function V(t="vnc"){let e=a[t];return{id:"",label:"",protocol:t,host:"",port:e,username:"",password:"",domain:"",security:"auto",remoteApp:null,display:{...d},ssh:{enabled:!1,port:a.ssh,username:""},openSshOnConnect:!1}}function x(t,e,n,r){let o=typeof t=="number"?t:Number.parseInt(String(t??""),10);return Number.isInteger(o)?Math.min(r,Math.max(n,o)):e}function _(t){let e=t??{};return{quality:x(e.quality,d.quality,1,9),compression:x(e.compression,d.compression,0,9),scaling:typeof e.scaling=="boolean"?e.scaling:d.scaling,viewOnly:!!e.viewOnly,audio:!!e.audio}}function T(t){if(typeof t=="string"){let i=t.trim();return i?{program:i}:null}if(!t||typeof t!="object")return null;let e=t,n=String(e.program??"").trim();if(!n)return null;let r=String(e.workingDir??"").trim(),o=String(e.arguments??"").trim();return{program:n,...r?{workingDir:r}:{},...o?{arguments:o}:{}}}function z(t){let e=h(t.protocol),n=String(t.host??"").trim(),r=u(t.port,a[e]),o=T(t.remoteApp??t.program),i=t.ssh??{},c={enabled:!!i.enabled,port:u(i.port,a.ssh),username:String(i.username??"").trim()},p={id:"",label:String(t.label??"").trim()||n,protocol:e,host:n,port:r,username:String(t.username??"").trim(),password:String(t.password??""),domain:String(t.domain??"").trim(),security:M(t.security),remoteApp:o,display:_(t.display),ssh:c,openSshOnConnect:!!t.openSshOnConnect};return p.id=String(t.id??"").trim()||E(p),p}function $(t){let{password:e,...n}=t;return n}function U(t){let e=`${t.host||"no address"}:${t.port}`,n=t.remoteApp?` \xB7 ${t.remoteApp.program}`:"";return`${t.protocol.toUpperCase()} \xB7 ${e}${n}`}function L(t){if(typeof t=="string"&&t.trim())return{program:t.trim()};if(!t||typeof t!="object")return;let e=t,n=String(e.program??"").trim();if(n)return{program:n,...e.workingDir?{workingDir:String(e.workingDir)}:{},...e.arguments?{arguments:String(e.arguments)}:{}}}function O(t,e){let n=typeof e=="string"&&e.trim()?e.trim():void 0;if(t===!0)return{port:f,...n?{username:n}:{}};if(typeof t=="number"||typeof t=="string"&&/^\d+$/.test(t.trim())){let i=u(t,0);return i?{port:i,...n?{username:n}:{}}:void 0}if(!t||typeof t!="object")return;let r=t;if(r.enabled===!1)return;let o=typeof r.username=="string"&&r.username.trim()?r.username.trim():n;return{port:u(r.port,f),...o?{username:o}:{}}}function R(t,e,n,r,o){if(!t)return[];let i;try{i=JSON.parse(t)}catch(c){return console.warn(`Failed to parse ${o.toUpperCase()}_HOSTS JSON, ignoring it:`,c),[]}return!Array.isArray(i)||i.length===0?[]:i.map((c,p)=>{let s=c??{},l=h(s.protocol,e),m=l==="rdp"?L(s.remoteApp):void 0,S=O(s.ssh??s.sshPort,s.sshUser??s.sshUsername),y=String(s.host??"")||n,w=String(s.name??"").trim()||y;return{id:String(s.id??"")||`${o}-${p+1}`,name:w,host:y,port:u(s.port??r,a[l]),protocol:l,...s.domain?{domain:String(s.domain)}:{},...g(s.security)?{security:s.security}:{},...m?{remoteApp:m}:{},...S?{ssh:S}:{}}})}function F(t){let e=t.defaultHost||"10.0.0.10",n=t.defaultPort||String(a.vnc),r=[...R(t.vncHostsJson,"vnc",e,n,"vnc-host"),...R(t.rdpHostsJson,"rdp",t.defaultRdpHost||e,t.defaultRdpPort||String(a.rdp),"rdp-host")];return r.length>0?r:[{id:"default-host",name:"Primary Host",host:e,port:u(n,a.vnc),protocol:"vnc"}]}function b(t){let e=String(t).trim().split(".");if(e.length!==4)return null;let n=0;for(let r of e){if(!/^\d{1,3}$/.test(r))return null;let o=Number.parseInt(r,10);if(o>255)return null;n=n<<8|o}return n>>>0}function H(t){if(!t)return[];let e=[];for(let n of t.split(",")){let r=n.trim();if(!r)continue;let o=r.split(".").findIndex(m=>m==="*"),[i,c]=o>=0?[r.replaceAll("*","0"),String(o*8)]:r.split("/"),p=b(i??"");if(p===null)continue;let s=c===void 0?32:Number.parseInt(c,10);if(!Number.isInteger(s)||s<0||s>32)continue;let l=s===0?0:4294967295<<32-s>>>0;e.push({base:(p&l)>>>0,mask:l})}return e}function G(t,e){let n=b(t);return n===null?!1:H(e).some(({base:r,mask:o})=>(n&o)>>>0===r)}var J={monitor:'<rect x="2" y="3" width="20" height="14" rx="2"/><path d="M8 21h8M12 17v4"/>',link:'<path d="M9 17H7A5 5 0 0 1 7 7h2M15 7h2a5 5 0 1 1 0 10h-2M8 12h8"/>',power:'<path d="M12 2v10"/><path d="M18.4 6.6a9 9 0 1 1-12.8 0"/>',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"/>',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"/>',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"/>',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"/>',check:'<path d="m5 13 4 4 10-10"/>',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"/>',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"/>',sliders:'<path d="M4 21v-7M4 10V3M12 21v-9M12 8V3M20 21v-5M20 12V3M2 14h4M10 8h4M18 16h4"/>',expand:'<path d="M15 3h6v6M9 21H3v-6M21 3l-7 7M3 21l7-7"/>',shield:'<path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/>',chevron:'<path d="m6 9 6 6 6-6"/>',back:'<path d="m15 18-6-6 6-6"/>',zap:'<path d="M13 2 3 14h9l-1 8 10-12h-9l1-8z"/>',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"/>',logout:'<path d="M9 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h4M16 17l5-5-5-5M21 12H9"/>',clock:'<circle cx="12" cy="12" r="9"/><path d="M12 7v5l3.5 2"/>',activity:'<path d="M22 12h-4l-3 9L9 3l-3 9H2"/>',transfer:'<path d="m3 16 4 4 4-4M7 20V4M21 8l-4-4-4 4M17 4v16"/>',screen:'<rect x="2" y="5" width="20" height="13" rx="2"/><path d="M7 21h10"/>',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"/>',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"/>',terminal:'<path d="m4 17 6-6-6-6M12 19h8"/>',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"/>',close:'<path d="M18 6 6 18M6 6l12 12"/>',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"/>',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"/>',panel:'<rect x="3" y="4" width="18" height="16" rx="2"/><path d="M14 4v16"/>',menu:'<path d="M4 7h16M4 12h16M4 17h16"/>',plus:'<path d="M12 5v14M5 12h14"/>',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"/>',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"/>'},j="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";var K="VNC_GATEWAY_READY_v1",X="VNC_GATEWAY_KEEPALIVE_v1",Z=25e3,Q=123;function tt(t){return!t.established||!t.close?!1:t.close.code===1006?!0:t.close.code===1011&&/tcp|socket|network|host closed/i.test(t.close.reason)}function et(t){let e=new TextEncoder;if(e.encode(t).byteLength<=123)return t;let n="";for(let r of t){if(e.encode(`${n}${r}\u2026`).byteLength>123)break;n+=r}return`${n}\u2026`}function nt(t){return t===1005||t===1006||t===1015?1011:t}async function rt(t){return typeof t=="string"?new TextEncoder().encode(t):t instanceof ArrayBuffer?new Uint8Array(t):t instanceof Blob?new Uint8Array(await t.arrayBuffer()):ArrayBuffer.isView(t)?new Uint8Array(t.buffer,t.byteOffset,t.byteLength):null}export{D as COMMAND_IDLE_MS,v as COMMAND_START_MS,d as DEFAULT_DISPLAY_SETTINGS,a as DEFAULT_PORTS,f as DEFAULT_SSH_PORT,j as FAVICON_DATA_URI,X as GATEWAY_KEEPALIVE_SIGNAL,K as GATEWAY_READY_SIGNAL,J as ICON_PATHS,Z as KEEPALIVE_INTERVAL_MS,Q as MAX_CLOSE_REASON_BYTES,P as RDP_SECURITY_MODES,A as REMOTE_PROTOCOLS,k as TRANSPORT_PROTOCOLS,E as connectionId,U as describeConnection,V as emptyConnection,G as hostInAllowedSubnets,b as ipv4ToInt,g as isRdpSecurity,C as isRemoteProtocol,tt as isRetryableDisconnect,rt as messageToBytes,z as normalizeConnection,_ as normalizeDisplaySettings,H as parseAllowedSubnets,F as parseConfiguredHosts,nt as sendableCloseCode,u as toPort,M as toRdpSecurity,h as toRemoteProtocol,et as websocketCloseReason,$ as withoutPassword};
+var _=["vnc","rdp"],V=["vnc","rdp","ssh"],P=["auto","nla","tls","rdp"],a={vnc:5900,rdp:3389,ssh:22},g=a.ssh,z=15e3,U=5*6e4;function T(t){return _.includes(t)}function y(t){return P.includes(t)}function d(t,e="vnc"){let n=String(t??"").toLowerCase();return T(n)?n:e}function b(t,e="auto"){let n=String(t??"").toLowerCase();return y(n)?n:e}function u(t,e){let n=typeof t=="number"?t:Number.parseInt(String(t??""),10);return Number.isInteger(n)&&n>0&&n<65536?n:e}var h={quality:6,compression:2,scaling:!0,viewOnly:!1,audio:!1};function O(t){let e=t.remoteApp?.program?.trim()??"",n=`${t.protocol||"vnc"}:${t.host.trim()}:${t.port||""}`;return(e?`${n}:${e}`:n).toLowerCase().slice(0,64)}function Y(t="vnc"){let e=a[t];return{id:"",label:"",protocol:t,host:"",port:e,username:"",password:"",domain:"",security:"auto",remoteApp:null,display:{...h},ssh:{enabled:!1,port:a.ssh,username:""},openSshOnConnect:!1}}function M(t,e,n,r){let o=typeof t=="number"?t:Number.parseInt(String(t??""),10);return Number.isInteger(o)?Math.min(r,Math.max(n,o)):e}function L(t){let e=t??{};return{quality:M(e.quality,h.quality,1,9),compression:M(e.compression,h.compression,0,9),scaling:typeof e.scaling=="boolean"?e.scaling:h.scaling,viewOnly:!!e.viewOnly,audio:!!e.audio}}function k(t){if(typeof t=="string"){let i=t.trim();return i?{program:i}:null}if(!t||typeof t!="object")return null;let e=t,n=String(e.program??"").trim();if(!n)return null;let r=String(e.workingDir??"").trim(),o=String(e.arguments??"").trim();return{program:n,...r?{workingDir:r}:{},...o?{arguments:o}:{}}}function F(t){let e=d(t.protocol),n=String(t.host??"").trim(),r=u(t.port,a[e]),o=k(t.remoteApp??t.program),i=t.ssh??{},c={enabled:!!i.enabled,port:u(i.port,a.ssh),username:(i.username??"").trim()},p={id:"",label:String(t.label??"").trim()||n,protocol:e,host:n,port:r,username:String(t.username??"").trim(),password:String(t.password??""),domain:String(t.domain??"").trim(),security:b(t.security),remoteApp:o,display:L(t.display),ssh:c,openSshOnConnect:!!t.openSshOnConnect};return p.id=String(t.id??"").trim()||O(p),p}function G(t){let{password:e,...n}=t;return n}function J(t){let e=`${t.host||"no address"}:${t.port}`,n=t.remoteApp?` \xB7 ${t.remoteApp.program}`:"";return`${t.protocol.toUpperCase()} \xB7 ${e}${n}`}var w="binary",f="airemote-cred.";function H(t){let e=new TextEncoder().encode(t),n="";for(let r of e)n+=String.fromCharCode(r);return btoa(n).replaceAll("+","-").replaceAll("/","_").replaceAll("=","")}function v(t){let e=t.replaceAll("-","+").replaceAll("_","/").padEnd(Math.ceil(t.length/4)*4,"="),n=atob(e),r=new Uint8Array(n.length);for(let o=0;o<n.length;o++)r[o]=n.charCodeAt(o);return new TextDecoder().decode(r)}function j(t){let e=t.username||"",n=t.password||"";return!e&&!n?[w]:[w,f+H(JSON.stringify({u:e,p:n}))]}function R(t){return t?t.split(",").map(e=>e.trim()).filter(Boolean):[]}function q(t){for(let e of R(t))if(e.startsWith(f))try{let n=JSON.parse(v(e.slice(f.length)));if(!n||typeof n!="object")return null;let{u:r,p:o}=n;return{username:typeof r=="string"?r:"",password:typeof o=="string"?o:""}}catch{return null}return null}function K(t){return R(t).find(e=>!e.startsWith(f))??null}function I(t){if(typeof t=="string"&&t.trim())return{program:t.trim()};if(!t||typeof t!="object")return;let e=t,n=String(e.program??"").trim();if(n)return{program:n,...e.workingDir?{workingDir:String(e.workingDir)}:{},...e.arguments?{arguments:String(e.arguments)}:{}}}function D(t,e){let n=typeof e=="string"&&e.trim()?e.trim():void 0;if(t===!0)return{port:g,...n?{username:n}:{}};if(typeof t=="number"||typeof t=="string"&&/^\d+$/.test(t.trim())){let i=u(t,0);return i?{port:i,...n?{username:n}:{}}:void 0}if(!t||typeof t!="object")return;let r=t;if(r.enabled===!1)return;let o=typeof r.username=="string"&&r.username.trim()?r.username.trim():n;return{port:u(r.port,g),...o?{username:o}:{}}}function A(t,e,n,r,o){if(!t)return[];let i;try{i=JSON.parse(t)}catch(c){return console.warn(`Failed to parse ${o.toUpperCase()}_HOSTS JSON, ignoring it:`,c),[]}return!Array.isArray(i)||i.length===0?[]:i.map((c,p)=>{let s=c??{},l=d(s.protocol,e),m=l==="rdp"?I(s.remoteApp):void 0,S=D(s.ssh??s.sshPort,s.sshUser??s.sshUsername),x=String(s.host??"")||n,E=String(s.name??"").trim()||x;return{id:String(s.id??"")||`${o}-${p+1}`,name:E,host:x,port:u(s.port??r,a[l]),protocol:l,...s.domain?{domain:String(s.domain)}:{},...y(s.security)?{security:s.security}:{},...m?{remoteApp:m}:{},...S?{ssh:S}:{}}})}function Q(t){let e=t.defaultHost||"10.0.0.10",n=t.defaultPort||String(a.vnc),r=[...A(t.vncHostsJson,"vnc",e,n,"vnc-host"),...A(t.rdpHostsJson,"rdp",t.defaultRdpHost||e,t.defaultRdpPort||String(a.rdp),"rdp-host")];return r.length>0?r:[{id:"default-host",name:"Primary Host",host:e,port:u(n,a.vnc),protocol:"vnc"}]}function C(t){let e=t.trim().split(".");if(e.length!==4)return null;let n=0;for(let r of e){if(!/^\d{1,3}$/.test(r))return null;let o=Number.parseInt(r,10);if(o>255)return null;n=n<<8|o}return n>>>0}function N(t){if(!t)return[];let e=[];for(let n of t.split(",")){let r=n.trim();if(!r)continue;let o=r.split(".").findIndex(m=>m==="*"),[i,c]=o>=0?[r.replaceAll("*","0"),String(o*8)]:r.split("/"),p=C(i??"");if(p===null)continue;let s=c===void 0?32:Number.parseInt(c,10);if(!Number.isInteger(s)||s<0||s>32)continue;let l=s===0?0:4294967295<<32-s>>>0;e.push({base:(p&l)>>>0,mask:l})}return e}function tt(t,e){let n=C(t);return n===null?!1:N(e).some(({base:r,mask:o})=>(n&o)>>>0===r)}var nt={monitor:'<rect x="2" y="3" width="20" height="14" rx="2"/><path d="M8 21h8M12 17v4"/>',link:'<path d="M9 17H7A5 5 0 0 1 7 7h2M15 7h2a5 5 0 1 1 0 10h-2M8 12h8"/>',power:'<path d="M12 2v10"/><path d="M18.4 6.6a9 9 0 1 1-12.8 0"/>',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"/>',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"/>',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"/>',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"/>',check:'<path d="m5 13 4 4 10-10"/>',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"/>',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"/>',sliders:'<path d="M4 21v-7M4 10V3M12 21v-9M12 8V3M20 21v-5M20 12V3M2 14h4M10 8h4M18 16h4"/>',expand:'<path d="M15 3h6v6M9 21H3v-6M21 3l-7 7M3 21l7-7"/>',shield:'<path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/>',chevron:'<path d="m6 9 6 6 6-6"/>',back:'<path d="m15 18-6-6 6-6"/>',zap:'<path d="M13 2 3 14h9l-1 8 10-12h-9l1-8z"/>',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"/>',logout:'<path d="M9 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h4M16 17l5-5-5-5M21 12H9"/>',clock:'<circle cx="12" cy="12" r="9"/><path d="M12 7v5l3.5 2"/>',activity:'<path d="M22 12h-4l-3 9L9 3l-3 9H2"/>',transfer:'<path d="m3 16 4 4 4-4M7 20V4M21 8l-4-4-4 4M17 4v16"/>',screen:'<rect x="2" y="5" width="20" height="13" rx="2"/><path d="M7 21h10"/>',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"/>',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"/>',terminal:'<path d="m4 17 6-6-6-6M12 19h8"/>',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"/>',close:'<path d="M18 6 6 18M6 6l12 12"/>',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"/>',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"/>',panel:'<rect x="3" y="4" width="18" height="16" rx="2"/><path d="M14 4v16"/>',menu:'<path d="M4 7h16M4 12h16M4 17h16"/>',plus:'<path d="M12 5v14M5 12h14"/>',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"/>',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"/>'},rt="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";var st="VNC_GATEWAY_READY_v1",it="VNC_GATEWAY_KEEPALIVE_v1",at=25e3,ct=123;function pt(t){return!t.established||!t.close?!1:t.close.code===1006?!0:t.close.code===1011&&/tcp|socket|network|host closed/i.test(t.close.reason)}function ut(t){let e=new TextEncoder;if(e.encode(t).byteLength<=123)return t;let n="";for(let r of t){if(e.encode(`${n}${r}\u2026`).byteLength>123)break;n+=r}return`${n}\u2026`}function lt(t){return t===1005||t===1006||t===1015?1011:t}async function mt(t){return typeof t=="string"?new TextEncoder().encode(t):t instanceof ArrayBuffer?new Uint8Array(t):t instanceof Blob?new Uint8Array(await t.arrayBuffer()):ArrayBuffer.isView(t)?new Uint8Array(t.buffer,t.byteOffset,t.byteLength):null}export{U as COMMAND_IDLE_MS,z as COMMAND_START_MS,h as DEFAULT_DISPLAY_SETTINGS,a as DEFAULT_PORTS,g as DEFAULT_SSH_PORT,rt as FAVICON_DATA_URI,it as GATEWAY_KEEPALIVE_SIGNAL,st as GATEWAY_READY_SIGNAL,nt as ICON_PATHS,at as KEEPALIVE_INTERVAL_MS,ct as MAX_CLOSE_REASON_BYTES,P as RDP_SECURITY_MODES,_ as REMOTE_PROTOCOLS,V as TRANSPORT_PROTOCOLS,w as WS_BINARY_SUBPROTOCOL,O as connectionId,J as describeConnection,Y as emptyConnection,tt as hostInAllowedSubnets,C as ipv4ToInt,y as isRdpSecurity,T as isRemoteProtocol,pt as isRetryableDisconnect,mt as messageToBytes,F as normalizeConnection,L as normalizeDisplaySettings,N as parseAllowedSubnets,Q as parseConfiguredHosts,q as readCredentialSubprotocol,K as selectSubprotocol,lt as sendableCloseCode,u as toPort,b as toRdpSecurity,d as toRemoteProtocol,ut as websocketCloseReason,j as websocketSubprotocols,G as withoutPassword};

package/dist/protocols.d.ts

@@ -1,3 +1,27 @@
+/**
+ * The part of a WebSocket the protocol engines actually use.
+ *
+ * The engines were written against a browser WebSocket pointed at the gateway's
+ * relay, and the CLI hands them a TCP socket wearing the same face (see
+ * `cli/transport.ts`). Naming that face is what lets both be passed without the
+ * engines being told which one they got -- and without the seam being an `any`,
+ * which is the same thing said less carefully.
+ */
+interface ByteTransport extends EventTarget {
+    readonly readyState: number;
+    binaryType: string;
+    /** The full range a browser WebSocket takes, so a real one satisfies this. */
+    send(data: string | ArrayBufferLike | ArrayBufferView | Blob): void;
+    close(code?: number, reason?: string): void;
+}
+/**
+ * A `CustomEvent` whose detail this code knows the shape of.
+ *
+ * The engines communicate by dispatching events, so their consumers spend a lot
+ * of time reaching into `event.detail`. Saying which shape is expected at the
+ * point of listening is what keeps that from being unchecked.
+ */
+type DetailListener<T> = (event: CustomEvent<T>) => void;
 /**
  * The vocabulary both halves of the gateway share.
  *
@@ -110,12 +134,24 @@ declare function connectionId(input: Pick<ConnectionSettings, 'protocol' | 'host
 /** A blank connection, ready for the dialog to fill in. */
 declare function emptyConnection(protocol?: RemoteProtocol): ConnectionSettings;
 declare function normalizeDisplaySettings(value: unknown): DisplaySettings;
+/**
+ * Anything a caller might have.
+ *
+ * Every field is `unknown` on purpose. This is the function that a saved card,
+ * a URL, a host-list entry and a localStorage blob all arrive at, and none of
+ * those had their types checked by anyone. Declaring them as already the right
+ * shape would not make them so -- it would only move the guesswork from here,
+ * where each field is coerced deliberately, to the callers, where it is not.
+ */
+type ConnectionInput = {
+    [K in keyof ConnectionSettings]?: unknown;
+} & Record<string, unknown>;
 /**
  * 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;
+declare function normalizeConnection(input: ConnectionInput): ConnectionSettings;
 /** What a connection is worth remembering by -- never the password. */
 type PersistedConnection = Omit<ConnectionSettings, 'password'>;
 declare function withoutPassword(settings: ConnectionSettings): PersistedConnection;
@@ -139,6 +175,11 @@ interface ScrollDelta {
     x: number;
     y: number;
 }
+/**
+ * What the metrics rail instruments. A real WebSocket in the browser; in the
+ * CLI, a shim with the same surface over a TCP socket straight at the host.
+ */
+type InstrumentableSocket = ByteTransport;
 /**
  * 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.
@@ -157,7 +198,7 @@ export interface RemoteSession extends EventTarget {
     /** 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 socket?: InstrumentableSocket | null;
     readonly screenGeometry: ScreenGeometry;
     movePointer(x: number, y: number): boolean;
     clickPointer(x: number, y: number, button?: PointerButton): boolean;
@@ -245,6 +286,45 @@ export interface ProtocolDriver {
     /** Protocol-specific wording for a close, or null to fall back to the shared text. */
     describeDisconnect(context: DisconnectContext): string | null;
 }
+/**
+ * Signing in with a key instead of a password.
+ *
+ * An identity is a public key blob, the algorithm name that goes with it, and
+ * something that can sign. What does the signing is deliberately behind a
+ * function: a key read off disk signs with Web Crypto, and a key held by
+ * ssh-agent signs by asking the agent -- the session cannot tell the two apart
+ * and does not need to.
+ *
+ * The parser here reads the format `ssh-keygen` writes by default, which no
+ * runtime can parse on its own: OpenSSH's own container rather than PKCS#8.
+ * Only unencrypted keys are read. A key with a passphrase would need bcrypt
+ * and a prompt, and the answer to a passphrase is ssh-agent, which is already
+ * holding the decrypted key.
+ */
+/** One key that can sign for a user, however it happens to be held. */
+interface SshIdentity {
+    /** The public key type, e.g. `ssh-ed25519`. */
+    readonly keyType: string;
+    /** The public key, in the wire format the host expects. */
+    readonly keyBlob: Uint8Array;
+    /** Where it came from, for logs and error messages. */
+    readonly comment: string;
+    /**
+     * Signature algorithms to offer, best first. RSA keys sign under several,
+     * and a host will say which of them it is willing to take.
+     */
+    readonly algorithms: readonly string[];
+    /** The full signature blob (algorithm name and signature) over `data`. */
+    sign(data: Uint8Array, algorithm: string): Promise<Uint8Array>;
+}
+/**
+ * Read a private key file.
+ *
+ * Returns one identity, or throws with the reason a human can act on -- which
+ * for the common failure is "this key has a passphrase, so let ssh-agent hold
+ * it" rather than a decoder error.
+ */
+declare function parsePrivateKey(text: string, comment?: string): Promise<SshIdentity>;
 export declare const DEFAULT_PORT = 22;
 export declare const COMMAND_MAX_MS: number;
 /**
@@ -253,9 +333,151 @@ export declare const COMMAND_MAX_MS: number;
  * 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 function frameCommand(family: string, command: string, id: string): string;
+/** What runCommand resolves with. */
+export interface CommandResult {
+    output: string;
+    exitStatus: number | null;
+    exitSignal?: string;
+    timedOut?: boolean;
+    started?: boolean;
+    reason?: string;
+    durationMs: number;
+}
+/** A tool command's output framing, hidden from the screen while it runs. */
+interface DisplayFilter {
+    begin: string;
+    end: string;
+    stage: 'before' | 'inside' | 'closing';
+    pending: string;
+}
+/** What a caller can ask of an SSH session. */
+export interface SshSessionOptions {
+    username?: string;
+    password?: string;
+    identities?: SshIdentity[] | (() => Promise<SshIdentity[]>);
+    preferredShell?: 'powershell';
+    /** Run a subsystem (e.g. 'sftp') rather than a shell. */
+    subsystem?: string;
+    columns?: number;
+    rows?: number;
+    hostLabel?: string;
+    log?: (step: string, detail?: unknown) => void;
+    verifyHost?: (info: {
+        fingerprint: string;
+        keyType: string;
+        algorithm: string;
+    }) => Promise<boolean> | boolean;
+    openTransport?: ((url: string) => ByteTransport) | null;
+    requestInput?: (prompt: {
+        prompt?: string;
+        echo?: boolean;
+    }) => Promise<string>;
+}
+/** What each SshSession event carries in its `detail`. */
+export interface SshSessionEventDetail {
+    data: {
+        bytes: Uint8Array;
+        display?: Uint8Array;
+        isStderr: boolean;
+    };
+    ready: {
+        fingerprint?: string;
+        shellFamily: string;
+    };
+    status: {
+        phase: string;
+        message: string;
+    };
+    banner: {
+        text: string;
+    };
+    secure: {
+        fingerprint: string;
+        kexAlgorithm: string;
+        hostKeyAlgorithm: string;
+        cipher: string;
+        firstTime: boolean;
+    };
+    error: {
+        message: string;
+    };
+    close: {
+        message: string;
+        exitStatus?: number | null;
+        clean?: boolean;
+        code?: number;
+    };
+    command: {
+        phase: 'start' | 'end';
+        command: string;
+        exitStatus?: number | null;
+        timedOut?: boolean;
+        started?: boolean;
+        /** Why it was given up on: never acknowledged, silent, or simply too long. */
+        reason?: string;
+        durationMs?: number;
+    };
+}
 export declare class SshSession extends EventTarget {
     #private;
+    /**
+     * Listen for one of this session's own events, typed by what it carries.
+     * The shapes are enumerated in `SshSessionEventDetail` just above.
+     */
+    addEventListener: {
+        <K extends keyof SshSessionEventDetail>(type: K, listener: (event: CustomEvent<SshSessionEventDetail[K]>) => void, options?: boolean | AddEventListenerOptions): void;
+        (type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | AddEventListenerOptions): void;
+    };
+    private readonly options;
+    private readonly username;
+    private password;
+    /**
+     * Keys to sign in with, if any. A function rather than a list is allowed
+     * because reading keys off a disk -- or asking an agent for them -- is work
+     * a session that never needs them should not do.
+     */
+    /** Replaced with the resolved list the first time it is read. */
+    private identities;
+    private readonly requestInput;
+    /** Whether there is anybody to ask; see the constructor. */
+    private readonly canAsk;
+    private columns;
+    private rows;
+    /** A subsystem to run instead of a shell, e.g. 'sftp'. */
+    private readonly subsystem;
+    private channelId;
+    private remoteChannelId;
+    private remoteWindow;
+    private remoteMaxPacket;
+    private localWindow;
+    private pendingWrites;
+    /** True while the interactive shell channel is usable. */
+    shellOpen: boolean;
+    private commandInFlight;
+    /** Set while a tool command runs, to keep its framing off the screen. */
+    displayFilter: DisplayFilter | null;
+    /** True only after the requested interactive shell is ready for commands. */
+    /** True once the interactive shell is actually usable, not merely authenticated. */
+    readySignaled: boolean;
+    private powerShellAttempted;
+    private powerShellTimer;
+    /** '', 'posix', 'cmd' or 'powershell'; learned from the prompt. */
+    /** 'powershell' when the host answered with one; '' until the shell is known. */
+    shellFamily: string;
+    private promptTail;
+    private exitStatus;
+    private exitSignal?;
+    private authMethods;
+    /** Which keys were offered and refused, for the message if nothing works. */
+    private triedKeys;
+    /** Set once the host has said no to the stored password. */
+    private passwordRejected;
+    private closed;
+    private waiters;
+    private readonly transport;
+    private fingerprint?;
+    private lastMessage?;
     /**
      * @param {string} url          gateway WebSocket URL
      * @param {object} options
@@ -268,11 +490,11 @@ export declare class SshSession extends EventTarget {
      * @param {(info: object) => Promise<boolean>} [options.verifyHost]
      * @param {(prompt: object) => Promise<string>} [options.requestInput]
      */
-    constructor(url: string, options?: {});
+    constructor(url: string, options?: SshSessionOptions);
     connect(): void;
     disconnect(): void;
     /** Send keystrokes, or anything else the terminal produces, to the shell. */
-    write(data: Uint8Array): void;
+    write(data: Uint8Array | string): void;
     /**
      * Run one command in this shell and return what it printed.
      *
@@ -295,16 +517,24 @@ export declare class SshSession extends EventTarget {
         idleMs?: number;
         maxMs?: number;
         startMs?: number;
-    }): Promise<unknown>;
+    }): Promise<CommandResult>;
     /** Tell the shell its window changed, so full-screen programs redraw. */
     resize(columns: number, rows: number): void;
 }
+import { Terminal } from '@xterm/xterm';
 export declare class SshTerminal {
-    constructor(container: any);
-    get columns(): any;
-    get rows(): any;
-    onData(handler: any): void;
-    onResize(handler: any): void;
+    private readonly container;
+    readonly terminal: Terminal;
+    private readonly fitAddon;
+    private readonly observer;
+    /** Where keystrokes go; readLine swaps it out while it owns the line. */
+    private dataHandler;
+    private fitting;
+    constructor(container: HTMLElement);
+    get columns(): number;
+    get rows(): number;
+    onData(handler: ((data: string) => void) | null): void;
+    onResize(handler: (cols: number, rows: number) => void): void;
     write(data: Uint8Array): void;
     /** Gateway-side notices, kept visually apart from what the host prints. */
     notice(text: string, tone?: string): void;
@@ -329,20 +559,20 @@ export declare class SshTerminal {
     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;
+        columns: number;
+        rows: number;
+        fontSize: number;
     };
-    get selection(): any;
+    get selection(): string;
     /**
      * 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>;
+        echo?: boolean;
+    }): Promise<string>;
     destroy(): void;
 }
 export declare const DRIVERS: Record<RemoteProtocol, ProtocolDriver>;