@phnx-labs/agents-cli 1.20.28 → 1.20.29

package/dist/commands/exec.js

@@ -324,11 +324,12 @@ export function registerRunCommand(program) {
             process.stderr.write(chalk.gray(`[loop] stopped: ${result.stoppedBy} after ${result.iterations} iteration(s), ${result.tokens} tokens\n`));
             process.exit(loopExitCode(result.stoppedBy));
         }
-        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, defaultModeFor, headlessPlanStallCommand, nativeResume, resolveInteractive }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports },] = await Promise.all([
+        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, defaultModeFor, headlessPlanStallCommand, nativeResume, resolveInteractive }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle }, { splitBundleRef, resolveSshTarget, remoteResolveEnv }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports },] = await Promise.all([
             import('../lib/exec.js'),
             import('../lib/agents.js'),
             import('../lib/profiles.js'),
             import('../lib/secrets/bundles.js'),
+            import('../lib/secrets/remote.js'),
             import('../lib/rotate.js'),
             import('../lib/versions.js'),
             import('../lib/plugins.js'),
@@ -776,17 +777,28 @@ export function registerRunCommand(program) {
         // ones. Any resolution failure (missing keychain item, blocked exec ref)
         // aborts before spawn so the agent never sees a partial env.
         let secretsEnv = {};
-        for (const bundleName of options.secrets) {
+        for (const bundleRef of options.secrets) {
             try {
-                const { bundle, env: bundleEnv } = readAndResolveBundleEnv(bundleName, { caller: `agent ${agent}` });
-                const entries = describeBundle(bundle);
-                const counts = {};
-                for (const e of entries) {
-                    counts[e.kind] = (counts[e.kind] || 0) + 1;
+                const { bundle: bundleName, host } = splitBundleRef(bundleRef);
+                if (host) {
+                    // Remote bundle (`bundle@host`): resolve over SSH and inject
+                    // ephemerally — values never touch this machine's keychain or disk.
+                    const target = await resolveSshTarget(host);
+                    const bundleEnv = await remoteResolveEnv(target, bundleName);
+                    console.log(chalk.gray(`[secrets] Resolved ${bundleName}@${host}: ${Object.keys(bundleEnv).length} keys (remote, ephemeral)`));
+                    secretsEnv = { ...secretsEnv, ...bundleEnv };
+                }
+                else {
+                    const { bundle, env: bundleEnv } = readAndResolveBundleEnv(bundleName, { caller: `agent ${agent}` });
+                    const entries = describeBundle(bundle);
+                    const counts = {};
+                    for (const e of entries) {
+                        counts[e.kind] = (counts[e.kind] || 0) + 1;
+                    }
+                    const breakdown = Object.entries(counts).map(([k, v]) => `${v} ${k}`).join(', ');
+                    console.log(chalk.gray(`[secrets] Resolved ${bundleName}: ${entries.length} keys (${breakdown})`));
+                    secretsEnv = { ...secretsEnv, ...bundleEnv };
                 }
-                const breakdown = Object.entries(counts).map(([k, v]) => `${v} ${k}`).join(', ');
-                console.log(chalk.gray(`[secrets] Resolved ${bundleName}: ${entries.length} keys (${breakdown})`));
-                secretsEnv = { ...secretsEnv, ...bundleEnv };
             }
             catch (err) {
                 console.error(chalk.red(err.message));

package/dist/commands/secrets.js

@@ -10,6 +10,7 @@ import chalk from 'chalk';
 import * as fs from 'fs';
 import { spawnSync } from 'child_process';
 import { SSH_TARGET_RE, assertValidSshTarget } from '../lib/ssh-exec.js';
+import { parseHostsOption, remoteResolveEnv, remoteSecretsRaw, resolveSshTarget, } from '../lib/secrets/remote.js';
 import { bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, readBundle, renameBundle, rotateBundleSecret, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, } from '../lib/secrets/bundles.js';
 import { getKeychainToken, getKeychainTokens, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
@@ -160,6 +161,47 @@ export function bundleEnvToDotenv(env) {
     }
     return lines.join('\n') + '\n';
 }
+/**
+ * Browse `agents secrets <args>` on one or more remote hosts over SSH and print
+ * each host's stdout verbatim (lossless — no parsing). With >1 host the output
+ * is grouped under a `── <host> ──` header. `tty` forces an interactive ssh
+ * session (run sequentially) so a remote Touch-ID / passphrase prompt can
+ * surface (e.g. `view --reveal`); otherwise hosts are queried in parallel.
+ * Exits non-zero if any host fails.
+ */
+async function browseRemote(targets, args, tty) {
+    const multi = targets.length > 1;
+    let failures = 0;
+    const render = (name, res) => {
+        if (multi)
+            console.log(chalk.bold.cyan(`\n── ${name} ──`));
+        if (res.code === 0) {
+            if (res.stdout)
+                process.stdout.write(res.stdout.endsWith('\n') ? res.stdout : `${res.stdout}\n`);
+            if (res.stderr.trim())
+                process.stderr.write(chalk.gray(res.stderr));
+        }
+        else {
+            failures++;
+            const msg = (res.stderr || res.stdout || '').trim();
+            const why = res.timedOut ? 'timed out' : res.code === null ? 'ssh failed' : `exit ${res.code}`;
+            console.error(chalk.red(`${name}: ${why}${msg ? `: ${msg}` : ''}`));
+        }
+    };
+    if (tty) {
+        for (const t of targets) {
+            const target = await resolveSshTarget(t);
+            render(t, remoteSecretsRaw(target, args, { tty: true }));
+        }
+    }
+    else {
+        const resolved = await Promise.all(targets.map((t) => resolveSshTarget(t)));
+        const results = resolved.map((target) => remoteSecretsRaw(target, args));
+        targets.forEach((t, i) => render(t, results[i]));
+    }
+    if (failures > 0)
+        process.exit(1);
+}
 /** Strip ANSI escape sequences so padding can be computed on visible width. */
 function visibleWidth(s) {
     // eslint-disable-next-line no-control-regex
@@ -450,8 +492,15 @@ export function registerSecretsCommands(program) {
     cmd
         .command('list')
         .alias('ls')
-        .description('List configured secrets bundles')
-        .action(async () => {
+        .description('List configured secrets bundles (use --host/--hosts to list bundles on other machines over SSH)')
+        .option('--host <target>', 'List bundles on a remote host over SSH (enrolled `agents hosts` name, ssh-config alias, or user@host)')
+        .option('--hosts <list>', 'Comma-separated hosts to list in one shot, e.g. yosemite-s0,yosemite-s1')
+        .action(async (opts) => {
+        const targets = parseHostsOption(opts);
+        if (targets.length > 0) {
+            await browseRemote(targets, ['list'], false);
+            return;
+        }
         const bundles = listBundles();
         if (bundles.length === 0) {
             console.log(chalk.gray('No secrets bundles configured.'));
@@ -481,8 +530,28 @@ export function registerSecretsCommands(program) {
         .description('Show a bundle. Keychain values are masked by default — pass --reveal to see them.')
         .option('--reveal', 'Print keychain-backed values in the clear (TTY only unless --plaintext)')
         .option('--plaintext', 'Allow --reveal in non-interactive shells (use with care)')
+        .option('--host <target>', 'Show a bundle on a remote host over SSH (enrolled `agents hosts` name, ssh-config alias, or user@host)')
+        .option('--hosts <list>', 'Comma-separated hosts to show in one shot, e.g. yosemite-s0,yosemite-s1')
         .action(async (name, opts) => {
         try {
+            const targets = parseHostsOption(opts);
+            if (targets.length > 0) {
+                if (!name) {
+                    console.error(chalk.red('A bundle name is required when viewing a remote host (interactive pick needs a local terminal).'));
+                    process.exit(1);
+                }
+                const args = ['view', name];
+                if (opts.reveal)
+                    args.push('--reveal');
+                if (opts.plaintext)
+                    args.push('--plaintext');
+                // With --reveal, force a TTY so the remote keychain prompt can surface
+                // (and the remote's "--reveal in a non-TTY needs --plaintext" gate is
+                // satisfied) — only when this side is itself interactive.
+                const tty = Boolean(opts.reveal) && Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+                await browseRemote(targets, args, tty);
+                return;
+            }
             const resolvedName = name ?? (await pickBundleName('view'));
             const bundle = readBundle(resolvedName);
             const entries = describeBundle(bundle);
@@ -1094,6 +1163,7 @@ Examples:
         .option('--host <target...>', 'Push the bundle over SSH to this target (host alias or user@host); repeatable for multiple machines')
         .option('--remote-backend <backend>', 'Backend for the bundle on the remote (with --host): keychain (default) or file (passphrase-encrypted, headless-readable). file forwards AGENTS_SECRETS_PASSPHRASE over stdin.', 'keychain')
         .option('--force', 'Overwrite existing keys/items on the target (used with --to-1password and --host)')
+        .option('--format <shell|json>', 'Output for --plaintext export: shell (default) or json (lossless, machine-readable; used by remote resolve)', 'shell')
         .action(async (bundleName, opts) => {
         try {
             const { readAndResolveBundleEnv, bundleToEnvPrefix, isReservedEnvName } = await import('../lib/secrets/bundles.js');
@@ -1204,11 +1274,21 @@ Examples:
                 console.log(chalk.green(`Exported to 1Password vault '${vault}': ${parts.join(', ')}.`));
                 return;
             }
+            if (opts.format && opts.format !== 'shell' && opts.format !== 'json') {
+                console.error(chalk.red(`Invalid --format ${JSON.stringify(opts.format)}. Expected 'shell' or 'json'.`));
+                process.exit(1);
+            }
             if (!opts.plaintext) {
                 console.error(chalk.red('export prints secrets in the clear and requires --plaintext (works for TTY and pipes alike).'));
                 process.exit(1);
             }
             const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `export to shell` });
+            if (opts.format === 'json') {
+                // Lossless, machine-readable form consumed by `remoteResolveEnv` over
+                // SSH. Single object of KEY -> value; values verbatim (newlines, quotes).
+                process.stdout.write(JSON.stringify(env));
+                return;
+            }
             const prefix = bundleToEnvPrefix(resolvedBundleName);
             for (const [k, v] of Object.entries(env)) {
                 const exportKey = isReservedEnvName(k) ? `${prefix}_${k}` : k;
@@ -1226,17 +1306,24 @@ Examples:
     });
     cmd
         .command('exec <bundle> [command...]')
-        .description('Run a command with the bundle\'s secrets injected into the environment')
+        .description('Run a command with the bundle\'s secrets injected into the environment (use --host to resolve the bundle from a remote machine, ephemerally)')
+        .option('--host <target>', 'Resolve <bundle> on a remote host over SSH and inject it (ephemeral — never stored on this machine)')
         .allowUnknownOption()
-        .action(async (bundleName, commandParts) => {
+        .action(async (bundleName, commandParts, execOpts) => {
         try {
             if (commandParts.length === 0) {
                 console.error(chalk.red('Usage: agents secrets exec <bundle> -- <command...>'));
                 process.exit(1);
             }
-            const { readAndResolveBundleEnv } = await import('../lib/secrets/bundles.js');
             const [cmd, ...args] = commandParts;
-            const { env: secretEnv } = readAndResolveBundleEnv(bundleName, { caller: `command ${cmd}` });
+            let secretEnv;
+            if (execOpts.host) {
+                secretEnv = await remoteResolveEnv(await resolveSshTarget(execOpts.host), bundleName);
+            }
+            else {
+                const { readAndResolveBundleEnv } = await import('../lib/secrets/bundles.js');
+                secretEnv = readAndResolveBundleEnv(bundleName, { caller: `command ${cmd}` }).env;
+            }
             const { spawn } = await import('child_process');
             const proc = spawn(cmd, args, {
                 stdio: 'inherit',

package/dist/commands/sessions.js

@@ -753,6 +753,7 @@ export function buildResumeCommand(session) {
         case 'hermes':
         case 'grok':
         case 'kimi':
+        case 'droid':
             // Grok (and some others) sessions are captured artifacts, not resumable the same way.
             return null;
     }

package/dist/commands/ssh.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `agents devices` (registry) + `agents ssh` (smart wrapper).
+ *
+ * `agents devices` keeps a registry of SSH device profiles — platform, login
+ * user, address, and auth — self-populated from `tailscale status --json`.
+ * `agents ssh <name>` then connects through one hardened path: preflight
+ * (offline → fail fast instead of a 2-minute hang), platform-aware exec
+ * (PowerShell on Windows), and password-from-bundle auth via an askpass shim.
+ * Rendering the registry to an ssh_config include also lets plain ssh / scp /
+ * rsync / `agents sessions --host` resolve the same logical names.
+ */
+import type { Command } from 'commander';
+/** Register both `agents ssh` and `agents devices`. */
+export declare function registerSshCommands(program: Command): void;

package/dist/commands/ssh.js

@@ -0,0 +1,263 @@
+/**
+ * `agents devices` (registry) + `agents ssh` (smart wrapper).
+ *
+ * `agents devices` keeps a registry of SSH device profiles — platform, login
+ * user, address, and auth — self-populated from `tailscale status --json`.
+ * `agents ssh <name>` then connects through one hardened path: preflight
+ * (offline → fail fast instead of a 2-minute hang), platform-aware exec
+ * (PowerShell on Windows), and password-from-bundle auth via an askpass shim.
+ * Rendering the registry to an ssh_config include also lets plain ssh / scp /
+ * rsync / `agents sessions --host` resolve the same logical names.
+ */
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { readAndResolveBundleEnv } from '../lib/secrets/bundles.js';
+import { getDevice, loadDevices, removeDevice, upsertDevice, } from '../lib/devices/registry.js';
+import { nodeToDeviceInput, parseTailscaleStatus, tailscaleStatusJson, } from '../lib/devices/tailscale.js';
+import { hostNameFor, renderSshConfig } from '../lib/devices/ssh-config.js';
+import { ASKPASS_BUNDLE_ENV, ASKPASS_KEY_ENV, buildSshInvocation, writeAskpassShim, } from '../lib/devices/connect.js';
+/** Parse `user@host` or `host` into pieces. */
+function parseTarget(target) {
+    const at = target.indexOf('@');
+    if (at === -1)
+        return { host: target };
+    return { user: target.slice(0, at), host: target.slice(at + 1) };
+}
+/** One-line summary of a device for `list`. */
+function deviceSummary(d) {
+    const addr = hostNameFor(d) ?? chalk.gray('no address');
+    const online = d.tailscale
+        ? d.tailscale.online
+            ? chalk.green('online')
+            : chalk.gray('offline')
+        : chalk.gray('unknown');
+    const reach = d.tailscale?.online && !d.tailscale.direct ? chalk.yellow(' (relayed)') : '';
+    return `  ${chalk.bold(d.name.padEnd(16))} ${String(d.platform).padEnd(8)} ${(d.user ? d.user + '@' : '') + addr}  ${online}${reach}`;
+}
+/** Resolve a device or exit with a clear error. */
+async function mustGetDevice(name) {
+    const d = await getDevice(name);
+    if (!d) {
+        console.error(chalk.red(`Unknown device '${name}'. See 'agents devices list'.`));
+        process.exit(1);
+    }
+    return d;
+}
+/** Register the `agents devices` command tree. */
+function registerDevicesCommands(program) {
+    const devicesCmd = program
+        .command('devices')
+        .description('Registry of SSH device profiles (platform, user, address, auth), self-populated from Tailscale.')
+        .addHelpText('after', `
+Typical workflow:
+  agents devices sync            # ingest tailscale nodes (auto-detect platform)
+  agents devices list            # see what's registered
+  agents devices set win-mini --auth password --bundle muqsit
+  agents devices render --write  # write ~/.ssh/config.d/agents include
+`);
+    devicesCmd
+        .command('sync')
+        .description('Ingest `tailscale status --json` and create/update device profiles (auto-detects platform, address, reachability).')
+        .action(async () => {
+        const spinner = ora('Reading tailscale status...').start();
+        try {
+            const nodes = parseTailscaleStatus(tailscaleStatusJson());
+            spinner.text = `Updating ${nodes.length} device${nodes.length === 1 ? '' : 's'}...`;
+            for (const node of nodes) {
+                await upsertDevice(node.name, nodeToDeviceInput(node));
+            }
+            spinner.succeed(`Synced ${nodes.length} device${nodes.length === 1 ? '' : 's'} from Tailscale`);
+        }
+        catch (err) {
+            spinner.fail(err.message);
+            process.exit(1);
+        }
+    });
+    devicesCmd
+        .command('list')
+        .alias('ls')
+        .description('List registered devices with platform, address, and reachability.')
+        .action(async () => {
+        const reg = await loadDevices();
+        const names = Object.keys(reg).sort();
+        if (names.length === 0) {
+            console.log(chalk.gray("No devices. Run 'agents devices sync' or 'agents devices add <name> <user@host>'."));
+            return;
+        }
+        console.log(chalk.bold(`Devices (${names.length})`));
+        for (const name of names)
+            console.log(deviceSummary(reg[name]));
+    });
+    devicesCmd
+        .command('show <name>')
+        .description('Show the full profile for one device.')
+        .action(async (name) => {
+        const d = await mustGetDevice(name);
+        console.log(JSON.stringify(d, null, 2));
+    });
+    devicesCmd
+        .command('add <name> <target>')
+        .description('Add a device manually (target is user@host or host).')
+        .option('--platform <platform>', 'windows | linux | macos')
+        .action(async (name, target, opts) => {
+        try {
+            const { host, user } = parseTarget(target);
+            const isIp = /^\d{1,3}(\.\d{1,3}){3}$/.test(host);
+            const d = await upsertDevice(name, {
+                platform: opts.platform ?? undefined,
+                user,
+                address: { via: 'manual', dnsName: isIp ? undefined : host, ip: isIp ? host : undefined },
+            });
+            console.log(chalk.green(`Added device '${name}'`) + chalk.gray(` (${d.platform}, ${user ? user + '@' : ''}${host})`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    devicesCmd
+        .command('set <name>')
+        .description('Update fields on an existing device (platform, user, auth).')
+        .option('--platform <platform>', 'windows | linux | macos')
+        .option('--user <user>', 'login user')
+        .option('--auth <method>', 'key | password')
+        .option('--bundle <bundle>', 'secrets bundle holding the password (for --auth password)')
+        .option('--bundle-key <key>', "key within the bundle (default 'password')")
+        .action(async (name, opts) => {
+        try {
+            const existing = await mustGetDevice(name);
+            const auth = opts.auth || opts.bundle || opts.bundleKey
+                ? {
+                    method: opts.auth ?? existing.auth.method,
+                    bundle: opts.bundle ?? existing.auth.bundle,
+                    bundleKey: opts.bundleKey ?? existing.auth.bundleKey,
+                }
+                : undefined;
+            const d = await upsertDevice(name, {
+                platform: opts.platform ?? undefined,
+                user: opts.user ?? undefined,
+                auth,
+            });
+            console.log(chalk.green(`Updated device '${name}'`) + chalk.gray(` (auth: ${d.auth.method}${d.auth.bundle ? ` via ${d.auth.bundle}` : ''})`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    devicesCmd
+        .command('rm <name>')
+        .alias('remove')
+        .description('Remove a device from the registry.')
+        .action(async (name) => {
+        const ok = await removeDevice(name);
+        if (!ok) {
+            console.error(chalk.red(`Unknown device '${name}'.`));
+            process.exit(1);
+        }
+        console.log(chalk.green(`Removed device '${name}'`));
+    });
+    devicesCmd
+        .command('render')
+        .description('Render the registry to ssh_config. Prints to stdout, or use --write to update ~/.ssh/config.d/agents.')
+        .option('--write', 'write to ~/.ssh/config.d/agents instead of printing')
+        .action(async (opts) => {
+        const reg = await loadDevices();
+        const text = renderSshConfig(reg);
+        if (!opts.write) {
+            process.stdout.write(text);
+            return;
+        }
+        const dir = path.join(os.homedir(), '.ssh', 'config.d');
+        const file = path.join(dir, 'agents');
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        fs.writeFileSync(file, text, { mode: 0o600 });
+        console.log(chalk.green(`Wrote ${file}`));
+        console.log(chalk.gray('Add this to ~/.ssh/config (once):  Include config.d/agents'));
+    });
+}
+/** Register the `agents ssh` smart wrapper. */
+function registerSshWrapper(program) {
+    const sshCmd = program
+        .command('ssh <name> [cmd...]')
+        .description('Connect to a registered device. Preflights reachability, picks the right shell, and authenticates (key or password-from-bundle).')
+        .allowUnknownOption()
+        .addHelpText('after', `
+Examples:
+  agents ssh win-mini                       # interactive login
+  agents ssh win-mini hostname              # run a command (PowerShell on Windows)
+  agents ssh yosemite-s0 uptime             # run a command (POSIX)
+
+Devices come from 'agents devices'. Password auth pulls the secret from a
+secrets bundle via an askpass shim — the password never touches argv.
+`)
+        .action(async (name, cmd) => {
+        // Hidden askpass bridge: ssh execs the shim, which re-invokes us here.
+        if (name === '__askpass') {
+            await runAskpass();
+            return;
+        }
+        const device = await mustGetDevice(name);
+        // Preflight: a device Tailscale last saw offline would otherwise hang
+        // for the full ConnectTimeout. Fail fast with a clear message instead.
+        if (device.tailscale && !device.tailscale.online) {
+            console.error(chalk.red(`Device '${name}' is offline (Tailscale last saw it ${device.tailscale.lastSeen ?? 'a while ago'}).`));
+            console.error(chalk.gray("Run 'agents devices sync' to refresh reachability."));
+            process.exit(1);
+        }
+        if (device.tailscale?.online && !device.tailscale.direct) {
+            console.error(chalk.yellow(`Note: connection to '${name}' is relayed (DERP ${device.tailscale.relay ?? '?'}) — expect higher latency.`));
+        }
+        try {
+            const shim = writeAskpassShim();
+            const { args, env } = buildSshInvocation(device, cmd, shim);
+            const res = spawnSync('ssh', args, {
+                stdio: 'inherit',
+                env: { ...process.env, ...env },
+            });
+            process.exit(res.status ?? 1);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    // Keep the hidden askpass invocation out of help.
+    void sshCmd;
+}
+/**
+ * The askpass side of password auth. Invoked by the shim (which ssh execs with
+ * SSH_ASKPASS): read the target bundle/key from the environment the wrapper
+ * set, resolve it through the existing Keychain path, and print the password
+ * to stdout for ssh to consume.
+ */
+async function runAskpass() {
+    const bundle = process.env[ASKPASS_BUNDLE_ENV];
+    const key = process.env[ASKPASS_KEY_ENV] ?? 'password';
+    if (!bundle) {
+        console.error(`askpass: ${ASKPASS_BUNDLE_ENV} not set`);
+        process.exit(1);
+    }
+    try {
+        const { env } = readAndResolveBundleEnv(bundle, { caller: 'agents ssh' });
+        const value = env[key];
+        if (value === undefined) {
+            console.error(`askpass: key '${key}' not found in bundle '${bundle}'`);
+            process.exit(1);
+        }
+        process.stdout.write(value);
+    }
+    catch (err) {
+        console.error(`askpass: ${err?.message ?? err}`);
+        process.exit(1);
+    }
+}
+/** Register both `agents ssh` and `agents devices`. */
+export function registerSshCommands(program) {
+    registerSshWrapper(program);
+    registerDevicesCommands(program);
+}

package/dist/index.js

@@ -51,7 +51,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadBudget, loadAlias, loadPty, loadTmux, loadBrowser, loadComputer, loadHosts, loadPull, loadPush, loadRepo, loadSetup, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadBudget, loadAlias, loadPty, loadTmux, loadBrowser, loadComputer, loadHosts, loadSsh, loadPull, loadPush, loadRepo, loadSetup, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { IS_WINDOWS } from './lib/platform/index.js';
 // Transparent shim delegate: the generated Windows `.cmd` shims invoke
@@ -784,6 +784,7 @@ async function registerAllEagerCommands() {
     await reg(loadBrowser);
     await reg(loadComputer);
     await reg(loadHosts);
+    await reg(loadSsh);
     registerJobsCronAliasCommand(program, 'jobs');
     registerJobsCronAliasCommand(program, 'cron');
     registerUpgradeCommand(program);

package/dist/lib/devices/connect.d.ts

@@ -0,0 +1,34 @@
+import { type DeviceProfile } from './registry.js';
+/** Env var the askpass shim reads to know which bundle holds the password. */
+export declare const ASKPASS_BUNDLE_ENV = "AGENTS_SSH_BUNDLE";
+/** Env var the askpass shim reads to know which key in the bundle is the password. */
+export declare const ASKPASS_KEY_ENV = "AGENTS_SSH_KEY";
+/**
+ * Build the `user@host` (or bare `host`) ssh target for a device and validate
+ * it against the shared injection guard. Throws if the device has no address.
+ */
+export declare function sshTargetFor(device: DeviceProfile): string;
+/**
+ * Wrap a remote command for the device's shell. Windows devices speak
+ * PowerShell, so a bare command is run through `powershell -NoProfile
+ * -Command`; POSIX devices get the command verbatim (the remote login shell
+ * parses it). Returns undefined when no command was given (interactive login).
+ */
+export declare function wrapRemoteCommand(device: DeviceProfile, cmd: string[]): string | undefined;
+/**
+ * Build the argv (after the `ssh` program name) and the environment overlay
+ * for connecting to a device. For password auth this points `SSH_ASKPASS` at
+ * the shim and disables pubkey + the host's interactive password prompt so the
+ * shim is the only auth path. Pure (no spawn) so it is unit-testable.
+ */
+export declare function buildSshInvocation(device: DeviceProfile, cmd: string[], askpassShimPath: string): {
+    args: string[];
+    env: Record<string, string>;
+};
+/**
+ * Write (idempotently) the askpass shim — a tiny executable that re-invokes
+ * this CLI as `agents ssh __askpass`. ssh execs `SSH_ASKPASS` with no usable
+ * args, so the shim carries no secret itself; it only bridges ssh's askpass
+ * protocol back into the CLI, which then resolves the bundle.
+ */
+export declare function writeAskpassShim(): string;

package/dist/lib/devices/connect.js

@@ -0,0 +1,101 @@
+/**
+ * Connection layer for `agents ssh` — turn a device profile into a real ssh
+ * invocation, with platform-aware command wrapping and password-from-bundle
+ * auth.
+ *
+ * Auth is genuinely two first-class, non-interactive methods:
+ *  - `key`      — the system ssh agent / on-disk keys (BatchMode-friendly).
+ *  - `password` — the secret is pulled from a Keychain-backed secrets bundle
+ *                 by an askpass shim. The wrapper points `SSH_ASKPASS` at the
+ *                 shim and forces its use; ssh calls the shim, the shim calls
+ *                 back into `agents ssh __askpass`, which resolves the bundle
+ *                 via the existing `readAndResolveBundleEnv` path and prints
+ *                 the password to ssh. The password never touches argv or an
+ *                 expect buffer.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { assertValidSshTarget, shellQuote } from '../ssh-exec.js';
+import { getCacheDir } from '../state.js';
+import { hostNameFor } from './ssh-config.js';
+/** Env var the askpass shim reads to know which bundle holds the password. */
+export const ASKPASS_BUNDLE_ENV = 'AGENTS_SSH_BUNDLE';
+/** Env var the askpass shim reads to know which key in the bundle is the password. */
+export const ASKPASS_KEY_ENV = 'AGENTS_SSH_KEY';
+/**
+ * Build the `user@host` (or bare `host`) ssh target for a device and validate
+ * it against the shared injection guard. Throws if the device has no address.
+ */
+export function sshTargetFor(device) {
+    const host = hostNameFor(device);
+    if (!host) {
+        throw new Error(`Device '${device.name}' has no address (dnsName/ip). Run \`agents devices sync\` or \`agents devices add\`.`);
+    }
+    const target = device.user ? `${device.user}@${host}` : host;
+    assertValidSshTarget(target);
+    return target;
+}
+/**
+ * Wrap a remote command for the device's shell. Windows devices speak
+ * PowerShell, so a bare command is run through `powershell -NoProfile
+ * -Command`; POSIX devices get the command verbatim (the remote login shell
+ * parses it). Returns undefined when no command was given (interactive login).
+ */
+export function wrapRemoteCommand(device, cmd) {
+    if (cmd.length === 0)
+        return undefined;
+    const joined = cmd.join(' ');
+    if (device.shell === 'powershell') {
+        return `powershell -NoProfile -Command ${shellQuote(joined)}`;
+    }
+    return joined;
+}
+/**
+ * Build the argv (after the `ssh` program name) and the environment overlay
+ * for connecting to a device. For password auth this points `SSH_ASKPASS` at
+ * the shim and disables pubkey + the host's interactive password prompt so the
+ * shim is the only auth path. Pure (no spawn) so it is unit-testable.
+ */
+export function buildSshInvocation(device, cmd, askpassShimPath) {
+    const target = sshTargetFor(device);
+    const remote = wrapRemoteCommand(device, cmd);
+    const env = {};
+    const args = ['-o', 'StrictHostKeyChecking=accept-new', '-o', 'ConnectTimeout=10'];
+    if (device.auth.method === 'password') {
+        if (!device.auth.bundle) {
+            throw new Error(`Device '${device.name}' uses password auth but has no secrets bundle. Set one with \`agents devices set ${device.name} --bundle <name>\`.`);
+        }
+        env.SSH_ASKPASS = askpassShimPath;
+        env.SSH_ASKPASS_REQUIRE = 'force';
+        env[ASKPASS_BUNDLE_ENV] = device.auth.bundle;
+        env[ASKPASS_KEY_ENV] = device.auth.bundleKey ?? 'password';
+        args.push('-o', 'PreferredAuthentications=password', '-o', 'PubkeyAuthentication=no', '-o', 'NumberOfPasswordPrompts=1');
+    }
+    else {
+        args.push('-o', 'BatchMode=yes');
+    }
+    // An interactive login (no remote command) needs a real tty.
+    if (!remote)
+        args.push('-tt');
+    args.push(target);
+    if (remote)
+        args.push(remote);
+    return { args, env };
+}
+/**
+ * Write (idempotently) the askpass shim — a tiny executable that re-invokes
+ * this CLI as `agents ssh __askpass`. ssh execs `SSH_ASKPASS` with no usable
+ * args, so the shim carries no secret itself; it only bridges ssh's askpass
+ * protocol back into the CLI, which then resolves the bundle.
+ */
+export function writeAskpassShim() {
+    const dir = path.join(getCacheDir(), 'devices');
+    fs.mkdirSync(dir, { recursive: true });
+    const shimPath = path.join(dir, 'askpass.sh');
+    // process.execPath = the node/bun binary; argv[1] = this CLI's entry script.
+    const node = process.execPath;
+    const entry = process.argv[1] ?? '';
+    const body = `#!/bin/sh\n# Generated by agents-cli — bridges ssh SSH_ASKPASS back into the CLI.\nexec ${shellQuote(node)} ${shellQuote(entry)} ssh __askpass\n`;
+    fs.writeFileSync(shimPath, body, { mode: 0o700 });
+    return shimPath;
+}