@phnx-labs/agents-cli 1.20.20 → 1.20.22

package/dist/lib/self-update.d.ts

@@ -12,6 +12,31 @@
  * to PATH resolution.
  */
 export declare const NPM_PACKAGE_NAME = "@phnx-labs/agents-cli";
+export type PackageManager = 'npm' | 'bun';
+/**
+ * The directory bun installs global packages into:
+ *   <BUN_INSTALL>/install/global   (BUN_INSTALL defaults to ~/.bun)
+ *
+ * A globally-installed scoped package then lives at
+ * `<bunGlobalDir>/node_modules/@phnx-labs/agents-cli` — note there is NO `lib`
+ * segment, unlike npm's POSIX layout. That single difference is why an
+ * npm-based upgrade silently misses a bun install (see deriveGlobalPrefix).
+ */
+export declare function bunGlobalDir(): string;
+/**
+ * Identify which package manager owns the install at `packageRoot`, so the
+ * upgrade can shell out to the one that actually replaces this copy.
+ *
+ * bun lays a global package out as `<bunGlobalDir>/node_modules/<scoped pkg>`,
+ * so the prefix (the parent of `node_modules`) is the bun global dir itself.
+ * Everything else — npm's `<prefix>/lib/node_modules` and the Windows
+ * `<prefix>/node_modules` — is treated as npm.
+ *
+ * Detection is path-based (no subprocess): it matches the resolved bun global
+ * dir from BUN_INSTALL/$HOME, and falls back to the structural `.bun/install/
+ * global` tail for a relocated BUN_INSTALL not exported into this process.
+ */
+export declare function detectPackageManager(packageRoot: string): PackageManager;
 export interface UpdateCheckCache {
     lastCheck: number;
     latestVersion: string;
@@ -49,6 +74,15 @@ export declare function deriveGlobalPrefix(packageRoot: string): string;
  * refreshAliasShims().
  */
 export declare function installPackageIntoPrefix(spec: string, prefix: string): Promise<void>;
+/**
+ * Install `spec` into bun's global store with `bun add -g`. bun writes to
+ * `<bunGlobalDir>/node_modules/<pkg>`, which is exactly the running package
+ * root for a bun install — so verifyInstalledVersion() sees the new version
+ * in place. bun skips untrusted lifecycle scripts, so the caller refreshes
+ * alias shims afterwards via refreshAliasShims() rather than relying on the
+ * package's postinstall hook.
+ */
+export declare function installPackageWithBun(spec: string): Promise<void>;
 /** Read the version field of the package.json at `packageRoot`, fresh from disk. */
 export declare function readInstalledVersion(packageRoot: string): string;
 /**

package/dist/lib/self-update.js

@@ -12,10 +12,55 @@
  * to PATH resolution.
  */
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { spawnSync } from 'child_process';
 import { compareVersions } from './versions.js';
 export const NPM_PACKAGE_NAME = '@phnx-labs/agents-cli';
+/**
+ * The directory bun installs global packages into:
+ *   <BUN_INSTALL>/install/global   (BUN_INSTALL defaults to ~/.bun)
+ *
+ * A globally-installed scoped package then lives at
+ * `<bunGlobalDir>/node_modules/@phnx-labs/agents-cli` — note there is NO `lib`
+ * segment, unlike npm's POSIX layout. That single difference is why an
+ * npm-based upgrade silently misses a bun install (see deriveGlobalPrefix).
+ */
+export function bunGlobalDir() {
+    const bunInstall = process.env.BUN_INSTALL || path.join(os.homedir(), '.bun');
+    return path.join(bunInstall, 'install', 'global');
+}
+/**
+ * Identify which package manager owns the install at `packageRoot`, so the
+ * upgrade can shell out to the one that actually replaces this copy.
+ *
+ * bun lays a global package out as `<bunGlobalDir>/node_modules/<scoped pkg>`,
+ * so the prefix (the parent of `node_modules`) is the bun global dir itself.
+ * Everything else — npm's `<prefix>/lib/node_modules` and the Windows
+ * `<prefix>/node_modules` — is treated as npm.
+ *
+ * Detection is path-based (no subprocess): it matches the resolved bun global
+ * dir from BUN_INSTALL/$HOME, and falls back to the structural `.bun/install/
+ * global` tail for a relocated BUN_INSTALL not exported into this process.
+ */
+export function detectPackageManager(packageRoot) {
+    const resolved = path.resolve(packageRoot);
+    const prefix = path.dirname(path.dirname(path.dirname(resolved))); // strip <scope>/<pkg>/node_modules
+    if (prefix === path.resolve(bunGlobalDir()))
+        return 'bun';
+    const parts = prefix.split(path.sep);
+    const n = parts.length;
+    if (n >= 3 && parts[n - 1] === 'global' && parts[n - 2] === 'install' && parts[n - 3] === '.bun') {
+        return 'bun';
+    }
+    return 'npm';
+}
+/** The shell command a user can run by hand to reproduce the upgrade for `manager`. */
+function manualInstallHint(manager, packageRoot, spec) {
+    if (manager === 'bun')
+        return `bun add -g ${spec}`;
+    return `npm install -g --prefix ${deriveGlobalPrefix(packageRoot)} ${spec}`;
+}
 /** Read the cached update-check state from disk. Returns null if the file is missing or corrupt. */
 export function readUpdateCache(file) {
     try {
@@ -102,6 +147,20 @@ export async function installPackageIntoPrefix(spec, prefix) {
     const execFileAsync = promisify(execFile);
     await execFileAsync('npm', ['install', '-g', '--prefix', prefix, spec, '--ignore-scripts']);
 }
+/**
+ * Install `spec` into bun's global store with `bun add -g`. bun writes to
+ * `<bunGlobalDir>/node_modules/<pkg>`, which is exactly the running package
+ * root for a bun install — so verifyInstalledVersion() sees the new version
+ * in place. bun skips untrusted lifecycle scripts, so the caller refreshes
+ * alias shims afterwards via refreshAliasShims() rather than relying on the
+ * package's postinstall hook.
+ */
+export async function installPackageWithBun(spec) {
+    const { execFile } = await import('child_process');
+    const { promisify } = await import('util');
+    const execFileAsync = promisify(execFile);
+    await execFileAsync('bun', ['add', '-g', spec]);
+}
 /** Read the version field of the package.json at `packageRoot`, fresh from disk. */
 export function readInstalledVersion(packageRoot) {
     return JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8')).version;
@@ -113,8 +172,10 @@ export function readInstalledVersion(packageRoot) {
 export function verifyInstalledVersion(packageRoot, expectedVersion) {
     const actual = readInstalledVersion(packageRoot);
     if (actual !== expectedVersion) {
-        throw new Error(`npm reported success but ${packageRoot} is still ${actual} (expected ${expectedVersion}). ` +
-            `Run manually: npm install -g --prefix ${deriveGlobalPrefix(packageRoot)} ${NPM_PACKAGE_NAME}@${expectedVersion}`);
+        const manager = detectPackageManager(packageRoot);
+        const hint = manualInstallHint(manager, packageRoot, `${NPM_PACKAGE_NAME}@${expectedVersion}`);
+        throw new Error(`the package manager reported success but ${packageRoot} is still ${actual} (expected ${expectedVersion}). ` +
+            `Run manually: ${hint}`);
     }
 }
 /**

package/dist/lib/session/sync/config.d.ts

@@ -13,14 +13,26 @@ export interface R2Config {
     /** S3-compatible endpoint for the account (no bucket, no trailing slash). */
     endpoint: string;
 }
+/** Window after a prompt-bearing resolution failure during which we skip
+ *  re-attempting (and thus re-prompting). SIGHUP / restart bypasses it. */
+export declare const RESOLVE_RETRY_COOLDOWN_MS: number;
+/** Drop the cached resolution so the next call reads the bundle fresh. Called on
+ *  daemon SIGHUP (to pick up rotated credentials) and between tests. */
+export declare function clearR2ConfigCache(): void;
 /**
- * Resolve R2 credentials from the `r2.backups` bundle. Throws a clear,
- * actionable error if the bundle or any key is missing — sync cannot proceed
- * without real credentials (no silent fallback).
+ * Resolve R2 credentials, reading the keychain at most once per process. The
+ * first call reads (and may prompt for Touch ID); every later call returns the
+ * memoized result. Throws if the bundle/keys are missing — failures are not
+ * memoized, but see isSyncConfigured for the re-prompt cooldown.
  */
 export declare function loadR2Config(): R2Config;
-/** True when the sync bundle exists and looks resolvable, without throwing. */
-export declare function isSyncConfigured(): boolean;
+/**
+ * True when the sync bundle exists and resolves, without throwing. After a
+ * prompt-bearing failure (e.g. a cancelled Touch ID) it returns false without
+ * re-reading the keychain for RESOLVE_RETRY_COOLDOWN_MS, so a dismissed prompt
+ * does not re-storm every cycle. `now` is injectable for tests.
+ */
+export declare function isSyncConfigured(now?: number): boolean;
 /**
  * This machine's stable, human-readable id, used as its R2 prefix and mirror
  * directory name. Tailnet hostnames (zion, yosemite-s0, mac-mini) are already

package/dist/lib/session/sync/config.js

@@ -12,7 +12,7 @@ export const SYNC_BUNDLE = 'r2.backups';
  * actionable error if the bundle or any key is missing — sync cannot proceed
  * without real credentials (no silent fallback).
  */
-export function loadR2Config() {
+function resolveR2Config() {
     const { env } = readAndResolveBundleEnv(SYNC_BUNDLE, { caller: 'sessions-sync' });
     const accountId = env.R2_ACCOUNT_ID?.trim();
     const bucket = env.R2_BUCKET_NAME?.trim();
@@ -36,13 +36,60 @@ export function loadR2Config() {
         endpoint: `https://${accountId}.r2.cloudflarestorage.com`,
     };
 }
-/** True when the sync bundle exists and looks resolvable, without throwing. */
-export function isSyncConfigured() {
+// ── Resolution cache ────────────────────────────────────────────────────────
+// The daemon calls isSyncConfigured() + syncSessions() every ~90s, and each used
+// to trigger a fresh read of the biometry-gated `r2.backups` keychain items —
+// one Touch ID prompt per gated item, every cycle, forever. We instead resolve
+// at most once per process: a success is memoized for the process lifetime
+// (cleared on daemon SIGHUP via clearR2ConfigCache), so subsequent cycles never
+// touch the keychain again. A *prompt-bearing* failure (cancelled Touch ID, etc.)
+// starts a cooldown so a dismissed prompt is not re-issued every cycle. A simply
+// absent bundle never prompts, so it is re-checked each cycle (fast pickup when
+// the user later adds credentials).
+let cachedConfig = null;
+let lastPromptFailureAt = 0;
+/** Window after a prompt-bearing resolution failure during which we skip
+ *  re-attempting (and thus re-prompting). SIGHUP / restart bypasses it. */
+export const RESOLVE_RETRY_COOLDOWN_MS = 30 * 60 * 1000; // 30 minutes
+/** Drop the cached resolution so the next call reads the bundle fresh. Called on
+ *  daemon SIGHUP (to pick up rotated credentials) and between tests. */
+export function clearR2ConfigCache() {
+    cachedConfig = null;
+    lastPromptFailureAt = 0;
+}
+/**
+ * Resolve R2 credentials, reading the keychain at most once per process. The
+ * first call reads (and may prompt for Touch ID); every later call returns the
+ * memoized result. Throws if the bundle/keys are missing — failures are not
+ * memoized, but see isSyncConfigured for the re-prompt cooldown.
+ */
+export function loadR2Config() {
+    if (cachedConfig)
+        return cachedConfig;
+    cachedConfig = resolveR2Config();
+    return cachedConfig;
+}
+/**
+ * True when the sync bundle exists and resolves, without throwing. After a
+ * prompt-bearing failure (e.g. a cancelled Touch ID) it returns false without
+ * re-reading the keychain for RESOLVE_RETRY_COOLDOWN_MS, so a dismissed prompt
+ * does not re-storm every cycle. `now` is injectable for tests.
+ */
+export function isSyncConfigured(now = Date.now()) {
+    if (cachedConfig)
+        return true;
+    if (lastPromptFailureAt && now - lastPromptFailureAt < RESOLVE_RETRY_COOLDOWN_MS)
+        return false;
     try {
         loadR2Config();
         return true;
     }
-    catch {
+    catch (err) {
+        // A missing bundle never prompts, so keep re-checking it each cycle (so a
+        // later `agents secrets add` is picked up quickly). Any other failure may
+        // have cost a prompt (cancelled Touch ID, keychain error) — back off.
+        if (!/not found/i.test(err.message))
+            lastPromptFailureAt = now;
         return false;
     }
 }

package/dist/lib/types.d.ts

@@ -5,6 +5,7 @@
  * configuration schemas, resource tracking, registry types, and permission
  * formats for each supported agent.
  */
+import type { CloudProviderId } from './cloud/types.js';
 /** Unique identifier for a supported AI coding agent. */
 export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'roo' | 'antigravity' | 'grok' | 'kimi' | 'droid';
 /** How `agents run <agent>` chooses an installed version when none is pinned. */
@@ -83,6 +84,13 @@ export interface AgentConfig {
     variableSyntax: string;
     supportsHooks: boolean;
     nativeAgentsSkillsDir?: boolean;
+    /**
+     * This agent's *own* cloud backend. `agents cloud run --agent <id>` routes
+     * here when no `--provider` is given (precedence: --provider > this >
+     * cloud.default_provider > rush). Undefined means the agent has no native
+     * cloud and falls back to the configured default.
+     */
+    cloudProvider?: CloudProviderId;
     capabilities: {
         hooks: Capability;
         mcp: Capability;

package/dist/lib/version.d.ts

@@ -5,3 +5,14 @@
  * get stale behavior without this check.
  */
 export declare function getCliVersion(): string;
+/**
+ * Read the version from package.json on disk every call, bypassing the cache.
+ *
+ * `getCliVersion()` memoizes the version a long-running process *started* with.
+ * After `npm i -g` overwrites the install in place, the on-disk package.json
+ * changes but the running process keeps its old in-memory code. Comparing this
+ * fresh read against the cached startup value is how a daemon/broker detects it
+ * is now stale and should reload onto the new code (self-healing). Returns
+ * 'unknown' on any error.
+ */
+export declare function getCliVersionFresh(): string;

package/dist/lib/version.js

@@ -23,3 +23,23 @@ export function getCliVersion() {
     }
     return cached;
 }
+/**
+ * Read the version from package.json on disk every call, bypassing the cache.
+ *
+ * `getCliVersion()` memoizes the version a long-running process *started* with.
+ * After `npm i -g` overwrites the install in place, the on-disk package.json
+ * changes but the running process keeps its old in-memory code. Comparing this
+ * fresh read against the cached startup value is how a daemon/broker detects it
+ * is now stale and should reload onto the new code (self-healing). Returns
+ * 'unknown' on any error.
+ */
+export function getCliVersionFresh() {
+    try {
+        const pkgPath = path.join(__dirname, '..', '..', 'package.json');
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        return String(pkg.version || 'unknown');
+    }
+    catch {
+        return 'unknown';
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.20",
+  "version": "1.20.22",
   "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",
@@ -25,6 +25,7 @@
     "dist/**/*.d.ts",
     "dist/**/*.json",
     "dist/lib/secrets/Agents CLI.app/**",
+    "dist/lib/menubar/MenubarHelper.app/**",
     "scripts/postinstall.js",
     "scripts/install-helper.js",
     "CHANGELOG.md",
@@ -43,7 +44,7 @@
     "url": "https://github.com/phnx-labs/agents-cli/issues"
   },
   "scripts": {
-    "build": "tsc && rm -rf 'dist/lib/secrets/AgentsKeychain.app' 'dist/lib/secrets/Agents CLI.app' && ([ \"$(uname)\" = \"Darwin\" ] && cp -R 'bin/Agents CLI.app' 'dist/lib/secrets/Agents CLI.app' || true)",
+    "build": "tsc && rm -rf 'dist/lib/secrets/AgentsKeychain.app' 'dist/lib/secrets/Agents CLI.app' 'dist/lib/menubar/MenubarHelper.app' && ([ \"$(uname)\" = \"Darwin\" ] && cp -R 'bin/Agents CLI.app' 'dist/lib/secrets/Agents CLI.app' || true) && ([ \"$(uname)\" = \"Darwin\" ] && [ -d 'bin/MenubarHelper.app' ] && mkdir -p 'dist/lib/menubar' && cp -R 'bin/MenubarHelper.app' 'dist/lib/menubar/MenubarHelper.app' || true)",
     "prepack": "scripts/verify-keychain-helper.sh",
     "postinstall": "node scripts/postinstall.js",
     "dev": "tsx src/index.ts",

package/scripts/postinstall.js

@@ -239,6 +239,8 @@ To enable version-aware shims, add this to your shell config:
     console.log(`  Installed shorthands: ${written.join(', ')}`);
   }
 
+  await healLongRunningProcesses();
+
   const version = getVersion();
   if (version) {
     const section = getChangelogSection(version);
@@ -250,6 +252,39 @@ To enable version-aware shims, add this to your shell config:
   }
 }
 
+/**
+ * Self-heal long-running processes onto the just-installed code (macOS).
+ *
+ * The root cause behind stale-behavior bugs is a daemon/broker that keeps
+ * running pre-upgrade code for days. An in-place `npm i -g` swaps the files but
+ * not the running processes — so we bounce them here, the one moment we know the
+ * code just changed. Best-effort and non-fatal: a failure must never break the
+ * install. Skipped in CI and when AGENTS_NO_HEAL=1.
+ */
+async function healLongRunningProcesses() {
+  if (process.platform !== 'darwin') return;
+  if (process.env.CI || process.env.AGENTS_NO_HEAL === '1') return;
+  // Routines daemon: restart so it reloads new code (e.g. picks up keychain
+  // read-memoization / broker fast-path that a stale daemon wouldn't have).
+  try {
+    const d = await import('../dist/lib/daemon.js');
+    if (d.isDaemonRunning?.()) {
+      d.stopDaemon?.();
+      d.startDaemon?.();
+      console.log('  Restarted the routines daemon onto this version.');
+    }
+  } catch { /* best effort */ }
+  // Persistent secrets-agent broker: kickstart so launchd relaunches it on the
+  // new code. No-op if the service isn't installed; never blocks.
+  try {
+    const a = await import('../dist/lib/secrets/agent.js');
+    if (a.secretsAgentServiceInstalled?.()) {
+      a.kickstartSecretsAgentService?.();
+      console.log('  Reloaded the secrets-agent service onto this version.');
+    }
+  } catch { /* best effort */ }
+}
+
 main().catch((err) => {
   console.error(err);
   process.exit(0);