ai-remote 0.3.0 → 0.3.1

package/README.md

@@ -1,32 +1,62 @@
 # ai-remote
 
-> Pure TypeScript protocol engines (RDP, VNC, SSH) and remote desktop vocabulary for AI agents, Node.js, and web browsers.
+> Pure TypeScript protocol engines (RDP, VNC, SSH) for Node.js, Cloudflare Workers, and web browsers — plus `npx ai-remote`, a CLI that drives a remote desktop and shows you what it is doing.
 
 [![npm version](https://img.shields.io/npm/v/ai-remote.svg)](https://www.npmjs.com/package/ai-remote)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-## Overview
+## 🚀 Quick Start (CLI)
 
-`ai-remote` is an environment-neutral core protocol library providing client-side implementations for **RDP**, **VNC**, and **SSH**. It powers browser-based remote gateways, terminal sessions, and automated AI agents driving remote desktops.
+Run immediately with `npx` (zero install):
 
-## Features
+```bash
+# Connect and open a live supervision window:
+AI_REMOTE_PASSWORD=secret npx ai-remote open 192.168.1.50 -u Administrator
 
-- **RDP Engine:**
-  - Complete X.224, MCS, and GCC capability negotiation.
-  - CredSSP v6 with NTLMv2 and TLS 1.2 client implementation over WebCrypto.
-  - Fast-path 16-bit interleaved RLE bitmap decoding.
-  - Shared clipboard support (`cliprdr` virtual channel).
-  - RemoteApp (RAIL) window orders and execution.
-- **SSH Engine:**
-  - RFC 4253 binary packet protocol with `curve25519-sha256` / `ecdh-sha2-nistp256`.
-  - AEAD ciphers (`aes256-gcm@openssh.com`, `aes128-gcm@openssh.com`).
-  - Terminal interactive and agent command execution.
-- **VNC Engine:**
-  - RFB protocol integration with Apple Diffie-Hellman handshake support.
-- **AI Agent Tool Vocabulary:**
-  - Standardized connection, device, protocol, and signal definitions.
+# Take a screenshot:
+AI_REMOTE_PASSWORD=secret npx ai-remote shot 192.168.1.50 -u Administrator -o screen.png
+
+# Click or type on the remote desktop:
+npx ai-remote click 192.168.1.50 500,300
+npx ai-remote type 192.168.1.50 "notepad"
+npx ai-remote key 192.168.1.50 Enter
+
+# Run commands in the remote terminal over SSH:
+npx ai-remote exec 192.168.1.50 "dir"
+```
+
+### CLI Commands
+
+```
+  ai-remote open   <host[:port]>          connect, show a window, and stay open
+  ai-remote shot   <host[:port]>          screenshot the desktop
+  ai-remote click  <host[:port]> X,Y      click, --button right|middle, --double
+  ai-remote type   <host[:port]> "text"   type into whatever has focus
+  ai-remote key    <host[:port]> <Code>   press keys, e.g. MetaLeft, ControlLeft+KeyA
+  ai-remote exec   <host[:port]> "cmd"    run a command in the terminal (SSH)
+  ai-remote shell  <host[:port]>          an interactive terminal
+  ai-remote do     <host[:port]> "steps"  several actions in one go
+  ai-remote view   <host[:port]>          open the window on a running session
+  ai-remote view   <host[:port]> --close  close the window, session keeps running
+  ai-remote status | list | close [<host>]
+  ai-remote probe  <host[:port]>          is anything listening?
+```
+
+### Common Options
+
+- `-u, --user NAME`: Account name on the host.
+- `-d, --domain NAME`: Windows domain or computer name.
+- `--ssh-user NAME`: Account for the SSH terminal (defaults to `--user`).
+- `--ssh-port N`: SSH port (default: 22).
+- `-s, --security MODE`: `auto` | `nla` | `tls` | `rdp` (default: `auto`).
+- `-W, --width N` / `-H, --height N`: Desktop resolution (default: 1280x800).
+- `-o, --out FILE`: Screenshot output file path (default: `screen.png`).
+- `--headless` / `--no-view`: Run headless without opening the viewer window.
+- `--json`: Output machine-readable JSON results on stdout.
+
+---
 
-## Installation
+## 📦 Library Installation
 
 ```bash
 pnpm add ai-remote
@@ -34,7 +64,7 @@ pnpm add ai-remote
 npm install ai-remote
 ```
 
-## Subpath Exports
+### Subpath Exports
 
 | Export | Description |
 |---|---|
@@ -45,6 +75,25 @@ npm install ai-remote
 | `ai-remote/protocols/vnc` | VNC session and input management |
 | `ai-remote/shared/*` | Direct access to shared models and utilities |
 
+---
+
+## ✨ Features
+
+- **RDP Protocol Engine:**
+  - Full X.224, MCS, and GCC capability negotiation.
+  - CredSSP v6 with NTLMv2 and TLS 1.2 client implementation over WebCrypto.
+  - Fast-path 16-bit interleaved RLE bitmap decoding.
+  - Shared clipboard support (`cliprdr` virtual channel).
+  - RemoteApp (RAIL) window orders and execution.
+- **SSH Engine:**
+  - RFC 4253 binary packet protocol with `curve25519-sha256` / `ecdh-sha2-nistp256`.
+  - AEAD ciphers (`aes256-gcm@openssh.com`, `aes128-gcm@openssh.com`).
+  - Terminal interactive and automated agent command execution.
+- **VNC Engine:**
+  - RFB protocol integration with Apple Diffie-Hellman handshake support.
+- **AI Agent Automation:**
+  - Fast headless actions, structured screen capture, and auto-attached SSH shells.
+
 ## License
 
 MIT © Leon Guo

package/dist/cli.mjs

@@ -1631,6 +1631,10 @@ var TcpTransport = class extends EventTarget {
 };
 
 // src/cli/shell.ts
+function bareUsername(username) {
+  const withoutDomain = username.includes("\\") ? username.split("\\").pop() : username;
+  return withoutDomain.split("@")[0].trim();
+}
 var Shell = class {
   options;
   session;
@@ -7194,7 +7198,10 @@ async function startViewer(session, port, { launch = true, openShell } = {}) {
   const detachShell = /* @__PURE__ */ new Map();
   async function attachShell(peer) {
     if (!openShell) {
-      peer.send(JSON.stringify({ type: "shell-error", message: "This session was started without a terminal. Restart it with --ssh-user NAME." }));
+      peer.send(JSON.stringify({
+        type: "shell-error",
+        message: "This session has no terminal available."
+      }));
       return;
     }
     if (detachShell.has(peer)) return;
@@ -7441,7 +7448,7 @@ async function runDaemon(options) {
       const started = new Shell({
         host: options.host,
         port: options.sshPort,
-        username: options.sshUsername || options.username,
+        username: options.sshUsername || bareUsername(options.username),
         password: options.password
       });
       await started.connect();
@@ -7681,7 +7688,8 @@ Steps for "do", separated by semicolons:
 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-user NAME    only if the terminal signs in as someone else;
+                         by default it reuses --user and the same password
       --ssh-port N       SSH port                      (default: 22)
   -s, --security MODE    auto | nla | tls | rdp        (default: auto)
   -W, --width  N         desktop width                 (default: 1280)
@@ -7997,7 +8005,7 @@ async function interactiveShell(args, host) {
   const shell = new Shell({
     host,
     port: Number(flag(args, "ssh-port") ?? 22),
-    username: flag(args, "ssh-user") ?? flag(args, "u", "user") ?? "",
+    username: flag(args, "ssh-user") ?? bareUsername(flag(args, "u", "user") ?? ""),
     password: password(),
     columns: process.stdout.columns ?? 120,
     rows: process.stdout.rows ?? 30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-remote",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "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": {

package/src/cli/cli.ts

@@ -10,7 +10,7 @@
 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 { bareUsername, Shell } from './shell';
 import { runDaemon } from './daemon';
 import { request } from './ipc';
 import { ensureRunDir, logPath, metaPath, RUN_DIR, sessionName, socketPath } from './paths';
@@ -59,7 +59,8 @@ Steps for "do", separated by semicolons:
 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-user NAME    only if the terminal signs in as someone else;
+                         by default it reuses --user and the same password
       --ssh-port N       SSH port                      (default: 22)
   -s, --security MODE    auto | nla | tls | rdp        (default: auto)
   -W, --width  N         desktop width                 (default: 1280)
@@ -376,7 +377,7 @@ 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') ?? '',
+    username: flag(args, 'ssh-user') ?? bareUsername(flag(args, 'u', 'user') ?? ''),
     password: password(),
     columns: process.stdout.columns ?? 120,
     rows: process.stdout.rows ?? 30,

package/src/cli/daemon.ts

@@ -13,7 +13,7 @@
 import net from 'node:net';
 import { unlinkSync, writeFileSync, existsSync } from 'node:fs';
 import { RdpSession, type SessionOptions } from './session';
-import { Shell } from './shell';
+import { bareUsername, Shell } from './shell';
 import { downscale, encodePng } from './png';
 import { startViewer, type Viewer } from './viewer';
 import { readMessages, writeMessage, type Request } from './ipc';
@@ -43,6 +43,10 @@ export async function runDaemon(options: DaemonOptions): Promise<void> {
    * The terminal is opened on first use rather than at connect time. Most
    * sessions never ask for one, and a second sign-in that nobody wanted is a
    * second chance to lock an account out.
+   *
+   * It signs in as the desktop's own account and password by default. Needing a
+   * separate flag to get a terminal on the machine you are already looking at
+   * is a question with an obvious answer, so it is not asked.
    */
   function openShell(): Promise<Shell> {
     if (shell) return Promise.resolve(shell);
@@ -52,7 +56,7 @@ export async function runDaemon(options: DaemonOptions): Promise<void> {
       const started = new Shell({
         host: options.host,
         port: options.sshPort,
-        username: options.sshUsername || options.username,
+        username: options.sshUsername || bareUsername(options.username),
         password: options.password,
       });
       await started.connect();

package/src/cli/shell.ts

@@ -9,6 +9,19 @@
 import { SshSession } from '../protocols/ssh/session';
 import { TcpTransport } from './transport';
 
+/**
+ * The account name on its own.
+ *
+ * An RDP username may carry the machine or domain with it -- `DESKTOP-01\\owner`
+ * or `owner@corp` -- and SSH wants neither. The terminal defaults to the same
+ * account as the desktop, so this is what makes that default work rather than
+ * fail on a name that was perfectly good for RDP.
+ */
+export function bareUsername(username: string): string {
+  const withoutDomain = username.includes('\\') ? username.split('\\').pop()! : username;
+  return withoutDomain.split('@')[0].trim();
+}
+
 export interface ShellOptions {
   host: string;
   port: number;

package/src/cli/viewer.ts

@@ -76,7 +76,10 @@ export async function startViewer(
    */
   async function attachShell(peer: WebSocketPeer): Promise<void> {
     if (!openShell) {
-      peer.send(JSON.stringify({ type: 'shell-error', message: 'This session was started without a terminal. Restart it with --ssh-user NAME.' }));
+      peer.send(JSON.stringify({
+        type: 'shell-error',
+        message: 'This session has no terminal available.',
+      }));
       return;
     }
     if (detachShell.has(peer)) return;