@phnx-labs/agents-cli 1.19.0 → 1.19.2

package/dist/lib/secrets/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * Cross-platform secure credential storage.
  *
- * macOS: Uses Keychain via signed Swift helper (AgentsKeychain.app) or `security` CLI.
+ * macOS: Uses Keychain via signed Swift helper (Agents CLI.app) or `security` CLI.
  * Linux: Uses libsecret (GNOME Keyring) via `secret-tool` CLI.
  * Windows: Not yet supported.
  *
@@ -56,6 +56,20 @@ export declare function setKeychainBackendForTest(b: KeychainBackend | null): Ke
 export declare function hasKeychainToken(item: string, sync?: boolean): boolean;
 /** Retrieve a secret value from the keychain/keyring. Throws if not found. */
 export declare function getKeychainToken(item: string, sync?: boolean): string;
+/**
+ * Batch-read multiple keychain items behind a single LocalAuthentication
+ * prompt. macOS shows ONE Touch ID prompt and every requested item is
+ * unlocked in the same process. Returns a Map keyed by item name. Missing
+ * items are absent from the map (caller decides whether that's an error).
+ *
+ * `reason` is shown to the user under the Touch ID prompt — e.g.
+ * "read 'hetzner.com' secrets for agent 'claude'". Apple's HIG recommends
+ * a lowercase verb phrase that completes the sentence "X is required to ___".
+ *
+ * On Linux or when a test backend is installed, falls back to individual
+ * `get` calls — no biometric prompt path on those platforms.
+ */
+export declare function getKeychainTokensBatch(items: string[], _sync?: boolean, reason?: string): Map<string, string>;
 /** Store or update a secret value in the keychain/keyring. iCloud-synced when sync=true (macOS only). */
 export declare function setKeychainToken(item: string, value: string, sync?: boolean): void;
 /** Delete a keychain/keyring item. Returns true if it existed. */

package/dist/lib/secrets/index.js

@@ -1,7 +1,7 @@
 /**
  * Cross-platform secure credential storage.
  *
- * macOS: Uses Keychain via signed Swift helper (AgentsKeychain.app) or `security` CLI.
+ * macOS: Uses Keychain via signed Swift helper (Agents CLI.app) or `security` CLI.
  * Linux: Uses libsecret (GNOME Keyring) via `secret-tool` CLI.
  * Windows: Not yet supported.
  *
@@ -55,7 +55,7 @@ export function profileKeychainItem(provider) {
 export function secretsKeychainItem(bundle, key) {
     return `${SERVICE_PREFIX}.secrets.${bundle}.${key}`;
 }
-// Resolve the bundled, signed-and-notarized AgentsKeychain.app shipped
+// Resolve the bundled, signed-and-notarized Agents CLI.app shipped
 // alongside the compiled JS. The .app embeds a provisioning profile that
 // grants the application-identifier + keychain-access-groups entitlements
 // macOS requires for kSecAttrSynchronizable writes. Bare CLI binaries
@@ -64,7 +64,7 @@ export function secretsKeychainItem(bundle, key) {
 // be prebuilt by `scripts/build-keychain-helper.sh` and shipped.
 function ensureKeychainHelper() {
     const here = path.dirname(fileURLToPath(import.meta.url));
-    const binPath = path.join(here, 'AgentsKeychain.app', 'Contents', 'MacOS', 'AgentsKeychain');
+    const binPath = path.join(here, 'Agents CLI.app', 'Contents', 'MacOS', 'Agents CLI');
     if (!fs.existsSync(binPath)) {
         throw new Error(`Keychain helper missing at ${binPath}. ` +
             'This npm package was built without the signed helper bundle. Reinstall agents-cli.');
@@ -118,7 +118,9 @@ export function getKeychainToken(item, sync = false) {
         if (token)
             return token;
     }
-    // Fallback: binary searches both synced and non-synced via kSecAttrSynchronizableAny
+    // Fallback: binary searches both synced and non-synced via kSecAttrSynchronizableAny.
+    // `get` is the unauthenticated path — no LocalAuthentication prompt. Used by
+    // profiles.ts (OAuth refresh) where biometric on every API call is too noisy.
     const bin = ensureKeychainHelper();
     const result = spawnSync(bin, ['get', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
@@ -134,6 +136,87 @@ export function getKeychainToken(item, sync = false) {
         throw new Error(`Keychain item '${item}' exists but is empty.`);
     return token;
 }
+/**
+ * Batch-read multiple keychain items behind a single LocalAuthentication
+ * prompt. macOS shows ONE Touch ID prompt and every requested item is
+ * unlocked in the same process. Returns a Map keyed by item name. Missing
+ * items are absent from the map (caller decides whether that's an error).
+ *
+ * `reason` is shown to the user under the Touch ID prompt — e.g.
+ * "read 'hetzner.com' secrets for agent 'claude'". Apple's HIG recommends
+ * a lowercase verb phrase that completes the sentence "X is required to ___".
+ *
+ * On Linux or when a test backend is installed, falls back to individual
+ * `get` calls — no biometric prompt path on those platforms.
+ */
+export function getKeychainTokensBatch(items, _sync = false, reason) {
+    const result = new Map();
+    if (items.length === 0)
+        return result;
+    if (backend) {
+        for (const item of items) {
+            try {
+                result.set(item, backend.get(item, _sync));
+            }
+            catch { /* missing — skip */ }
+        }
+        return result;
+    }
+    assertSupportedPlatform();
+    if (isLinux()) {
+        for (const item of items) {
+            try {
+                result.set(item, linuxBackend.get(item, _sync));
+            }
+            catch { /* missing — skip */ }
+        }
+        return result;
+    }
+    // macOS: single helper invocation with Touch ID gate.
+    const bin = ensureKeychainHelper();
+    const helperArgs = ['get-batch', os.userInfo().username];
+    if (reason)
+        helperArgs.push('--reason', reason);
+    helperArgs.push(...items);
+    const child = spawnSync(bin, helperArgs, {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (child.status !== 0) {
+        const msg = child.stderr?.toString().trim();
+        throw new Error(msg || `Failed to batch-read ${items.length} keychain items.`);
+    }
+    const out = child.stdout?.toString() ?? '';
+    // Parser. Output is a sequence of records:
+    //   "V <service>\n<value>\n"   (present)
+    //   "M <service>\n"            (missing)
+    // Service names cannot contain '\n' (validated at write time); values are
+    // also newline-free (rejected by setKeychainToken). So splitting on '\n'
+    // and walking line-by-line is unambiguous.
+    const lines = out.split('\n');
+    // Last entry from split is the empty string after a trailing newline.
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line === '' && i === lines.length - 1)
+            break;
+        if (line.startsWith('V ')) {
+            const service = line.slice(2);
+            const value = lines[i + 1] ?? '';
+            result.set(service, value);
+            i += 2;
+        }
+        else if (line.startsWith('M ')) {
+            i += 1;
+        }
+        else if (line === '') {
+            i += 1;
+        }
+        else {
+            throw new Error(`Malformed get-batch output line: ${JSON.stringify(line)}`);
+        }
+    }
+    return result;
+}
 /** Store or update a secret value in the keychain/keyring. iCloud-synced when sync=true (macOS only). */
 export function setKeychainToken(item, value, sync = false) {
     if (backend) {
@@ -151,28 +234,23 @@ export function setKeychainToken(item, value, sync = false) {
         linuxBackend.set(item, value, sync);
         return;
     }
-    // macOS path
-    if (sync) {
-        const bin = ensureKeychainHelper();
-        const result = spawnSync(bin, ['set', item, os.userInfo().username], {
-            input: value,
-            stdio: ['pipe', 'pipe', 'pipe'],
-        });
-        if (result.status !== 0) {
-            const msg = result.stderr?.toString().trim();
-            throw new Error(msg || `Failed to write keychain item '${item}'.`);
-        }
-        return;
-    }
-    // `security -i` keeps the value out of argv (and `ps`).
-    const user = os.userInfo().username;
-    const cmd = `add-generic-password -a ${quoteForSecurityCli(user)} -s ${quoteForSecurityCli(item)} -w ${quoteForSecurityCli(value)} -T ${quoteForSecurityCli('')} -U\n`;
-    const result = spawnSync('security', ['-i'], {
-        input: cmd,
+    // macOS path. Both sync and non-sync writes go through the .app helper so
+    // the item picks up our SecAccess ACL (helper as trusted reader). That ACL
+    // is what stops macOS from showing the legacy "enter password" sheet on
+    // subsequent reads. The helper takes an optional `nosync` arg for
+    // device-local writes; sync writes get kSecAttrSynchronizable=true by
+    // default.
+    const bin = ensureKeychainHelper();
+    const args = ['set', item, os.userInfo().username];
+    if (!sync)
+        args.push('nosync');
+    const result = spawnSync(bin, args, {
+        input: value,
         stdio: ['pipe', 'pipe', 'pipe'],
     });
     if (result.status !== 0) {
-        throw new Error(`Failed to write keychain item '${item}' (exit ${result.status}).`);
+        const msg = result.stderr?.toString().trim();
+        throw new Error(msg || `Failed to write keychain item '${item}'.`);
     }
 }
 /** Delete a keychain/keyring item. Returns true if it existed. */
@@ -193,9 +271,6 @@ export function deleteKeychainToken(item, sync = false) {
         stdio: ['ignore', 'pipe', 'pipe'],
     }).status === 0;
 }
-function quoteForSecurityCli(s) {
-    return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
-}
 /** Enumerate keychain/keyring item names starting with the given prefix. */
 export function listKeychainItems(prefix) {
     if (backend)

package/dist/lib/session/db.d.ts

@@ -157,5 +157,15 @@ export declare function getRowCount(): {
 };
 /** Count sessions older than the given timestamp (for dry-run previews). */
 export declare function countSessionsOlderThan(cutoffMs: number): number;
+/**
+ * Rewrite file_path for all sessions whose path starts with oldPrefix, replacing
+ * it with newPrefix + the unchanged suffix. Also clears the matching scan_ledger
+ * entries so they are re-indexed from the new location on the next scan.
+ *
+ * Used by removeVersion after soft-deleting a version directory to trash, so
+ * that session reads (transcript view, /continue) still work from the trash path.
+ * Returns the number of session rows updated.
+ */
+export declare function updateSessionFilePaths(oldPrefix: string, newPrefix: string): number;
 /** Delete sessions older than the given timestamp. Returns the number of rows deleted. */
 export declare function deleteSessionsOlderThan(cutoffMs: number): number;

package/dist/lib/session/db.js

@@ -749,6 +749,32 @@ export function countSessionsOlderThan(cutoffMs) {
     const row = db.prepare(`SELECT COUNT(*) AS n FROM sessions WHERE timestamp < ?`).get(cutoffIso);
     return row.n;
 }
+/**
+ * Rewrite file_path for all sessions whose path starts with oldPrefix, replacing
+ * it with newPrefix + the unchanged suffix. Also clears the matching scan_ledger
+ * entries so they are re-indexed from the new location on the next scan.
+ *
+ * Used by removeVersion after soft-deleting a version directory to trash, so
+ * that session reads (transcript view, /continue) still work from the trash path.
+ * Returns the number of session rows updated.
+ */
+export function updateSessionFilePaths(oldPrefix, newPrefix) {
+    const db = getDB();
+    const rows = db
+        .prepare(`SELECT id, file_path FROM sessions WHERE file_path LIKE ?`)
+        .all(oldPrefix + '%');
+    if (rows.length === 0)
+        return 0;
+    const txn = db.transaction(() => {
+        for (const { id, file_path } of rows) {
+            const newPath = newPrefix + file_path.slice(oldPrefix.length);
+            db.prepare(`UPDATE sessions SET file_path = ? WHERE id = ?`).run(newPath, id);
+            db.prepare(`DELETE FROM scan_ledger WHERE file_path = ?`).run(canonicalLedgerKey(file_path));
+        }
+    });
+    txn();
+    return rows.length;
+}
 /** Delete sessions older than the given timestamp. Returns the number of rows deleted. */
 export function deleteSessionsOlderThan(cutoffMs) {
     const db = getDB();

package/dist/lib/shims.d.ts

@@ -55,8 +55,12 @@ export interface ConflictInfo {
  *   v12 — helper calls inside generated shims use the absolute agents-cli
  *         entrypoint instead of PATH-resolved `agents`.
  *   v13 — validate agents.yaml version strings before constructing binary paths.
+ *   v14 — derive `configDirName` from `agentConfig.configDir` relative to $HOME
+ *         instead of hardcoding `.${agent}`. Backwards-compatible for every
+ *         existing agent (their configDir is `~/.{agent}`); enables nested
+ *         layouts like Antigravity's `~/.gemini/antigravity-cli/`.
  */
-export declare const SHIM_SCHEMA_VERSION = 13;
+export declare const SHIM_SCHEMA_VERSION = 14;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.

package/dist/lib/shims.js

@@ -179,8 +179,12 @@ async function promptConflictStrategy(conflictInfos) {
  *   v12 — helper calls inside generated shims use the absolute agents-cli
  *         entrypoint instead of PATH-resolved `agents`.
  *   v13 — validate agents.yaml version strings before constructing binary paths.
+ *   v14 — derive `configDirName` from `agentConfig.configDir` relative to $HOME
+ *         instead of hardcoding `.${agent}`. Backwards-compatible for every
+ *         existing agent (their configDir is `~/.{agent}`); enables nested
+ *         layouts like Antigravity's `~/.gemini/antigravity-cli/`.
  */
-export const SHIM_SCHEMA_VERSION = 13;
+export const SHIM_SCHEMA_VERSION = 14;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
@@ -196,7 +200,11 @@ function getAgentsBinForGeneratedShim() {
 export function generateShimScript(agent) {
     const agentConfig = AGENTS[agent];
     const cliCommand = agentConfig.cliCommand;
-    const configDirName = `.${agent}`;
+    // Derive the relative config-dir path from the registry. For most agents
+    // this is just `.${agent}` (e.g., `.claude`, `.codex`); for nested layouts
+    // like Antigravity (`~/.gemini/antigravity-cli`) it carries the full
+    // subpath so per-version HOME symlinks reach the right place.
+    const configDirName = path.relative(os.homedir(), agentConfig.configDir);
     const agentsBin = shellQuote(getAgentsBinForGeneratedShim());
     const managedEnv = agent === 'claude'
         ? `
@@ -504,7 +512,9 @@ function assertSafeVersion(version) {
 export function generateVersionedAliasScript(agent, version) {
     assertSafeVersion(version);
     const agentConfig = AGENTS[agent];
-    const configDirName = `.${agent}`;
+    // Same derivation as `generateShimScript` so nested layouts (e.g.,
+    // Antigravity's `~/.gemini/antigravity-cli`) land in the right place.
+    const configDirName = path.relative(os.homedir(), agentConfig.configDir);
     const managedEnv = agent === 'claude'
         ? `
 # Claude stores OAuth credentials in the macOS keychain. Scope them to this
@@ -637,7 +647,9 @@ function getAgentConfigPath(agent) {
 function getVersionConfigPath(agent, version) {
     const agentConfig = AGENTS[agent];
     const versionsDir = getVersionsDir();
-    const configDirName = `.${agent}`; // .claude, .codex, etc.
+    // Carry the agent's full configDir subpath so nested layouts work.
+    // e.g., antigravity → `.gemini/antigravity-cli`, claude → `.claude`.
+    const configDirName = path.relative(os.homedir(), agentConfig.configDir);
     return path.join(versionsDir, agent, version, 'home', configDirName);
 }
 /**
@@ -709,6 +721,7 @@ export async function switchConfigSymlink(agent, version) {
             }
             // Different target - update it
             fs.unlinkSync(configPath);
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
             fs.symlinkSync(versionConfigPath, configPath);
             return { success: true };
         }
@@ -721,7 +734,7 @@ export async function switchConfigSymlink(agent, version) {
             const finalBackupPath = path.join(agentBackupDir, String(timestamp));
             fs.mkdirSync(agentBackupDir, { recursive: true });
             fs.renameSync(configPath, finalBackupPath);
-            // Create symlink
+            // Create symlink (parent already exists since the dir we just moved was here)
             fs.symlinkSync(versionConfigPath, configPath);
             return { success: true, backupPath: finalBackupPath };
         }
@@ -731,7 +744,10 @@ export async function switchConfigSymlink(agent, version) {
     }
     catch (err) {
         if (err.code === 'ENOENT') {
-            // Config path doesn't exist - create symlink
+            // Config path doesn't exist - create symlink.
+            // For nested layouts (e.g., ~/.gemini/antigravity-cli) the parent dir
+            // may also be missing if the parent agent (Gemini) is not installed.
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
             fs.symlinkSync(versionConfigPath, configPath);
             return { success: true };
         }

package/dist/lib/types.d.ts

@@ -6,7 +6,7 @@
  * formats for each supported agent.
  */
 /** Unique identifier for a supported AI coding agent. */
-export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'roo';
+export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'roo' | 'antigravity' | 'grok';
 /** How `agents run <agent>` chooses an installed version when none is pinned. */
 export type RunStrategy = 'pinned' | 'available' | 'balanced';
 /** Preview features that users can opt into via `agents beta`. */