@phnx-labs/agents-cli 1.22.114 → 1.22.116

package/dist/commands/browser.js

@@ -25,7 +25,11 @@ import { withActorEnv } from '../lib/hosts/dispatch.js';
 import { streamAgentsOnHost, passthroughSshOptions, } from '../lib/hosts/passthrough.js';
 import { buildRemoteAgentsInvocation, HOST_ROUTING_SPECS, stripRoutingFlags, } from '../lib/hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
-import { sshExec, SSH_OPTS } from '../lib/ssh-exec.js';
+import { sshExec, SSH_OPTS, sshStreamWithArgs } from '../lib/ssh-exec.js';
+import { getBrowserRuntimeDir } from '../lib/state.js';
+import { buildSshInvocation, writeAskpassShim } from '../lib/devices/connect.js';
+import { resolveDeviceProfile } from '../lib/devices/resolve-profile.js';
+import { resolveDeviceTarget } from '../lib/devices/resolve-target.js';
 import { flagValue } from '../lib/hosts/routing-flag.js';
 import { browserTaskPicker } from './browser-picker.js';
 import { assertRemoteControlAllowed, isFleetRemoteInvocation } from '../lib/browser/remote-control.js';
@@ -35,7 +39,7 @@ import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 import { buildHar } from '../lib/browser/har.js';
 import { getCliVersion } from '../lib/version.js';
 import { runBrowserIPCStream } from '../lib/browser/stream.js';
-import { machineId } from '../lib/machine-id.js';
+import { machineId, normalizeHost } from '../lib/machine-id.js';
 import { isArcRunning } from '../lib/browser/drivers/arc.js';
 import { resolveBrowserTarget } from '../lib/browser/resolve-target.js';
 /**
@@ -179,6 +183,158 @@ export function remoteStartTaskName(stdout, explicit) {
     }
     return trimmed.split('\n').map((line) => line.trim()).find(Boolean);
 }
+/**
+ * Fetch an absolute remote file into a private local path, bounded.
+ *
+ * Bounded for real, not by a pre-flight `stat`: the byte budget is enforced on the
+ * stream as it arrives (`sshExecRawStream` + `cat`), so a file that grows between
+ * a size check and the copy — or a peer that lies about the size — still cannot
+ * spend more than the budget. `scp` could not do this; it would transfer
+ * everything before this process got a chance to refuse.
+ *
+ * The local file is written 0600 inside a 0700 directory, because a capture can
+ * show anything that was on the peer's screen and a world-readable temp path
+ * would publish it to every local user.
+ */
+/**
+ * The command that streams one file's RAW BYTES to stdout on the device's shell.
+ *
+ * Platform-correct, not one command with a portable-looking name. On Windows
+ * `cat` is an alias for `Get-Content`, which is a TEXT reader: it decodes the
+ * file, splits it into lines, and re-encodes on output — so a screenshot arrives
+ * corrupted rather than merely reordered. The .NET path opens a `FileStream` and
+ * copies it into the raw stdout handle, bypassing PowerShell's object/text
+ * pipeline entirely, which is the only way binary survives.
+ */
+export function remoteReadFileArgv(remotePath, shell) {
+    if (shell === 'powershell') {
+        // Single-quoted inside the script with pwsh's own doubling, because this whole
+        // script is ONE argv token to the outer powershell.
+        const literal = remotePath.replace(/'/g, "''");
+        return ['powershell', '-NoProfile', '-Command', [
+                '$ErrorActionPreference=' + "'Stop';",
+                `$in=[System.IO.File]::OpenRead('${literal}');`,
+                'try{$out=[System.Console]::OpenStandardOutput();$in.CopyTo($out);$out.Flush()}finally{$in.Dispose()}',
+            ].join(' ')];
+    }
+    // `--` so a path that begins with a dash is a path, not an option.
+    return ['cat', '--', remotePath];
+}
+/**
+ * Largest capture `browser show --device` will pull. A capture is a screenshot,
+ * a PDF or a short recording; anything past this is not something a viewer should
+ * stream over ssh, and the cap is what makes the transfer BOUNDED rather than
+ * "however big the peer's file happens to be".
+ */
+export const REMOTE_VIEW_MAX_BYTES = 64 * 1024 * 1024;
+/** Write a whole buffer, looping until it is all out. */
+function writeFully(handle, chunk) {
+    let offset = 0;
+    while (offset < chunk.length) {
+        // `writeSync` may write FEWER bytes than asked (a signal, a pipe boundary),
+        // and ignoring the return value silently truncated the file mid-capture.
+        const wrote = fs.writeSync(handle, chunk, offset, chunk.length - offset);
+        if (wrote <= 0)
+            throw new Error('local write made no progress');
+        offset += wrote;
+    }
+}
+/**
+ * Fetch an absolute remote file into a private local path, bounded.
+ *
+ * Auth is the CANONICAL device path, not a hand-rolled ssh: `buildSshInvocation`
+ * supplies the askpass shim for a password-auth box, `-i`/`IdentitiesOnly` for an
+ * explicit identity file, and the managed known-hosts pinning. Building the ssh
+ * args here instead meant a password-auth device could not be reached at all and
+ * an explicit `identityFile` was silently ignored.
+ *
+ * Bounded for real, not by a pre-flight `stat`: the byte budget is enforced on the
+ * stream as it arrives, so a file that grows between a size check and the copy — or
+ * a peer that misreports its size — still cannot spend more than the budget.
+ *
+ * The local file is written 0600 inside a 0700 directory, because a capture can
+ * show anything that was on the peer's screen and a world-readable temp path
+ * would publish it to every local user.
+ */
+export async function fetchRemoteFileForViewing(device, remotePath, localPath, opts = {}) {
+    const posixAbsolute = path.posix.isAbsolute(remotePath);
+    const windowsAbsolute = /^[A-Za-z]:[\\/]/.test(remotePath) || /^\\\\/.test(remotePath);
+    if (!posixAbsolute && !windowsAbsolute) {
+        throw new Error(`Remote path must be absolute: got "${remotePath}".\n`
+            + 'This machine cannot resolve the peer\'s working directory, so a relative path\n'
+            + 'would name a different file there than you meant here.');
+    }
+    // `resolveDeviceTarget` is the SAME resolver `agents ssh` uses, so it yields the
+    // full device profile — platform, shell and auth — that `buildSshInvocation`
+    // needs. `resolveHost` returns a hosts-registry `Host`, which carries none of
+    // that: with it, a password-auth device could not be reached and an explicit
+    // identityFile was silently dropped.
+    const resolved = await resolveDeviceTarget(device);
+    if (!resolved)
+        throw new Error(`Unknown device "${device}". Next: agents devices list`);
+    const profile = resolveDeviceProfile(resolved);
+    const maxBytes = opts.maxBytes ?? REMOTE_VIEW_MAX_BYTES;
+    // A POSIX device cannot read a Windows path and vice versa; saying so here beats
+    // a confusing shell error from the peer.
+    if (profile.shell === 'powershell' && posixAbsolute && !windowsAbsolute) {
+        throw new Error(`"${remotePath}" is a POSIX path but ${device} runs PowerShell. Pass the Windows path (e.g. C:\\Users\\…).`);
+    }
+    if (profile.shell !== 'powershell' && windowsAbsolute) {
+        throw new Error(`"${remotePath}" is a Windows path but ${device} is a POSIX host. Pass the absolute POSIX path.`);
+    }
+    const resolvedLocal = path.resolve(localPath);
+    const dir = path.dirname(resolvedLocal);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    fs.chmodSync(dir, 0o700);
+    const handle = fs.openSync(resolvedLocal, 'w', 0o600);
+    let written = 0;
+    let overflow = false;
+    const controller = new AbortController();
+    try {
+        // `argv: true` is what makes a path containing a space or a quote survive —
+        // the same exact-token delivery `agents ssh --argv` exposes.
+        const { args, env } = buildSshInvocation(profile, remoteReadFileArgv(remotePath, profile.shell), writeAskpassShim(), {}, { argv: true });
+        const result = await sshStreamWithArgs({
+            args,
+            env,
+            timeoutMs: opts.timeoutMs ?? 120_000,
+            signal: controller.signal,
+            onStdout: (chunk) => {
+                if (overflow)
+                    return;
+                if (written + chunk.length > maxBytes) {
+                    overflow = true;
+                    controller.abort();
+                    return;
+                }
+                writeFully(handle, chunk);
+                written += chunk.length;
+            },
+        });
+        if (overflow) {
+            throw new Error(`Refusing to pull ${device}:${remotePath}: larger than the ${maxBytes}-byte view budget.`);
+        }
+        if (result.timedOut)
+            throw new Error(`Timed out pulling ${device}:${remotePath}.`);
+        if (result.code !== 0) {
+            const detail = result.stderr.toString('utf8').trim();
+            throw new Error(`Failed to read ${device}:${remotePath}${detail ? `: ${detail}` : ` (ssh exited ${result.code})`}`);
+        }
+        if (written === 0)
+            throw new Error(`${device}:${remotePath} is empty or was not readable.`);
+    }
+    catch (error) {
+        // Never leave a partial file behind for a viewer to open as if it were whole.
+        try {
+            fs.unlinkSync(resolvedLocal);
+        }
+        catch { /* nothing to clean */ }
+        throw error;
+    }
+    finally {
+        fs.closeSync(handle);
+    }
+}
 async function pullRemoteFile(device, remotePath, localPath) {
     const host = await resolveHost(device);
     if (!host) {
@@ -2071,8 +2227,14 @@ function registerTaskCommands(browser) {
     });
     browser
         .command('show <url>')
-        .description('Open a URL for a human to read: goes to browser.viewer (default: browser.profile), and binds no task')
+        .description('Open a URL or local file for a human to read: goes to browser.viewer (default: browser.profile), and binds no task')
         .option('--os-browser', 'Use the OS default handler instead of the configured viewer')
+        // `--device` here names WHERE THE FILE IS, not where to open it. `show` is the
+        // one browser verb narrowly exempt from the task-routing refusal
+        // (`REJECT_DEVICE_MESSAGE`) because it binds no task and has nothing to route:
+        // it is a local viewer, so the flag can only mean "the source lives there".
+        // Every other verb still refuses `--device` — a task is bound at `start`.
+        .option('--device <name>', 'fetch the file from this device, then view it locally (absolute path only)')
         .option('--json', 'Output machine-readable JSON')
         .action(async (url, opts) => {
         // The entry point external tools need. `navigate` binds a task, which the
@@ -2083,20 +2245,48 @@ function registerTaskCommands(browser) {
         // drive letter (`C:\Users\me\plan.html`), so a real path was treated as a
         // URL. A scheme is at least two characters.
         const isLocalFile = !/^[a-z][a-z0-9+.-]+:/i.test(url);
-        const outcome = isLocalFile
-            ? await showFile(path.resolve(url), { osBrowser: opts.osBrowser })
+        let localTarget = isLocalFile ? path.resolve(url) : undefined;
+        let fetched;
+        if (opts.device) {
+            // A URL is already reachable from here, so `--device` with one is a
+            // contradiction rather than a no-op: it says the source is remote while
+            // naming something that is not a file on that peer.
+            if (!isLocalFile) {
+                console.error(`--device names the device holding a FILE, so it cannot be combined with a URL.\n  Drop --device to open ${url} here, or pass an absolute path on ${opts.device}.`);
+                process.exit(1);
+            }
+            // The peer's path, verbatim — NOT path.resolve()'d, which would rewrite it
+            // against this machine's cwd and name a different file there.
+            const remotePath = url;
+            const dir = path.join(getBrowserRuntimeDir(), 'remote-views');
+            fetched = path.join(dir, `${normalizeHost(opts.device)}-${Date.now()}-${path.basename(remotePath) || 'capture'}`);
+            try {
+                await fetchRemoteFileForViewing(opts.device, remotePath, fetched);
+            }
+            catch (error) {
+                console.error(error.message);
+                process.exit(1);
+            }
+            localTarget = fetched;
+        }
+        const outcome = localTarget
+            ? await showFile(localTarget, { osBrowser: opts.osBrowser })
             : await showUrl(url, { osBrowser: opts.osBrowser });
+        // The fetched copy is what a viewer actually opened, so it is what the
+        // caller is told about — pointing at the peer's path would name a file that
+        // is not on this machine.
+        const shown = fetched ?? url;
         if (opts.json) {
-            console.log(JSON.stringify(outcome, null, 2));
+            console.log(JSON.stringify({ ...outcome, ...(fetched ? { source: `${opts.device}:${url}`, local: fetched } : {}) }, null, 2));
         }
         else if (outcome.via === 'none') {
-            console.error(`Could not open a browser — open this yourself:\n  ${url}`);
+            console.error(`Could not open a browser — open this yourself:\n  ${shown}`);
         }
         else if (outcome.via === 'profile') {
-            console.log(`Shown in ${outcome.profile}: ${url}`);
+            console.log(`Shown in ${outcome.profile}: ${shown}`);
         }
         else {
-            console.log(`Opened in the OS default browser: ${url}`);
+            console.log(`Opened in the OS default browser: ${shown}`);
         }
         if (outcome.via === 'none')
             process.exit(1);
@@ -2572,6 +2762,11 @@ function registerTaskCommands(browser) {
                 // instead of the raw `comet-local@endpoint-0` key (RUSH-2709).
                 const endpointLabel = profile.endpoint ? `endpoint: ${profile.endpoint}, ` : '';
                 console.log(`\n${profile.name} (${endpointLabel}${portLabel}, ${pidLabel})`);
+                // A profile whose live state could not be read is still listed, and
+                // says so — it is not silently dropped and not shown as healthy.
+                if (profile.unavailable) {
+                    console.log(`  Unavailable: ${profile.unavailable}`);
+                }
                 if (profile.tasks.length === 0) {
                     console.log('  No active tasks');
                 }
@@ -2593,6 +2788,12 @@ function registerTaskCommands(browser) {
                             String(task.tabCount).padEnd(6) +
                             domains.slice(0, 20).padEnd(22) +
                             age);
+                        // The recorded tab count above is what the task owns on disk; this
+                        // says the live tabs behind it could not be read, so the count is
+                        // not mistaken for verified-live tabs.
+                        if (task.unavailable) {
+                            console.log('  '.padEnd(14) + `↳ tabs unreadable: ${task.unavailable}`);
+                        }
                     }
                 }
             }

package/dist/commands/doctor.d.ts

@@ -18,9 +18,8 @@
  * Read-only always: doctor diagnoses, it never mutates. To fix the gaps it
  * finds — install missing resources, repair Claude-invalid plugin manifests,
  * refresh stale plugins, reconcile drift, repair hook runtime shims — run
- * `agents sync <agent>@all` (the one fixer, a superset of the old `doctor
- * --fix`). Run `agents prune cleanup` to act on orphan readouts. `--fix` is a
- * deprecated no-op that now errors with a pointer to `agents sync`.
+ * `agents sync <agent>@all` (the one fixer). Run `agents prune cleanup` to act
+ * on orphan readouts.
  */
 import type { Command } from 'commander';
 import { type FleetInventory } from '../lib/devices/fleet-divergence.js';

package/dist/commands/doctor.js

@@ -1251,7 +1251,6 @@ export function registerDoctorCommand(program) {
         .description('Diagnose CLI availability, sync status, and resource divergence (optionally for a specific agent[@version]).')
         .option('--json', 'Output machine-readable JSON')
         .option('--diff', 'In target mode, include unified diffs for divergent files')
-        .option('--fix', '(deprecated) doctor is diagnose-only — this errors with a pointer to `agents sync`, the one fixer')
         .option('--kind <kinds>', 'Restrict to comma-separated resource kinds (commands,skills,hooks,rules,mcp,permissions,subagents,plugins,workflows,memory)')
         .option('--cwd <path>', 'Resolution cwd for project layer detection (default: process.cwd())')
         .option('--adopt <agent>', "Take over the agent's native launcher that shadows the shim (symlink it to the version-managed shim; reversible with --release)")
@@ -1381,16 +1380,6 @@ export function registerDoctorCommand(program) {
             }
             return;
         }
-        // `doctor --fix` moved to `agents sync` — doctor is diagnose-only now.
-        // Keep the flag for one release as a signpost: it never heals, it points at
-        // the one fixer and exits non-zero so scripts and muscle memory get a clear
-        // redirect instead of a silent no-op.
-        if (opts.fix) {
-            const where = target ? `agents sync ${target}` : 'agents sync <agent>@all';
-            console.error(chalk.yellow('`agents doctor --fix` has moved to `agents sync`.'));
-            console.error(chalk.gray(`  doctor now only diagnoses. To fix, run: ${where}`));
-            process.exit(1);
-        }
         if (!target) {
             // Singleflight + short-TTL cache for the bare `doctor --json` overview.
             // This overview probes every host CLI, every agent's sign-in, and every

package/dist/commands/events.d.ts

@@ -42,13 +42,11 @@ export interface EventsOptions {
     limit?: string;
     json?: boolean;
     follow?: boolean;
-    /** @deprecated Prefer --include ops / --exclude activity */
-    audit?: boolean;
     include?: string;
     exclude?: string;
 }
 /** Add the one canonical event-reader option surface to a command or alias. */
-export declare function addEventsReadOptions(command: Command, includeAuditFlag?: boolean): Command;
+export declare function addEventsReadOptions(command: Command): Command;
 /** Canonical reader used by `agents events`, `agents events audit`, and `agents logs`. */
 export declare function runEventsCommand(options: EventsOptions, forceAudit?: boolean): Promise<void>;
 /** Shared by `events stats` and the `logs stats` alias. */

package/dist/commands/events.js

@@ -195,7 +195,7 @@ function registerEmitSubcommand(events) {
     });
 }
 /** Add the one canonical event-reader option surface to a command or alias. */
-export function addEventsReadOptions(command, includeAuditFlag = true) {
+export function addEventsReadOptions(command) {
     command
         .option('--include <families>', `Only these families (comma-sep): ${EVENT_FAMILIES.join(', ')}`)
         .option('--exclude <families>', `Drop these families (comma-sep): ${EVENT_FAMILIES.join(', ')}`)
@@ -211,9 +211,6 @@ export function addEventsReadOptions(command, includeAuditFlag = true) {
         .option('--limit <n>', 'Max records to show; 0 for no cap (default 50)', '50')
         .option('--json', 'Output raw records as JSON')
         .option('-f, --follow', "Tail today's operational log live");
-    if (includeAuditFlag) {
-        command.option('--audit', 'Deprecated: operational events only — prefer --include ops or --exclude activity');
-    }
     return command;
 }
 /** Canonical reader used by `agents events`, `agents events audit`, and `agents logs`. */
@@ -242,11 +239,11 @@ export async function runEventsCommand(options, forceAudit = false) {
         process.exitCode = 2;
         return;
     }
-    // --audit / forceAudit = ops-only when no family flags. Families own the
-    // source selection via applyFamilies — never override includeActivity after.
+    // forceAudit (`events audit` / `logs`) = ops-only when no family flags. Families
+    // own the source selection via applyFamilies — never override includeActivity after.
     const includeActivity = (includeFamilies !== undefined || excludeFamilies !== undefined)
         ? true
-        : !(forceAudit || options.audit);
+        : !forceAudit;
     const fetched = readUnifiedEvents({
         startDate,
         eventTypes: options.event && options.event.length ? options.event : undefined,

package/dist/commands/exec.d.ts

@@ -53,7 +53,6 @@ interface ExecCommandActionOptions {
      * @deprecated Hidden alias for `--device auto`. Resolved before host dispatch.
      * Remove after one release.
      */
-    smart?: boolean;
     acp?: boolean;
     yes?: boolean;
     loop?: boolean;