@phnx-labs/agents-cli 1.20.27 → 1.20.28

package/dist/lib/startup/command-registry.js

@@ -45,6 +45,7 @@ export const loadPty = async () => (await import('../../commands/pty.js')).regis
 export const loadTmux = async () => (await import('../../commands/tmux.js')).registerTmuxCommands;
 export const loadBrowser = async () => (await import('../../commands/browser.js')).registerBrowserCommand;
 export const loadComputer = async () => (await import('../../commands/computer.js')).registerComputerCommand;
+export const loadHosts = async () => (await import('../../commands/hosts.js')).registerHostsCommand;
 export const loadPull = async () => (await import('../../commands/pull.js')).registerPullCommand;
 export const loadPush = async () => (await import('../../commands/push.js')).registerPushCommand;
 export const loadRepo = async () => (await import('../../commands/repo.js')).registerRepoCommands;
@@ -126,6 +127,7 @@ export const COMMAND_LOADERS = {
     tmux: [loadTmux],
     browser: [loadBrowser],
     computer: [loadComputer],
+    hosts: [loadHosts],
     pull: [loadPull],
     push: [loadPush],
     repo: [loadRepo],

package/dist/lib/types.d.ts

@@ -612,6 +612,27 @@ export interface Meta {
      * lives separately in ~/.agents/.cache/browser/<profile>/.
      */
     browser?: Record<string, BrowserProfileConfig>;
+    /**
+     * Agent-host registry keyed by host name (`agents hosts`). Portable user
+     * config synced with `agents repo push/pull`. For `ssh-config` hosts this is
+     * just an overlay (caps/os) — the connection details stay in ~/.ssh/config and
+     * are never copied. `inline` hosts carry their own address/user.
+     */
+    hosts?: Record<string, HostEntry>;
+}
+/** Persisted agent-host entry in agents.yaml (overlay or inline). */
+export interface HostEntry {
+    /** `ssh-config`: reach via the bare name (ssh resolves). `inline`: use address/user below. */
+    source: 'ssh-config' | 'inline';
+    /** SSH-reachable target — inline hosts only (ssh-config hosts omit it). */
+    address?: string;
+    /** SSH user — inline hosts only. */
+    user?: string;
+    /** Captured at enroll probe. */
+    os?: string;
+    /** Free-form capability tags for routing (e.g. ['gpu']). */
+    caps?: string[];
+    addedAt?: string;
 }
 /** Browser profile definition stored in agents.yaml. */
 export interface BrowserProfileConfig {

package/dist/lib/versions.d.ts

@@ -241,12 +241,16 @@ export declare function resolveVersion(agent: AgentId, projectPath?: string): st
 /**
  * Normalize a user-supplied @version token across CLI subcommands.
  *
- *   undefined / "" / "default"  -> undefined  (caller falls back to project pin or global default)
+ *   undefined / "" / "default" / "pinned" -> undefined  (caller falls back to project pin or global default)
+ *   "any"                       -> undefined  (caller imposes no version constraint — e.g. resume across any version)
  *   "latest"                    -> highest installed version (process.exit if none installed)
  *   "oldest"                    -> lowest installed version (process.exit if none installed)
  *   "x.y.z" (installed)         -> "x.y.z"
  *   "x.y.z" (not installed)     -> process.exit with installed-list hint
  *
+ * `pinned` is a synonym for `default`: both name the project pin / global
+ * default, which the caller resolves.
+ *
  * Use this anywhere the user can type `agents <cmd> claude@<token>` to keep the
  * vocabulary consistent. Subcommands with different semantics for `latest`
  * (install/remove/use, where `latest` means npm-latest) keep their existing
@@ -255,7 +259,7 @@ export declare function resolveVersion(agent: AgentId, projectPath?: string): st
 export declare function resolveVersionAlias(agent: AgentId, raw: string | undefined | null): string | undefined;
 /**
  * Loose variant of resolveVersionAlias for record-filter contexts (sessions,
- * team history). Same `default`/`latest`/`oldest` semantics, but explicit
+ * team history). Same `default`/`pinned`/`latest`/`oldest` semantics, but explicit
  * versions pass through unchanged so historical records of uninstalled versions
  * remain queryable.
  */

package/dist/lib/versions.js

@@ -1363,19 +1363,23 @@ export function resolveVersion(agent, projectPath) {
 /**
  * Normalize a user-supplied @version token across CLI subcommands.
  *
- *   undefined / "" / "default"  -> undefined  (caller falls back to project pin or global default)
+ *   undefined / "" / "default" / "pinned" -> undefined  (caller falls back to project pin or global default)
+ *   "any"                       -> undefined  (caller imposes no version constraint — e.g. resume across any version)
  *   "latest"                    -> highest installed version (process.exit if none installed)
  *   "oldest"                    -> lowest installed version (process.exit if none installed)
  *   "x.y.z" (installed)         -> "x.y.z"
  *   "x.y.z" (not installed)     -> process.exit with installed-list hint
  *
+ * `pinned` is a synonym for `default`: both name the project pin / global
+ * default, which the caller resolves.
+ *
  * Use this anywhere the user can type `agents <cmd> claude@<token>` to keep the
  * vocabulary consistent. Subcommands with different semantics for `latest`
  * (install/remove/use, where `latest` means npm-latest) keep their existing
  * parsing.
  */
 export function resolveVersionAlias(agent, raw) {
-    if (!raw || raw === 'default')
+    if (!raw || raw === 'default' || raw === 'pinned' || raw === 'any')
         return undefined;
     if (raw === 'latest' || raw === 'oldest') {
         const installed = listInstalledVersions(agent);
@@ -1399,12 +1403,12 @@ export function resolveVersionAlias(agent, raw) {
 }
 /**
  * Loose variant of resolveVersionAlias for record-filter contexts (sessions,
- * team history). Same `default`/`latest`/`oldest` semantics, but explicit
+ * team history). Same `default`/`pinned`/`latest`/`oldest` semantics, but explicit
  * versions pass through unchanged so historical records of uninstalled versions
  * remain queryable.
  */
 export function resolveVersionAliasLoose(agent, raw) {
-    if (!raw || raw === 'default')
+    if (!raw || raw === 'default' || raw === 'pinned' || raw === 'any')
         return undefined;
     if (raw === 'latest' || raw === 'oldest') {
         const installed = listInstalledVersions(agent);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.27",
+  "version": "1.20.28",
   "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",

package/scripts/postinstall.js

@@ -239,6 +239,10 @@ To enable version-aware shims, add this to your shell config:
     console.log(`  Installed shorthands: ${written.join(', ')}`);
   }
 
+  if (process.platform !== 'win32') {
+    await ensureAgentsResolvablePosix();
+  }
+
   await healLongRunningProcesses();
 
   const version = getVersion();
@@ -252,6 +256,64 @@ To enable version-aware shims, add this to your shell config:
   }
 }
 
+/**
+ * Make the `agents` command resolvable in a *login* shell on POSIX.
+ *
+ * `agents`/`ag` reach PATH only through npm's bin symlink in the npm global-bin
+ * dir. Under nvm (and other per-user node prefixes) that dir is missing from a
+ * non-interactive login shell's PATH, so `bash -lc 'agents …'` fails with
+ * command-not-found — which breaks `agents secrets export --host` (it runs
+ * `bash -lc 'agents secrets import …'` on the remote) and the routines daemon
+ * (src/lib/daemon.ts falls back to bare `agents`). This is the POSIX symmetric
+ * counterpart of the Windows branch in main() that registers npm's global-bin
+ * dir on the user PATH.
+ *
+ * Self-heal, not a prompt: it fires ONLY when `agents` is otherwise
+ * unresolvable — the genuinely-broken state — so it acts decisively, exactly
+ * like the Windows PATH registration. The symlink never clobbers a dev build
+ * (scripts/install.sh) or any real file. Skipped in CI (ephemeral homes) and
+ * when AGENTS_NO_HEAL=1.
+ */
+async function ensureAgentsResolvablePosix() {
+  if (process.env.CI || process.env.AGENTS_NO_HEAL === '1') return;
+  try {
+    const { localBinDir, ensureLocalBinSymlink, loginShellResolves, dirOnLoginPath } =
+      await import('../dist/lib/platform/posixpath.js');
+
+    // macOS/homebrew, system-node Linux, and dev-build users already resolve it.
+    if (loginShellResolves('agents')) return;
+
+    const binDir = localBinDir();
+    const results = ['agents', 'ag'].map((name) => ensureLocalBinSymlink(name, AGENTS_BIN, binDir));
+    if (!results.some((r) => r.created)) return; // nothing we could safely link
+
+    if (dirOnLoginPath(binDir)) {
+      console.log(`\n  Linked 'agents' into ${binDir} (already on the login PATH) so 'bash -lc agents' resolves.`);
+      return;
+    }
+
+    // ~/.local/bin isn't on the *bash* login PATH yet. The consumers run
+    // `bash -lc`, so add it to the file a bash login shell reads (~/.bash_profile
+    // when present, else ~/.profile) — not the interactive $SHELL rc, which for a
+    // zsh user (.zshrc) bash would never source.
+    const bashRc = fs.existsSync(path.join(HOME, '.bash_profile'))
+      ? path.join(HOME, '.bash_profile')
+      : path.join(HOME, '.profile');
+    const marker = '# agents-cli: ensure ~/.local/bin on PATH (so the agents command resolves)';
+    let already = false;
+    try {
+      already = fs.existsSync(bashRc) && fs.readFileSync(bashRc, 'utf-8').includes(marker);
+    } catch { /* unreadable rc — fall through and append */ }
+    if (!already) {
+      fs.appendFileSync(bashRc, `\n${marker}\nexport PATH="${binDir}:$PATH"\n`);
+    }
+    console.log(`\n  Linked 'agents' into ${binDir} and added it to PATH in ${path.basename(bashRc)}.`);
+    console.log(`  Restart your shell (or run: source ~/${path.basename(bashRc)}) to pick it up.`);
+  } catch {
+    /* best-effort: a failure here must never break the install */
+  }
+}
+
 /**
  * Self-heal long-running processes onto the just-installed code (macOS).
  *