ai-remote 0.4.14 → 0.4.16

package/README.md

@@ -35,6 +35,69 @@ npx ai-remote exec "systemctl status nginx"
 npx ai-remote close
 ```
 
+### What a command costs, and where the time actually goes
+
+Measured on an M4, `list` with two sessions open:
+
+| | median |
+| --- | --- |
+| Node itself, starting and doing nothing | 24 ms |
+| this CLI, run directly | 27 ms |
+| `npx he --version` -- a package with **no dependencies** | 332 ms |
+| `npx ai-remote list` | 328 ms |
+
+The third row is the one that matters. A package with nothing in it costs the
+same under `npx` as this one does, because that 300 ms is `npm exec` resolving
+the spec, revalidating a packument against the registry and spawning -- work npm
+does before the package it is running exists to it. No published version of any
+package can be faster than that row, and this one is at it.
+
+So the way to spend less of it is to invoke `npx` fewer times, not to make each
+invocation cheaper. Batch the steps:
+
+```bash
+# Four npx invocations: ~1200 ms, of which ~1200 ms is npm.
+npx ai-remote key MetaLeft
+npx ai-remote type notepad
+npx ai-remote key Enter
+npx ai-remote shot -o s.png
+
+# The same four steps, one invocation: ~305 ms.
+npx ai-remote do "key MetaLeft; wait 800; type notepad; key Enter; wait 1500; shot s.png"
+```
+
+`ai-remote shell` is the same idea for a terminal: one invocation, a session
+that stays open, and no npm between keystrokes.
+
+Run `node bench/cli.bench.mjs` in this repository to get the table above for
+your own machine -- including the no-dependency control, without which npm's
+300 ms reads like something this package could fix.
+
+### About the `npm notice run ...` lines
+
+They are npm's, not this package's. `@npmcli/run-script` writes them
+unconditionally at npm's default log level:
+
+```
+@npmcli/run-script/lib/run-script-pkg.js:53
+    log.notice('run', `${cmd.trim()} ${args?.join(' ')}`.trim())
+```
+
+There is no field in `package.json`, no `.npmrc` inside the tarball and no
+publish flag that reaches them -- they are printed before this program starts.
+Silencing them is a choice made where the command is run:
+
+```bash
+npx --silent ai-remote list           # this invocation only
+NPM_CONFIG_LOGLEVEL=error npx ...     # this shell only
+npm config set loglevel error         # this machine, all npm commands
+npm install -g ai-remote              # no npm in the path at all; use `remotectl`
+```
+
+The last one also skips the 300 ms: `remotectl list` answers in about 27 ms. It
+is a per-machine decision rather than something the package can carry, which is
+why `npx` is still what the examples here use.
+
 ### CLI Commands
 
 ```
@@ -48,11 +111,14 @@ npx ai-remote close
   ai-remote key   <Code>             press keys, e.g. MetaLeft, ControlLeft+KeyA
   ai-remote exec  "cmd"              run a command in the terminal (SSH)
   ai-remote shell                    an interactive terminal
+  ai-remote reconnect                a new terminal: fresh login, fresh PATH
+  ai-remote clipboard [on|off]       share this machine's clipboard both ways
+  ai-remote cp <src> <dst>           copy files; a remote path starts with ':'
   ai-remote do    "steps"            several actions in one go
   ai-remote view                     open the window on the session
   ai-remote view --close             close the window, session keeps running
   ai-remote status                   what the session is doing
-  ai-remote list                     every session that is open
+  ai-remote list                     every session open, and every password kept
   ai-remote saved                    machines with a password kept
   ai-remote forget [<host[:port]>]   throw one away; --all throws all
   ai-remote close                    close it; --all closes every session
@@ -75,6 +141,22 @@ npx ai-remote shot --session desk
 npx ai-remote close --all
 ```
 
+`list` answers both halves of "what can I get back to". Every open session, with
+`password saved` against the ones that have one:
+
+```
+* desk   192.168.1.50:3389  1920x1080  pid 6551  http://127.0.0.1:7373/?t=...  password saved (login keychain)
+  build  192.168.1.60:3389  1280x800   pid 6808
+
+Saved, nothing open (`ai-remote open <host>` needs no password):
+  owner@192.168.1.70:3389              login keychain    saved 2026-08-28
+```
+
+The second block is the machines with a password kept but nothing running --
+`open` on one of those needs nothing else. It reads the index beside the
+keystore rather than the keystore, so a listing never raises a keychain prompt;
+`saved` shows that block on its own.
+
 `probe` is the one command besides `open` that still takes an address, because
 it answers whether a session could be opened at all; with no address it probes
 the current session's host.
@@ -134,6 +216,113 @@ npx ai-remote exec "uname -a"
 npx ai-remote shell                                # Ctrl-] to leave
 ```
 
+### The clipboard
+
+Off by default, and turned on either from the **clipboard button in the window's
+toolbar** or from a command line:
+
+```bash
+npx ai-remote clipboard on                    # both directions, until turned off
+npx ai-remote clipboard                       # what it is doing now
+npx ai-remote open 192.168.1.50 -u owner --clipboard
+```
+
+While it is on, text copied on this machine reaches the remote clipboard and text
+copied there reaches this one. Only a desktop carries a clipboard -- RDP
+negotiates a `cliprdr` channel and VNC has cut-text in the protocol -- so a
+terminal-only session has none and the toolbar button does not appear.
+
+**The bridge is the session's, not the page's.** The obvious place to put it
+would be the viewer, using the browser's `navigator.clipboard` -- but a browser
+only grants a page the clipboard while that page is focused, and the moment
+somebody wants the remote clipboard is exactly the moment they have clicked away
+into a local application to paste it. So the session does the copying, on this
+machine, whether or not a window is open; the toolbar button turns it on rather
+than doing it. Two windows on one session are two views of one switch.
+
+Two consequences worth knowing:
+
+- **It polls.** No platform gives Node a clipboard-change event, so the local
+  side is read twice a second while sharing is on. That is why it is a toggle
+  and not always on, and why off is a real off: the timer is not running and the
+  host's clipboard messages are dropped.
+- **Nothing goes round in circles.** Text that arrived from the host is not then
+  noticed by the poller and pushed back to it, and what was already on the
+  clipboard when sharing started is not treated as a change -- so turning
+  sharing on does not send something copied an hour ago.
+
+It uses whatever the platform has: `pbcopy`/`pbpaste` on macOS,
+`Set-Clipboard`/`Get-Clipboard` on Windows, and `wl-clipboard`, `xclip` or
+`xsel` on Linux. A machine with none reports the clipboard as unavailable and
+the button stays hidden rather than offering a switch that cannot work.
+
+Sharing sits behind the same control gate as keyboard and pointer input: a
+watch-only viewer can read the screen and cannot reach either clipboard.
+
+### A new terminal, after installing something
+
+A shell inherits its environment when it signs in, and nothing can change a
+running process's inherited environment from outside it. So a program installed
+a moment ago is simply not on the PATH of the shell that installed it, and
+running the command again will not find it however many times it is tried.
+
+`reconnect` is the fix, and it is the same one a person reaches for -- close the
+terminal, open another:
+
+```bash
+npx ai-remote exec "winget install OpenJS.NodeJS"
+npx ai-remote reconnect
+npx ai-remote exec "node --version"
+
+npx ai-remote exec --reconnect "node --version"   # or both in one call
+```
+
+The session, the desktop and the window stay exactly where they are; only the
+terminal is new. That also means the working directory and any exported
+variables are gone, which is the point -- it is a new login, not a refresh.
+
+On Windows a fresh login can still inherit a stale environment, because sshd
+built its own environment block when the service started. Reading the PATH
+straight out of the registry works regardless:
+
+```bash
+npx ai-remote exec '$env:Path = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Environment]::GetEnvironmentVariable("Path","User")'
+```
+
+### Copying files
+
+`cp` is `scp` with the session standing in for the host: a remote path starts
+with a colon, and anything else is on this machine.
+
+```bash
+npx ai-remote cp ./setup.exe :C:/Users/owner/Desktop/   # to the session in hand
+npx ai-remote cp :/var/log/syslog ./syslog              # from it
+npx ai-remote cp -r ./site :/srv/www                    # a whole directory
+npx ai-remote cp desk:/tmp/a.txt build:/tmp/a.txt       # between two sessions
+```
+
+SFTP underneath, which is what `scp` itself uses since OpenSSH 9 deprecated its
+own wire protocol. So the host needs no `scp` binary, a filename with a space or
+a quote in it is a length-prefixed string rather than a quoting problem, and
+nothing passes through a shell -- which is why a Windows host needs no special
+case here even though `exec` needs several.
+
+Two rules about the grammar:
+
+- **A one-letter prefix is a drive, not a session.** `C:/Users/owner/x.txt` is a
+  path on this machine, and always will be. Two or more characters before the
+  colon name a session -- by its name, or by its host.
+- **A destination that already exists as a directory takes the source's name
+  under it.** `cp a.txt :/tmp` is `/tmp/a.txt`, and `cp -r ./site :/srv/www`
+  with `www` already there is `/srv/www/site`. A destination that does not exist
+  is the name the copy takes.
+
+Chunks are 32 KB with eight in flight, so a transfer gets the bandwidth the link
+has rather than one round trip per chunk. The mode travels with the file. The
+transfer is its own SSH connection rather than the session's, so a large copy
+does not stall the terminal somebody is watching. `--json` reports `bytes`,
+`files` and `rate`.
+
 ### Signing in
 
 Keys first, then a password.
@@ -166,6 +355,7 @@ where a decrypted key belongs, and it is offered from there.
 - `-s, --security MODE`: `auto` | `nla` | `tls` | `rdp` (default: `auto`).
 - `-W, --width N` / `-H, --height N`: Desktop resolution (default: 1280x800).
 - `--idle MINUTES`: Close an unused session (default: 0, never).
+- `--clipboard`: Share this machine's clipboard with the desktop, both ways.
 - `--headless` / `--no-view`: Run headless without opening the viewer window.
 - `--no-reuse`: A second session beside one that is already open.
 - `--save`: Keep the password for next time, once it has worked.
@@ -174,6 +364,8 @@ where a decrypted key belongs, and it is offered from there.
 
 - `--session NAME`: Which session to drive (default: the one opened last).
 - `-o, --out FILE`: Screenshot output file path (default: `screen.png`).
+- `-r, --recursive`: For `cp`, copy a directory.
+- `--reconnect`: For `exec`, open a new terminal first, then run the command.
 - `--max-edge N`: Shrink a screenshot to fit N.
 - `--json`: Output machine-readable JSON results on stdout.
 
@@ -216,6 +408,7 @@ npm install ai-remote
   - 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.
+  - SFTP version 3 client on a subsystem channel, for file transfer.
 - **VNC Engine:**
   - RFB protocol integration with Apple Diffie-Hellman handshake support.
 - **AI Agent Automation:**

package/SKILL.md

@@ -30,6 +30,27 @@ reconnects between acting and looking can never see the result of its own
 action. Reuse also makes each command effectively instant — a keystroke is
 ~0.15s against ~5s for a fresh RDP handshake.
 
+**Batch steps into one invocation where you can.** `npx` costs about 300 ms per
+call before this tool runs at all — npm resolving the package, not the package
+doing anything, and the same 300 ms for a package with no code in it. The tool
+itself answers in about 27 ms. So four steps run as four commands spend roughly a
+second waiting on npm and a tenth of one doing the work:
+
+```bash
+# ~1200 ms, nearly all npm
+npx ai-remote key MetaLeft
+npx ai-remote type notepad
+npx ai-remote key Enter
+npx ai-remote shot -o s.png
+
+# ~305 ms, same four steps
+npx ai-remote do "key MetaLeft; wait 800; type notepad; key Enter; wait 1500; shot s.png"
+```
+
+Look between steps when you need to see the result before choosing the next one;
+batch the runs of steps you already know. The `npm notice run ...` lines npx
+prints are npm's own and harmless — ignore them, or add `--silent`.
+
 ## Working loop
 
 Act, then look. The session holds the framebuffer, so a screenshot taken after a
@@ -128,6 +149,71 @@ leave) — that one is for a human, not for an agent, because it never returns.
 Reach for the GUI when the task is genuinely graphical. Reach for `exec` for
 anything a shell can do.
 
+**After installing anything, reconnect.** A shell's environment is fixed when it
+signs in, so a `node` installed a moment ago is not on the PATH of the shell that
+installed it, and asking again will never find it:
+
+```bash
+npx ai-remote exec "winget install OpenJS.NodeJS"
+npx ai-remote reconnect                     # a new login, so a new PATH
+npx ai-remote exec "node --version"
+
+npx ai-remote exec --reconnect "node --version"   # or both in one call
+```
+
+The session, the desktop and the window all stay put — only the terminal is new,
+which also means the working directory and any exported variables are gone. On
+Windows, if a fresh login still cannot see it, sshd handed down its own stale
+environment; read the PATH straight out of the registry instead:
+
+```bash
+npx ai-remote exec '$env:Path = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Environment]::GetEnvironmentVariable("Path","User")'
+```
+
+Note `&&` is not valid in PowerShell 5.1 — use `;` to chain, or `if ($?) { ... }`
+when the second command should only run if the first worked.
+
+## The clipboard
+
+Off by default. The **clipboard button in the window's toolbar** turns it on, or
+from a command line:
+
+```bash
+npx ai-remote clipboard on          # both directions, until turned off
+npx ai-remote clipboard             # what it is doing now
+npx ai-remote open HOST -u USER --clipboard    # on from the start
+```
+
+While it is on, text copied on this machine reaches the remote clipboard and
+text copied there reaches this one — so a password, a path or a stack trace
+moves without being typed. Only a desktop has a clipboard: RDP negotiates one
+and VNC has it in the protocol, while an `--ssh` session has none and the button
+does not appear.
+
+Turn it off before copying anything on this machine that the remote end should
+not see. Off is a real off — nothing is read and nothing is written.
+
+## Copying files
+
+`cp` is scp with the session standing in for the host. A remote path starts with
+a colon; anything else is on this machine.
+
+```bash
+npx ai-remote cp ./setup.exe :C:/Users/owner/Desktop/   # to the session in hand
+npx ai-remote cp :/var/log/syslog ./syslog              # from it
+npx ai-remote cp -r ./site :/srv/www                    # a directory
+npx ai-remote cp desk:/tmp/a.txt build:/tmp/a.txt       # between two sessions
+```
+
+SFTP underneath, so the host needs no `scp` binary, spaces in filenames need no
+quoting, and nothing goes through a shell. Two rules worth knowing: a one-letter
+prefix is a drive, not a session, so `C:/Users/owner/x.txt` is local; and a
+destination that already exists as a directory takes the source's name under it,
+so `cp -r ./site :/srv/www` with `www` there gives `/srv/www/site`.
+
+Uploading is how you get a script onto a machine, which is usually better than
+typing one into a GUI. `--json` reports `bytes`, `files` and `rate`.
+
 ## A Mac, or anything else that speaks VNC
 
 `--vnc` opens the screen over VNC instead of RDP; port 5900 implies it. Every
@@ -188,10 +274,17 @@ command line is visible to every process on the machine.
 
 ```bash
 npx ai-remote open 192.168.1.20 -u owner --save   # keep it, once it has worked
-npx ai-remote saved                               # what is kept, and where
+npx ai-remote list                                # sessions, each marked if it has one
+npx ai-remote saved                               # only what is kept, and where
 npx ai-remote forget 192.168.1.20                 # one machine; --all for every one
 ```
 
+`list` answers both halves of "what can I get back to": every open session, with
+`password saved` against the ones that have one, and then the machines with a
+password kept but nothing open — those need no `-u` or password to reopen. It
+reads the index beside the keystore, not the keystore, so it never raises a
+keychain prompt.
+
 `--save` writes to the system keystore — the login keychain on macOS, the desktop
 keyring on Linux — and where there is neither, to an encrypted file under
 `~/.config/ai-remote`; the command says which it got. That file is proof against
@@ -208,7 +301,8 @@ The session opened last is the one commands drive. With several open, name them:
 npx ai-remote open 192.168.1.20 -u owner --session desk
 npx ai-remote open 192.168.1.30 -u owner --session build
 
-npx ai-remote list                  # * marks the one commands will use
+npx ai-remote list                  # * marks the one commands will use,
+                                    # and it also lists saved passwords
 npx ai-remote shot --session desk   # a name, a host, or host:port
 npx ai-remote close --all           # or `close` for the current one
 ```
@@ -240,7 +334,14 @@ fresh `shot` rather than trusting one from before you paused.
   authority either way, so a session nobody watches is not a lesser session.
 - `--fullscreen` fills the display and makes RDP use the current monitor's
   logical resolution. Add `--side-panel` to `open` to start with a fixed-width
-  SSH terminal docked on the right; its 420 pixels are removed from RDP width.
+  SSH terminal docked on the right; its 610 pixels -- eighty columns, which is
+  what a Windows shell assumes it has -- are removed from the RDP width, and the
+  divider between the panes can be dragged.
+- `--audio` (RDP only) asks the host to redirect the session's sound and plays
+  it in the window; the toolbar's speaker button mutes it. Off unless asked for:
+  the stream costs bandwidth in both directions, and Windows stops playing
+  through the host's own speakers while it is redirected. A headless session
+  ignores the flag, having nowhere to play anything.
 - `ai-remote view` adds a window to a headless session later (`view --watch-only`
   for an observer one); `view --close` takes it away without ending the session.
 - `--view-port N` moves the window's local server off 7373, which matters only
@@ -304,7 +405,7 @@ what `status` reports rather than what you asked for.
 ```bash
 export AI_REMOTE_PASSWORD=...
 npx ai-remote open HOST[:PORT] -u USER [-d DOMAIN] [--session NAME] [--fullscreen] [--side-panel]
-                               [-W 1920 -H 1080] [-s auto|nla|tls|rdp] [--save] [--idle N]
+                               [-W 1920 -H 1080] [-s auto|nla|tls|rdp] [--save] [--idle N] [--audio]
 npx ai-remote open HOST --ssh -u USER [-i ~/.ssh/id_ed25519]      # a terminal, no desktop
 npx ai-remote open HOST --vnc -u USER                             # a screen over VNC
 npx ai-remote vnc [--vnc-port N]                                  # ...or add one to this session
@@ -313,7 +414,10 @@ npx ai-remote click X,Y [--button right|middle] [--double]
 npx ai-remote type "text"
 npx ai-remote key ControlLeft+KeyA
 npx ai-remote do "key MetaLeft; wait 800; type notepad; shot s.png"
-npx ai-remote exec "command"
+npx ai-remote exec "command" [--reconnect]
+npx ai-remote reconnect                                           # a new login: fresh PATH
+npx ai-remote clipboard [on|off]                                  # share text both ways
+npx ai-remote cp [-r] SRC DST                                     # ':path' is on the session
 npx ai-remote view [--watch-only] [--close]
 npx ai-remote status | list | close [--all]
 npx ai-remote saved | forget [HOST[:PORT]] [--all]
@@ -337,5 +441,6 @@ node packages/core/dist/cli.mjs open HOST -u USER --headless
 
 The CLI's own source is [`packages/core/src/cli/`](src/cli/):
 `cli.ts` is the grammar, `sessions.ts` decides which session a command drives,
-`daemon.ts` is the process that holds the connection, and `viewer.ts` plus
-`window.ts` are the window. `pnpm test` covers them.
+`daemon.ts` is the process that holds the connection, `copy.ts` is `cp` over the
+SFTP client in [`protocols/ssh/sftp.ts`](src/protocols/ssh/sftp.ts), and
+`viewer.ts` plus `window.ts` are the window. `pnpm test` covers them.