ai-remote 0.4.15 → 0.4.17

package/README.md

@@ -111,6 +111,8 @@ why `npx` is still what the examples here use.
   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
@@ -214,6 +216,147 @@ npx ai-remote exec "uname -a"
 npx ai-remote shell                                # Ctrl-] to leave
 ```
 
+### Modifier keys between a Mac and a PC
+
+A Mac's shortcut modifier is Command; Windows and Linux use Control. Send the
+physical key through unchanged and Command-C on a Windows desktop opens the
+Start menu and types a C, because Command is physically the same key as the
+Windows logo key.
+
+Microsoft's own Mac client sends it through unchanged and documents the
+consequence: *"The Command key on the Mac keyboard equals the Windows key. To
+perform actions that use the Command button on the Mac, you will need to use the
+control button in Windows (for example Copy = Ctrl+C)."* That is consistent, and
+it is also the thing people complain about most, because it asks the fingers to
+learn a second shortcut modifier for one application.
+
+So by default, when one end is a Mac and the other is not, **Control and Command
+swap**:
+
+| pressed on the Mac | arrives on the Windows/Linux desktop |
+| --- | --- |
+| Command | Control — `Command-C` copies |
+| Control | the Windows key — `Control-D` shows the desktop |
+| Option | Alt, unchanged |
+
+and the mirror when a PC keyboard drives a Mac desktop (the VNC case):
+
+| pressed on the PC | arrives on the Mac |
+| --- | --- |
+| Control | Command — `Control-C` copies |
+| Windows key | Control |
+| Alt | Option, unchanged |
+
+A swap rather than a redirect, deliberately: it is a bijection, so the Windows
+key is still reachable and nothing becomes impossible to press. Redirecting
+Command to Control and leaving Control alone would give a Mac two Controls and
+no Windows key at all.
+
+```bash
+npx ai-remote open 192.168.1.50 -u owner                   # adapt, the default
+npx ai-remote open 192.168.1.50 -u owner --keys literal     # Microsoft's behaviour
+```
+
+The far end is worked out rather than assumed: RDP is Windows, and for VNC only
+macOS Screen Sharing offers Apple's Diffie-Hellman security type, which is
+already what decides how far a scroll notch goes. Ends that agree -- Mac to Mac,
+PC to PC, Linux to Windows -- are left alone entirely, and `status` reports what
+the mapping is doing under `keys`.
+
+**Only the window's live keyboard goes through this.** `key` and `do` name the
+key they want *on the host*, so they are never remapped -- `key MetaLeft` opens
+the Start menu on Windows whatever keyboard is in front of you, and
+`key ControlLeft+KeyC` means Control-C there. Ctrl+Alt+Del is likewise a
+sequence the session synthesizes from real Windows codes, not three keys somebody
+pressed, so the swap does not turn it into Windows+Alt+Del.
+
+### The clipboard
+
+**On by default.** Text copied on this machine reaches the remote clipboard and
+text copied there reaches this one. The **clipboard button in the window's
+toolbar** is the switch, and so is the command line:
+
+```bash
+npx ai-remote clipboard                       # what it is doing now
+npx ai-remote clipboard off                   # stop it for this session
+npx ai-remote open 192.168.1.50 -u owner --no-clipboard
+```
+
+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, the toolbar
+button does not appear, and nothing is started.
+
+Two things follow from it being a default rather than a choice, and both are
+worth knowing:
+
+- **Everything you copy locally is sent** while a session is open. That is the
+  point, and it is also the reason `open` prints one line saying so. If you are
+  about to copy something the remote machine should not have, `clipboard off`
+  first.
+- **It polls, so it costs something.** No platform gives Node a
+  clipboard-change event, so the local side is read twice a second for as long
+  as the session is open. Measured on an M4 that is 5.7 ms per read, about 1% of
+  one core per session. The rate stays at twice a second rather than being
+  slowed to save it, because the failure it prevents -- pasting what was on the
+  clipboard *before* the thing you just copied -- is worse than the cost.
+
+**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
@@ -280,6 +423,9 @@ 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).
+- `--no-clipboard`: Do not share this machine's clipboard. Shared by default.
+- `--keys MODE`: `adapt` (default) swaps Control and Command when one end is a
+  Mac and the other is not; `literal` sends every key through as itself.
 - `--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.
@@ -289,6 +435,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.
+- `--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.
 

package/SKILL.md

@@ -114,6 +114,29 @@ screenshot full size and click the coordinates you read off it.
 image tokens and a 800px one is a fraction of that, usually with no loss of
 anything you needed to see.
 
+## Modifier keys between a Mac and a PC
+
+When one end is a Mac and the other is not, **Control and Command swap** so the
+shortcut key the fingers know keeps working:
+
+| pressed on a Mac | arrives on Windows/Linux |
+| --- | --- |
+| Command | Control — so Command-C copies |
+| Control | the Windows key |
+| Option | Alt, unchanged |
+
+and the mirror when a PC keyboard drives a Mac desktop: Control arrives as
+Command, the Windows key as Control, Alt as Option.
+
+`open --keys literal` turns it off and sends every key through as itself, which
+is what Microsoft's own Mac client does — there, Command *is* the Windows key and
+Windows shortcuts want Control.
+
+**This applies only to the window's live keyboard.** `key` and `do` name the key
+they want *on the host*, so they are never remapped: `key MetaLeft` opens the
+Start menu on Windows whatever the local keyboard is, and `key ControlLeft+KeyC`
+means Control-C there.
+
 ## Keys
 
 Key codes are DOM-style physical codes: `MetaLeft`, `Enter`, `Escape`, `Tab`,
@@ -149,6 +172,51 @@ 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
+
+**On by default**, both ways: 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.
+
+```bash
+npx ai-remote clipboard             # what it is doing now
+npx ai-remote clipboard off         # stop it for this session
+npx ai-remote open HOST -u USER --no-clipboard    # never start it
+```
+
+The toolbar's clipboard button is the same switch. Only a desktop has a
+clipboard — RDP negotiates one and VNC has it in the protocol — so an `--ssh`
+session has none and the button does not appear.
+
+**Tell the user it is on** if they are about to copy something on their own
+machine that the remote end should not see: while sharing is on, everything
+copied locally is sent. `clipboard 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
@@ -370,7 +438,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
+                              # open --keys adapt|literal   modifier mapping
 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]

package/dist/{cli-chunk-7UHHVT7Q.mjs → cli-chunk-DGHEB4P5.mjs}

@@ -1,8 +1,9 @@
 import {
   ROOT,
+  VERSION,
   isTitlebarDragPoint,
   logicalDisplaySize
-} from "./cli-chunk-K2DYJXC5.mjs";
+} from "./cli-chunk-ZQ32C4LC.mjs";
 
 // src/cli/window.ts
 import { spawn } from "node:child_process";
@@ -208,7 +209,8 @@ var ICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><def
 // src/cli/bundle.ts
 var APP_NAME = "ai-remote";
 var windowsDir = () => join(ROOT, "window");
-var bundleDir = () => join(windowsDir(), `v${ICON_VERSION}`, `${APP_NAME}.app`);
+var bundleName = () => `v${VERSION}-${ICON_VERSION}`;
+var bundleDir = () => join(windowsDir(), bundleName(), `${APP_NAME}.app`);
 var PLIST = `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -220,8 +222,8 @@ var PLIST = `<?xml version="1.0" encoding="UTF-8"?>
   <key>CFBundleIconFile</key><string>${APP_NAME}</string>
   <key>CFBundlePackageType</key><string>APPL</string>
   <key>CFBundleInfoDictionaryVersion</key><string>6.0</string>
-  <key>CFBundleShortVersionString</key><string>1.0</string>
-  <key>CFBundleVersion</key><string>${ICON_VERSION}</string>
+  <key>CFBundleShortVersionString</key><string>${VERSION}</string>
+  <key>CFBundleVersion</key><string>${VERSION}</string>
   <key>NSHighResolutionCapable</key><true/>
   <key>LSApplicationCategoryType</key><string>public.app-category.utilities</string>
 </dict>
@@ -248,7 +250,7 @@ function build(app, executable) {
   writeFileSync(join(contents, "Resources", `${APP_NAME}.icns`), iconIcns());
   symlinkSync(process.execPath, executable);
   for (const old of readdirSync(windowsDir())) {
-    if (old !== `v${ICON_VERSION}`) rmSync(join(windowsDir(), old), { recursive: true, force: true });
+    if (old !== bundleName()) rmSync(join(windowsDir(), old), { recursive: true, force: true });
   }
 }
 

package/dist/{cli-chunk-RBCU3NX4.mjs → cli-chunk-Q33YGIDO.mjs}

@@ -1,7 +1,7 @@
 import {
   SshSession,
   TcpTransport
-} from "./cli-chunk-EYQCDSPT.mjs";
+} from "./cli-chunk-S2TWL5LF.mjs";
 
 // src/cli/shell.ts
 function bareUsername(username) {

package/dist/{cli-chunk-EYQCDSPT.mjs → cli-chunk-S2TWL5LF.mjs}

@@ -935,6 +935,18 @@ function filterDisplay(session, bytes) {
   }
   return shown ? encodeUtf8(shown) : NO_BYTES;
 }
+function announceCommand(session, command) {
+  const shown = command.replace(/\r?\n/g, " \u23CE ").trimEnd();
+  if (!shown) return;
+  session.dispatchEvent(new CustomEvent("data", {
+    detail: {
+      bytes: NO_BYTES,
+      display: encodeUtf8(`\x1B[1m${shown}\x1B[0m\r
+`),
+      isStderr: false
+    }
+  }));
+}
 function releaseDisplayFilter(session) {
   const filter = session.displayFilter;
   session.displayFilter = null;
@@ -1092,6 +1104,7 @@ var SshSession = class extends EventTarget {
     this.commandInFlight = true;
     const startedAt = Date.now();
     this.displayFilter = { begin, end, stage: "before", pending: "" };
+    announceCommand(this, text);
     this.dispatchEvent(new CustomEvent("command", {
       detail: { phase: "start", id, command: text }
     }));

package/dist/{cli-chunk-K2DYJXC5.mjs → cli-chunk-ZQ32C4LC.mjs}

@@ -1,3 +1,6 @@
+// src/cli/generated/version.ts
+var VERSION = "0.4.17";
+
 // src/cli/viewer-layout.ts
 var TERMINAL_COLUMNS = 80;
 var TERMINAL_CELL_WIDTH = 7.25;
@@ -48,6 +51,7 @@ var logPath = (name) => join(RUN_DIR, `${name}.log`);
 var currentPath = () => join(ROOT, "current");
 
 export {
+  VERSION,
   SIDE_PANEL_WIDTH,
   isTitlebarDragPoint,
   logicalDisplaySize,

package/dist/{cli-copy-NRXMTHID.mjs → cli-copy-BOF44DWQ.mjs}

@@ -1,7 +1,7 @@
 import {
   SshSession,
   TcpTransport
-} from "./cli-chunk-EYQCDSPT.mjs";
+} from "./cli-chunk-S2TWL5LF.mjs";
 import {
   SshReader,
   SshWriter