@phnx-labs/agents-cli 1.20.18 → 1.20.20

package/dist/lib/secrets/linux.js

@@ -7,24 +7,21 @@
  * (common on server-class Linux — no graphical login means the keyring
  * passphrase never enters the daemon, so `secret-tool store` fails with
  * "Cannot create an item in a locked collection"), we transparently switch
- * to a file-based AES-256-GCM encrypted store under
- * `~/.agents/.cache/secrets/`. The encryption key is scrypt-derived from a
- * passphrase read from `AGENTS_SECRETS_PASSPHRASE` (preferred) or a TTY
- * prompt. The decision is cached per process; one stderr line is emitted
- * the first time the fallback activates.
+ * to the AES-256-GCM encrypted-file store in ./filestore.ts. The decision is
+ * cached per process; one stderr line is emitted the first time the fallback
+ * activates.
  *
  * Secrets stored via secret-tool use:
  *   service = "agents-cli"
  *   account = username
  *   item    = the secret identifier
- *
- * File-fallback layout: one `<item>.enc` JSON file per item, mode 0600.
  */
-import { spawnSync, execSync } from 'child_process';
-import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'crypto';
-import * as fs from 'fs';
+import { spawnSync } from 'child_process';
 import * as os from 'os';
-import * as path from 'path';
+import { fileStore, fileDir, fileStoreHasItems, machinePassphraseExists, _resetFileStoreForTest, } from './filestore.js';
+// Re-exported so existing importers (and tests) can keep reaching these via
+// './linux.js'. The implementations live in ./filestore.ts.
+export { encryptForFallback, decryptForFallback, fileBackend, } from './filestore.js';
 const SERVICE = 'agents-cli';
 // ---------- secret-tool availability ----------
 function secretToolAvailable() {
@@ -38,12 +35,6 @@ let isAvailable = false;
 // ---------- file fallback state ----------
 let useFileFallback = false;
 let warnedFallback = false;
-let warnedAutoPassphrase = false;
-let fileDirOverride = null;
-let cachedPassphrase = null;
-function fileDir() {
-    return fileDirOverride ?? path.join(os.homedir(), '.agents', '.cache', 'secrets');
-}
 function activateFileFallback() {
     if (useFileFallback)
         return;
@@ -57,18 +48,6 @@ function isLockedCollectionError(stderr) {
     return /locked collection/i.test(stderr) ||
         /Prompt was dismissed/i.test(stderr);
 }
-/** True if the fallback dir has any committed encrypted items. Means an
- *  earlier process (this one or another) already routed writes to the file
- *  store, so this process must keep reading/writing from the same store —
- *  otherwise `list` / `get` / `has` would silently miss them. */
-function fileFallbackPreviouslyActivated() {
-    try {
-        return fs.readdirSync(fileDir()).some((e) => e.endsWith('.enc'));
-    }
-    catch {
-        return false;
-    }
-}
 /**
  * Decide which backend a given op should use. Activates file fallback if
  * `secret-tool` is missing and `AGENTS_SECRETS_PASSPHRASE` is set, OR if a
@@ -79,7 +58,7 @@ function fileFallbackPreviouslyActivated() {
 function preflight() {
     if (useFileFallback)
         return 'file';
-    if (fileFallbackPreviouslyActivated()) {
+    if (fileStoreHasItems()) {
         activateFileFallback();
         return 'file';
     }
@@ -107,233 +86,12 @@ function preflight() {
     }
     return 'secret-tool';
 }
-// ---------- passphrase ----------
-function readPassphraseFromTty() {
-    const fd = fs.openSync('/dev/tty', 'r+');
-    let echoDisabled = false;
-    try {
-        fs.writeSync(fd, 'Enter AGENTS_SECRETS_PASSPHRASE: ');
-        try {
-            execSync('stty -echo < /dev/tty', { stdio: 'ignore' });
-            echoDisabled = true;
-        }
-        catch {
-            // stty not available — fall through; passphrase will echo. Better
-            // than refusing to function.
-        }
-        let pass = '';
-        const buf = Buffer.alloc(1);
-        while (true) {
-            const n = fs.readSync(fd, buf, 0, 1, null);
-            if (n === 0)
-                break;
-            const ch = buf.toString('utf8', 0, n);
-            if (ch === '\n' || ch === '\r')
-                break;
-            pass += ch;
-        }
-        return pass;
-    }
-    finally {
-        if (echoDisabled) {
-            try {
-                execSync('stty echo < /dev/tty', { stdio: 'ignore' });
-            }
-            catch { /* best effort */ }
-        }
-        try {
-            fs.writeSync(fd, '\n');
-        }
-        catch { /* best effort */ }
-        fs.closeSync(fd);
-    }
-}
-/** Path of the auto-provisioned machine-local passphrase. Lives alongside the
- *  encrypted items but is never itself an item (no `.enc` suffix, so it's
- *  excluded from list/has/get and from fileFallbackPreviouslyActivated). */
-function passphraseFilePath() {
-    return path.join(fileDir(), '.passphrase');
-}
-/** True if a machine-local passphrase has already been provisioned. */
-function machinePassphraseExists() {
-    try {
-        return fs.readFileSync(passphraseFilePath(), 'utf8').trim().length > 0;
-    }
-    catch {
-        return false;
-    }
-}
-function readMachinePassphrase() {
-    try {
-        const p = fs.readFileSync(passphraseFilePath(), 'utf8').trim();
-        return p.length > 0 ? p : null;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Provision (or read back) a stable machine-local passphrase for the encrypted
- * file store, so `agents secrets` works out of the box on a headless box where
- * the keyring is locked and no AGENTS_SECRETS_PASSPHRASE is set.
- *
- * Security model: this is encryption-at-rest with the key held in a 0600 file —
- * the same posture as an SSH private key, and identical to the common
- * "export AGENTS_SECRETS_PASSPHRASE=… in ~/.zshenv (chmod 600)" workaround. The
- * keyring (key in a daemon's locked memory) is stronger but is unavailable
- * without a graphical/unlocked session. For an off-disk key, set
- * AGENTS_SECRETS_PASSPHRASE (it always takes precedence) or unlock the keyring.
- */
-function provisionMachinePassphrase() {
-    const existing = readMachinePassphrase();
-    if (existing)
-        return existing;
-    ensureFileDir();
-    const generated = randomBytes(32).toString('base64');
-    const fp = passphraseFilePath();
-    try {
-        // wx: fail if a concurrent process created it first (then we read theirs).
-        fs.writeFileSync(fp, generated, { mode: 0o600, flag: 'wx' });
-    }
-    catch {
-        const raced = readMachinePassphrase();
-        if (raced)
-            return raced;
-        throw new Error(`Failed to provision machine-local passphrase at ${fp}.`);
-    }
-    if (!warnedAutoPassphrase) {
-        warnedAutoPassphrase = true;
-        process.stderr.write(`[agents] keyring locked and no AGENTS_SECRETS_PASSPHRASE set; provisioned a ` +
-            `machine-local passphrase at ${fp} (mode 0600). Set AGENTS_SECRETS_PASSPHRASE ` +
-            `for a key held off disk.\n`);
-    }
-    return generated;
-}
-function getPassphrase() {
-    if (cachedPassphrase !== null)
-        return cachedPassphrase;
-    const env = process.env.AGENTS_SECRETS_PASSPHRASE;
-    if (env && env.length > 0) {
-        cachedPassphrase = env;
-        return env;
-    }
-    // A previously-provisioned machine-local passphrase is this machine's stable
-    // file-store key — prefer it for both interactive and headless runs so they
-    // always agree (a TTY run won't re-prompt once the file exists).
-    const onDisk = readMachinePassphrase();
-    if (onDisk) {
-        cachedPassphrase = onDisk;
-        return onDisk;
-    }
-    // First run, no env, no provisioned key: prompt when interactive, otherwise
-    // (headless — the reported bug) auto-provision instead of hard-failing.
-    if (process.stdin.isTTY) {
-        const p = readPassphraseFromTty();
-        if (!p)
-            throw new Error('No passphrase entered.');
-        cachedPassphrase = p;
-        return p;
-    }
-    cachedPassphrase = provisionMachinePassphrase();
-    return cachedPassphrase;
-}
-function deriveKey(passphrase, salt) {
-    return scryptSync(passphrase, salt, 32);
-}
-/** Encrypt plaintext under a passphrase using AES-256-GCM with a random
- *  scrypt salt and a random 96-bit IV. Exported for tests. */
-export function encryptForFallback(plaintext, passphrase) {
-    const salt = randomBytes(16);
-    const iv = randomBytes(12);
-    const key = deriveKey(passphrase, salt);
-    const cipher = createCipheriv('aes-256-gcm', key, iv);
-    const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
-    return {
-        salt: salt.toString('hex'),
-        iv: iv.toString('hex'),
-        authTag: cipher.getAuthTag().toString('hex'),
-        ciphertext: ciphertext.toString('hex'),
-    };
-}
-/** Decrypt an EncFile under a passphrase. Throws on wrong key or tampered
- *  ciphertext (auth-tag mismatch). Exported for tests. */
-export function decryptForFallback(enc, passphrase) {
-    const salt = Buffer.from(enc.salt, 'hex');
-    const iv = Buffer.from(enc.iv, 'hex');
-    const authTag = Buffer.from(enc.authTag, 'hex');
-    const ciphertext = Buffer.from(enc.ciphertext, 'hex');
-    const key = deriveKey(passphrase, salt);
-    const decipher = createDecipheriv('aes-256-gcm', key, iv);
-    decipher.setAuthTag(authTag);
-    const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
-    return plaintext.toString('utf8');
-}
-// ---------- file backend ----------
-function fileFor(item) {
-    return path.join(fileDir(), `${item}.enc`);
-}
-function ensureFileDir() {
-    fs.mkdirSync(fileDir(), { recursive: true, mode: 0o700 });
-}
-function fileHas(item) {
-    return fs.existsSync(fileFor(item));
-}
-function fileGet(item) {
-    const fp = fileFor(item);
-    if (!fs.existsSync(fp)) {
-        throw new Error(`Secret '${item}' not found in encrypted store.`);
-    }
-    const raw = fs.readFileSync(fp, 'utf8');
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        throw new Error(`Encrypted secret file ${fp} is corrupt (not valid JSON).`);
-    }
-    try {
-        return decryptForFallback(parsed, getPassphrase());
-    }
-    catch {
-        throw new Error(`Failed to decrypt '${item}'. Wrong AGENTS_SECRETS_PASSPHRASE or tampered file.`);
-    }
-}
-function fileSet(item, value) {
-    ensureFileDir();
-    const enc = encryptForFallback(value, getPassphrase());
-    fs.writeFileSync(fileFor(item), JSON.stringify(enc), { mode: 0o600 });
-}
-function fileDelete(item) {
-    const fp = fileFor(item);
-    if (!fs.existsSync(fp))
-        return true; // idempotent, matches secret-tool clear
-    fs.unlinkSync(fp);
-    return true;
-}
-function fileList(prefix) {
-    const dir = fileDir();
-    if (!fs.existsSync(dir))
-        return [];
-    return fs.readdirSync(dir)
-        .filter((f) => f.endsWith('.enc'))
-        .map((f) => f.slice(0, -'.enc'.length))
-        .filter((name) => name.startsWith(prefix));
-}
-/** File-only KeychainBackend (exported for tests; the public surface uses
- *  the secret-tool-with-fallback `linuxBackend` below). */
-export const fileBackend = {
-    has: fileHas,
-    get: fileGet,
-    set: fileSet,
-    delete: fileDelete,
-    list: fileList,
-};
 // ---------- secret-tool ops with fallback ----------
 /** secret-tool lookup attributes:
  *   service=agents-cli account=<user> item=<itemName> */
 export function hasSecretToolToken(item) {
     if (preflight() === 'file')
-        return fileHas(item);
+        return fileStore.has(item);
     const user = os.userInfo().username;
     const result = spawnSync('secret-tool', [
         'lookup',
@@ -347,13 +105,13 @@ export function hasSecretToolToken(item) {
     const stderr = result.stderr?.toString() ?? '';
     if (isLockedCollectionError(stderr)) {
         activateFileFallback();
-        return fileHas(item);
+        return fileStore.has(item);
     }
     return false;
 }
 export function getSecretToolToken(item) {
     if (preflight() === 'file')
-        return fileGet(item);
+        return fileStore.get(item);
     const user = os.userInfo().username;
     const result = spawnSync('secret-tool', [
         'lookup',
@@ -370,7 +128,7 @@ export function getSecretToolToken(item) {
     const stderr = result.stderr?.toString() ?? '';
     if (isLockedCollectionError(stderr)) {
         activateFileFallback();
-        return fileGet(item);
+        return fileStore.get(item);
     }
     throw new Error(`Secret '${item}' not found in keyring.`);
 }
@@ -378,7 +136,7 @@ export function setSecretToolToken(item, value) {
     if (!value || !value.trim())
         throw new Error('Secret value is empty.');
     if (preflight() === 'file')
-        return fileSet(item, value);
+        return fileStore.set(item, value);
     const user = os.userInfo().username;
     const label = `agents-cli: ${item}`;
     const result = spawnSync('secret-tool', [
@@ -393,7 +151,7 @@ export function setSecretToolToken(item, value) {
     const stderr = result.stderr?.toString().trim() ?? '';
     if (isLockedCollectionError(stderr)) {
         activateFileFallback();
-        fileSet(item, value);
+        fileStore.set(item, value);
         return;
     }
     throw new Error(`Failed to store secret '${item}': ${stderr || 'unknown error'}\n` +
@@ -402,7 +160,7 @@ export function setSecretToolToken(item, value) {
 }
 export function deleteSecretToolToken(item) {
     if (preflight() === 'file')
-        return fileDelete(item);
+        return fileStore.delete(item);
     const user = os.userInfo().username;
     const result = spawnSync('secret-tool', [
         'clear',
@@ -415,7 +173,7 @@ export function deleteSecretToolToken(item) {
     const stderr = result.stderr?.toString() ?? '';
     if (isLockedCollectionError(stderr)) {
         activateFileFallback();
-        return fileDelete(item);
+        return fileStore.delete(item);
     }
     // secret-tool clear returns 0 whether the item existed or not.
     // A non-zero exit that isn't a locked-collection error is a real failure;
@@ -456,7 +214,7 @@ export function parseSecretToolItems(output, prefix) {
  */
 export function listSecretToolItems(prefix) {
     if (preflight() === 'file')
-        return fileList(prefix);
+        return fileStore.list(prefix);
     const result = spawnSync('secret-tool', [
         'search',
         '--all',
@@ -466,7 +224,7 @@ export function listSecretToolItems(prefix) {
         const stderr = result.stderr?.toString() ?? '';
         if (isLockedCollectionError(stderr)) {
             activateFileFallback();
-            return fileList(prefix);
+            return fileStore.list(prefix);
         }
         return [];
     }
@@ -495,13 +253,12 @@ export const linuxBackend = {
     },
 };
 /** Test-only: reset module state so independent test cases don't bleed
- *  passphrase / fallback decisions across each other. */
+ *  passphrase / fallback decisions across each other. File-store state (file
+ *  dir + cached passphrase) lives in ./filestore.ts and is reset there. */
 export function _resetForTest(opts = {}) {
-    fileDirOverride = opts.fileDir ?? null;
+    _resetFileStoreForTest({ fileDir: opts.fileDir ?? null, passphrase: opts.passphrase ?? null });
     useFileFallback = opts.forceFileFallback ?? false;
     warnedFallback = false;
-    warnedAutoPassphrase = false;
-    cachedPassphrase = opts.passphrase ?? null;
     checkedAvailability = false;
     isAvailable = false;
 }

package/dist/lib/versions.d.ts

@@ -176,6 +176,26 @@ export declare function installVersion(agent: AgentId, version: string, onProgre
     installedVersion: string;
     error?: string;
 }>;
+/**
+ * Fold a stale literal `latest` version dir into the real resolved version.
+ *
+ * Script-installed agents (droid, grok) have no npm package to read a version
+ * from, so the installer resolves the version by probing `<cli> --version`
+ * after the install script runs. When that probe failed (3s timeout, or the
+ * freshly-dropped binary not yet resolvable on PATH) the installer fell back to
+ * the literal string `latest`, creating a `versions/<agent>/latest/` dir. A
+ * later install where the probe succeeded then created a SECOND dir at the real
+ * semver, orphaning `latest` — and because these agents' getBinaryPath points
+ * at a single global binary regardless of version dir, `latest` keeps showing
+ * up in `agents view` next to the real version forever.
+ *
+ * Call this once the install path has resolved a real version: if a stale
+ * `latest` dir exists, rename it onto the real version (preserving `home/`), or
+ * if the real dir already exists, soft-delete the `latest` dir to trash. No-op
+ * when nothing was resolved or no stale dir is present, so it is safe to call
+ * on every script-based install. Returns the action taken (for tests/logging).
+ */
+export declare function reconcileStaleLatestDir(agent: AgentId, installedVersion: string): Promise<'none' | 'renamed' | 'trashed'>;
 /**
  * Soft-delete a version directory by moving it to ~/.agents/.system/trash/versions/.
  * Returns the trash path on success or null on failure / no source.

package/dist/lib/versions.js

@@ -996,6 +996,9 @@ export async function installVersion(agent, version, onProgress) {
             await execAsync(script, { timeout: 120000 });
             if (version === 'latest') {
                 installedVersion = await getCliVersionFromPath(agent) || version;
+                // Fold any stale literal `latest` dir from an earlier probe-failed
+                // install into the real version so it stops shadowing `agents view`.
+                await reconcileStaleLatestDir(agent, installedVersion);
             }
             onProgress?.(`${agentConfig.name} installed. Setting up agents-cli version home for isolation...`);
         }
@@ -1158,6 +1161,51 @@ function removeInstallArtifacts(versionDir) {
         fs.rmSync(path.join(versionDir, entry), { recursive: true, force: true });
     }
 }
+/**
+ * Fold a stale literal `latest` version dir into the real resolved version.
+ *
+ * Script-installed agents (droid, grok) have no npm package to read a version
+ * from, so the installer resolves the version by probing `<cli> --version`
+ * after the install script runs. When that probe failed (3s timeout, or the
+ * freshly-dropped binary not yet resolvable on PATH) the installer fell back to
+ * the literal string `latest`, creating a `versions/<agent>/latest/` dir. A
+ * later install where the probe succeeded then created a SECOND dir at the real
+ * semver, orphaning `latest` — and because these agents' getBinaryPath points
+ * at a single global binary regardless of version dir, `latest` keeps showing
+ * up in `agents view` next to the real version forever.
+ *
+ * Call this once the install path has resolved a real version: if a stale
+ * `latest` dir exists, rename it onto the real version (preserving `home/`), or
+ * if the real dir already exists, soft-delete the `latest` dir to trash. No-op
+ * when nothing was resolved or no stale dir is present, so it is safe to call
+ * on every script-based install. Returns the action taken (for tests/logging).
+ */
+export async function reconcileStaleLatestDir(agent, installedVersion) {
+    if (installedVersion === 'latest')
+        return 'none';
+    const staleLatestDir = getVersionDir(agent, 'latest');
+    const realVersionDir = getVersionDir(agent, installedVersion);
+    if (staleLatestDir === realVersionDir || !fs.existsSync(staleLatestDir)) {
+        return 'none';
+    }
+    if (!fs.existsSync(realVersionDir)) {
+        fs.renameSync(staleLatestDir, realVersionDir);
+        return 'renamed';
+    }
+    // Both dirs exist. Stripping install artifacts would not hide `latest` for
+    // global-binary agents (getBinaryPath ignores dir contents), so the whole
+    // dir must go. Soft-delete to trash so any `home/` data stays recoverable
+    // via `agents restore <agent>@latest`, then rewrite session file paths to
+    // point at the trashed location so history stays readable. The session-db
+    // module is imported lazily — it carries a top-level await that the CJS test
+    // harness can't statically transform, so it must stay out of the eager graph.
+    const trashPath = softDeleteVersionDir(agent, 'latest');
+    if (trashPath) {
+        const { updateSessionFilePaths } = await import('./session/db.js');
+        updateSessionFilePaths(staleLatestDir, trashPath);
+    }
+    return 'trashed';
+}
 /**
  * Soft-delete a version directory by moving it to ~/.agents/.system/trash/versions/.
  * Returns the trash path on success or null on failure / no source.

package/package.json

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