ai-remote 0.1.0 → 0.3.0

package/src/cli/ipc.ts

@@ -0,0 +1,78 @@
+/**
+ * The conversation between a command and the session it attaches to.
+ *
+ * Newline-delimited JSON over a unix socket. Nothing here crosses a network,
+ * so the format is chosen to be obvious in a log rather than compact.
+ */
+
+import net from 'node:net';
+import { StringDecoder } from 'node:string_decoder';
+
+export interface Request {
+  id: number;
+  op: string;
+  args?: Record<string, unknown>;
+}
+
+export interface Response {
+  id: number;
+  ok: boolean;
+  result?: unknown;
+  error?: string;
+  /** The exit code this failure should produce, when it has a natural one. */
+  code?: number;
+}
+
+/**
+ * Read newline-delimited JSON off a socket, one object at a time.
+ *
+ * The decoder is stateful rather than a `toString()` per chunk, because a read
+ * boundary can fall inside a multi-byte character: `type HOST "café"` split at
+ * the wrong byte used to arrive as a replacement character. It holds the
+ * incomplete tail until the rest of it turns up.
+ */
+export function readMessages(socket: net.Socket, onMessage: (value: any) => void): void {
+  const decoder = new StringDecoder('utf8');
+  let buffer = '';
+  socket.on('data', (chunk) => {
+    buffer += decoder.write(chunk as Buffer);
+    for (;;) {
+      const newline = buffer.indexOf('\n');
+      if (newline === -1) return;
+      const line = buffer.slice(0, newline);
+      buffer = buffer.slice(newline + 1);
+      if (!line.trim()) continue;
+      try { onMessage(JSON.parse(line)); } catch { /* a truncated write; drop it */ }
+    }
+  });
+}
+
+export const writeMessage = (socket: net.Socket, value: unknown): void => {
+  socket.write(`${JSON.stringify(value)}\n`);
+};
+
+/** Send one request to a running session and wait for its answer. */
+export function request(path: string, op: string, args: Record<string, unknown> = {}, timeoutMs = 120_000): Promise<Response> {
+  return new Promise((resolve, reject) => {
+    const socket = net.connect(path);
+    let settled = false;
+
+    const finish = (error: Error | null, response?: Response) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      if (error) reject(error); else resolve(response!);
+    };
+
+    const timer = setTimeout(() => finish(new Error(`The session did not answer "${op}" in time.`)), timeoutMs);
+
+    socket.on('connect', () => writeMessage(socket, { id: 1, op, args }));
+    socket.on('error', (error: NodeJS.ErrnoException) => {
+      // ENOENT and ECONNREFUSED both mean the same thing to a caller: the
+      // session named by that socket is not running.
+      finish(Object.assign(error, { notRunning: error.code === 'ENOENT' || error.code === 'ECONNREFUSED' }));
+    });
+    readMessages(socket, (message) => finish(null, message as Response));
+  });
+}

package/src/cli/paths.ts

@@ -0,0 +1,28 @@
+/**
+ * Where a running session leaves its door open.
+ *
+ * One directory per user, mode 0700, because the socket in it accepts input
+ * for a live desktop: anything that can reach it can type on the machine.
+ */
+
+import { mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const ROOT = join(homedir(), '.ai-remote');
+export const RUN_DIR = join(ROOT, 'run');
+
+export function ensureRunDir(): string {
+  mkdirSync(RUN_DIR, { recursive: true, mode: 0o700 });
+  return RUN_DIR;
+}
+
+/** A stable name for a target, so a second command finds the first one's session. */
+export function sessionName(host: string, port: number, explicit?: string): string {
+  if (explicit) return explicit.replace(/[^\w.-]/g, '_');
+  return `${host}_${port}`.replace(/[^\w.-]/g, '_');
+}
+
+export const socketPath = (name: string) => join(RUN_DIR, `${name}.sock`);
+export const metaPath = (name: string) => join(RUN_DIR, `${name}.json`);
+export const logPath = (name: string) => join(RUN_DIR, `${name}.log`);

package/src/cli/png.ts

@@ -0,0 +1,106 @@
+/**
+ * A PNG writer, so a screenshot needs no dependency.
+ *
+ * The browser encodes JPEG through the canvas it already has. Node has no
+ * image encoder at all, but it does have DEFLATE -- which is the only
+ * compression PNG defines -- so the rest is three chunks and two checksums.
+ */
+
+import { deflateSync } from 'node:zlib';
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+function crc32(bytes: Uint8Array): number {
+  let c = 0xffffffff;
+  for (let i = 0; i < bytes.length; i++) c = CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function chunk(type: string, body: Uint8Array): Uint8Array {
+  const out = new Uint8Array(12 + body.length);
+  const view = new DataView(out.buffer);
+  view.setUint32(0, body.length);
+  for (let i = 0; i < 4; i++) out[4 + i] = type.charCodeAt(i);
+  out.set(body, 8);
+  view.setUint32(8 + body.length, crc32(out.subarray(4, 8 + body.length)));
+  return out;
+}
+
+/** RGBA in, PNG out. Rows are filtered `None`, which DEFLATE handles well enough. */
+export function encodePng(rgba: Uint8Array, width: number, height: number): Uint8Array {
+  const stride = width * 4;
+  const raw = new Uint8Array((stride + 1) * height);
+  for (let y = 0; y < height; y++) {
+    raw[y * (stride + 1)] = 0;
+    raw.set(rgba.subarray(y * stride, y * stride + stride), y * (stride + 1) + 1);
+  }
+
+  const ihdr = new Uint8Array(13);
+  const view = new DataView(ihdr.buffer);
+  view.setUint32(0, width);
+  view.setUint32(4, height);
+  ihdr[8] = 8;   // bit depth
+  ihdr[9] = 6;   // colour type: truecolour with alpha
+  ihdr[10] = 0;  // compression: deflate
+  ihdr[11] = 0;  // filter: adaptive
+  ihdr[12] = 0;  // interlace: none
+
+  const parts = [
+    new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk('IHDR', ihdr),
+    chunk('IDAT', new Uint8Array(deflateSync(raw, { level: 6 }))),
+    chunk('IEND', new Uint8Array(0)),
+  ];
+
+  const total = parts.reduce((sum, part) => sum + part.length, 0);
+  const png = new Uint8Array(total);
+  let offset = 0;
+  for (const part of parts) {
+    png.set(part, offset);
+    offset += part.length;
+  }
+  return png;
+}
+
+/**
+ * Nearest-neighbour downscale to fit `maxEdge`.
+ *
+ * A box filter would look better, but this frame exists to be read -- by a
+ * model or by a person checking what happened -- and nearest-neighbour keeps
+ * single-pixel text strokes from being averaged into grey.
+ */
+export function downscale(
+  rgba: Uint8Array,
+  width: number,
+  height: number,
+  maxEdge: number
+): { rgba: Uint8Array; width: number; height: number } {
+  const scale = Math.min(1, maxEdge / Math.max(width, height));
+  if (scale >= 1) return { rgba, width, height };
+
+  const outWidth = Math.max(1, Math.round(width * scale));
+  const outHeight = Math.max(1, Math.round(height * scale));
+  const out = new Uint8Array(outWidth * outHeight * 4);
+
+  for (let y = 0; y < outHeight; y++) {
+    const sourceY = Math.min(height - 1, Math.floor(y / scale));
+    for (let x = 0; x < outWidth; x++) {
+      const sourceX = Math.min(width - 1, Math.floor(x / scale));
+      const from = (sourceY * width + sourceX) * 4;
+      const to = (y * outWidth + x) * 4;
+      out[to] = rgba[from];
+      out[to + 1] = rgba[from + 1];
+      out[to + 2] = rgba[from + 2];
+      out[to + 3] = rgba[from + 3];
+    }
+  }
+  return { rgba: out, width: outWidth, height: outHeight };
+}

package/src/cli/session.ts

@@ -0,0 +1,263 @@
+/**
+ * One RDP session, headless.
+ *
+ * The same client the browser runs, given a TCP transport and a framebuffer
+ * instead of a WebSocket and a canvas. Nothing above the transport knows the
+ * difference, which is the point of the seam.
+ */
+
+import { RdpClient } from '../protocols/rdp/client';
+import { Framebuffer, type PaintedRect } from './framebuffer';
+import { TcpTransport } from './transport';
+
+export interface SessionOptions {
+  host: string;
+  port: number;
+  username: string;
+  password: string;
+  domain: string;
+  width: number;
+  height: number;
+  security: 'auto' | 'nla' | 'tls' | 'rdp';
+  /** Shown in this session's own log lines and sent to the host. */
+  clientName: string;
+  /**
+   * Where the bytes go. Defaults to a TCP socket at `host:port`.
+   *
+   * Injectable for the same reason the client's is: a test can drive a whole
+   * session against a mock host with no network, and a future gateway mode can
+   * point the same session at a relay instead.
+   */
+  openTransport?: () => any;
+}
+
+export interface PointerState {
+  x: number;
+  y: number;
+}
+
+type Listener = (rects: PaintedRect[], framebuffer: Framebuffer) => void;
+
+export class RdpSession {
+  readonly framebuffer = new Framebuffer();
+  readonly options: SessionOptions;
+
+  client: any;
+  connected = false;
+  lastError = '';
+
+  #painters = new Set<Listener>();
+  #resizers = new Set<(width: number, height: number) => void>();
+  #pointer: PointerState = { x: 0, y: 0 };
+
+  constructor(options: SessionOptions) {
+    this.options = options;
+
+    this.client = new RdpClient(`tcp://${options.host}:${options.port}`, {
+      width: options.width,
+      height: options.height,
+      username: options.username,
+      password: options.password,
+      domain: options.domain,
+      security: options.security,
+      clientName: options.clientName,
+      clipboard: true,
+      openTransport: options.openTransport ?? (() => new TcpTransport(options.host, options.port)),
+    });
+
+    this.client.addEventListener('ready', (event: any) => {
+      const { width, height } = event.detail;
+      this.framebuffer.resize(width, height);
+      this.connected = true;
+      for (const notify of this.#resizers) notify(width, height);
+    });
+
+    this.client.addEventListener('resize', (event: any) => {
+      const { width, height } = event.detail;
+      this.framebuffer.resize(width, height);
+      for (const notify of this.#resizers) notify(width, height);
+    });
+
+    this.client.addEventListener('bitmap', (event: any) => {
+      const painted = this.framebuffer.draw(event.detail.rects, event.detail.palette ?? null);
+      if (painted.length) for (const notify of this.#painters) notify(painted, this.framebuffer);
+    });
+
+    this.client.addEventListener('palette', (event: any) => {
+      this.framebuffer.palette = event.detail;
+    });
+
+    this.client.addEventListener('error', (event: any) => {
+      this.lastError = event.detail?.message || '';
+    });
+
+    this.client.addEventListener('close', () => {
+      this.connected = false;
+    });
+  }
+
+  onPaint(listener: Listener): () => void {
+    this.#painters.add(listener);
+    return () => this.#painters.delete(listener);
+  }
+
+  onResize(listener: (width: number, height: number) => void): () => void {
+    this.#resizers.add(listener);
+    return () => this.#resizers.delete(listener);
+  }
+
+  /** Resolves when the desktop is up, or rejects with what the host said. */
+  connect(timeoutMs = 30_000): Promise<{ width: number; height: number }> {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const finish = (error: Error | null, size?: { width: number; height: number }) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (error) reject(error); else resolve(size!);
+      };
+
+      const timer = setTimeout(
+        () => {
+          this.client.disconnect();
+          finish(new Error(`The host did not present a desktop within ${Math.round(timeoutMs / 1000)}s.`));
+        },
+        timeoutMs
+      );
+
+      this.client.addEventListener('ready', (event: any) => finish(null, event.detail));
+      this.client.addEventListener('close', (event: any) => {
+        const detail = event.detail || {};
+        finish(new Error(this.lastError || detail.message || 'The connection closed during the handshake.'));
+      });
+
+      // RdpClient opens its transport in its own constructor, so by the time
+      // this runs the negotiation is already in flight. Listeners attached
+      // here still arrive first: every transport event is asynchronous.
+    });
+  }
+
+  disconnect(): void {
+    // The client suppresses its own close event on an explicit disconnect, so
+    // this is the only place that can answer "is it still connected" honestly.
+    this.connected = false;
+    this.client.disconnect();
+  }
+
+  // --- input ----------------------------------------------------------------
+  //
+  // These mirror what the browser's display layer does with a DOM event: the
+  // pointer is positioned and the button flag travels with it, and a key is
+  // sent by its DOM code because that is what maps to a scancode. The keysym
+  // is only the fallback for a character with no key of its own -- the same
+  // order of preference the RDP driver uses.
+
+  get pointer(): PointerState {
+    return { ...this.#pointer };
+  }
+
+  movePointer(x: number, y: number): void {
+    this.#pointer = this.#clamp(x, y);
+    this.client.sendMouseMove(this.#pointer.x, this.#pointer.y);
+  }
+
+  /** `button` is 0 left, 1 middle, 2 right, as the UI numbers them. */
+  pointerButton(x: number, y: number, button: number, pressed: boolean): void {
+    this.#pointer = this.#clamp(x, y);
+    this.client.sendMouseButton(button, pressed, this.#pointer.x, this.#pointer.y);
+  }
+
+  click(x: number, y: number, button = 0): void {
+    this.movePointer(x, y);
+    this.pointerButton(x, y, button, true);
+    this.pointerButton(x, y, button, false);
+  }
+
+  /**
+   * Scroll by whole notches, positive being down and right -- the direction
+   * the driver interface names.
+   *
+   * The client's `sendWheel` takes a direction and emits exactly one notch, so
+   * a count has to become that many calls. Passing 3 to it would scroll one
+   * notch, not three, which is a quiet way to look like scrolling is broken.
+   */
+  scroll(x: number, y: number, notchesX: number, notchesY: number): void {
+    this.#pointer = this.#clamp(x, y);
+    const { x: px, y: py } = this.#pointer;
+
+    for (let i = 0; i < Math.abs(notchesY); i++) {
+      this.client.sendWheel(Math.sign(notchesY), px, py, false);
+    }
+    for (let i = 0; i < Math.abs(notchesX); i++) {
+      this.client.sendWheel(Math.sign(notchesX), px, py, true);
+    }
+  }
+
+  typeText(text: string): void {
+    this.client.sendUnicode(text);
+  }
+
+  /** One key by its DOM code, e.g. `Enter`, `ControlLeft`, `F5`. */
+  sendKeyCode(code: string, pressed: boolean): boolean {
+    return this.client.sendKeyByCode(code, pressed) !== false;
+  }
+
+  sendCtrlAltDel(): void {
+    this.client.sendCtrlAltDel();
+  }
+
+  /** Ask the host to repaint the whole desktop, so a screenshot is complete. */
+  requestFullRepaint(): void {
+    if (!this.framebuffer.width) return;
+    this.client.refresh({
+      left: 0,
+      top: 0,
+      right: this.framebuffer.width - 1,
+      bottom: this.framebuffer.height - 1,
+    });
+  }
+
+  /**
+   * Resolve once the desktop has painted and then gone quiet.
+   *
+   * A screenshot taken the instant the handshake finishes is black: the host
+   * has agreed on a desktop size but has not sent any of it yet. Waiting for a
+   * fixed delay instead would be either too short on a busy machine or wasted
+   * time on an idle one, so this waits for the thing that actually matters --
+   * pixels arriving, and then stopping.
+   */
+  settle({ quietMs = 500, timeoutMs = 8000 } = {}): Promise<{ painted: boolean; waitedMs: number }> {
+    return new Promise((resolve) => {
+      const started = Date.now();
+      const deadline = started + timeoutMs;
+      let seen = -1;
+      let quietSince = Date.now();
+
+      const timer = setInterval(() => {
+        const generation = this.framebuffer.generation;
+        if (generation !== seen) {
+          seen = generation;
+          quietSince = Date.now();
+        }
+
+        const painted = this.framebuffer.paints > 0;
+        const quiet = Date.now() - quietSince >= quietMs;
+        if ((painted && quiet) || Date.now() >= deadline) {
+          clearInterval(timer);
+          resolve({ painted, waitedMs: Date.now() - started });
+        }
+      }, 80);
+    });
+  }
+
+  setClipboard(text: string): void {
+    this.client.setClipboardText(text);
+  }
+
+  #clamp(x: number, y: number): PointerState {
+    return {
+      x: Math.max(0, Math.min(Math.max(0, this.framebuffer.width - 1), Math.round(x))),
+      y: Math.max(0, Math.min(Math.max(0, this.framebuffer.height - 1), Math.round(y))),
+    };
+  }
+}

package/src/cli/shell.ts

@@ -0,0 +1,171 @@
+/**
+ * An SSH shell on the same machine the desktop is showing.
+ *
+ * RDP has no shell channel, so a terminal beside the desktop is a second
+ * connection to the same host. The engine is the browser's, unchanged: the key
+ * exchange, the session keys and the password exist only in this process.
+ */
+
+import { SshSession } from '../protocols/ssh/session';
+import { TcpTransport } from './transport';
+
+export interface ShellOptions {
+  host: string;
+  port: number;
+  username: string;
+  password: string;
+  columns?: number;
+  rows?: number;
+}
+
+export interface CommandResult {
+  output: string;
+  exitStatus: number | null;
+  timedOut: boolean;
+  durationMs: number | null;
+}
+
+export class Shell {
+  readonly options: ShellOptions;
+  session: any;
+  ready = false;
+  lastError = '';
+
+  #sinks = new Set<(bytes: Uint8Array) => void>();
+  /** What the shell has printed, so a viewer attaching late sees the scrollback. */
+  #scrollback: Uint8Array[] = [];
+  #scrollbackBytes = 0;
+
+  constructor(options: ShellOptions) {
+    this.options = options;
+
+    this.session = new SshSession(`tcp://${options.host}:${options.port}`, {
+      username: options.username,
+      password: options.password,
+      columns: options.columns ?? 120,
+      rows: options.rows ?? 30,
+      // Every host this reaches was named by the person running the command,
+      // on their own network. There is no stored known_hosts to compare with
+      // yet, so nothing useful can be decided here.
+      verifyHost: async () => true,
+      openTransport: () => new TcpTransport(options.host, options.port),
+    });
+
+    this.session.addEventListener('data', (event: any) => {
+      // `display` is what the terminal should show: the same stream with the
+      // framing `runCommand` wraps around a command filtered back out. `bytes`
+      // is the unfiltered original, which would leak those markers on screen.
+      const bytes: Uint8Array = event.detail.display ?? event.detail.bytes;
+      if (!bytes?.length) return;
+      this.#remember(bytes);
+      for (const sink of this.#sinks) sink(bytes);
+    });
+
+    this.session.addEventListener('ready', () => { this.ready = true; });
+    this.session.addEventListener('error', (event: any) => {
+      this.lastError = event.detail?.message || '';
+    });
+    this.session.addEventListener('close', () => { this.ready = false; });
+  }
+
+  /** Everything printed so far, capped so a long-running shell cannot grow forever. */
+  get scrollback(): Uint8Array {
+    const total = this.#scrollback.reduce((sum, chunk) => sum + chunk.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of this.#scrollback) { out.set(chunk, offset); offset += chunk.length; }
+    return out;
+  }
+
+  onData(sink: (bytes: Uint8Array) => void): () => void {
+    this.#sinks.add(sink);
+    return () => this.#sinks.delete(sink);
+  }
+
+  connect(timeoutMs = 30_000): Promise<void> {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const finish = (error?: Error) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (error) reject(error); else resolve();
+      };
+
+      const timer = setTimeout(
+        () => finish(new Error(`The SSH host did not open a shell within ${Math.round(timeoutMs / 1000)}s.`)),
+        timeoutMs
+      );
+
+      this.session.addEventListener('ready', () => finish());
+      this.session.addEventListener('close', (event: any) => {
+        finish(new Error(this.lastError || event.detail?.message || 'The SSH connection closed during sign-in.'));
+      });
+
+      this.session.connect();
+    });
+  }
+
+  /**
+   * Run one command and wait for its output and exit status.
+   *
+   * The first command against a Windows host usually fails: the engine frames
+   * commands POSIX-style to find where the output starts and ends, cmd.exe
+   * rejects that, and the engine notes the shell family and asks to be called
+   * again. That is a detail of how the shell was discovered, not something a
+   * caller did wrong, so the retry happens here instead of reaching them.
+   */
+  async runCommand(command: string): Promise<CommandResult> {
+    let result;
+    try {
+      result = await this.session.runCommand(command);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (!/run the command again|not a POSIX shell/i.test(message)) throw error;
+
+      // Discovering the shell family restarts it, so the retry has to wait for
+      // the prompt to come back rather than firing straight into a shell that
+      // is still opening.
+      await this.#waitForPrompt();
+      result = await this.session.runCommand(command);
+    }
+    return {
+      output: result.output ?? '',
+      exitStatus: result.exitStatus ?? null,
+      timedOut: Boolean(result.timedOut),
+      durationMs: result.durationMs ?? null,
+    };
+  }
+
+  /** Wait until the shell will accept a framed command again. */
+  async #waitForPrompt(timeoutMs = 15_000): Promise<void> {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (this.session.shellOpen && this.session.readySignaled !== false) return;
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    throw new Error('The SSH shell did not come back after its family was discovered.');
+  }
+
+  /** Raw keystrokes, for an interactive terminal. */
+  write(text: string): void {
+    this.session.write(text);
+  }
+
+  resize(columns: number, rows: number): void {
+    this.session.resize?.(columns, rows);
+  }
+
+  disconnect(): void {
+    try { this.session.disconnect(); } catch { /* already gone */ }
+  }
+
+  #remember(bytes: Uint8Array): void {
+    const CAP = 256 * 1024;
+    this.#scrollback.push(bytes);
+    this.#scrollbackBytes += bytes.length;
+    while (this.#scrollbackBytes > CAP && this.#scrollback.length > 1) {
+      this.#scrollbackBytes -= this.#scrollback.shift()!.length;
+    }
+  }
+}