ai-remote 0.1.0 → 0.3.0

package/src/cli/transport.ts

@@ -0,0 +1,86 @@
+/**
+ * A TCP socket wearing the shape of a WebSocket.
+ *
+ * The protocol engines were written against a browser WebSocket pointed at the
+ * gateway's relay. What they actually use of it is small -- open, message,
+ * close, error, send, readyState, close() -- so a direct TCP connection can
+ * present the same face and the engines never learn which one they were given.
+ *
+ * The one asymmetry is the gateway's own control frames. GATEWAY_READY and
+ * GATEWAY_KEEPALIVE are a conversation between the browser and the relay, and
+ * they are strings precisely so they can never be mistaken for protocol bytes.
+ * There is no relay here, so they are dropped: forwarding them would push
+ * `VNC_GATEWAY_READY_v1` into the middle of an X.224 negotiation.
+ */
+
+import net from 'node:net';
+
+export class TcpTransport extends EventTarget {
+  static readonly CONNECTING = 0;
+  static readonly OPEN = 1;
+  static readonly CLOSING = 2;
+  static readonly CLOSED = 3;
+
+  readyState = 0;
+  /** Set by the engines; this transport always delivers ArrayBuffers. */
+  binaryType = 'arraybuffer';
+
+  #socket: net.Socket;
+  #closeSent = false;
+
+  constructor(host: string, port: number) {
+    super();
+
+    this.#socket = net.connect({ host, port, noDelay: true });
+
+    this.#socket.on('connect', () => {
+      this.readyState = 1;
+      this.dispatchEvent(new Event('open'));
+    });
+
+    this.#socket.on('data', (chunk: Buffer) => {
+      // A copy, because Node reuses its read buffer and the engines hold on to
+      // what they are handed until a frame is complete.
+      const bytes = new Uint8Array(chunk.byteLength);
+      bytes.set(chunk);
+      this.dispatchEvent(new MessageEvent('message', { data: bytes.buffer }));
+    });
+
+    this.#socket.on('error', (error: Error) => {
+      this.dispatchEvent(new Event('error'));
+      this.#reportClose(1006, error.message, false);
+    });
+
+    this.#socket.on('close', () => {
+      this.#reportClose(1006, 'The host closed the TCP connection.', false);
+    });
+  }
+
+  send(data: string | Uint8Array | ArrayBuffer): void {
+    // Gateway control frames. There is no gateway.
+    if (typeof data === 'string') return;
+    if (this.readyState !== 1) return;
+    this.#socket.write(data instanceof ArrayBuffer ? new Uint8Array(data) : data);
+  }
+
+  close(code = 1000, reason = ''): void {
+    if (this.readyState >= 2) return;
+    this.readyState = 2;
+    this.#socket.destroy();
+    this.#reportClose(code, reason, code === 1000);
+  }
+
+  #reportClose(code: number, reason: string, wasClean: boolean): void {
+    if (this.#closeSent) return;
+    this.#closeSent = true;
+    this.readyState = 3;
+
+    // CloseEvent is not a Node global. The engines read exactly these three
+    // fields, so a plain Event carrying them is indistinguishable to them.
+    const event = new Event('close') as Event & { code: number; reason: string; wasClean: boolean };
+    event.code = code;
+    event.reason = reason;
+    event.wasClean = wasClean;
+    this.dispatchEvent(event);
+  }
+}

package/src/cli/viewer-client/assets.d.ts

@@ -0,0 +1,4 @@
+// The viewer bundle imports xterm's stylesheet so the page carries it instead
+// of reaching for a CDN. esbuild turns it into CSS output; TypeScript only
+// needs to know the import is legal.
+declare module '*.css';

package/src/cli/viewer-client/main.ts

@@ -0,0 +1,300 @@
+/**
+ * The viewer front end: the desktop, and a terminal beside it.
+ *
+ * This is a real bundle rather than a hand-written script in a string, for one
+ * reason: a Windows console addresses the cursor absolutely -- conhost emits
+ * `ESC[9;1H` between every line of output -- so anything less than a genuine
+ * terminal emulator renders its output scrambled. xterm.js is that emulator,
+ * and the web front end in this repository already uses it.
+ */
+
+import { Terminal } from '@xterm/xterm';
+import { FitAddon } from '@xterm/addon-fit';
+import '@xterm/xterm/css/xterm.css';
+
+type Json = Record<string, any>;
+
+const $ = <T extends HTMLElement>(id: string) => document.getElementById(id) as T;
+
+const canvas = $<HTMLCanvasElement>('screen');
+const context = canvas.getContext('2d', { alpha: false })!;
+const stateEl = $('state');
+const sizeEl = $('size');
+const hostEl = $('host');
+const hintEl = $('hint');
+const fitBtn = $('fit');
+const ctlBtn = $('control');
+const termBtn = $('term');
+const fsBtn = $('full');
+const termPane = $('terminal');
+const termHost = $('termHost');
+
+let control = false;
+let painted = 0;
+
+const socket = new WebSocket(location.href.replace(/^http/, 'ws'));
+socket.binaryType = 'arraybuffer';
+
+const send = (message: Json) => {
+  if (socket.readyState === WebSocket.OPEN) socket.send(JSON.stringify(message));
+};
+
+// --- terminal ---------------------------------------------------------------
+
+const terminal = new Terminal({
+  convertEol: false,
+  cursorBlink: true,
+  fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
+  fontSize: 12,
+  scrollback: 5000,
+  theme: {
+    background: '#0d0f13',
+    foreground: '#d6dae3',
+    cursor: '#7ee2a8',
+    selectionBackground: '#2f4a7a',
+  },
+});
+const fitAddon = new FitAddon();
+terminal.loadAddon(fitAddon);
+
+let terminalOpened = false;
+let terminalAttached = false;
+
+function openTerminal(open: boolean): void {
+  termPane.classList.toggle('open', open);
+  termBtn.setAttribute('aria-pressed', String(open));
+  if (!open) return;
+
+  if (!terminalOpened) {
+    terminalOpened = true;
+    terminal.open(termHost);
+    // Keystrokes go straight to the shell, so the terminal behaves like a
+    // terminal: Ctrl-C interrupts, arrows reach the shell's own history.
+    terminal.onData((data) => {
+      if (!control) {
+        terminal.write('\r\n\x1b[33m[take control first — the terminal types on the remote machine]\x1b[m\r\n');
+        return;
+      }
+      send({ type: 'shell-input', text: data });
+    });
+  }
+
+  // Two frames, because the pane has only just been given a size and the
+  // first frame measures the layout it had before that. Fitting too early
+  // computes one column, and a shell told it has one column wraps every line
+  // of its output into a vertical ribbon.
+  requestAnimationFrame(() => requestAnimationFrame(() => {
+    fitAddon.fit();
+    reportSize();
+    if (!terminalAttached) {
+      terminalAttached = true;
+      send({ type: 'shell-attach' });
+    }
+    terminal.focus();
+  }));
+}
+
+/**
+ * Tell the shell how wide its terminal is -- but never a size that cannot be
+ * real. A bad measurement is worse than a stale one: the shell reflows its
+ * output to whatever it is told.
+ */
+function reportSize(): void {
+  if (terminal.cols < 20 || terminal.rows < 5) return;
+  send({ type: 'shell-resize', columns: terminal.cols, rows: terminal.rows });
+}
+
+new ResizeObserver(() => {
+  if (!terminalOpened || !termPane.classList.contains('open')) return;
+  fitAddon.fit();
+  reportSize();
+}).observe(termPane);
+
+termBtn.addEventListener('click', () => openTerminal(termBtn.getAttribute('aria-pressed') !== 'true'));
+
+// --- the desktop ------------------------------------------------------------
+
+socket.addEventListener('open', () => {
+  stateEl.textContent = 'live';
+  stateEl.className = 'pill live';
+});
+
+socket.addEventListener('close', () => {
+  stateEl.textContent = 'disconnected';
+  stateEl.className = 'pill dead';
+  terminal.write('\r\n\x1b[31m[the session ended]\x1b[m\r\n');
+});
+
+socket.addEventListener('message', async (event) => {
+  if (typeof event.data !== 'string') {
+    await paint(new Uint8Array(event.data as ArrayBuffer));
+    return;
+  }
+
+  const message: Json = JSON.parse(event.data);
+  switch (message.type) {
+    case 'hello':
+    case 'resize':
+      resize(message);
+      if (message.host) hostEl.textContent = message.host;
+      break;
+    case 'control':
+      setControl(Boolean(message.on));
+      break;
+    case 'shell-data':
+      terminal.write(Uint8Array.from(atob(message.base64), (c) => c.charCodeAt(0)));
+      break;
+    case 'shell-status':
+      if (message.state === 'opening') terminal.write('\x1b[90m[opening a shell…]\x1b[m\r\n');
+      break;
+    case 'shell-error':
+      terminal.write(`\r\n\x1b[31m[${message.message}]\x1b[m\r\n`);
+      break;
+    default:
+      break;
+  }
+});
+
+function resize({ width, height }: Json): void {
+  if (!width || !height) return;
+  canvas.width = width;
+  canvas.height = height;
+  sizeEl.textContent = `${width}×${height}`;
+}
+
+/** Inflate with the platform's own decompressor; no library involved. */
+async function inflate(bytes: Uint8Array): Promise<Uint8Array> {
+  const stream = new Blob([bytes as BlobPart]).stream()
+    .pipeThrough(new DecompressionStream('deflate'));
+  return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+
+async function paint(frame: Uint8Array): Promise<void> {
+  const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+  const left = view.getUint16(1, true);
+  const top = view.getUint16(3, true);
+  const width = view.getUint16(5, true);
+  const height = view.getUint16(7, true);
+
+  const rgba = await inflate(frame.subarray(9));
+  if (rgba.length < width * height * 4) return;
+
+  // The buffer came from a DecompressionStream, so it is a plain ArrayBuffer;
+  // the cast is only needed because a Uint8Array may in general be backed by a
+  // SharedArrayBuffer, which ImageData does not accept.
+  const pixels = new Uint8ClampedArray(rgba.buffer as ArrayBuffer, 0, width * height * 4);
+  context.putImageData(new ImageData(pixels, width, height), left, top);
+
+  if (++painted === 1) canvas.focus();
+}
+
+// --- input ------------------------------------------------------------------
+//
+// Positions are in desktop pixels. The canvas may be scaled to fit, so every
+// pointer event is mapped back through the element's real size.
+
+function at(event: MouseEvent): { x: number; y: number } {
+  const box = canvas.getBoundingClientRect();
+  return {
+    x: Math.round((event.clientX - box.left) * (canvas.width / box.width)),
+    y: Math.round((event.clientY - box.top) * (canvas.height / box.height)),
+  };
+}
+
+const desktop = (message: Json) => { if (control) send(message); };
+
+canvas.addEventListener('mousemove', (e) => desktop({ type: 'move', ...at(e) }));
+canvas.addEventListener('mousedown', (e) => {
+  e.preventDefault();
+  canvas.focus();
+  desktop({ type: 'button', ...at(e), button: e.button, pressed: true });
+});
+canvas.addEventListener('mouseup', (e) => {
+  e.preventDefault();
+  desktop({ type: 'button', ...at(e), button: e.button, pressed: false });
+});
+canvas.addEventListener('contextmenu', (e) => e.preventDefault());
+canvas.addEventListener('wheel', (e) => {
+  e.preventDefault();
+  desktop({ type: 'scroll', ...at(e), dx: Math.sign(e.deltaX), dy: Math.sign(e.deltaY) });
+}, { passive: false });
+
+canvas.addEventListener('keydown', (e) => {
+  if (!control) return;
+  e.preventDefault();
+  desktop({ type: 'key', code: e.code, pressed: true });
+});
+canvas.addEventListener('keyup', (e) => {
+  if (!control) return;
+  e.preventDefault();
+  desktop({ type: 'key', code: e.code, pressed: false });
+});
+
+// --- fullscreen -------------------------------------------------------------
+//
+// What a remote-desktop client does with the key: the desktop takes the whole
+// display, the page chrome gets out of the way, and keystrokes go to the host
+// rather than to the browser. Fit is forced on while it lasts, because a 1:1
+// desktop larger than the screen would otherwise be a fullscreen scrollbar.
+
+let fitBeforeFullscreen = true;
+
+async function toggleFullscreen(): Promise<void> {
+  if (document.fullscreenElement) {
+    await document.exitFullscreen().catch(() => {});
+    return;
+  }
+  fitBeforeFullscreen = fitBtn.getAttribute('aria-pressed') === 'true';
+  await document.documentElement.requestFullscreen({ navigationUI: 'hide' }).catch(() => {});
+}
+
+document.addEventListener('fullscreenchange', () => {
+  const on = Boolean(document.fullscreenElement);
+  document.body.classList.toggle('fullscreen', on);
+  fsBtn.setAttribute('aria-pressed', String(on));
+  setFit(on ? true : fitBeforeFullscreen);
+  if (!termPane.classList.contains('open')) canvas.focus();
+});
+
+fsBtn.addEventListener('click', () => void toggleFullscreen());
+
+/**
+ * F11 belongs to the host once it has the keyboard, so fullscreen is on a
+ * chord the remote desktop has no use for. Escape leaves, which is what every
+ * fullscreen surface does anyway.
+ */
+window.addEventListener('keydown', (event) => {
+  if (event.key === 'F11' && !control) { event.preventDefault(); void toggleFullscreen(); }
+  if (event.shiftKey && event.ctrlKey && event.code === 'KeyF') {
+    event.preventDefault();
+    void toggleFullscreen();
+  }
+}, true);
+
+// --- controls ---------------------------------------------------------------
+
+function setFit(on: boolean): void {
+  fitBtn.setAttribute('aria-pressed', String(on));
+  canvas.classList.toggle('fit', on);
+}
+
+fitBtn.addEventListener('click', () => setFit(fitBtn.getAttribute('aria-pressed') !== 'true'));
+
+// Ask; the server decides. The button reflects what came back, so it can never
+// claim control the session has not actually granted.
+ctlBtn.addEventListener('click', () => send({ type: 'control', on: !control }));
+
+function setControl(on: boolean): void {
+  control = on;
+  ctlBtn.setAttribute('aria-pressed', String(on));
+  ctlBtn.textContent = on ? 'Release control' : 'Take control';
+  hintEl.textContent = on
+    ? 'You have control. Keyboard and pointer go to the remote machine.'
+    : 'Watching. The agent is driving — press “Take control” to send input yourself.';
+  if (on && !termPane.classList.contains('open')) canvas.focus();
+}
+
+$('cad').addEventListener('click', () => {
+  if (!control) { hintEl.textContent = 'Take control first — Ctrl+Alt+Del is input like any other.'; return; }
+  send({ type: 'cad' });
+});

package/src/cli/viewer-page.ts

@@ -0,0 +1,102 @@
+/**
+ * The viewer page.
+ *
+ * The markup and its styling live here; the behaviour is a real bundle, built
+ * from src/cli/viewer-client and inlined at build time. A published CLI has no
+ * asset directory it can rely on being unpacked beside it, so both arrive as
+ * strings.
+ */
+
+import { VIEWER_CSS, VIEWER_JS } from './generated/viewer-bundle';
+
+export const PAGE = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>ai-remote viewer</title>
+<style>
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; height: 100vh; display: flex; flex-direction: column;
+    background: #12141a; color: #e6e8ee;
+    font: 13px/1.5 ui-sans-serif, -apple-system, "Segoe UI", system-ui, sans-serif;
+  }
+  header {
+    display: flex; align-items: center; gap: 12px; flex-wrap: wrap;
+    padding: 8px 12px; background: #181b21; border-bottom: 1px solid #262b34;
+  }
+  header .title { font-weight: 600; }
+  header .spacer { flex: 1; }
+  .pill {
+    padding: 2px 8px; border-radius: 999px; background: #22272f;
+    border: 1px solid #2f353f; font-variant-numeric: tabular-nums; font-size: 12px;
+  }
+  .pill.live { color: #7ee2a8; border-color: #2c5540; }
+  .pill.dead { color: #ff9b9b; border-color: #5c3131; }
+  button {
+    font: inherit; color: inherit; background: #22272f; cursor: pointer;
+    border: 1px solid #2f353f; border-radius: 6px; padding: 4px 10px;
+  }
+  button:hover { background: #2c323c; }
+  button[aria-pressed="true"] { background: #2f4a7a; border-color: #3f63a4; }
+  .body { flex: 1; min-height: 0; display: flex; flex-direction: column; }
+  main {
+    flex: 1; min-height: 0; display: grid; place-items: center;
+    overflow: auto; padding: 12px;
+  }
+  canvas { display: block; background: #000; box-shadow: 0 10px 30px rgba(0,0,0,.8); outline: none; }
+  canvas.fit { max-width: 100%; max-height: 100%; object-fit: contain; }
+  #terminal {
+    display: none; min-height: 0; height: 40%;
+    border-top: 1px solid #262b34; background: #0d0f13; padding: 6px 8px 2px;
+  }
+  #terminal.open { display: block; }
+  #termHost { height: 100%; }
+  footer { padding: 6px 12px; background: #181b21; border-top: 1px solid #262b34; color: #97a0b0; }
+
+  /* Fullscreen: the desktop, and nothing else. The header stays reachable by
+     moving the pointer to the top edge, so control and the terminal are not
+     lost behind a keystroke nobody can guess. */
+  body.fullscreen { background: #000; }
+  body.fullscreen main { padding: 0; }
+  body.fullscreen footer { display: none; }
+  body.fullscreen canvas { box-shadow: none; }
+  body.fullscreen header {
+    position: fixed; inset: 0 0 auto 0; z-index: 10;
+    background: rgba(24, 27, 33, .94); border-bottom-color: rgba(38, 43, 52, .9);
+    transform: translateY(-100%); transition: transform .18s ease;
+  }
+  body.fullscreen header:hover,
+  body.fullscreen header:focus-within { transform: none; }
+  body.fullscreen::before {
+    content: ''; position: fixed; inset: 0 0 auto 0; height: 8px; z-index: 9;
+  }
+  body.fullscreen:has(header:hover)::before { height: 0; }
+${VIEWER_CSS}
+</style>
+</head>
+<body>
+<header>
+  <span class="title">ai-remote</span>
+  <span class="pill" id="host">—</span>
+  <span class="pill" id="size">—</span>
+  <span class="pill" id="state">connecting…</span>
+  <span class="spacer"></span>
+  <button id="fit" aria-pressed="true">Fit</button>
+  <button id="full" aria-pressed="false" title="Fullscreen (Ctrl+Shift+F, Escape to leave)">Fullscreen</button>
+  <button id="control" aria-pressed="false" title="While off, you watch without sending input">Take control</button>
+  <button id="term" aria-pressed="false">Terminal</button>
+  <button id="cad">Ctrl+Alt+Del</button>
+</header>
+<div class="body">
+  <main><canvas id="screen" class="fit" tabindex="0"></canvas></main>
+  <section id="terminal"><div id="termHost"></div></section>
+</div>
+<footer id="hint">Watching. The agent is driving — press “Take control” to send input yourself.</footer>
+<script type="module">
+${VIEWER_JS}
+</script>
+</body>
+</html>`;