@phnx-labs/agents-cli 1.20.28 → 1.20.30

package/dist/lib/shims.js

@@ -16,7 +16,7 @@ import { confirm, select } from '@inquirer/prompts';
 import { IS_WINDOWS, prependToWindowsUserPath } from './platform/index.js';
 import { getShimsDir, getVersionsDir, getBackupsDir, ensureAgentsDir } from './state.js';
 export { getShimsDir };
-import { AGENTS } from './agents.js';
+import { AGENTS, agentConfigDirName } from './agents.js';
 /**
  * Files and directories to always skip during conflict detection and migration.
  * These are never user config that should be migrated.
@@ -596,8 +596,14 @@ export function removeShim(agent) {
  *   v5 — hard-disable Codex startup update checks in versioned aliases.
  *   v6 — versions moved from ~/.agents-system/versions to ~/.agents/versions
  *        (two-repo split: system = shipped defaults, user = operational state).
+ *   v7 — runtime state split into ~/.agents/.history and ~/.agents/.cache.
+ *   v8 — resolve grok/kimi/droid binaries from their real install locations
+ *        (~/.grok/downloads, ~/.kimi-code/bin, ~/.local/bin) instead of the
+ *        hardcoded node_modules/.bin, which never exists for these three and
+ *        made every versioned alias (the path `agents teams` pins to) fail
+ *        with "<agent>@<version> not installed". Also emit GROK_HOME.
  */
-export const VERSIONED_ALIAS_SCHEMA_VERSION = 7;
+export const VERSIONED_ALIAS_SCHEMA_VERSION = 8;
 /** Internal marker string used to embed the schema version in versioned alias scripts. */
 const VERSIONED_ALIAS_VERSION_MARKER = 'agents-versioned-alias-version:';
 // The version string is interpolated into a generated bash script and into
@@ -640,22 +646,70 @@ export CODEX_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${co
 # version MCP and session state are isolated.
 export COPILOT_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
 `
-                : agent === 'kimi'
+                : agent === 'grok'
                     ? `
+# Grok Build uses GROK_HOME to isolate its entire configuration tree (skills,
+# hooks, plugins, agents, memory, sessions, config.toml, MCP). Point direct
+# aliases at the versioned home for isolation parity with the main shim.
+export GROK_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
+`
+                    : agent === 'kimi'
+                        ? `
 # Kimi Code CLI honors KIMI_CODE_HOME to relocate ~/.kimi-code (config.toml,
 # mcp.json, sessions, skills, hooks). Point direct aliases at the versioned home.
 export KIMI_CODE_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
 `
-                    : '';
+                        : '';
     const launchArgs = agent === 'codex' ? ' -c check_for_update_on_startup=false' : '';
+    // Resolve the binary the same way the main shim does (see generateShimScript).
+    // Grok, Kimi, and Droid do NOT ship into node_modules/.bin — Grok downloads a
+    // native binary to ~/.grok/downloads, Kimi to ~/.kimi-code/bin, and Droid
+    // (Factory AI) installs a standalone binary to ~/.local/bin. Hardcoding the
+    // node_modules path made every versioned alias for these three fail with
+    // "<agent>@<version> not installed", which is exactly the path `agents teams`
+    // takes once it pins a teammate's version.
+    // This template is unix-only — on Windows the .cmd companion delegates to
+    // "agents __shim" which resolves via getBinaryPath() instead.
+    const versionDir = `$HOME/.agents/.history/versions/${agent}/${version}`;
+    const binaryResolution = agent === 'grok'
+        ? `# Grok ships its native binary in ~/.grok/downloads, not node_modules.
+GROK_DOWNLOADS="$HOME/.grok/downloads"
+BINARY=""
+if [ -d "$GROK_DOWNLOADS" ]; then
+  BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | grep -i "${version}" | head -1)
+  [ -n "$BINARY" ] || BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | head -1)
+fi
+[ -n "$BINARY" ] && [ -x "$BINARY" ] || BINARY=$(command -v grok 2>/dev/null || echo "")`
+        : agent === 'kimi'
+            ? `# Kimi ships its binary in ~/.kimi-code/bin, not node_modules.
+KIMI_BINARY="$HOME/.kimi-code/bin/kimi"
+if [ -x "$KIMI_BINARY" ]; then
+  BINARY="$KIMI_BINARY"
+else
+  BINARY=$(command -v kimi 2>/dev/null || echo "")
+fi`
+            : agent === 'droid'
+                ? `# Droid (Factory AI) installs a standalone native binary at ~/.local/bin/droid;
+# there is no npm package and nothing lands in node_modules/.bin. The PATH
+# fallback refuses anything under our shims dir to avoid an infinite re-exec.
+DROID_BINARY="$HOME/.local/bin/droid"
+if [ -x "$DROID_BINARY" ]; then
+  BINARY="$DROID_BINARY"
+else
+  BINARY=$(command -v droid 2>/dev/null || echo "")
+  case "$BINARY" in
+    "$HOME/.agents/.cache/shims/"*) BINARY="" ;;
+  esac
+fi`
+                : `BINARY="${versionDir}/node_modules/.bin/${agentConfig.cliCommand}"`;
     return `#!/bin/bash
 # Auto-generated by agents-cli - do not edit
 # ${VERSIONED_ALIAS_VERSION_MARKER} ${VERSIONED_ALIAS_SCHEMA_VERSION}
 # Direct alias for ${agentConfig.name}@${version}
 
-BINARY="$HOME/.agents/.history/versions/${agent}/${version}/node_modules/.bin/${agentConfig.cliCommand}"
+${binaryResolution}
 
-if [ ! -x "$BINARY" ]; then
+if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
   echo "agents: ${agent}@${version} not installed" >&2
   exit 1
 fi
@@ -831,6 +885,70 @@ function detectMigrationConflicts(agent, version) {
  *
  * Returns: { success: boolean, backupPath?: string, error?: string }
  */
+/**
+ * Seed a version's config home with the account credential so switching versions
+ * doesn't log the CLI out. Droid/antigravity/kimi (registry `authFiles`) store
+ * login as files inside the per-version config dir; sign-in is account-global,
+ * so we copy the FRESHEST existing copy (by mtime, across all installed version
+ * homes) into `toConfigDir` when its copy is missing or older. mtime is
+ * preserved so the "freshest" comparison stays stable and switches don't
+ * ping-pong. Best-effort: a failed copy just means the user re-logs in.
+ */
+export function carryForwardAuthFiles(agent, toConfigDir) {
+    const authFiles = AGENTS[agent].authFiles;
+    if (!authFiles || authFiles.length === 0)
+        return;
+    const configDirName = agentConfigDirName(agent);
+    const versionsBase = path.join(getVersionsDir(), agent);
+    let sourceDirs = [];
+    try {
+        sourceDirs = fs
+            .readdirSync(versionsBase)
+            .map(v => path.join(versionsBase, v, 'home', configDirName));
+    }
+    catch {
+        return; // no installed versions to source from
+    }
+    for (const rel of authFiles) {
+        const dest = path.join(toConfigDir, rel);
+        const destResolved = path.resolve(dest);
+        // Newest existing source copy across all version homes (excluding dest).
+        let newest = null;
+        for (const dir of sourceDirs) {
+            const src = path.join(dir, rel);
+            if (path.resolve(src) === destResolved)
+                continue;
+            let st;
+            try {
+                st = fs.statSync(src);
+            }
+            catch {
+                continue;
+            }
+            if (!st.isFile())
+                continue;
+            if (!newest || st.mtimeMs > newest.mtimeMs)
+                newest = { path: src, mtimeMs: st.mtimeMs };
+        }
+        if (!newest)
+            continue;
+        // Skip when the target already has an at-least-as-fresh copy.
+        try {
+            const dstat = fs.statSync(dest);
+            if (dstat.mtimeMs >= newest.mtimeMs)
+                continue;
+        }
+        catch { /* dest missing — copy below */ }
+        try {
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            const srcStat = fs.statSync(newest.path);
+            fs.copyFileSync(newest.path, dest);
+            fs.chmodSync(dest, (srcStat.mode & 0o777) || 0o600);
+            fs.utimesSync(dest, srcStat.atime, srcStat.mtime);
+        }
+        catch { /* best-effort; a failed carry just means a re-login */ }
+    }
+}
 export async function switchConfigSymlink(agent, version) {
     const configPath = getAgentConfigPath(agent);
     const versionConfigPath = getVersionConfigPath(agent, version);
@@ -838,6 +956,12 @@ export async function switchConfigSymlink(agent, version) {
     if (!fs.existsSync(versionConfigPath)) {
         fs.mkdirSync(versionConfigPath, { recursive: true });
     }
+    // Carry the account credential into the version we're switching to. Droid /
+    // antigravity / kimi store login as files INSIDE the per-version config home;
+    // switching versions repoints the symlink to a home that was never logged in,
+    // silently logging the CLI out. Sign-in is account-global, so seed the target
+    // home with the freshest existing credential before we flip the symlink.
+    carryForwardAuthFiles(agent, versionConfigPath);
     try {
         const stat = fs.lstatSync(configPath);
         if (stat.isSymbolicLink()) {

package/dist/lib/ssh-tunnel.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Shared SSH port-forward tunnel + remote computer-helper provisioning.
+ *
+ * Two layers live here:
+ *
+ *  1. `startSSHTunnel` — the generic `ssh -L localPort:127.0.0.1:remotePort -N`
+ *     spawn, extracted verbatim from the browser CDP driver so both the browser
+ *     and `agents computer --host` reach a remote loopback service through one
+ *     hardened tunnel. Behavior for the browser caller is unchanged (default,
+ *     foreground, stderr-captured).
+ *
+ *  2. Remote computer-helper orchestration — resolve a registered device to an
+ *     ssh target, push the cross-published Windows daemon exe, register it as a
+ *     LOGON scheduled task (interactive session so real-desktop UIA/screenshot
+ *     works and it survives the ssh disconnect), and open a tunnel the TS RPC
+ *     client drives via TCP. Everything rides the existing `ssh-exec` /
+ *     `devices/connect` primitives — no parallel SSH implementation.
+ */
+import { type ChildProcess } from 'child_process';
+import { type DeviceProfile } from './devices/registry.js';
+export interface StartTunnelOptions {
+    /**
+     * Detach the tunnel so it OUTLIVES this CLI process. Used by
+     * `agents computer start --host` — the tunnel must persist across separate
+     * verb invocations (`apps`, `click`, …) until `stop --host` tears it down.
+     * The browser driver leaves this false: it holds the tunnel for the lifetime
+     * of one CDP session and kills it on cleanup.
+     */
+    detached?: boolean;
+}
+/** Build the ssh argv (after the `ssh` program name) for an `-L` tunnel. Pure. */
+export declare function buildTunnelArgs(user: string, host: string, localPort: number, remotePort: number): string[];
+/**
+ * Spawn `ssh -L localPort:127.0.0.1:remotePort -N user@host`.
+ *
+ * Foreground (default): stderr is captured so a tunnel that dies inside 500ms
+ * rejects with the ssh error — the browser driver's original contract. Detached
+ * mode ignores stdio and `unref`s the child so the parent can exit while the
+ * tunnel lives; liveness is then confirmed by the caller probing the service.
+ */
+export declare function startSSHTunnel(user: string, host: string, localPort: number, remotePort: number, opts?: StartTunnelOptions): Promise<ChildProcess>;
+/** Loopback TCP port the Windows daemon binds on the remote (Program.cs default). */
+export declare const REMOTE_HELPER_PORT = 8765;
+/** Task Scheduler task name for the daemon. Stable so setup/stop pair up. */
+export declare const REMOTE_TASK_NAME = "AgentsComputerHelper";
+/** Basename of the cross-published exe under packages/computer-helper-win/dist. */
+export declare const WIN_HELPER_EXE = "computer-helper-win.exe";
+/**
+ * Locate the cross-published Windows daemon exe. Only the local build output is
+ * a candidate — `scripts/build-win.sh` writes it to packages/.../dist/.
+ */
+export declare function resolveWinHelperExe(): string | null;
+/** Persisted per-device tunnel state so verbs can reconnect after `start --host`. */
+export interface RemoteTunnelState {
+    device: string;
+    target: string;
+    localPort: number;
+    remotePort: number;
+    tunnelPid: number;
+    token: string | null;
+    taskName: string;
+    startedAt: number;
+}
+/** State file path for a device. Device names are ssh-alias safe (validated). */
+export declare function remoteStatePath(device: string): string;
+export declare function readRemoteState(device: string): RemoteTunnelState | null;
+export declare function writeRemoteState(state: RemoteTunnelState): void;
+export declare function clearRemoteState(device: string): void;
+/** Resolve a registered device to its ssh pieces, or throw a clear error. */
+export declare function resolveRemoteDevice(name: string): Promise<{
+    device: DeviceProfile;
+    target: string;
+    user: string;
+    host: string;
+}>;
+/**
+ * PowerShell that streams base64 from stdin, decodes it incrementally to
+ * %LOCALAPPDATA%\agents\computer-helper-win.exe, and stops any running instance
+ * first so the file isn't locked. The CryptoStream/FromBase64Transform decode
+ * is streaming — the ~156MB exe never lands in memory whole on the remote.
+ */
+export declare function buildPushScript(): string;
+/**
+ * PowerShell that registers the daemon as a LOGON scheduled task. Interactive
+ * logon type + Highest run level so the daemon runs in the real desktop session
+ * (UIAutomation and ScreenCapture need a live session, not Session 0) and
+ * survives ssh disconnect — the same rationale as the browser WMI launch. The
+ * task is started immediately so the caller need not log out/in.
+ */
+export declare function buildRegisterTaskScript(port: number, taskName: string): string;
+/** PowerShell that unregisters the task and stops any running daemon process. */
+export declare function buildUnregisterTaskScript(taskName: string): string;
+/**
+ * `setup --host`: push the exe, then register + start the LOGON task. Both hops
+ * go through `sshExec` (BatchMode key auth — the same hardening the browser
+ * driver and `agents ssh` use). Throws with the remote stderr on any failure.
+ */
+export declare function setupRemoteHelper(name: string): Promise<{
+    target: string;
+    taskName: string;
+}>;
+/** Reserve a free local TCP port by binding :0 and reading the assigned port. */
+export declare function pickFreePort(): Promise<number>;
+/**
+ * `start --host`: open a detached ssh -L tunnel to the remote daemon, verify it
+ * answers over TCP, and persist the tunnel state so verbs can reconnect. Returns
+ * the state (and leaves the tunnel running in the background).
+ */
+export declare function startRemoteTunnel(name: string): Promise<RemoteTunnelState>;
+/**
+ * `stop --host`: kill the local tunnel, unregister the remote task (best-effort
+ * — the box may be offline), and clear the persisted state.
+ */
+export declare function stopRemoteHelper(name: string): Promise<{
+    tunnelKilled: boolean;
+    taskRemoved: boolean;
+}>;
+/**
+ * Point this process's RPC client at a device's live tunnel by setting
+ * COMPUTER_HELPER_TCP / COMPUTER_HELPER_TOKEN from persisted state. Called for
+ * remote verbs (`apps --host`, `click --host`, …) so the shared
+ * openComputerClient() transparently selects the TcpClient transport — no
+ * per-verb wiring. Exits with guidance when there is no active tunnel.
+ */
+export declare function hydrateRemoteEnvFromState(name: string): void;
+/** Generate a shared-secret token (reserved for token-file provisioning). */
+export declare function generateToken(): string;

package/dist/lib/ssh-tunnel.js

@@ -0,0 +1,346 @@
+/**
+ * Shared SSH port-forward tunnel + remote computer-helper provisioning.
+ *
+ * Two layers live here:
+ *
+ *  1. `startSSHTunnel` — the generic `ssh -L localPort:127.0.0.1:remotePort -N`
+ *     spawn, extracted verbatim from the browser CDP driver so both the browser
+ *     and `agents computer --host` reach a remote loopback service through one
+ *     hardened tunnel. Behavior for the browser caller is unchanged (default,
+ *     foreground, stderr-captured).
+ *
+ *  2. Remote computer-helper orchestration — resolve a registered device to an
+ *     ssh target, push the cross-published Windows daemon exe, register it as a
+ *     LOGON scheduled task (interactive session so real-desktop UIA/screenshot
+ *     works and it survives the ssh disconnect), and open a tunnel the TS RPC
+ *     client drives via TCP. Everything rides the existing `ssh-exec` /
+ *     `devices/connect` primitives — no parallel SSH implementation.
+ */
+import { spawn } from 'child_process';
+import * as net from 'net';
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { randomBytes } from 'crypto';
+import { sshExec } from './ssh-exec.js';
+import { encodePowerShell } from './browser/drivers/ssh.js';
+import { getDevice } from './devices/registry.js';
+import { sshTargetFor } from './devices/connect.js';
+import { hostNameFor } from './devices/ssh-config.js';
+import { getCacheDir } from './state.js';
+import { openComputerClient, resolveTcpEndpoint } from './computer-rpc.js';
+/** Build the ssh argv (after the `ssh` program name) for an `-L` tunnel. Pure. */
+export function buildTunnelArgs(user, host, localPort, remotePort) {
+    return [
+        '-L',
+        `${localPort}:127.0.0.1:${remotePort}`,
+        `${user}@${host}`,
+        '-N',
+        '-o',
+        'StrictHostKeyChecking=accept-new',
+        '-o',
+        'BatchMode=yes',
+        '-o',
+        'ConnectTimeout=10',
+    ];
+}
+/**
+ * Spawn `ssh -L localPort:127.0.0.1:remotePort -N user@host`.
+ *
+ * Foreground (default): stderr is captured so a tunnel that dies inside 500ms
+ * rejects with the ssh error — the browser driver's original contract. Detached
+ * mode ignores stdio and `unref`s the child so the parent can exit while the
+ * tunnel lives; liveness is then confirmed by the caller probing the service.
+ */
+export function startSSHTunnel(user, host, localPort, remotePort, opts = {}) {
+    return new Promise((resolve, reject) => {
+        const args = buildTunnelArgs(user, host, localPort, remotePort);
+        const tunnel = spawn('ssh', args, {
+            stdio: opts.detached ? 'ignore' : ['ignore', 'ignore', 'pipe'],
+            detached: Boolean(opts.detached),
+        });
+        let stderr = '';
+        tunnel.stderr?.on('data', (data) => {
+            stderr += data.toString();
+        });
+        tunnel.on('error', (err) => {
+            reject(new Error(`SSH tunnel failed: ${err.message}`));
+        });
+        setTimeout(() => {
+            if (tunnel.killed) {
+                reject(new Error(`SSH tunnel died: ${stderr}`));
+            }
+            else {
+                // Let the CLI exit without waiting on a persistent tunnel.
+                if (opts.detached)
+                    tunnel.unref();
+                resolve(tunnel);
+            }
+        }, 500);
+    });
+}
+// ---------------------------------------------------------------------------
+// 2. Remote computer-helper orchestration
+// ---------------------------------------------------------------------------
+/** Loopback TCP port the Windows daemon binds on the remote (Program.cs default). */
+export const REMOTE_HELPER_PORT = 8765;
+/** Task Scheduler task name for the daemon. Stable so setup/stop pair up. */
+export const REMOTE_TASK_NAME = 'AgentsComputerHelper';
+/** Basename of the cross-published exe under packages/computer-helper-win/dist. */
+export const WIN_HELPER_EXE = 'computer-helper-win.exe';
+/**
+ * Locate the cross-published Windows daemon exe. Only the local build output is
+ * a candidate — `scripts/build-win.sh` writes it to packages/.../dist/.
+ */
+export function resolveWinHelperExe() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        // Running from the agents-cli checkout (src/lib -> repo root).
+        path.resolve(here, '..', '..', 'packages', 'computer-helper-win', 'dist', WIN_HELPER_EXE),
+        // Bundled with the npm package (dist/lib -> package root).
+        path.resolve(here, '..', 'computer-helper-win', WIN_HELPER_EXE),
+    ];
+    for (const c of candidates) {
+        if (fs.existsSync(c))
+            return c;
+    }
+    return null;
+}
+function remoteStateDir() {
+    return path.join(getCacheDir(), 'computer', 'remote');
+}
+/** State file path for a device. Device names are ssh-alias safe (validated). */
+export function remoteStatePath(device) {
+    return path.join(remoteStateDir(), `${device}.json`);
+}
+export function readRemoteState(device) {
+    try {
+        return JSON.parse(fs.readFileSync(remoteStatePath(device), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeRemoteState(state) {
+    const dir = remoteStateDir();
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(remoteStatePath(state.device), JSON.stringify(state, null, 2), { mode: 0o600 });
+}
+export function clearRemoteState(device) {
+    try {
+        fs.unlinkSync(remoteStatePath(device));
+    }
+    catch {
+        /* already gone */
+    }
+}
+/** Resolve a registered device to its ssh pieces, or throw a clear error. */
+export async function resolveRemoteDevice(name) {
+    const device = await getDevice(name);
+    if (!device) {
+        throw new Error(`Unknown device '${name}'. Register it with \`agents devices add\` / \`agents devices sync\`, then retry.`);
+    }
+    if (device.platform !== 'windows') {
+        throw new Error(`Device '${name}' is ${device.platform}, not windows. \`agents computer --host\` drives the Windows computer-helper daemon.`);
+    }
+    const target = sshTargetFor(device); // validates address + injection guard
+    const host = hostNameFor(device); // sshTargetFor already threw if absent
+    const user = device.user || process.env.USER || 'Administrator';
+    return { device, target, user, host };
+}
+/**
+ * PowerShell that streams base64 from stdin, decodes it incrementally to
+ * %LOCALAPPDATA%\agents\computer-helper-win.exe, and stops any running instance
+ * first so the file isn't locked. The CryptoStream/FromBase64Transform decode
+ * is streaming — the ~156MB exe never lands in memory whole on the remote.
+ */
+export function buildPushScript() {
+    return [
+        `$dir = Join-Path $env:LOCALAPPDATA 'agents'`,
+        `New-Item -ItemType Directory -Force -Path $dir | Out-Null`,
+        `$dst = Join-Path $dir '${WIN_HELPER_EXE}'`,
+        `Get-Process -Name 'computer-helper-win' -ErrorAction SilentlyContinue | Stop-Process -Force -ErrorAction SilentlyContinue`,
+        `$si = [Console]::OpenStandardInput()`,
+        `$t = New-Object Security.Cryptography.FromBase64Transform`,
+        `$cs = New-Object Security.Cryptography.CryptoStream($si, $t, [Security.Cryptography.CryptoStreamMode]::Read)`,
+        `$fs = [IO.File]::Create($dst)`,
+        `$cs.CopyTo($fs)`,
+        `$fs.Close(); $cs.Close()`,
+        `Write-Output $dst`,
+    ].join('; ');
+}
+/**
+ * PowerShell that registers the daemon as a LOGON scheduled task. Interactive
+ * logon type + Highest run level so the daemon runs in the real desktop session
+ * (UIAutomation and ScreenCapture need a live session, not Session 0) and
+ * survives ssh disconnect — the same rationale as the browser WMI launch. The
+ * task is started immediately so the caller need not log out/in.
+ */
+export function buildRegisterTaskScript(port, taskName) {
+    return [
+        `$exe = Join-Path (Join-Path $env:LOCALAPPDATA 'agents') '${WIN_HELPER_EXE}'`,
+        `$action = New-ScheduledTaskAction -Execute $exe -Argument '--port ${port}'`,
+        `$trigger = New-ScheduledTaskTrigger -AtLogOn`,
+        `$principal = New-ScheduledTaskPrincipal -UserId $env:USERNAME -LogonType Interactive -RunLevel Highest`,
+        `$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -ExecutionTimeLimit ([TimeSpan]::Zero)`,
+        `Register-ScheduledTask -TaskName '${taskName}' -Action $action -Trigger $trigger -Principal $principal -Settings $settings -Force | Out-Null`,
+        `Start-ScheduledTask -TaskName '${taskName}'`,
+    ].join('; ');
+}
+/** PowerShell that unregisters the task and stops any running daemon process. */
+export function buildUnregisterTaskScript(taskName) {
+    return [
+        `Unregister-ScheduledTask -TaskName '${taskName}' -Confirm:$false -ErrorAction SilentlyContinue`,
+        `Get-Process -Name 'computer-helper-win' -ErrorAction SilentlyContinue | Stop-Process -Force -ErrorAction SilentlyContinue`,
+    ].join('; ');
+}
+/**
+ * `setup --host`: push the exe, then register + start the LOGON task. Both hops
+ * go through `sshExec` (BatchMode key auth — the same hardening the browser
+ * driver and `agents ssh` use). Throws with the remote stderr on any failure.
+ */
+export async function setupRemoteHelper(name) {
+    const { target } = await resolveRemoteDevice(name);
+    const exe = resolveWinHelperExe();
+    if (!exe) {
+        throw new Error(`Windows helper exe not built. Run: bash scripts/build-win.sh`);
+    }
+    // Push: base64 the exe locally, stream it over ssh stdin to the decoder.
+    const b64 = fs.readFileSync(exe).toString('base64');
+    const push = sshExec(target, encodePowerShell(buildPushScript()), {
+        input: b64,
+        timeoutMs: 600_000, // ~156MB over the wire — allow up to 10 minutes
+    });
+    if (push.code !== 0) {
+        throw new Error(`pushing helper exe to '${name}' failed (exit ${push.code ?? 'null'}): ${push.stderr.trim() || push.stdout.trim()}`);
+    }
+    // Register + start the LOGON task.
+    const reg = sshExec(target, encodePowerShell(buildRegisterTaskScript(REMOTE_HELPER_PORT, REMOTE_TASK_NAME)), {
+        timeoutMs: 60_000,
+    });
+    if (reg.code !== 0) {
+        throw new Error(`registering scheduled task on '${name}' failed (exit ${reg.code ?? 'null'}): ${reg.stderr.trim() || reg.stdout.trim()}`);
+    }
+    return { target, taskName: REMOTE_TASK_NAME };
+}
+/** Reserve a free local TCP port by binding :0 and reading the assigned port. */
+export function pickFreePort() {
+    return new Promise((resolve, reject) => {
+        const srv = net.createServer();
+        srv.once('error', reject);
+        srv.listen(0, '127.0.0.1', () => {
+            const addr = srv.address();
+            const port = typeof addr === 'object' && addr ? addr.port : 0;
+            srv.close(() => (port ? resolve(port) : reject(new Error('could not reserve a local port'))));
+        });
+    });
+}
+/**
+ * `start --host`: open a detached ssh -L tunnel to the remote daemon, verify it
+ * answers over TCP, and persist the tunnel state so verbs can reconnect. Returns
+ * the state (and leaves the tunnel running in the background).
+ */
+export async function startRemoteTunnel(name) {
+    const { target, user, host } = await resolveRemoteDevice(name);
+    const remotePort = REMOTE_HELPER_PORT;
+    const localPort = await pickFreePort();
+    const tunnel = await startSSHTunnel(user, host, localPort, remotePort, { detached: true });
+    const tunnelPid = tunnel.pid ?? 0;
+    // Verify the daemon answers through the tunnel before we record it. This is
+    // the real end-to-end check: tunnel up + daemon listening + RPC round-trips.
+    const token = null; // tunnel-gated; the daemon runs token-less
+    const prevTcp = process.env.COMPUTER_HELPER_TCP;
+    process.env.COMPUTER_HELPER_TCP = `127.0.0.1:${localPort}`;
+    const client = openComputerClient();
+    let ok = false;
+    let probeErr = '';
+    try {
+        const r = await client.call('list_apps');
+        ok = !r.error;
+        if (r.error)
+            probeErr = `${r.error.code}: ${r.error.message}`;
+    }
+    catch (e) {
+        probeErr = e.message;
+    }
+    finally {
+        await client.close();
+        if (prevTcp === undefined)
+            delete process.env.COMPUTER_HELPER_TCP;
+        else
+            process.env.COMPUTER_HELPER_TCP = prevTcp;
+    }
+    if (!ok) {
+        try {
+            if (tunnelPid)
+                process.kill(tunnelPid);
+        }
+        catch { /* gone */ }
+        throw new Error(`tunnel to '${name}' opened but the daemon did not answer (${probeErr}). ` +
+            `Is it installed? Run: agents computer setup --host ${name}`);
+    }
+    const state = {
+        device: name,
+        target,
+        localPort,
+        remotePort,
+        tunnelPid,
+        token,
+        taskName: REMOTE_TASK_NAME,
+        startedAt: Date.now(),
+    };
+    writeRemoteState(state);
+    return state;
+}
+/**
+ * `stop --host`: kill the local tunnel, unregister the remote task (best-effort
+ * — the box may be offline), and clear the persisted state.
+ */
+export async function stopRemoteHelper(name) {
+    const state = readRemoteState(name);
+    let tunnelKilled = false;
+    if (state?.tunnelPid) {
+        try {
+            process.kill(state.tunnelPid);
+            tunnelKilled = true;
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    let taskRemoved = false;
+    try {
+        const { target } = await resolveRemoteDevice(name);
+        const res = sshExec(target, encodePowerShell(buildUnregisterTaskScript(REMOTE_TASK_NAME)), { timeoutMs: 60_000 });
+        taskRemoved = res.code === 0;
+    }
+    catch {
+        /* device gone / offline — local teardown still succeeds */
+    }
+    clearRemoteState(name);
+    return { tunnelKilled, taskRemoved };
+}
+/**
+ * Point this process's RPC client at a device's live tunnel by setting
+ * COMPUTER_HELPER_TCP / COMPUTER_HELPER_TOKEN from persisted state. Called for
+ * remote verbs (`apps --host`, `click --host`, …) so the shared
+ * openComputerClient() transparently selects the TcpClient transport — no
+ * per-verb wiring. Exits with guidance when there is no active tunnel.
+ */
+export function hydrateRemoteEnvFromState(name) {
+    const state = readRemoteState(name);
+    if (!state) {
+        console.error(`No active remote tunnel for '${name}'.`);
+        console.error(`Run:  agents computer start --host ${name}`);
+        process.exit(1);
+    }
+    process.env.COMPUTER_HELPER_TCP = `127.0.0.1:${state.localPort}`;
+    if (state.token)
+        process.env.COMPUTER_HELPER_TOKEN = state.token;
+    // Touch resolveTcpEndpoint so a later platform-gate check sees the endpoint.
+    void resolveTcpEndpoint();
+}
+/** Generate a shared-secret token (reserved for token-file provisioning). */
+export function generateToken() {
+    return randomBytes(24).toString('hex');
+}

package/dist/lib/startup/command-registry.d.ts

@@ -68,6 +68,7 @@ export declare const loadTmux: ModuleLoader;
 export declare const loadBrowser: ModuleLoader;
 export declare const loadComputer: ModuleLoader;
 export declare const loadHosts: ModuleLoader;
+export declare const loadSsh: ModuleLoader;
 export declare const loadPull: ModuleLoader;
 export declare const loadPush: ModuleLoader;
 export declare const loadRepo: ModuleLoader;