ai-remote 0.1.0 → 0.3.0

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "ai-remote",
-  "version": "0.1.0",
-  "description": "Pure TypeScript protocol engines (RDP, VNC, SSH) and remote desktop vocabulary for AI agents, Node.js, and web browsers",
+  "version": "0.3.0",
+  "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": {
+    "ai-remote": "./dist/cli.mjs",
+    "remotectl": "./dist/cli.mjs"
+  },
   "license": "MIT",
   "author": {
     "name": "Leon Guo",
@@ -21,7 +25,10 @@
     "ai-agent",
     "remote-control",
     "novnc",
-    "xterm"
+    "xterm",
+    "cli",
+    "npx",
+    "agent"
   ],
   "main": "./dist/index.js",
   "types": "./src/index.ts",
@@ -78,5 +85,8 @@
     "@xterm/xterm": "^6.0.0",
     "esbuild": "^0.28.2",
     "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=22"
   }
 }

package/src/cli/cli.ts

@@ -0,0 +1,451 @@
+/**
+ * ai-remote -- drive a remote machine from the command line.
+ *
+ * Connects straight to the host over TCP: no gateway in the path, and no
+ * browser in the path either. The first command opens a session that stays
+ * open; the ones after it attach to that same session, so a click and the
+ * screenshot of what the click did are part of one conversation with the host.
+ */
+
+import { basename, resolve as resolvePath } from 'node:path';
+import { spawn } from 'node:child_process';
+import { readFileSync, readdirSync, existsSync, openSync, unlinkSync } from 'node:fs';
+import { Shell } from './shell';
+import { runDaemon } from './daemon';
+import { request } from './ipc';
+import { ensureRunDir, logPath, metaPath, RUN_DIR, sessionName, socketPath } from './paths';
+
+/** The tail of a session's log, for when it did not start. */
+function readLog(name: string): string {
+  try {
+    return readFileSync(logPath(name), 'utf8')
+      .split('\n')
+      .filter((line) => line.trim() && !/^\s/.test(line) && !line.startsWith('[RDP] '))
+      .slice(-4)
+      .join('\n');
+  } catch { return ''; }
+}
+
+/**
+ * Whichever name this was invoked by. The package installs two -- `ai-remote`
+ * to match itself, so `npx ai-remote` works, and `remotectl` because it is the
+ * better thing to type once it is on a PATH -- and help that names the other
+ * one sends people to a command they did not run.
+ */
+const NAME = (() => {
+  const invoked = basename(process.argv[1] ?? '').replace(/\.mjs$/, '');
+  return invoked === 'ai-remote' || invoked === 'remotectl' ? invoked : 'ai-remote';
+})();
+
+const USAGE = `${NAME} -- drive a remote desktop, with a window you can watch
+
+  ${NAME} open   <host[:port]>          connect, show a window, and stay open
+  ${NAME} shot   <host[:port]>          screenshot the desktop
+  ${NAME} click  <host[:port]> X,Y      click, --button right|middle, --double
+  ${NAME} type   <host[:port]> "text"   type into whatever has focus
+  ${NAME} key    <host[:port]> <Code>   press keys, e.g. MetaLeft, ControlLeft+KeyA
+  ${NAME} exec   <host[:port]> "cmd"    run a command in the terminal (SSH)
+  ${NAME} shell  <host[:port]>          an interactive terminal
+  ${NAME} do     <host[:port]> "steps"  several actions in one go
+  ${NAME} view   <host[:port]>          open the window on a running session
+  ${NAME} view   <host[:port]> --close   close the window, session keeps running
+  ${NAME} status | list | close [<host>]
+  ${NAME} probe  <host[:port]>          is anything listening?
+
+Steps for "do", separated by semicolons:
+  move X,Y · click X,Y[,right|middle] · dblclick X,Y · scroll X,Y,DX,DY
+  type TEXT · key Code[+Code...] · cad · wait MS · shot FILE
+
+Options
+  -u, --user NAME        account on the host
+  -d, --domain NAME      Windows domain or computer name
+      --ssh-user NAME    account for the terminal (default: --user)
+      --ssh-port N       SSH port                      (default: 22)
+  -s, --security MODE    auto | nla | tls | rdp        (default: auto)
+  -W, --width  N         desktop width                 (default: 1280)
+  -H, --height N         desktop height                (default: 800)
+  -o, --out FILE         where a screenshot goes       (default: screen.png)
+      --max-edge N       shrink a screenshot to fit N
+      --view-port N      port for the window           (default: 7373)
+      --idle MINUTES     close an unused session       (default: 0, never)
+      --headless         no window (same as --no-view)
+      --no-view          no window
+      --no-open          window, but do not launch a browser
+      --no-reuse         a fresh session, ignoring any that is already open
+      --json             machine-readable result on stdout
+
+The password comes from AI_REMOTE_PASSWORD (or REMOTECTL_PASSWORD). There is no
+--password flag: a command line is visible to every process on the machine.
+
+Exit codes: 0 ok · 10 unreachable · 11 auth rejected · 12 bad usage · 13 timeout
+`;
+
+interface Args {
+  command: string;
+  target: string;
+  rest: string[];
+  flags: Record<string, string | boolean>;
+}
+
+const VALUE_FLAGS = new Set([
+  'u', 'user', 'd', 'domain', 's', 'security', 'W', 'width', 'H', 'height',
+  'o', 'out', 'at', 'button', 'max-edge', 'view-port', 'idle', 'name',
+  'ssh-user', 'ssh-port', 'settle',
+]);
+
+function parse(argv: string[]): Args {
+  const flags: Record<string, string | boolean> = {};
+  const positional: string[] = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (!token.startsWith('-') || token === '-') { positional.push(token); continue; }
+    const name = token.replace(/^--?/, '');
+    if (VALUE_FLAGS.has(name)) flags[name] = argv[++i] ?? '';
+    else flags[name] = true;
+  }
+
+  return { command: positional[0] ?? '', target: positional[1] ?? '', rest: positional.slice(2), flags };
+}
+
+const flag = (args: Args, ...names: string[]): string | undefined => {
+  for (const name of names) if (typeof args.flags[name] === 'string') return args.flags[name] as string;
+  return undefined;
+};
+const has = (args: Args, ...names: string[]) => names.some((name) => args.flags[name] === true);
+
+function splitTarget(target: string, fallbackPort: number) {
+  const stripped = target.replace(/^\w+:\/\//, '');
+  const [host, port] = stripped.split(':');
+  return { host, port: port ? Number(port) : fallbackPort };
+}
+
+class CliError extends Error {
+  constructor(message: string, readonly code: number) { super(message); }
+}
+
+const password = () => process.env.AI_REMOTE_PASSWORD ?? process.env.REMOTECTL_PASSWORD ?? '';
+
+// --- session lookup ---------------------------------------------------------
+
+interface Meta { name: string; host: string; port: number; pid: number; viewer: string | null; width: number; height: number; startedAt: string }
+
+function liveSessions(): Meta[] {
+  ensureRunDir();
+  return readdirSync(RUN_DIR)
+    .filter((file) => file.endsWith('.json'))
+    .flatMap((file) => {
+      try {
+        const meta = JSON.parse(readFileSync(`${RUN_DIR}/${file}`, 'utf8')) as Meta;
+        // A metadata file outliving its process means the daemon was killed.
+        try { process.kill(meta.pid, 0); } catch { cleanup(meta.name); return []; }
+        return [meta];
+      } catch { return []; }
+    });
+}
+
+function cleanup(name: string): void {
+  for (const file of [socketPath(name), metaPath(name), logPath(name)]) {
+    try { if (existsSync(file)) unlinkSync(file); } catch { /* already gone */ }
+  }
+}
+
+/** Ask a running session to do something, or report that there is none. */
+async function ask(name: string, op: string, args: Record<string, unknown> = {}): Promise<any> {
+  const response = await request(socketPath(name), op, args).catch((error: any) => {
+    if (error?.notRunning) return null;
+    throw error;
+  });
+  if (!response) return null;
+  if (!response.ok) throw new CliError(response.error ?? `The session refused "${op}".`, response.code ?? 1);
+  return response.result;
+}
+
+/**
+ * Start a session in the background and wait for it to answer.
+ *
+ * The daemon is this same executable: one file, so there is nothing to find on
+ * disk and nothing to keep in step with it.
+ */
+async function startSession(args: Args, name: string, host: string, port: number): Promise<any> {
+  // Rebuilt rather than forwarded. This process's own argv carries the command
+  // that triggered the start -- `shot`, `click` -- and passing it through would
+  // make the session try to run it as well as host it.
+  const daemonArgs = [
+    process.argv[1], '__session', `${host}:${port}`,
+    '--name', name,
+    '-u', flag(args, 'u', 'user') ?? '',
+    '-d', flag(args, 'd', 'domain') ?? '',
+    '-s', flag(args, 's', 'security') ?? 'auto',
+    '-W', flag(args, 'W', 'width') ?? '1280',
+    '-H', flag(args, 'H', 'height') ?? '800',
+    '--ssh-user', flag(args, 'ssh-user') ?? flag(args, 'u', 'user') ?? '',
+    '--ssh-port', flag(args, 'ssh-port') ?? '22',
+    '--view-port', flag(args, 'view-port') ?? '7373',
+    '--idle', flag(args, 'idle') ?? '30',
+  ];
+  if (has(args, 'no-view', 'headless')) daemonArgs.push('--no-view');
+  if (has(args, 'no-open')) daemonArgs.push('--no-open');
+
+  // Its output goes to a file rather than nowhere: a session that fails to
+  // start is the one moment its log is worth having.
+  ensureRunDir();
+  const log = openSync(logPath(name), 'a');
+
+  const child = spawn(process.execPath, daemonArgs, {
+    detached: true,
+    stdio: ['ignore', log, log],
+    env: { ...process.env, AI_REMOTE_PASSWORD: password() },
+  });
+  child.unref();
+
+  const deadline = Date.now() + 45_000;
+  while (Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 250));
+    const status = await ask(name, 'status').catch(() => null);
+    if (status) return status;
+  }
+  const detail = readLog(name);
+  throw new CliError(
+    `The session did not come up.${detail ? `\n${detail}` : ''}`,
+    /password|credential|logon|CredSSP|auth/i.test(detail) ? 11 : 13
+  );
+}
+
+// --- entry ------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  const args = parse(process.argv.slice(2));
+  if (!args.command || has(args, 'h', 'help')) { process.stdout.write(USAGE); return; }
+
+  const json = has(args, 'json');
+
+  if (args.command === 'list' || (args.command === 'status' && !args.target)) {
+    const sessions = liveSessions();
+    if (json) { process.stdout.write(`${JSON.stringify({ sessions })}\n`); return; }
+    if (!sessions.length) { process.stdout.write('No sessions are open.\n'); return; }
+    for (const meta of sessions) {
+      process.stdout.write(`${meta.name}  ${meta.host}:${meta.port}  ${meta.width}x${meta.height}  pid ${meta.pid}`
+        + `${meta.viewer ? `  ${meta.viewer}` : ''}\n`);
+    }
+    return;
+  }
+
+  if (!args.target && args.command !== 'close') throw new CliError('Name the machine to connect to.', 12);
+
+  const { host, port } = splitTarget(args.target || '', 3389);
+  const name = sessionName(host, port, flag(args, 'name'));
+
+  if (args.command === 'close') {
+    const targets = args.target ? [name] : liveSessions().map((meta) => meta.name);
+    for (const target of targets) {
+      await ask(target, 'close').catch(() => null);
+      cleanup(target);
+      process.stdout.write(`Closed ${target}.\n`);
+    }
+    if (!targets.length) process.stdout.write('No sessions are open.\n');
+    return;
+  }
+
+  if (args.command === 'probe') {
+    const { reachable, ms, detail } = await probe(host, port);
+    if (json) process.stdout.write(`${JSON.stringify({ host, port, reachable, ms, detail })}\n`);
+    else process.stdout.write(`${host}:${port} ${reachable ? `reachable in ${ms}ms` : `unreachable — ${detail}`}\n`);
+    if (!reachable) throw new CliError(detail, 10);
+    return;
+  }
+
+  // The hidden command the background session runs as.
+  if (args.command === '__session') {
+    await runDaemon({
+      name,
+      host,
+      port,
+      username: flag(args, 'u', 'user') ?? '',
+      password: password(),
+      domain: flag(args, 'd', 'domain') ?? '',
+      width: Number(flag(args, 'W', 'width') ?? 1280),
+      height: Number(flag(args, 'H', 'height') ?? 800),
+      security: (flag(args, 's', 'security') ?? 'auto') as 'auto',
+      clientName: 'ai-remote',
+      view: !has(args, 'no-view', 'headless'),
+      launchBrowser: !has(args, 'no-open'),
+      viewPort: Number(flag(args, 'view-port') ?? 7373),
+      sshUsername: flag(args, 'ssh-user') ?? flag(args, 'u', 'user') ?? '',
+      sshPort: Number(flag(args, 'ssh-port') ?? 22),
+      // Zero by default: a session stays open until it is closed. An agent
+      // that pauses to think is not an agent that has finished.
+      idleMs: Math.max(0, Number(flag(args, 'idle') ?? 0)) * 60_000,
+    });
+    return;
+  }
+
+  if (args.command === 'shell') { await interactiveShell(args, host); return; }
+
+  // Everything else runs against a session: the one already open, or a new one.
+  let status = has(args, 'no-reuse') ? null : await ask(name, 'status');
+  const reused = Boolean(status);
+  if (!status) status = await startSession(args, name, host, port);
+
+  const report: Record<string, unknown> = { host, port, name, reused, width: status.width, height: status.height };
+
+  switch (args.command) {
+    case 'open':
+      // A session that was started headless can be given a window later, and
+      // asking to open one that is already open just re-pops it.
+      if (!has(args, 'no-view', 'headless') && !status.viewer) {
+        Object.assign(status, await ask(name, 'view-open', { launch: !has(args, 'no-open') }));
+      }
+      Object.assign(report, { viewer: status.viewer });
+      break;
+
+    case 'view': {
+      if (has(args, 'close')) {
+        const { closed } = await ask(name, 'view-close');
+        Object.assign(report, { viewer: null, closed });
+        break;
+      }
+      Object.assign(report, await ask(name, 'view-open', { launch: !has(args, 'no-open') }));
+      break;
+    }
+
+    case 'shot': {
+      const file = resolvePath(flag(args, 'o', 'out') ?? 'screen.png');
+      const maxEdge = Number(flag(args, 'max-edge') ?? 0);
+      Object.assign(report, await ask(name, 'shot', { file, maxEdge }));
+      break;
+    }
+
+    case 'click': {
+      const spec = flag(args, 'at') ?? args.rest[0];
+      if (!spec) throw new CliError('click needs a position, e.g. `click 192.168.1.5 640,400`', 12);
+      const [x, y] = spec.split(',').map(Number);
+      const button = flag(args, 'button') ?? 'left';
+      const step = `click ${x},${y}${button === 'left' ? '' : `,${button}`}`;
+      await ask(name, 'script', { script: has(args, 'double') ? `${step}; ${step}` : step });
+      Object.assign(report, { clicked: { x, y, button } });
+      break;
+    }
+
+    case 'type': {
+      const text = args.rest.join(' ');
+      if (!text) throw new CliError('type needs some text', 12);
+      await ask(name, 'script', { script: `type ${text}` });
+      Object.assign(report, { typed: text.length });
+      break;
+    }
+
+    case 'key': {
+      if (!args.rest.length) throw new CliError('key needs at least one code, e.g. MetaLeft', 12);
+      await ask(name, 'script', { script: args.rest.map((code) => `key ${code}`).join('; ') });
+      Object.assign(report, { keys: args.rest });
+      break;
+    }
+
+    case 'do': {
+      const script = args.rest.join(' ');
+      if (!script) throw new CliError('do needs a script, e.g. "key MetaLeft; wait 800; shot s.png"', 12);
+      Object.assign(report, await ask(name, 'script', { script }));
+      break;
+    }
+
+    case 'exec': {
+      const command = args.rest.join(' ');
+      if (!command) throw new CliError('exec needs a command to run', 12);
+      const result = await ask(name, 'exec', { command });
+      Object.assign(report, result);
+      if (!json) {
+        process.stdout.write(result.output.endsWith('\n') ? result.output : `${result.output}\n`);
+        if (result.exitStatus) process.stderr.write(`exit ${result.exitStatus}\n`);
+      }
+      if (json) process.stdout.write(`${JSON.stringify({ ok: result.exitStatus === 0, ...report })}\n`);
+      process.exit(result.exitStatus === 0 ? 0 : 1);
+      return;
+    }
+
+    default:
+      throw new CliError(`Unknown command "${args.command}".`, 12);
+  }
+
+  if (json) process.stdout.write(`${JSON.stringify({ ok: true, ...report })}\n`);
+  else process.stdout.write(`${describe(args.command, report)}\n`);
+}
+
+/** A terminal on the host, attached to this process's own stdin and stdout. */
+async function interactiveShell(args: Args, host: string): Promise<void> {
+  const shell = new Shell({
+    host,
+    port: Number(flag(args, 'ssh-port') ?? 22),
+    username: flag(args, 'ssh-user') ?? flag(args, 'u', 'user') ?? '',
+    password: password(),
+    columns: process.stdout.columns ?? 120,
+    rows: process.stdout.rows ?? 30,
+  });
+
+  await shell.connect().catch((error: Error) => {
+    throw new CliError(error.message, /password|auth|denied/i.test(error.message) ? 11 : 10);
+  });
+
+  shell.onData((bytes) => process.stdout.write(bytes));
+
+  if (process.stdin.isTTY) process.stdin.setRawMode(true);
+  process.stdin.resume();
+  process.stdin.on('data', (chunk) => {
+    // Ctrl-] leaves, the way telnet has always done it, so Ctrl-C stays
+    // available to the program running on the far side.
+    if (chunk.length === 1 && chunk[0] === 0x1d) { shell.disconnect(); process.exit(0); }
+    shell.write(chunk.toString('utf8'));
+  });
+
+  process.stdout.on('resize', () => shell.resize(process.stdout.columns ?? 120, process.stdout.rows ?? 30));
+  process.stderr.write('[connected — Ctrl-] to leave]\r\n');
+  await new Promise(() => {});
+}
+
+async function probe(host: string, port: number) {
+  const net = await import('node:net');
+  const started = Date.now();
+  return new Promise<{ reachable: boolean; ms: number; detail: string }>((resolve) => {
+    const socket = net.connect({ host, port });
+    const done = (reachable: boolean, detail: string) => {
+      socket.destroy();
+      resolve({ reachable, ms: Date.now() - started, detail });
+    };
+    socket.setTimeout(5000);
+    socket.on('connect', () => done(true, 'the port accepted a connection'));
+    socket.on('timeout', () => done(false, 'the connection attempt timed out'));
+    socket.on('error', (error: Error) => done(false, error.message));
+  });
+}
+
+function describe(command: string, report: Record<string, unknown>): string {
+  const size = `${report.width}x${report.height}`;
+  const where = report.reused ? 'the open session' : 'a new session';
+
+  if (command === 'open') {
+    return `${report.reused ? 'Already connected' : 'Connected'} to ${report.host}:${report.port} at ${size}.`
+      + `${report.viewer ? `\nWindow: ${report.viewer}` : ''}`
+      + `\nRun more commands against it, then \`${NAME} close ${report.host}\` when you are done.`;
+  }
+  if (command === 'view') {
+    if (report.viewer) return `Window: ${report.viewer}`;
+    return report.closed
+      ? 'Closed the window. The session is still open.'
+      : 'There was no window open.';
+  }
+  if (command === 'shot') return `Wrote ${report.file} (${report.width}x${report.height}) from ${where}.`;
+  if (command === 'click') {
+    const { x, y } = report.clicked as { x: number; y: number };
+    return `Clicked (${x}, ${y}) on a ${size} desktop.`;
+  }
+  if (command === 'type') return `Typed ${report.typed} characters.`;
+  if (command === 'key') return `Pressed ${(report.keys as string[]).join(', ')}.`;
+  if (command === 'do') return `Ran ${(report.steps as string[]).length} steps: ${(report.steps as string[]).join(' → ')}`;
+  return 'Done.';
+}
+
+main().catch((error: unknown) => {
+  const code = error instanceof CliError ? error.code : 1;
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(code);
+});