@phnx-labs/agents-cli 1.20.62 → 1.20.64

package/dist/lib/hosts/passthrough.js

@@ -1,10 +1,8 @@
 /**
  * Generic `--host` passthrough — the single choke point that runs an allowlisted
- * `agents <command>` on a remote host instead of locally, so read-only and
- * config commands (`view`, `usage`, `cost`, `doctor`, `inspect`, `list`, `sync`)
- * and the team lifecycle (`teams …`) all gain remote support with no per-command
- * code. Called once from `index.ts` before commander parses; returns `true` when
- * it handled the invocation (the local command must then NOT run).
+ * `agents <command>` on a remote host instead of locally. Called once from
+ * `index.ts` before commander parses; returns `true` when it handled the
+ * invocation (the local command must then NOT run).
  *
  * Transport is SSH (via `ssh-exec.ts`), never a daemon: SSH is the one hardened
  * choke point already used everywhere, and it gives auth + encryption + host-key
@@ -12,9 +10,11 @@
  * long-running case — `teams start --watch` — dispatches detached so the remote
  * supervisor outlives a dropped connection.
  *
- * `run`, `sessions`, and `feed` are deliberately absent from the table below:
- * they own richer `--host` handling in their own command actions (detached run
- * dispatch or multi-host fan-out) and must fall through to it.
+ * Commands with their own richer `--host` handling (`run`/`sessions`/`feed`/
+ * `computer`/`secrets`/`logs`/…) are listed in {@link OWN_HOST_COMMANDS} and
+ * fall through to their local actions. Everything else either routes via this
+ * table or, when `--host`/`--device` is present, exits with a clear
+ * "not supported" message — never commander's raw `unknown option`.
  */
 import chalk from 'chalk';
 import { assertValidSshTarget, sshStream } from '../ssh-exec.js';
@@ -24,19 +24,90 @@ import { dispatchAgentsCommand } from './dispatch.js';
 import { stripRoutingFlags, buildRemoteAgentsInvocation, HOST_ROUTING_SPECS, } from './remote-cmd.js';
 import { resolveRemoteOsSync } from './remote-os.js';
 import { machineId } from '../session/sync/config.js';
+/**
+ * First-class groups that run transparently on a remote via SSH when
+ * `--host`/`--device` is present. Keep both canonical names and aliases
+ * (`repo`/`repos`, `exec`/`run`) so either argv form routes the same way.
+ *
+ * Prefer adding here over per-command SSH code — this is the single choke point.
+ */
 const REMOTE_PASSTHROUGH = {
+    // status / inspect
     view: {},
+    inspect: {},
+    doctor: {},
+    status: {},
+    check: {},
+    list: {},
     usage: {},
     cost: {},
     output: {},
-    doctor: {},
-    inspect: {},
-    list: {},
+    budget: {},
+    // config / resources
     sync: { nonInteractive: ['--yes'] },
+    pull: {},
+    push: {},
+    repo: {},
+    repos: {},
+    plugins: {},
+    skills: {},
+    hooks: {},
+    commands: {},
+    rules: {},
+    memory: {},
+    permissions: {},
+    perms: {},
+    mcp: {},
+    cli: {},
+    subagents: {},
+    workflows: {},
+    packages: {},
+    models: {},
+    profiles: {},
+    defaults: {},
+    alias: {},
+    // lifecycle
     teams: {},
     message: {},
     routines: {},
+    jobs: {},
+    cron: {},
+    // misc remote-sensible
+    prune: {},
+    trash: {},
+    restore: {},
+    worktree: {},
+    events: {},
+    audit: {},
+    lock: {},
+    feedback: {},
+    wallet: {},
+    daemon: {},
+    pty: {},
+    tmux: {},
+    watchdog: {},
+    factory: {},
+    browser: {},
+    versions: {},
 };
+/**
+ * Commands that register and interpret `--host`/`--device` themselves — must
+ * fall through to local commander even when the flag is present. Do not add
+ * these to {@link REMOTE_PASSTHROUGH}.
+ */
+const OWN_HOST_COMMANDS = new Set([
+    'run',
+    'exec', // deprecated alias of run
+    'sessions',
+    'feed',
+    'computer',
+    'secrets',
+    'logs',
+    'hosts',
+    'ssh',
+    'devices',
+    'fleet', // alias of devices
+]);
 /** `--no-tty` is stripped like the routing flags but carries no value. */
 const STRIP_SPECS = [...HOST_ROUTING_SPECS, { long: 'no-tty', takesValue: false }];
 /** Pull the value of `--host`/`-H`/`--remote-cwd` (any form) out of an argv. */
@@ -83,15 +154,26 @@ async function resolveTargetHost(name, any) {
 /**
  * Route `agents <command> … --host <name>` to a remote if the command is
  * host-routable and a `--host` (or its `--device` alias) was given. Returns
- * `false` (run locally) when neither flag is present, the command isn't in the
- * table, or the target is this very machine.
+ * `false` (run locally) when neither flag is present, the command owns its own
+ * host handling, the target is this very machine, or placement flags need the
+ * local action. Returns `true` after printing a clear error when the flag is
+ * present on a command that is neither routable nor self-handling — so the user
+ * never sees commander's raw `unknown option '--host'`.
  *
  * @param command the resolved subcommand name (`process.argv`'s first non-flag).
  * @param allArgs `process.argv.slice(2)` — the command name followed by its args.
  */
 export async function maybeRunOnHost(command, allArgs) {
-    const spec = REMOTE_PASSTHROUGH[command];
-    if (!spec)
+    const hostFlag = flagValue(allArgs, 'host', 'H');
+    const deviceFlag = flagValue(allArgs, 'device');
+    const hostName = hostFlag ?? deviceFlag;
+    if (!hostName)
+        return false;
+    // Commands with their own richer --host semantics must reach local commander
+    // BEFORE any single-target conflict gate. sessions/feed merge --host and
+    // --device into a multi-host list; rejecting "conflicting" pairs would break
+    // `agents sessions --host a --device b` / `agents feed --host a --device b`.
+    if (OWN_HOST_COMMANDS.has(command))
         return false;
     // Placement, not routing: `teams add`/`teams create` read `--device`/`--devices`
     // (and `--host`/`--hosts`) as WHERE to place a teammate / the team pool — the
@@ -107,16 +189,6 @@ export async function maybeRunOnHost(command, allArgs) {
             return false;
         }
     }
-    // `--device` is a first-class alias of `--host` (mirrors `agents run`); the
-    // device registry is the source of truth for machine identity. Reject a
-    // conflicting pair rather than silently preferring one — same rule as run.
-    const hostFlag = flagValue(allArgs, 'host', 'H');
-    const deviceFlag = flagValue(allArgs, 'device');
-    if (hostFlag && deviceFlag && hostFlag !== deviceFlag) {
-        console.error(chalk.red('Conflicting --host/--device values — pass just one.'));
-        process.exitCode = 1;
-        return true;
-    }
     // `--hosts` is always a generic fleet flag — bail for every command so the
     // local aggregator handles it. `--devices` is fan-out on most commands but
     // a placement flag on `routines` (which devices may run the routine), so
@@ -125,14 +197,32 @@ export async function maybeRunOnHost(command, allArgs) {
         return false;
     if (allArgs.includes('--devices') && command !== 'routines')
         return false;
-    const hostName = hostFlag ?? deviceFlag;
-    if (!hostName)
-        return false;
+    const spec = REMOTE_PASSTHROUGH[command];
+    if (!spec) {
+        // Flag was accepted (no raw commander "unknown option") but this group has
+        // no remote semantics — say so clearly instead of falling through.
+        console.error(chalk.red(`\`agents ${command}\` does not support --host/--device (no remote interpretation).`) +
+            chalk.gray(' Run without the flag, or use a host-routable group (repos, view, sync, teams, doctor, …).'));
+        process.exitCode = 1;
+        return true;
+    }
+    // Single-target remote path only: reject a conflicting --host/--device pair
+    // rather than silently preferring one (same rule as `agents run`).
+    if (hostFlag && deviceFlag && hostFlag !== deviceFlag) {
+        console.error(chalk.red('Conflicting --host/--device values — pass just one.'));
+        process.exitCode = 1;
+        return true;
+    }
     // Running against your own machine is just a local run — skip the SSH round-trip.
     // `machineId()` is the same self-identifier the device registry and session
     // sync use (lowercased short hostname); compare case-insensitively.
-    if (hostName.toLowerCase() === machineId())
+    // Strip the routing flags from process.argv so the local command never sees
+    // an unregistered `--host`/`--device` and dies with "unknown option".
+    if (hostName.toLowerCase() === machineId()) {
+        const stripped = stripRoutingFlags(allArgs, STRIP_SPECS);
+        process.argv = [process.argv[0], process.argv[1], ...stripped];
         return false;
+    }
     const remoteCwd = flagValue(allArgs, 'remote-cwd');
     const any = allArgs.includes('--any');
     let host;

package/dist/lib/mailbox-gc.js

@@ -9,7 +9,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { getMailboxRootDir } from './state.js';
-import { mailboxDir, isValidMailboxId, readMessage, } from './mailbox.js';
+import { mailboxDir, isValidMailboxId, readMessage, sweepExpired, } from './mailbox.js';
 import { listBlocks, removeBlock } from './feed.js';
 const DEFAULT_MAX_CONSUMED_AGE_MINUTES = 24 * 60;
 function consumedAgeMinutes(file, now) {
@@ -134,21 +134,9 @@ export function gcMailbox(activeBoxIds, options = {}) {
             }
         }
         else {
-            // Live box: lazy expiry is handled by drain/peek, but sweep here for GC metrics.
-            // We still need to read expired messages; reuse readMessage directly to avoid
-            // importing sweepExpired and duplicating logic.
-            for (const sub of ['inbox', 'processing']) {
-                const dir = path.join(boxDir, sub);
-                for (const file of jsonFiles(dir)) {
-                    const msg = readMessage(path.join(dir, file));
-                    if (msg && msg.expiresAt) {
-                        const ts = Date.parse(msg.expiresAt);
-                        if (!Number.isNaN(ts) && ts <= now.getTime()) {
-                            result.messagesDroppedExpired++;
-                        }
-                    }
-                }
-            }
+            // Live box: archive expired messages (same path as drain/peek) so GC does
+            // not leave expired files in inbox/processing while only bumping metrics.
+            result.messagesDroppedExpired += sweepExpired(boxDir, name, now);
             result.consumedPruned += pruneConsumed(boxDir, maxConsumedAgeMinutes, now);
         }
     }

package/dist/lib/mailbox.d.ts

@@ -69,3 +69,42 @@ export declare function drain(boxDir: string, boxId?: string, now?: Date): Mailb
 export declare function peek(boxDir: string, boxId?: string, now?: Date): MailboxMessage[];
 /** Delete pending (not-yet-claimed) inbox messages. Returns the count removed. */
 export declare function clear(boxDir: string): number;
+/** Which bucket a stored message currently sits in. */
+export type MailboxState = 'inbox' | 'processing' | 'consumed';
+/** A message read back from a box, tagged with the bucket it was found in. */
+export interface StoredMessage extends MailboxMessage {
+    state: MailboxState;
+}
+/** A stored message enriched with the mailbox identity used by comms renderers. */
+export interface CommsMsg {
+    from: string;
+    to: string;
+    toLabel: string;
+    ts: string;
+    text: string;
+    state: MailboxState;
+    box: string;
+}
+/**
+ * Enumerate the box ids under `root` (directory names that are valid mailbox
+ * ids). Read-only; does not create the root. Sorted for stable output.
+ */
+export declare function listBoxes(root?: string): string[];
+/**
+ * Read every message in a box across all three buckets (inbox, processing,
+ * consumed) WITHOUT consuming, sweeping, or archiving anything. Unlike `peek`,
+ * this includes `consumed/` — the delivered history — so callers can surface a
+ * communication log. Each row is tagged with its bucket. Sorted FIFO by msgId
+ * (which is time-sortable), oldest first.
+ */
+export declare function readBox(boxDir: string): StoredMessage[];
+/**
+ * Poll the complete spool and yield each message once when its box/msgId pair
+ * first appears. Existing messages establish the initial baseline unless
+ * `backfill` is requested; moving a message between buckets does not re-emit it.
+ */
+export declare function watchMessages(root: string, opts: {
+    signal?: AbortSignal;
+    intervalMs?: number;
+    backfill?: boolean;
+}): AsyncGenerator<CommsMsg>;

package/dist/lib/mailbox.js

@@ -267,3 +267,115 @@ export function clear(boxDir) {
     }
     return n;
 }
+/**
+ * Enumerate the box ids under `root` (directory names that are valid mailbox
+ * ids). Read-only; does not create the root. Sorted for stable output.
+ */
+export function listBoxes(root = getMailboxRootDir()) {
+    let names;
+    try {
+        names = fs.readdirSync(root);
+    }
+    catch {
+        return [];
+    }
+    return names.filter((n) => isValidMailboxId(n) && fs.statSync(path.join(root, n)).isDirectory()).sort();
+}
+/**
+ * Read every message in a box across all three buckets (inbox, processing,
+ * consumed) WITHOUT consuming, sweeping, or archiving anything. Unlike `peek`,
+ * this includes `consumed/` — the delivered history — so callers can surface a
+ * communication log. Each row is tagged with its bucket. Sorted FIFO by msgId
+ * (which is time-sortable), oldest first.
+ */
+export function readBox(boxDir) {
+    const out = [];
+    const buckets = [
+        [inboxDir(boxDir), 'inbox'],
+        [processingDir(boxDir), 'processing'],
+        [consumedDir(boxDir), 'consumed'],
+    ];
+    for (const [dir, state] of buckets) {
+        for (const name of jsonFiles(dir)) {
+            const msg = readMessage(path.join(dir, name));
+            if (msg)
+                out.push({ ...msg, state });
+        }
+    }
+    out.sort((a, b) => (a.msgId < b.msgId ? -1 : a.msgId > b.msgId ? 1 : 0));
+    return out;
+}
+/**
+ * Poll the complete spool and yield each message once when its box/msgId pair
+ * first appears. Existing messages establish the initial baseline unless
+ * `backfill` is requested; moving a message between buckets does not re-emit it.
+ */
+export async function* watchMessages(root, opts) {
+    const seen = new Set();
+    const requestedInterval = opts.intervalMs ?? 500;
+    const intervalMs = Number.isFinite(requestedInterval) ? Math.max(1, requestedInterval) : 500;
+    let firstPoll = true;
+    while (!opts.signal?.aborted) {
+        const fresh = [];
+        for (const box of listBoxes(root)) {
+            for (const stored of readBox(mailboxDir(box, root))) {
+                const key = `${box}\0${stored.msgId}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                if (firstPoll && !opts.backfill)
+                    continue;
+                fresh.push({
+                    key,
+                    message: {
+                        from: stored.from || 'operator',
+                        to: stored.to,
+                        toLabel: box.slice(0, 8),
+                        ts: stored.ts,
+                        text: stored.text,
+                        state: stored.state,
+                        box,
+                    },
+                });
+            }
+        }
+        firstPoll = false;
+        fresh.sort((a, b) => compareWatched(a.message.ts, b.message.ts) ||
+            compareWatched(a.key, b.key));
+        for (const { message } of fresh) {
+            if (opts.signal?.aborted)
+                return;
+            yield message;
+        }
+        if (!await waitForMailboxPoll(intervalMs, opts.signal))
+            return;
+    }
+}
+function compareWatched(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** Wait for the next poll, resolving immediately when the watcher is aborted. */
+function waitForMailboxPoll(intervalMs, signal) {
+    if (signal?.aborted)
+        return Promise.resolve(false);
+    return new Promise((resolve) => {
+        let timer;
+        let settled = false;
+        const finish = (keepWatching) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            resolve(keepWatching);
+        };
+        const onAbort = () => finish(false);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        if (signal?.aborted) {
+            finish(false);
+            return;
+        }
+        timer = setTimeout(() => finish(true), intervalMs);
+    });
+}

package/dist/lib/migrate.d.ts

@@ -44,6 +44,18 @@ export declare function foldLegacySystemRepo(): void;
  * drive a fixture tree without touching the user's ~/.agents.
  */
 export declare function migrateAgentsYaml(systemDir?: string, userDir?: string): void;
+/**
+ * Fold the legacy GLOBAL browser captures root
+ * (`~/.agents/.cache/browser/sessions/<task>/`) into the new PER-PROFILE layout
+ * (`~/.agents/.cache/browser/<profile>/sessions/<task>/`), so each profile is one
+ * self-contained tree and the new `browser sessions` listing finds old captures.
+ *
+ * Attribution: a legacy `sessions/<task>` dir is owned by whichever profile's
+ * `tasks.json` still lists that task name. Tasks no profile claims (the profile
+ * was deleted, or tasks.json was cleared) move under a `_legacy` pseudo-profile so
+ * nothing is lost. Idempotent — once the global `sessions/` root is gone it no-ops.
+ */
+export declare function foldBrowserSessionsIntoProfiles(browserDir?: string): void;
 /**
  * Repair self-referential agent binary symlinks.
  *

package/dist/lib/migrate.js

@@ -359,6 +359,56 @@ function foldUserHooksYamlIntoAgentsYaml() {
     }
     catch { /* best-effort */ }
 }
+/**
+ * Fold the legacy GLOBAL browser captures root
+ * (`~/.agents/.cache/browser/sessions/<task>/`) into the new PER-PROFILE layout
+ * (`~/.agents/.cache/browser/<profile>/sessions/<task>/`), so each profile is one
+ * self-contained tree and the new `browser sessions` listing finds old captures.
+ *
+ * Attribution: a legacy `sessions/<task>` dir is owned by whichever profile's
+ * `tasks.json` still lists that task name. Tasks no profile claims (the profile
+ * was deleted, or tasks.json was cleared) move under a `_legacy` pseudo-profile so
+ * nothing is lost. Idempotent — once the global `sessions/` root is gone it no-ops.
+ */
+export function foldBrowserSessionsIntoProfiles(browserDir = path.join(CACHE_DIR, 'browser')) {
+    const legacySessionsDir = path.join(browserDir, 'sessions');
+    let taskDirs;
+    try {
+        taskDirs = fs.readdirSync(legacySessionsDir, { withFileTypes: true });
+    }
+    catch {
+        return; // no legacy global sessions/ root — already folded or never existed
+    }
+    // Map task name -> owning profile from every profile's tasks.json (first wins).
+    const taskOwner = new Map();
+    let profileDirs = [];
+    try {
+        profileDirs = fs.readdirSync(browserDir, { withFileTypes: true });
+    }
+    catch { /* browserDir vanished mid-run */ }
+    for (const p of profileDirs) {
+        if (!p.isDirectory() || p.name === 'sessions' || p.name === '_legacy')
+            continue;
+        try {
+            const state = JSON.parse(fs.readFileSync(path.join(browserDir, p.name, 'tasks.json'), 'utf-8'));
+            for (const taskName of Object.keys(state)) {
+                if (!taskOwner.has(taskName))
+                    taskOwner.set(taskName, p.name);
+            }
+        }
+        catch { /* missing or invalid tasks.json */ }
+    }
+    for (const taskEntry of taskDirs) {
+        if (!taskEntry.isDirectory())
+            continue;
+        const owner = taskOwner.get(taskEntry.name) ?? '_legacy';
+        // A capture dir can hold a nested recordings/ subdir and may collide with a
+        // dest that already has newer captures — moveDirOnce merges (skip-existing),
+        // moveFileOnce would EISDIR on unlink and silently strand the captures.
+        moveDirOnce(path.join(legacySessionsDir, taskEntry.name), path.join(browserDir, owner, 'sessions', taskEntry.name));
+    }
+    rmEmptyDirTree(legacySessionsDir);
+}
 /**
  * Fold ~/.agents/browser/profiles/*.yaml into ~/.agents/agents.yaml under a
  * `browser:` key, then delete the profiles directory. Single user file to sync.
@@ -1582,7 +1632,7 @@ function containsOnlyDsStore(dir) {
 function warnSystemOrphans() {
     const SHIPPED_ALLOWLIST = new Set([
         // resource directories shipped by the npm package
-        'commands', 'hooks', 'skills', 'rules', 'mcp', 'cli', 'permissions', 'subagents', 'profiles', 'agents',
+        'commands', 'hooks', 'skills', 'rules', 'mcp', 'cli', 'permissions', 'subagents', 'profiles', 'agents', 'routines',
         // top-level metadata files
         'agents.yaml', 'hooks.yaml', 'README.md', 'CHANGELOG.md',
         // git + repo metadata
@@ -1966,6 +2016,10 @@ export async function runMigration() {
     // migrateRuntimeToCache so any legacy plugins/ still at the user-root from
     // very-old layouts have already been handled.
     migratePluginsBackToUserRoot();
+    // Browser captures: fold the legacy global browser/sessions/<task> root into the
+    // per-profile browser/<profile>/sessions/<task> layout. After the cache moves so
+    // the browser dir is at its canonical .cache location.
+    foldBrowserSessionsIntoProfiles();
     // System-repo sweep: move every remaining operational dir into its canonical
     // user-bucket location, then drop known-dead artifacts and warn about
     // anything we don't recognize. Order: durable (sessions/teams/trash/repos/

package/dist/lib/paths.d.ts

@@ -1,3 +1,9 @@
+/**
+ * True when `name` is a safe single path segment: non-empty, not '.'/'..',
+ * free of path separators and null bytes, and within the filename length limit.
+ * Dot-prefixed names like '.env.example' are allowed.
+ */
+export declare function isSafeSegmentName(name: string): boolean;
 /**
  * Resolve base + name while preventing path-traversal attacks.
  * Rejects path separators, null bytes, '.' and '..', and any resolved path
@@ -6,3 +12,10 @@
  * Allows spaces, unicode, and other common filename characters.
  */
 export declare function safeJoin(base: string, name: string): string;
+/**
+ * Assert that `target` (which may legitimately contain path separators, e.g. a
+ * multi-segment relative key) stays within `root` after normalization. Use this
+ * where a caller must accept nested relative paths but the input is untrusted —
+ * `safeJoin` is stricter and only allows single segments.
+ */
+export declare function assertWithin(root: string, target: string): string;

package/dist/lib/paths.js

@@ -1,4 +1,15 @@
 import * as path from 'path';
+/**
+ * True when `name` is a safe single path segment: non-empty, not '.'/'..',
+ * free of path separators and null bytes, and within the filename length limit.
+ * Dot-prefixed names like '.env.example' are allowed.
+ */
+export function isSafeSegmentName(name) {
+    return (!!name &&
+        name !== '.' && name !== '..' &&
+        !/[\/\\\x00]/.test(name) &&
+        name.length <= 255);
+}
 /**
  * Resolve base + name while preventing path-traversal attacks.
  * Rejects path separators, null bytes, '.' and '..', and any resolved path
@@ -7,10 +18,7 @@ import * as path from 'path';
  * Allows spaces, unicode, and other common filename characters.
  */
 export function safeJoin(base, name) {
-    if (!name ||
-        name === '.' || name === '..' ||
-        /[\/\\\x00]/.test(name) ||
-        name.length > 255) {
+    if (!isSafeSegmentName(name)) {
         throw new Error(`Invalid name: ${name}`);
     }
     const resolved = path.resolve(base, name);
@@ -18,3 +26,17 @@ export function safeJoin(base, name) {
         throw new Error(`Path escape: ${name}`);
     return resolved;
 }
+/**
+ * Assert that `target` (which may legitimately contain path separators, e.g. a
+ * multi-segment relative key) stays within `root` after normalization. Use this
+ * where a caller must accept nested relative paths but the input is untrusted —
+ * `safeJoin` is stricter and only allows single segments.
+ */
+export function assertWithin(root, target) {
+    const base = path.resolve(root);
+    const resolved = path.resolve(target);
+    if (resolved !== base && !resolved.startsWith(base + path.sep)) {
+        throw new Error(`Path escape: ${target}`);
+    }
+    return resolved;
+}