ai-remote 0.4.14 → 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
@@ -128,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
@@ -188,10 +230,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 +257,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 +290,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 +361,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
@@ -314,6 +371,7 @@ 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]
@@ -337,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.