@phnx-labs/agents-cli 1.20.25 → 1.20.27

package/dist/lib/session/remote.js

@@ -0,0 +1,114 @@
+/**
+ * `agents sessions --host <target>` — run the session query on a remote machine
+ * over SSH and stream its output back. Session transcripts and the index DB live
+ * on the machine that produced them (see `discover.ts`, all `os.homedir()`-rooted),
+ * so instead of syncing the bytes here we invoke the *remote's own* `agents
+ * sessions` against its already-built index and forward stdout verbatim.
+ *
+ * This is the live counterpart to `agents sessions sync` (R2/CRDT, eventual): no
+ * upfront copy, always current, but the peer must be reachable. SSH access is the
+ * only auth — if you can `ssh <host>`, you own the box (no identity layer by design).
+ *
+ * Mirrors the transport already used by `agents secrets export --to-ssh`
+ * (`src/commands/secrets.ts`): `ssh -o BatchMode=yes <host> bash -lc '<cmd>'`,
+ * with `bash -lc` so the remote login PATH resolves `agents`.
+ */
+import { spawnSync } from 'child_process';
+import chalk from 'chalk';
+/**
+ * SSH target: a bare ssh-config host alias (e.g. `yosemite-s1`) or `user@host`.
+ * The strict allowlist blocks shell metacharacters and a leading `-`, so a target
+ * can never be smuggled in as an ssh argv flag.
+ */
+export const SSH_TARGET_RE = /^[a-zA-Z0-9._-]+(@[a-zA-Z0-9._-]+)?$/;
+export function assertValidSshTarget(host) {
+    if (!SSH_TARGET_RE.test(host)) {
+        throw new Error(`Invalid SSH target ${JSON.stringify(host)}. Expected a host alias or user@host ` +
+            `(letters, digits, '.', '_', '-').`);
+    }
+}
+/** POSIX single-quote a string for safe interpolation into a remote shell command. */
+export function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Strip the `--host`/`-H` flag (and its value) from a raw `agents sessions` argv,
+ * leaving the args to forward to the remote unchanged. The remote runs the same
+ * binary, so every other flag (`--since`, `--last`, `--json`, query, …) carries
+ * over for free. Handles every form commander accepts: `--host h`, `--host=h`,
+ * `-H h`, `-H=h`, and the glued short form `-Hh`.
+ *
+ * @param argv full process argv; the sessions args begin at index 2
+ *             (`[runtime, script, 'sessions', ...]`).
+ */
+export function buildForwardedArgs(argv, hosts = new Set()) {
+    const args = argv.slice(2);
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--host' || a === '-H') {
+            // Commander's `<target...>` variadic accepts both `--host a --host b` and
+            // `--host a b` — consume every consecutive token that is a known host so
+            // the variadic form doesn't leak the extra hosts into the remote argv.
+            // Fall back to consuming the single next token when we have no host set
+            // (e.g. malformed input) so the flag value never leaks either way.
+            if (hosts.size > 0) {
+                while (i + 1 < args.length && hosts.has(args[i + 1]))
+                    i++;
+            }
+            else {
+                i++; // also consume the separate value token
+            }
+            continue;
+        }
+        if (a.startsWith('--host=') || a.startsWith('-H='))
+            continue;
+        if (/^-H.+/.test(a))
+            continue; // glued short form: -Hyosemite-s1
+        out.push(a);
+    }
+    return out;
+}
+/**
+ * Build the single remote command string for `ssh <host> <cmd>`. Forwarded args
+ * are quoted for the inner login shell, then the whole `agents …` invocation is
+ * quoted again so it survives `bash -lc <...>`.
+ */
+export function buildRemoteCommand(forwardedArgs) {
+    const inner = ['agents', ...forwardedArgs].map(shellQuote).join(' ');
+    return `bash -lc ${shellQuote(inner)}`;
+}
+const SSH_OPTS = [
+    '-o', 'BatchMode=yes',
+    '-o', 'StrictHostKeyChecking=accept-new',
+    '-o', 'ConnectTimeout=10',
+];
+/**
+ * Run the current `agents sessions` invocation on one or more remote machines over
+ * SSH, streaming each remote's output to the terminal. Sets `process.exitCode = 1`
+ * if any host fails. Reads the invocation from `process.argv` (override via
+ * `argv` for testing).
+ */
+export function runRemoteSessions(hosts, argv = process.argv) {
+    for (const host of hosts)
+        assertValidSshTarget(host); // fail fast on any bad target
+    const remoteCmd = buildRemoteCommand(buildForwardedArgs(argv, new Set(hosts)));
+    const multi = hosts.length > 1;
+    let failures = 0;
+    for (const host of hosts) {
+        if (multi)
+            process.stdout.write(chalk.cyan(`\n── ${host} ──\n`));
+        const res = spawnSync('ssh', [...SSH_OPTS, host, remoteCmd], { stdio: 'inherit' });
+        if (res.error) {
+            failures++;
+            console.error(chalk.red(`${host}: ${res.error.message}`));
+            continue;
+        }
+        if (res.status !== 0) {
+            failures++;
+            console.error(chalk.red(`${host}: remote query failed (exit ${res.status ?? 'signal'}).`));
+        }
+    }
+    if (failures > 0)
+        process.exitCode = 1;
+}

package/dist/lib/staleness/checkers/rules.js

@@ -54,7 +54,19 @@ function activeSources(agent, version, cwd) {
             result['rules.yaml'] = yamlPath;
     }
     for (const sub of compose.subrules) {
-        result[`subrules/${sub.name}.md`] = sub.sourcePath;
+        // Key off the actual source path so dir-form subrules (subrules/<name>/rule.md)
+        // and flat ones (subrules/<name>.md) both fingerprint the file that really
+        // contributes to the output, not a hard-coded `.md` that may not exist.
+        if (sub.subruleDir) {
+            result[`subrules/${sub.name}/rule.md`] = sub.sourcePath;
+            // Fingerprint hooks.yaml too so editing a hook re-syncs the rules section.
+            const hooksFile = path.join(sub.subruleDir, 'hooks.yaml');
+            if (fs.existsSync(hooksFile))
+                result[`subrules/${sub.name}/hooks.yaml`] = hooksFile;
+        }
+        else {
+            result[`subrules/${sub.name}.md`] = sub.sourcePath;
+        }
     }
     return result;
 }

package/dist/lib/staleness/detectors/commands.js

@@ -1,8 +1,8 @@
 /**
  * Commands detector — mirrors versions.ts:343-357. Inspects the version home,
- * returns command names. Honors the commands-as-skills marker for grok and
- * Codex >= 0.117.0; falls back to scanning `{agentDir}/<commandsSubdir>/` for
- * the native path.
+ * returns command names. Honors the commands-as-skills marker for skills-only
+ * agents (grok, kimi, Codex >= 0.117.0, …); falls back to scanning
+ * `{agentDir}/<commandsSubdir>/` for the native path.
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -29,13 +29,14 @@ function buildCommandsDetector(agent) {
         },
     };
 }
-// Detector registration mirrors writers/commands.ts — see that file for the
-// openclaw vs grok asymmetry.
+// Detector registration mirrors writers/commands.ts — skills-capable agents
+// with no native command-file dir convert commands to skills by default; only
+// agents with their own slash-command runtime (nativeCommandRuntime) opt out.
 export const commandsDetectors = lazyAgentMap(() => {
     const m = {};
     for (const id of Object.keys(AGENTS)) {
         const cfg = AGENTS[id];
-        if (cfg.capabilities.commands === false && (!cfg.commandsSubdir || cfg.commandsSubdir === '') && id !== 'grok')
+        if (cfg.capabilities.commands === false && (!cfg.commandsSubdir || cfg.commandsSubdir === '') && cfg.nativeCommandRuntime)
             continue;
         const hasCommands = cfg.capabilities.commands !== false;
         const hasSkills = cfg.capabilities.skills !== false;

package/dist/lib/staleness/writers/commands.js

@@ -80,25 +80,20 @@ function buildCommandsWriter(agent) {
 //   - commands-as-skills (grok, codex >= 0.117.0)
 //
 // Agents that have skills but use a NATIVE non-file slash-command system
-// (openclaw → Gateway-based commands) are NOT registered. The signal is an
-// empty `commandsSubdir`: there's no directory to write to AND the agent
-// doesn't want commands-as-skills either (it has its own runtime command
-// resolver).
+// (openclaw → Gateway-based commands) are NOT registered. They declare
+// `nativeCommandRuntime: true` to opt out — their own runtime resolves slash
+// commands, so there's nothing to write and nothing to convert.
 export const commandsWriters = lazyAgentMap(() => {
     const m = {};
     for (const id of Object.keys(AGENTS)) {
         const cfg = AGENTS[id];
         if (cfg.capabilities.commands === false && (!cfg.skillsDir || cfg.skillsDir === ''))
             continue;
-        // Native non-file slash-command runtime — no version-home write.
+        // Skills-capable agent with no native command-file dir: convert commands to
+        // skills by default (grok, kimi, …). Opt out only agents with their own
+        // slash-command runtime (openclaw).
         if (cfg.capabilities.commands === false && (!cfg.commandsSubdir || cfg.commandsSubdir === '')) {
-            // Grok has empty commandsSubdir AND wants commands-as-skills.
-            // Distinguish: grok has skillsDir set; openclaw also has skillsDir, so we
-            // can't use that. The cleanest signal is the agent's `cliCommand` set —
-            // openclaw flags `commands: false` AND has its Gateway runtime, while
-            // grok flags `commands: false` because grok's slash commands are skills.
-            // We opt in explicitly: only grok takes commands-as-skills today.
-            if (id !== 'grok')
+            if (cfg.nativeCommandRuntime)
                 continue;
         }
         const hasCommands = cfg.capabilities.commands !== false;

package/dist/lib/startup/dev-build.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Decide whether the CLI is running from a source checkout (a "dev build") vs an
+ * installed package. Dev builds suppress autopull / migrations / auto-update so
+ * iterating on the repo never mutates the user's real setup.
+ *
+ * Two signals:
+ *   1. A `0.0.0-dev*` version stamp (scripts/install.sh dev installs).
+ *   2. Running out of an actual agents-cli git checkout.
+ *
+ * Signal 2 must be precise. The naive check —
+ * `existsSync(dirname(dirname(argv[1])) + '/.git')` — false-positives badly:
+ *   - npm-global bins are symlinks. `/opt/homebrew/bin/agents` →
+ *     `…/node_modules/@phnx-labs/agents-cli/dist/index.js`. Without resolving the
+ *     symlink, `dirname(dirname())` walks to `/opt/homebrew`, which is **itself a
+ *     git repo** (Homebrew). So every Homebrew-node user looked like a dev build
+ *     and had migrations + the menu-bar self-heal silently disabled.
+ *
+ * Fix: resolve the symlink with realpath, then require the `.git`'s repo root to
+ * actually be the agents-cli package (its package.json `name`), not some
+ * unrelated ancestor that happens to be version-controlled.
+ */
+export declare function detectDevBuild(argv1: string, version: string): boolean;

package/dist/lib/startup/dev-build.js

@@ -0,0 +1,41 @@
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Decide whether the CLI is running from a source checkout (a "dev build") vs an
+ * installed package. Dev builds suppress autopull / migrations / auto-update so
+ * iterating on the repo never mutates the user's real setup.
+ *
+ * Two signals:
+ *   1. A `0.0.0-dev*` version stamp (scripts/install.sh dev installs).
+ *   2. Running out of an actual agents-cli git checkout.
+ *
+ * Signal 2 must be precise. The naive check —
+ * `existsSync(dirname(dirname(argv[1])) + '/.git')` — false-positives badly:
+ *   - npm-global bins are symlinks. `/opt/homebrew/bin/agents` →
+ *     `…/node_modules/@phnx-labs/agents-cli/dist/index.js`. Without resolving the
+ *     symlink, `dirname(dirname())` walks to `/opt/homebrew`, which is **itself a
+ *     git repo** (Homebrew). So every Homebrew-node user looked like a dev build
+ *     and had migrations + the menu-bar self-heal silently disabled.
+ *
+ * Fix: resolve the symlink with realpath, then require the `.git`'s repo root to
+ * actually be the agents-cli package (its package.json `name`), not some
+ * unrelated ancestor that happens to be version-controlled.
+ */
+export function detectDevBuild(argv1, version) {
+    if (version.startsWith('0.0.0-dev'))
+        return true;
+    try {
+        const cliPath = fs.realpathSync(argv1 || '');
+        const repoRoot = path.dirname(path.dirname(cliPath));
+        if (!fs.existsSync(path.join(repoRoot, '.git')))
+            return false;
+        const pkgPath = path.join(repoRoot, 'package.json');
+        if (!fs.existsSync(pkgPath))
+            return false;
+        const name = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))?.name;
+        return name === '@phnx-labs/agents-cli';
+    }
+    catch {
+        return false;
+    }
+}

package/dist/lib/types.d.ts

@@ -77,6 +77,13 @@ export interface AgentConfig {
     commandsDir: string;
     commandsSubdir: string;
     skillsDir: string;
+    /**
+     * Agent resolves slash-commands through its own runtime (e.g. openclaw's
+     * Gateway), so agents-cli commands must NOT be converted into skills for it.
+     * Skills-capable agents WITHOUT a native command-file dir convert commands to
+     * skills by default; set this to opt such an agent out of that conversion.
+     */
+    nativeCommandRuntime?: boolean;
     hooksDir: string;
     pluginManifestDir?: string;
     instructionsFile: string;
@@ -563,9 +570,13 @@ export interface ExtraRepoConfig {
 export interface Meta {
     agents?: Partial<Record<AgentId, string>>;
     run?: RunConfig;
-    /** macOS secrets-agent config. `auto` makes the first real keychain read of a
-     * `session`-tier bundle populate the broker so concurrent runs read silently. */
+    /** macOS secrets-agent config. `policy` is the default prompt policy for
+     * bundles without an explicit per-bundle policy: `daily` (the default) asks
+     * once per ~24h, `always` asks every time. `auto` (default on) lets the first
+     * real keychain read of a `daily` bundle populate the broker so concurrent
+     * runs read silently — set it `false` to force a prompt on every read. */
     secrets?: {
+        policy?: 'always' | 'daily';
         agent?: {
             auto?: boolean;
         };

package/dist/lib/versions.d.ts

@@ -144,8 +144,10 @@ export declare function isOldestInstalled(agent: AgentId): Promise<{
     installed: boolean;
     version: string | null;
 }>;
+/** Drop the installed-versions cache (call after install/remove mutations). */
+export declare function invalidateInstalledVersionsCache(agent?: AgentId): void;
 /**
- * List all installed versions for an agent.
+ * List all installed versions for an agent (cached by versions-dir mtime).
  */
 export declare function listInstalledVersions(agent: AgentId): string[];
 /**

package/dist/lib/versions.js

@@ -898,14 +898,36 @@ export async function isOldestInstalled(agent) {
     }
     return { installed: isVersionInstalled(agent, oldestVersion), version: oldestVersion };
 }
+// Per-process cache for listInstalledVersions. The agent's versions dir mtime
+// changes whenever a version dir is added or removed (install/remove), so a
+// stamp match means the installed set is unchanged and we skip the readdir +
+// N binary stats. Mirrors the readMeta() cache in state.ts. Hot path:
+// resolveAgentTargets and every enumerate-style consumer hit this.
+const installedVersionsCache = new Map();
+/** Drop the installed-versions cache (call after install/remove mutations). */
+export function invalidateInstalledVersionsCache(agent) {
+    if (agent)
+        installedVersionsCache.delete(agent);
+    else
+        installedVersionsCache.clear();
+}
 /**
- * List all installed versions for an agent.
+ * List all installed versions for an agent (cached by versions-dir mtime).
  */
 export function listInstalledVersions(agent) {
     const agentVersionsDir = path.join(getVersionsDir(), agent);
-    if (!fs.existsSync(agentVersionsDir)) {
+    let stamp;
+    try {
+        stamp = fs.statSync(agentVersionsDir).mtimeMs;
+    }
+    catch {
+        installedVersionsCache.set(agent, { stamp: 0, versions: [] });
         return [];
     }
+    const cached = installedVersionsCache.get(agent);
+    if (cached && cached.stamp === stamp) {
+        return cached.versions;
+    }
     const entries = fs.readdirSync(agentVersionsDir, { withFileTypes: true });
     const versions = [];
     for (const entry of entries) {
@@ -916,7 +938,9 @@ export function listInstalledVersions(agent) {
             }
         }
     }
-    return versions.sort(compareVersions);
+    versions.sort(compareVersions);
+    installedVersionsCache.set(agent, { stamp, versions });
+    return versions;
 }
 /**
  * List every version directory for an agent, including ones missing the
@@ -1831,7 +1855,15 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
         // dot-dirs to keep plugin-managed subtrees (.plugins/, .promptcuts) intact.
         const skillsTargetSweep = path.join(agentDir, 'skills');
         if (!userPassedSelection && fs.existsSync(skillsTargetSweep) && !fs.lstatSync(skillsTargetSweep).isSymbolicLink()) {
+            // Trust real skills AND command-skills: when commandsAsSkills, the
+            // commands writer (above) materialized each command as a skill dir under
+            // skills/. Those names are not in skillsToSync, so without this they'd be
+            // swept as orphans — silently deleting every converted command (e.g.
+            // /recap on kimi/grok).
             const trustedSkills = new Set(skillsToSync);
+            if (commandsAsSkills)
+                for (const cmd of commandsToSync)
+                    trustedSkills.add(cmd);
             for (const entry of fs.readdirSync(skillsTargetSweep, { withFileTypes: true })) {
                 if (!entry.isDirectory() || entry.name.startsWith('.'))
                     continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.25",
+  "version": "1.20.27",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",
@@ -92,10 +92,10 @@
     "diff": "9.0.0",
     "marked": "15.0.12",
     "marked-terminal": "7.3.0",
-    "ora": "9.4.0",
+    "ora": "9.4.1",
     "proper-lockfile": "4.1.2",
     "simple-git": "3.36.0",
-    "smol-toml": "1.6.1",
+    "smol-toml": "1.7.0",
     "yaml": "2.9.0"
   },
   "devDependencies": {