@phnx-labs/agents-cli 1.20.7 → 1.20.9

package/dist/lib/computer-rpc.d.ts

@@ -21,6 +21,8 @@ export declare function writeComputerPeers(allowedExecPaths: string[]): void;
 export declare function resolveHelperExec(): string | null;
 export declare function resolveHelperApp(): string | null;
 export declare function openComputerClient(): ComputerClient;
+export declare const RPC_TIMEOUT_MS = 30000;
+export declare function resolveRpcTimeoutMs(env: string | undefined): number;
 export declare function describeTransport(): {
     kind: 'socket' | 'stdio' | 'none';
     path: string | null;

package/dist/lib/computer-rpc.js

@@ -200,6 +200,15 @@ export function openComputerClient() {
     }
     return new StdioClient(helperExec);
 }
+// Per-call RPC timeout. Without it a hung daemon (deadlocked connection
+// queue, stopped process) hangs the CLI forever — the waiter map never
+// settles. 30s clears every daemon-side ceiling (wait caps at 30s,
+// launch_app at 10s, screenshot at 5s). Overridable for slower flows.
+export const RPC_TIMEOUT_MS = 30_000;
+export function resolveRpcTimeoutMs(env) {
+    const n = Number(env);
+    return Number.isFinite(n) && n > 0 ? n : RPC_TIMEOUT_MS;
+}
 // Shared waiter map + line parser. Both transports plug their reader into
 // `handleChunk` and their writer into `send`.
 class BaseClient {
@@ -241,8 +250,19 @@ class BaseClient {
         }
         const id = this.nextId++;
         const payload = JSON.stringify({ id, method, params: params ?? {} }) + '\n';
+        const timeoutMs = resolveRpcTimeoutMs(process.env.COMPUTER_HELPER_RPC_TIMEOUT_MS);
         return new Promise((resolve) => {
-            this.waiters.set(id, resolve);
+            const timer = setTimeout(() => {
+                if (this.waiters.delete(id)) {
+                    resolve({ id, error: { code: 'rpc_timeout', message: `helper did not respond within ${timeoutMs}ms` } });
+                }
+            }, timeoutMs);
+            // Resolve as an error (never reject) so callers flow through unwrap()
+            // uniformly, matching failPending's contract.
+            this.waiters.set(id, (r) => {
+                clearTimeout(timer);
+                resolve(r);
+            });
             this.send(payload);
         });
     }

package/dist/lib/daemon.js

@@ -11,7 +11,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { getDaemonDir as getDaemonDirRoot } from './state.js';
-import { isAlive } from './platform/index.js';
+import { isAlive, killTree } from './platform/index.js';
 import { listJobs as listAllJobs } from './routines.js';
 import { JobScheduler } from './scheduler.js';
 import { executeJobDetached, monitorRunningJobs } from './runner.js';
@@ -437,17 +437,23 @@ export function stopDaemon() {
     }
     const pid = readDaemonPid();
     if (pid) {
-        try {
-            process.kill(pid, 'SIGTERM');
+        if (process.platform === 'win32') {
+            // Windows has no graceful termination signal — terminate the daemon and
+            // its job/browser child tree in one shot (taskkill /T), so stop doesn't
+            // report success while children keep running.
+            killTree(pid);
         }
-        catch { /* process already exited */ }
-        setTimeout(() => {
+        else {
             try {
-                process.kill(pid, 0);
-                process.kill(pid, 'SIGKILL');
+                process.kill(pid, 'SIGTERM');
             }
             catch { /* process already exited */ }
-        }, 5000);
+            // Escalate to a hard tree-kill if it ignored SIGTERM after the grace period.
+            setTimeout(() => {
+                if (isAlive(pid))
+                    killTree(pid);
+            }, 5000);
+        }
     }
     removeDaemonPid();
     return true;
@@ -479,6 +485,12 @@ export function signalDaemonReload() {
     const pid = readDaemonPid();
     if (!pid)
         return false;
+    if (process.platform === 'win32') {
+        // Windows has no SIGHUP, so signal-based live reload isn't available. Sending
+        // it would throw; instead report "not reloaded" so callers tell the user to
+        // restart the daemon to pick up job changes.
+        return false;
+    }
     try {
         process.kill(pid, 'SIGHUP');
         return true;

package/dist/lib/fs-walk.d.ts

@@ -1,2 +1,8 @@
-/** Walk a directory recursively for files with a given extension. */
+/** Walk a directory recursively for files with a given extension, newest first. */
 export declare function walkForFiles(dir: string, ext: string, limit: number): string[];
+/**
+ * Return the newest mtime (ms) among files with the given extension, or null
+ * when none match. Single pass tracking the max — no collection or sort.
+ * Hot-path helper for the `agents run` account-recency probe.
+ */
+export declare function latestFileMtimeMs(dir: string, ext: string): number | null;

package/dist/lib/fs-walk.js

@@ -1,35 +1,69 @@
 import * as fs from 'fs';
 import * as path from 'path';
-/** Walk a directory recursively for files with a given extension. */
-export function walkForFiles(dir, ext, limit) {
-    const results = [];
+/**
+ * Recursively visit files with a given extension, calling onFile with each
+ * match's path and mtime. Uses dirent types from readdir so only matching
+ * files (and symlinks, to preserve follow semantics) pay a stat call —
+ * directories are classified for free. On large session trees this roughly
+ * halves the syscall count versus stat-per-entry.
+ */
+function walkEntries(dir, ext, onFile) {
     function walk(d, depth) {
         if (depth > 5)
             return;
         let entries;
         try {
-            entries = fs.readdirSync(d);
+            entries = fs.readdirSync(d, { withFileTypes: true });
         }
         catch {
             return;
         }
         for (const entry of entries) {
-            const full = path.join(d, entry);
-            const stat = safeStatSync(full);
-            if (!stat)
-                continue;
-            if (stat.isDirectory()) {
+            const full = path.join(d, entry.name);
+            let isDirectory = entry.isDirectory();
+            // Symlinks: dirent reports the link itself, but the previous stat-based
+            // walk followed links into directories and matched linked files. Stat
+            // (which follows) only for symlinks to keep that behavior.
+            if (entry.isSymbolicLink()) {
+                const stat = safeStatSync(full);
+                if (!stat)
+                    continue;
+                isDirectory = stat.isDirectory();
+            }
+            if (isDirectory) {
                 walk(full, depth + 1);
             }
-            else if (entry.endsWith(ext)) {
-                results.push({ path: full, mtime: stat.mtimeMs });
+            else if (entry.name.endsWith(ext)) {
+                const stat = safeStatSync(full);
+                if (stat)
+                    onFile(full, stat.mtimeMs);
             }
         }
     }
     walk(dir, 0);
+}
+/** Walk a directory recursively for files with a given extension, newest first. */
+export function walkForFiles(dir, ext, limit) {
+    const results = [];
+    walkEntries(dir, ext, (filePath, mtimeMs) => {
+        results.push({ path: filePath, mtime: mtimeMs });
+    });
     results.sort((a, b) => b.mtime - a.mtime);
     return results.slice(0, limit).map(r => r.path);
 }
+/**
+ * Return the newest mtime (ms) among files with the given extension, or null
+ * when none match. Single pass tracking the max — no collection or sort.
+ * Hot-path helper for the `agents run` account-recency probe.
+ */
+export function latestFileMtimeMs(dir, ext) {
+    let latest = null;
+    walkEntries(dir, ext, (_filePath, mtimeMs) => {
+        if (latest === null || mtimeMs > latest)
+            latest = mtimeMs;
+    });
+    return latest;
+}
 function safeStatSync(p) {
     try {
         return fs.statSync(p);

package/dist/lib/git.js

@@ -8,6 +8,7 @@
 import simpleGit from 'simple-git';
 import * as fs from 'fs';
 import * as path from 'path';
+import { IS_WINDOWS, isWindowsAbsolutePath } from './platform/index.js';
 import { getPackageLocalPath } from './state.js';
 import { DEFAULT_SYSTEM_REPO, systemRepoSlug } from './types.js';
 /**
@@ -127,8 +128,10 @@ export function parseSource(source) {
             ref,
         };
     }
-    // Local path (absolute or relative)
-    if (cleanSource.startsWith('/') || cleanSource.startsWith('./') || cleanSource.startsWith('../')) {
+    // Local path (absolute or relative). On Windows also recognize drive-letter
+    // (C:\…) and UNC (\\…) roots, which the POSIX prefixes miss.
+    if (cleanSource.startsWith('/') || cleanSource.startsWith('./') || cleanSource.startsWith('../')
+        || (IS_WINDOWS && isWindowsAbsolutePath(cleanSource))) {
         if (fs.existsSync(cleanSource)) {
             return {
                 type: 'local',

package/dist/lib/log-follow.d.ts

@@ -0,0 +1,7 @@
+export interface FollowOptions {
+    /** Poll interval in milliseconds (default 500). */
+    intervalMs?: number;
+    /** Start at the current end of file (skip existing content). Default false. */
+    fromEnd?: boolean;
+}
+export declare function followFile(filePath: string, onChunk: (text: string) => void, opts?: FollowOptions): () => void;

package/dist/lib/log-follow.js

@@ -0,0 +1,65 @@
+/**
+ * Cross-platform `tail -f`.
+ *
+ * Replaces spawning the POSIX `tail` binary (absent on Windows) with a poll-based
+ * follower that behaves identically on every platform and needs no external
+ * dependency. Reads bytes appended since the last position every `intervalMs`;
+ * resets to 0 if the file shrinks (truncation / log rotation). The active timer
+ * keeps the event loop alive, so callers just register a SIGINT handler that
+ * calls the returned stop().
+ */
+import * as fs from 'fs';
+export function followFile(filePath, onChunk, opts = {}) {
+    const intervalMs = opts.intervalMs ?? 500;
+    let pos = 0;
+    if (opts.fromEnd) {
+        try {
+            pos = fs.statSync(filePath).size;
+        }
+        catch {
+            pos = 0;
+        }
+    }
+    else {
+        try {
+            const initial = fs.readFileSync(filePath);
+            if (initial.length > 0)
+                onChunk(initial.toString('utf-8'));
+            pos = initial.length;
+        }
+        catch { /* file may not exist yet — start at 0 and wait for it to appear */ }
+    }
+    const poll = () => {
+        let size;
+        try {
+            size = fs.statSync(filePath).size;
+        }
+        catch {
+            return; /* gone / not yet created */
+        }
+        if (size < pos)
+            pos = 0; // truncated or rotated — re-read from the top
+        if (size <= pos)
+            return;
+        let fd;
+        try {
+            fd = fs.openSync(filePath, 'r');
+            const buf = Buffer.alloc(size - pos);
+            const bytes = fs.readSync(fd, buf, 0, buf.length, pos);
+            pos += bytes;
+            if (bytes > 0)
+                onChunk(buf.subarray(0, bytes).toString('utf-8'));
+        }
+        catch { /* transient read error — retry next tick */ }
+        finally {
+            if (fd !== undefined) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch { /* noop */ }
+            }
+        }
+    };
+    const timer = setInterval(poll, intervalMs);
+    return () => clearInterval(timer);
+}

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

@@ -18,3 +18,4 @@ export declare const IS_LINUX: boolean;
 export * from './paths.js';
 export * from './exec.js';
 export * from './process.js';
+export * from './ipc.js';

package/dist/lib/platform/index.js

@@ -18,3 +18,4 @@ export const IS_LINUX = process.platform === 'linux';
 export * from './paths.js';
 export * from './exec.js';
 export * from './process.js';
+export * from './ipc.js';

package/dist/lib/platform/ipc.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resolve the address a local daemon listens on / clients connect to.
+ *
+ * POSIX: the AF_UNIX socket file path itself.
+ * Windows: a named pipe (`\\.\pipe\agents-<hash>`). Filesystem socket files
+ * aren't supported there, and named pipes are NOT filesystem objects — derive a
+ * stable name from a hash of the socket path so client and server agree without
+ * touching disk, and never probe the result with fs.existsSync (it always reports
+ * false). Both forms are accepted by net.createServer / net.createConnection.
+ */
+export declare function ipcEndpoint(socketPath: string, platform?: NodeJS.Platform): string;

package/dist/lib/platform/ipc.js

@@ -0,0 +1,21 @@
+/**
+ * Local-daemon IPC endpoint, platform-aware.
+ */
+import * as crypto from 'crypto';
+/**
+ * Resolve the address a local daemon listens on / clients connect to.
+ *
+ * POSIX: the AF_UNIX socket file path itself.
+ * Windows: a named pipe (`\\.\pipe\agents-<hash>`). Filesystem socket files
+ * aren't supported there, and named pipes are NOT filesystem objects — derive a
+ * stable name from a hash of the socket path so client and server agree without
+ * touching disk, and never probe the result with fs.existsSync (it always reports
+ * false). Both forms are accepted by net.createServer / net.createConnection.
+ */
+export function ipcEndpoint(socketPath, platform = process.platform) {
+    if (platform === 'win32') {
+        const hash = crypto.createHash('sha1').update(socketPath).digest('hex').slice(0, 16);
+        return `\\\\.\\pipe\\agents-${hash}`;
+    }
+    return socketPath;
+}

package/dist/lib/platform/paths.d.ts

@@ -20,3 +20,10 @@ export declare function toComparablePath(p: string, platform?: NodeJS.Platform):
  * correctly on all three platforms.
  */
 export declare function homeDir(): string;
+/**
+ * Is this a Windows absolute path — a drive-letter root (`C:\`, `C:/`) or a UNC
+ * share (`\\server\share`)? Used by local-source parsing to recognize a native
+ * Windows path that the POSIX `/`, `./`, `../` prefixes miss. Caller decides
+ * whether to apply it (typically gated on win32).
+ */
+export declare function isWindowsAbsolutePath(p: string): boolean;

package/dist/lib/platform/paths.js

@@ -47,3 +47,12 @@ export function toComparablePath(p, platform = process.platform) {
 export function homeDir() {
     return os.homedir();
 }
+/**
+ * Is this a Windows absolute path — a drive-letter root (`C:\`, `C:/`) or a UNC
+ * share (`\\server\share`)? Used by local-source parsing to recognize a native
+ * Windows path that the POSIX `/`, `./`, `../` prefixes miss. Caller decides
+ * whether to apply it (typically gated on win32).
+ */
+export function isWindowsAbsolutePath(p) {
+    return WIN_DRIVE_RE.test(p) || p.startsWith('\\\\');
+}

package/dist/lib/platform/process.d.ts

@@ -1,6 +1,14 @@
 /**
- * Process liveness / control, platform-aware.
+ * Forcefully terminate a process AND its descendant tree.
+ *
+ * Windows: `taskkill /F /T /PID` — the only reliable way to take down the whole
+ * tree (a bare TerminateProcess leaves children orphaned, which is exactly the
+ * "stop reported success but the tree is still alive" bug). POSIX: SIGKILL to the
+ * pid (matching the existing hard-kill behavior; callers that own a process group
+ * can pass the negative pid). Best-effort — never throws; an already-exited
+ * process counts as success.
  */
+export declare function killTree(pid: number): void;
 /**
  * Is a process with this PID currently alive?
  *

package/dist/lib/platform/process.js

@@ -1,6 +1,33 @@
 /**
  * Process liveness / control, platform-aware.
  */
+import { execFileSync } from 'child_process';
+/**
+ * Forcefully terminate a process AND its descendant tree.
+ *
+ * Windows: `taskkill /F /T /PID` — the only reliable way to take down the whole
+ * tree (a bare TerminateProcess leaves children orphaned, which is exactly the
+ * "stop reported success but the tree is still alive" bug). POSIX: SIGKILL to the
+ * pid (matching the existing hard-kill behavior; callers that own a process group
+ * can pass the negative pid). Best-effort — never throws; an already-exited
+ * process counts as success.
+ */
+export function killTree(pid) {
+    if (!pid || pid <= 0)
+        return;
+    if (process.platform === 'win32') {
+        try {
+            execFileSync('taskkill', ['/F', '/T', '/PID', String(pid)], { stdio: 'ignore' });
+        }
+        catch { /* already gone, or no such pid */ }
+    }
+    else {
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch { /* already gone */ }
+    }
+}
 /**
  * Is a process with this PID currently alive?
  *

package/dist/lib/plugins.js

@@ -12,6 +12,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { execFileSync } from 'child_process';
 import { getPluginsDir, getTrashPluginsDir, getExtraPluginsDir, getProjectPluginsDir } from './state.js';
+import { IS_WINDOWS, isWindowsAbsolutePath, homeDir } from './platform/index.js';
 import { listInstalledVersions, getVersionHomePath } from './versions.js';
 import { AGENTS, agentConfigDirName } from './agents.js';
 import { capableAgents, isCapable } from './capabilities.js';
@@ -1007,9 +1008,10 @@ export function parseInstallSpec(spec) {
 export async function installPlugin(spec) {
     const { name: specName, source } = parseInstallSpec(spec);
     // Resolve local path (handle ~)
-    const isLocalPath = source.startsWith('/') || source.startsWith('./') || source.startsWith('../') || source.startsWith('~');
+    const isLocalPath = source.startsWith('/') || source.startsWith('./') || source.startsWith('../') || source.startsWith('~')
+        || (IS_WINDOWS && isWindowsAbsolutePath(source));
     const resolvedSource = isLocalPath
-        ? source.replace(/^~/, process.env.HOME || '~')
+        ? source.replace(/^~/, homeDir())
         : source;
     const pluginsDir = getPluginsDir();
     fs.mkdirSync(pluginsDir, { recursive: true });
@@ -1085,7 +1087,7 @@ export async function updatePlugin(name) {
             execFileSync('git', ['-C', plugin.root, 'pull', '--ff-only'], { stdio: 'pipe' });
         }
         else {
-            const resolvedSource = sourceInfo.source.replace(/^~/, process.env.HOME || '~');
+            const resolvedSource = sourceInfo.source.replace(/^~/, homeDir());
             if (!fs.existsSync(resolvedSource)) {
                 return { success: false, error: `Source path no longer exists: ${resolvedSource}` };
             }

package/dist/lib/refresh.js

@@ -212,8 +212,8 @@ export async function refresh(options = {}) {
     if (!isShimsInPath()) {
         const pathResult = addShimsToPath();
         if (pathResult.success && !pathResult.alreadyPresent) {
-            console.log(chalk.green(`\nAdded shims to ~/${pathResult.rcFile}`));
-            console.log(chalk.gray('Restart your shell or run: source ~/' + pathResult.rcFile));
+            console.log(chalk.green(`\nAdded shims to ${pathResult.location}`));
+            console.log(chalk.gray(pathResult.reloadHint));
         }
         else if (!pathResult.success) {
             console.log(chalk.yellow('\nCould not auto-add shims to PATH:'));

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

@@ -0,0 +1,86 @@
+/**
+ * Self-update install plumbing.
+ *
+ * The hard requirement: an upgrade must replace the copy that is currently
+ * running. A bare `npm install -g` writes into the global prefix of whatever
+ * `npm` PATH happens to resolve — on machines with more than one node
+ * installation (nvm + Homebrew + vendored runtimes) that prefix can belong to
+ * a different node than the one this copy lives under. The install then
+ * "succeeds" while the running copy stays stale and re-prompts forever.
+ *
+ * So every step here is anchored to the running package root on disk, never
+ * to PATH resolution.
+ */
+export declare const NPM_PACKAGE_NAME = "@phnx-labs/agents-cli";
+export interface UpdateCheckCache {
+    lastCheck: number;
+    latestVersion: string;
+    dismissed?: string;
+}
+/** Read the cached update-check state from disk. Returns null if the file is missing or corrupt. */
+export declare function readUpdateCache(file: string): UpdateCheckCache | null;
+/**
+ * Persist the latest known version and current timestamp. Preserves an
+ * existing `dismissed` marker — the background refresh must not erase a
+ * user's "Skip this version" choice, or they get re-prompted for the exact
+ * version they dismissed.
+ */
+export declare function saveUpdateCheck(file: string, latestVersion: string): void;
+/** Record that the user chose to skip `version`; suppresses prompts until a newer version appears. */
+export declare function dismissUpdateVersion(file: string, version: string): void;
+/** Whether the cached state warrants an upgrade prompt for a copy running `currentVersion`. */
+export declare function shouldPromptUpgrade(cache: UpdateCheckCache | null, currentVersion: string): boolean;
+/**
+ * Derive the npm global prefix that owns the install at `packageRoot`.
+ *
+ * npm's global layout for a scoped package:
+ *   POSIX:   <prefix>/lib/node_modules/@phnx-labs/agents-cli
+ *   Windows: <prefix>/node_modules/@phnx-labs/agents-cli
+ *
+ * Throws when `packageRoot` is not inside a node_modules tree (e.g. running
+ * from a source checkout) — there is no prefix to install into, and guessing
+ * one is exactly the bug this module exists to prevent.
+ */
+export declare function deriveGlobalPrefix(packageRoot: string): string;
+/**
+ * Install `spec` into an explicit global prefix. `--prefix` pins the
+ * destination no matter which npm binary PATH resolves. `--ignore-scripts`
+ * skips lifecycle scripts; the caller refreshes alias shims afterwards via
+ * refreshAliasShims().
+ */
+export declare function installPackageIntoPrefix(spec: string, prefix: string): Promise<void>;
+/** Read the version field of the package.json at `packageRoot`, fresh from disk. */
+export declare function readInstalledVersion(packageRoot: string): string;
+/**
+ * Assert that the install at `packageRoot` now carries `expectedVersion`.
+ * npm exiting 0 only proves it wrote *somewhere*; this proves it wrote *here*.
+ */
+export declare function verifyInstalledVersion(packageRoot: string, expectedVersion: string): void;
+/**
+ * Re-run the freshly installed copy's postinstall in shims-only mode so the
+ * bare-command aliases (secrets, sessions, ...) pick up the new entrypoint
+ * and any aliases added in the new version. Best-effort: a failure here
+ * leaves the previous shims in place, which still point at the (now
+ * upgraded) package root.
+ */
+export declare function refreshAliasShims(packageRoot: string): void;
+export interface AgentsCliInstall {
+    /** The PATH entry (`<dir>/agents`) that resolves to this install. */
+    binPath: string;
+    /** Package root containing package.json and dist/. */
+    packageRoot: string;
+    version: string;
+}
+/**
+ * Scan PATH for `agents` entrypoints and resolve each to the agents-cli
+ * package root it executes. More than one distinct root means upgrades,
+ * shims, and the command the user types can act on different copies — the
+ * divergence behind silently-failing self-updates.
+ *
+ * npm bin entries are symlinks that resolve to `<packageRoot>/dist/index.js`
+ * (the dev install's `~/.local/bin/agents` chains through the dev prefix to
+ * the same shape). Anything that doesn't resolve to a dist/index.js inside a
+ * package named @phnx-labs/agents-cli is some other tool and is skipped.
+ * POSIX-only: Windows npm bins are .cmd wrappers, not symlinks.
+ */
+export declare function findAgentsCliInstalls(pathEnv: string): AgentsCliInstall[];