ai-remote 0.4.13 → 0.4.15

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,12 @@ 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 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 +139,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 +214,40 @@ npx ai-remote exec "uname -a"
 npx ai-remote shell                                # Ctrl-] to leave
 ```
 
+### 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.
@@ -174,6 +288,7 @@ 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.
 - `--max-edge N`: Shrink a screenshot to fit N.
 - `--json`: Output machine-readable JSON results on stdout.
 
@@ -216,6 +331,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
@@ -117,7 +138,9 @@ npx ai-remote exec "hostname"
 npx ai-remote exec "dir C:\\Users"
 ```
 
-`exec` reuses the session's own account and password, so it needs no flags. Its
+`exec` reuses the session's own account and password, so it needs no flags —
+give `open` `--ssh-user NAME` or `--ssh-port N` only when the terminal signs in
+as somebody else, or on a port other than 22. Its
 stdout is the command's output, and it exits 0 when the command did and 1 when
 it did not — the command's own status is in `exitStatus` under `--json` if you
 need the number. `ai-remote shell` opens an interactive terminal (Ctrl-] to
@@ -126,6 +149,27 @@ 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.
 
+## 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
@@ -141,7 +185,8 @@ npx ai-remote click 640,400
 
 A session that is already open gets a screen with `ai-remote vnc`, which takes
 no host because the session already knows the machine. That is the way to give a
-terminal session a desktop without closing it.
+terminal session a desktop without closing it; `--vnc-port N` if the screen is
+not on 5900.
 
 ## A host with no desktop
 
@@ -168,6 +213,42 @@ variable at all. `-i FILE` names a key instead, and repeats. A key with a
 passphrase is never read off disk: `ssh-add` it, and it is offered from the
 agent.
 
+## Passwords, and not typing them twice
+
+A desktop always wants one; a terminal usually does not, because of the keys
+above. Three places are tried, in this order:
+
+1. `AI_REMOTE_PASSWORD` in this shell, or `REMOTECTL_PASSWORD` under the other
+   name.
+2. Whatever `--save` kept for that machine.
+3. You, at the terminal — only when one is attached, and only after the first
+   two have come up empty.
+
+This shell wins, so a password exported deliberately is never quietly overridden
+by one saved months ago. There is no `--password` flag and there will not be: a
+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 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
+a glance, not against somebody who can read your home directory.
+
+`--no-prompt` (or `--batch`) turns a missing password into an immediate failure
+instead of a question. Use it in anything unattended, where a prompt is a hang.
+
 ## Sessions
 
 The session opened last is the one commands drive. With several open, name them:
@@ -176,14 +257,20 @@ 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
 ```
 
-Nothing times out and nothing closes itself — a session that an agent left
-mid-task is a feature, not a leak — so **close what you open** when the task is
-done, or tell the user it is still running.
+`open` on a machine that already has a session attaches to that one instead of
+building a second; `--no-reuse` is how you get two on purpose.
+
+Nothing times out and nothing closes itself by default — a session that an agent
+left mid-task is a feature, not a leak — so **close what you open** when the task
+is done, or tell the user it is still running. `--idle MINUTES` at `open` time
+sets one to close itself after that long unused, for when nobody will be back to
+do it.
 
 ## Watching
 
@@ -203,9 +290,19 @@ 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
+  when two sessions want it at once. `--no-open` keeps the window but does not
+  launch a browser at it.
 
 ## Reading results
 
@@ -242,6 +339,9 @@ the other half of the answer is a key: `ssh-add ~/.ssh/id_ed25519`, or
 `-i FILE`. The session's log names every key it offered and every key it passed
 over, and why.
 
+`-s nla | tls | rdp` pins the RDP security layer when `auto` picks one the host
+will not finish; it makes no difference over VNC or SSH.
+
 **Unreachable (10).** — `ai-remote probe <host>` is the one command besides
 `open` that still takes an address: it answers whether anything is listening
 before you spend a handshake finding out.
@@ -261,17 +361,20 @@ 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] [--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                                                 # ...or add one to this session
+npx ai-remote vnc [--vnc-port N]                                  # ...or add one to this session
 npx ai-remote shot [-o FILE] [--max-edge N] [--json]
 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 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]
 npx ai-remote probe [HOST[:PORT]]
 ```
 
@@ -292,5 +395,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.