@phnx-labs/agents-cli 1.20.6 → 1.20.8

package/dist/index.js

@@ -103,6 +103,21 @@ import { isInteractiveTerminal, isPromptCancelled } from './commands/utils.js';
 import { AGENTS } from './lib/agents.js';
 import { getGlobalDefault, listInstalledVersions } from './lib/versions.js';
 import { addShimsToPath, ensureShimCurrent, ensureVersionedAliasCurrent, getPathShadowingExecutable, getPathSetupInstructions, getShimsDir, isShimsInPath, listAgentsWithInstalledVersions, removeLegacyUserShim, } from './lib/shims.js';
+import { IS_WINDOWS } from './lib/platform/index.js';
+// Transparent shim delegate: the generated Windows `.cmd` shims invoke
+// `agents __shim <agent>[@version] <raw args>`. Intercept here, before commander
+// parses anything, so the agent's own flags (`--help`, `--version`, etc.) pass
+// through completely untouched and we skip registering the full command tree.
+if (process.argv[2] === '__shim') {
+    const spec = process.argv[3] || '';
+    const rawArgs = process.argv.slice(4);
+    const atIndex = spec.indexOf('@');
+    const agent = atIndex === -1 ? spec : spec.slice(0, atIndex);
+    const pinned = atIndex === -1 ? undefined : spec.slice(atIndex + 1);
+    const { execShimPassthrough } = await import('./lib/exec.js');
+    const code = await execShimPassthrough(agent, rawArgs, process.cwd(), pinned || undefined);
+    process.exit(code);
+}
 const program = new Command();
 program
     .name('agents')
@@ -134,7 +149,7 @@ Agent versions:
   prune cleanup [target]          Remove orphan resources and older duplicate version installs
   trash                           Inspect and restore soft-deleted version directories
   view [agent[@version]]          List versions, or inspect one in detail
-  inspect <agent>[@version]       Deep details for one agent+version — paths, capabilities, resources, drill into any kind
+  inspect <target>                Deep details for one agent+version, or a DotAgents repo (user|system|project|alias|path)
 
 Agent configuration (synced across versions):
   rules                           Instructions given to agents (CLAUDE.md, etc.)
@@ -461,6 +476,13 @@ async function maybeBootstrapShimIntegration(requestedCommand, helpOrVersionRequ
     for (const agent of installedAgents) {
         removeLegacyUserShim(agent);
     }
+    // The remaining flow is rc-file PATH repair, which is POSIX-only. On Windows
+    // the shims were just regenerated (incl. `.cmd` companions) above; PATH setup
+    // is covered by the install-time guidance, so stop here rather than printing
+    // shell-rc instructions that don't apply.
+    if (IS_WINDOWS) {
+        return;
+    }
     const defaultAgents = installedAgents.filter((agent) => getGlobalDefault(agent));
     const shadowed = defaultAgents
         .map((agent) => ({ agent, shadowedBy: getPathShadowingExecutable(agent) }))

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,6 +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 { listJobs as listAllJobs } from './routines.js';
 import { JobScheduler } from './scheduler.js';
 import { executeJobDetached, monitorRunningJobs } from './runner.js';
@@ -114,14 +115,10 @@ export function isDaemonRunning() {
     const pid = readDaemonPid();
     if (!pid)
         return false;
-    try {
-        process.kill(pid, 0);
+    if (isAlive(pid))
         return true;
-    }
-    catch {
-        removeDaemonPid();
-        return false;
-    }
+    removeDaemonPid();
+    return false;
 }
 /** Redact values that look like tokens or credentials in a log message. */
 function redactSecrets(message) {

package/dist/lib/exec.d.ts

@@ -95,6 +95,15 @@ export declare const AGENT_COMMANDS: Record<AgentId, AgentCommandTemplate>;
 export declare function buildExecCommand(options: ExecOptions): string[];
 /** Spawn an agent and return its exit code. Convenience wrapper over spawnAgent. */
 export declare function execAgent(options: ExecOptions): Promise<number>;
+/**
+ * Transparent passthrough exec for generated shims — the node-side delegate that
+ * Windows `.cmd` shims call. Resolves the active version (explicit pin, else
+ * project/default) and execs the real binary with the user's RAW args and the
+ * per-version env isolation, WITHOUT injecting mode/model/reasoning flags. This
+ * mirrors what the POSIX bash shim does inline (`exec $BINARY $launchArgs "$@"`),
+ * keeping version resolution in one place instead of reimplementing it in batch.
+ */
+export declare function execShimPassthrough(agent: AgentId, rawArgs: string[], cwd: string, pinnedVersion?: string): Promise<number>;
 /**
  * Patterns that indicate a rate/usage limit. Matching is intentionally broad
  * because providers phrase these differently -- Anthropic uses "5-hour limit"

package/dist/lib/exec.js

@@ -11,7 +11,7 @@ import * as path from 'path';
 import { ALL_MODES } from './types.js';
 import { AGENTS } from './agents.js';
 import { parseTimeout } from './routines.js';
-import { getVersionHomePath, isVersionInstalled, resolveVersion } from './versions.js';
+import { getBinaryPath, getVersionHomePath, isVersionInstalled, resolveVersion } from './versions.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
 import { maybeRotate, createTimer, redactPrompt, redactArgs } from './events.js';
 import { sanitizeProcessEnv } from './secrets/bundles.js';
@@ -367,10 +367,27 @@ export function buildExecCommand(options) {
     // Resolve to the absolute path of the shim so spawn doesn't depend on PATH —
     // on Linux installs where the shims dir isn't on PATH, spawning the bare
     // versioned name fails with ENOENT even though `agents view` shows the agent.
+    //
+    // On Windows, shims are bash scripts and cannot be executed by spawn() directly.
+    // buildExecEnv() already sets the isolation env vars (CLAUDE_CONFIG_DIR, CODEX_HOME,
+    // etc.) that the bash shim would set, so we can skip the shim entirely and resolve
+    // straight to the real binary via getBinaryPath.
     if (options.version && cmd.length > 0) {
-        const versionedName = `${cmd[0]}@${options.version}`;
-        const absPath = path.join(getShimsDir(), versionedName);
-        cmd[0] = fs.existsSync(absPath) ? absPath : versionedName;
+        if (process.platform === 'win32') {
+            const binaryPath = getBinaryPath(options.agent, options.version);
+            const binaryPathCmd = binaryPath + '.cmd';
+            if (fs.existsSync(binaryPathCmd)) {
+                cmd[0] = binaryPathCmd;
+            }
+            else if (fs.existsSync(binaryPath)) {
+                cmd[0] = binaryPath;
+            }
+        }
+        else {
+            const versionedName = `${cmd[0]}@${options.version}`;
+            const absPath = path.join(getShimsDir(), versionedName);
+            cmd[0] = fs.existsSync(absPath) ? absPath : versionedName;
+        }
     }
     // Add reasoning effort flags (before mode flags for codex -c positioning)
     // For codex, -c must come before 'exec' subcommand, so we insert at position 1
@@ -458,6 +475,42 @@ export async function execAgent(options) {
     const { exitCode } = await spawnAgent(options);
     return exitCode;
 }
+/**
+ * Transparent passthrough exec for generated shims — the node-side delegate that
+ * Windows `.cmd` shims call. Resolves the active version (explicit pin, else
+ * project/default) and execs the real binary with the user's RAW args and the
+ * per-version env isolation, WITHOUT injecting mode/model/reasoning flags. This
+ * mirrors what the POSIX bash shim does inline (`exec $BINARY $launchArgs "$@"`),
+ * keeping version resolution in one place instead of reimplementing it in batch.
+ */
+export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
+    const version = pinnedVersion ?? resolveVersion(agent, cwd) ?? undefined;
+    if (!version || !isVersionInstalled(agent, version)) {
+        process.stderr.write(`agents: no installed default for ${agent}. Set one with: agents use ${agent} <version>\n`);
+        return 127;
+    }
+    let binary = getBinaryPath(agent, version);
+    if (process.platform === 'win32') {
+        // npm ships <cmd>.cmd alongside the bare script on Windows; that's the runnable form.
+        const cmdPath = binary + '.cmd';
+        if (fs.existsSync(cmdPath))
+            binary = cmdPath;
+    }
+    // The only flag the bash shim injects (codex); everything else is transparent.
+    const launchArgs = agent === 'codex' ? ['-c', 'check_for_update_on_startup=false'] : [];
+    // mode/effort are required by ExecOptions but unused by buildExecEnv (which only
+    // derives the per-version config-dir env); pass the agent's default to satisfy the type.
+    const env = buildExecEnv({ agent, version, cwd, mode: defaultModeFor(agent), effort: 'auto' });
+    const useShell = process.platform === 'win32' && (!path.isAbsolute(binary) || binary.endsWith('.cmd'));
+    return new Promise((resolve) => {
+        const child = spawn(binary, [...launchArgs, ...rawArgs], { cwd, stdio: 'inherit', env, shell: useShell });
+        child.on('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+        child.on('error', (err) => {
+            process.stderr.write(`agents: failed to launch ${agent}: ${err.message}\n`);
+            resolve(127);
+        });
+    });
+}
 /**
  * Spawn an agent process and return its exit code plus a tee'd copy of stderr.
  *
@@ -495,11 +548,14 @@ async function spawnAgent(options) {
         const stdio = interactive
             ? ['inherit', 'inherit', 'inherit']
             : ['inherit', piped ? 'pipe' : 'inherit', 'pipe'];
+        // On Windows, .cmd batch wrappers (npm-installed CLIs) require shell:true
+        // whether addressed by name or absolute path.
+        const useShell = process.platform === 'win32' && (!path.isAbsolute(executable) || executable.endsWith('.cmd'));
         const child = spawn(executable, args, {
             cwd: options.cwd || process.cwd(),
             stdio,
             env: buildExecEnv(options),
-            shell: false,
+            shell: useShell,
         });
         // Mark startup time (time from function call to process spawn)
         timer.mark('startup');

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

@@ -0,0 +1,9 @@
+/** PATH-search command for the platform: `where` on Windows, else `which`. */
+export declare function whichCommand(platform?: NodeJS.Platform): string;
+/**
+ * Resolve an executable name to its absolute path via the OS PATH search, or
+ * `null` if not found. On Windows `where` can return several lines (one per
+ * PATHEXT match, e.g. `agents.cmd` and `agents.ps1`) — the first is the one the
+ * shell would actually run, matching `which` semantics on POSIX.
+ */
+export declare function findExecutable(name: string, platform?: NodeJS.Platform): string | null;

package/dist/lib/platform/exec.js

@@ -0,0 +1,24 @@
+/**
+ * Executable resolution, platform-aware.
+ */
+import { execFileSync } from 'child_process';
+/** PATH-search command for the platform: `where` on Windows, else `which`. */
+export function whichCommand(platform = process.platform) {
+    return platform === 'win32' ? 'where' : 'which';
+}
+/**
+ * Resolve an executable name to its absolute path via the OS PATH search, or
+ * `null` if not found. On Windows `where` can return several lines (one per
+ * PATHEXT match, e.g. `agents.cmd` and `agents.ps1`) — the first is the one the
+ * shell would actually run, matching `which` semantics on POSIX.
+ */
+export function findExecutable(name, platform = process.platform) {
+    try {
+        const out = execFileSync(whichCommand(platform), [name], { encoding: 'utf-8' });
+        const first = out.trim().split(/\r?\n/)[0]?.trim();
+        return first || null;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Platform abstraction — the ONE place OS-divergent behavior is decided.
+ *
+ * Consumers express intent (`looksLikePath`, `findExecutable`, `isAlive`) instead
+ * of scattering `process.platform === 'win32'` checks. Each helper that has an
+ * observable branch accepts an explicit `platform` argument (defaulting to
+ * `process.platform`), so all three OSes are unit-testable on any host.
+ *
+ * Modules grow per concern as features land:
+ *   paths   — path classification + normalization
+ *   exec    — executable resolution
+ *   process — process liveness / control
+ * (ipc + shell follow when their consumers migrate off inline branches.)
+ */
+export declare const IS_WINDOWS: boolean;
+export declare const IS_MACOS: boolean;
+export declare const IS_LINUX: boolean;
+export * from './paths.js';
+export * from './exec.js';
+export * from './process.js';

package/dist/lib/platform/index.js

@@ -0,0 +1,20 @@
+/**
+ * Platform abstraction — the ONE place OS-divergent behavior is decided.
+ *
+ * Consumers express intent (`looksLikePath`, `findExecutable`, `isAlive`) instead
+ * of scattering `process.platform === 'win32'` checks. Each helper that has an
+ * observable branch accepts an explicit `platform` argument (defaulting to
+ * `process.platform`), so all three OSes are unit-testable on any host.
+ *
+ * Modules grow per concern as features land:
+ *   paths   — path classification + normalization
+ *   exec    — executable resolution
+ *   process — process liveness / control
+ * (ipc + shell follow when their consumers migrate off inline branches.)
+ */
+export const IS_WINDOWS = process.platform === 'win32';
+export const IS_MACOS = process.platform === 'darwin';
+export const IS_LINUX = process.platform === 'linux';
+export * from './paths.js';
+export * from './exec.js';
+export * from './process.js';

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

@@ -0,0 +1,22 @@
+/**
+ * Does this positional argument look like a filesystem path (vs a search term)?
+ *
+ * POSIX markers (`.`, `./`, `../`, `/`, `~`) are recognized on every platform —
+ * identical to the long-standing behavior. Windows-only shapes (drive-letter
+ * `C:\…`, UNC `\\…`, backslash-relative `.\` / `..\`) are recognized ONLY on
+ * win32, so a literal `C:\repo` typed on macOS/Linux still resolves as a search
+ * term — i.e. no behavior change off Windows.
+ */
+export declare function looksLikePath(query: string, platform?: NodeJS.Platform): boolean;
+/**
+ * Normalize a path for comparison/prefix-matching: backslashes folded to forward
+ * slashes and lowercased on Windows (its filesystem is case-insensitive). On
+ * POSIX the input is returned unchanged, so callers behave exactly as before.
+ */
+export declare function toComparablePath(p: string, platform?: NodeJS.Platform): string;
+/**
+ * Canonical home directory. Use this instead of `process.env.HOME`, which is
+ * unset on Windows (where the home is `USERPROFILE`); `os.homedir()` resolves
+ * correctly on all three platforms.
+ */
+export declare function homeDir(): string;

package/dist/lib/platform/paths.js

@@ -0,0 +1,49 @@
+/**
+ * Path classification + normalization, platform-aware.
+ */
+import * as os from 'os';
+/** Windows drive-letter absolute path: `C:\` or `C:/`. */
+const WIN_DRIVE_RE = /^[a-zA-Z]:[\\/]/;
+/**
+ * Does this positional argument look like a filesystem path (vs a search term)?
+ *
+ * POSIX markers (`.`, `./`, `../`, `/`, `~`) are recognized on every platform —
+ * identical to the long-standing behavior. Windows-only shapes (drive-letter
+ * `C:\…`, UNC `\\…`, backslash-relative `.\` / `..\`) are recognized ONLY on
+ * win32, so a literal `C:\repo` typed on macOS/Linux still resolves as a search
+ * term — i.e. no behavior change off Windows.
+ */
+export function looksLikePath(query, platform = process.platform) {
+    if (query === '.' ||
+        query.startsWith('./') ||
+        query.startsWith('../') ||
+        query.startsWith('/') ||
+        query.startsWith('~')) {
+        return true;
+    }
+    if (platform === 'win32') {
+        return (WIN_DRIVE_RE.test(query) ||
+            query.startsWith('\\\\') ||
+            query.startsWith('.\\') ||
+            query.startsWith('..\\'));
+    }
+    return false;
+}
+/**
+ * Normalize a path for comparison/prefix-matching: backslashes folded to forward
+ * slashes and lowercased on Windows (its filesystem is case-insensitive). On
+ * POSIX the input is returned unchanged, so callers behave exactly as before.
+ */
+export function toComparablePath(p, platform = process.platform) {
+    if (platform === 'win32')
+        return p.replace(/\\/g, '/').toLowerCase();
+    return p;
+}
+/**
+ * Canonical home directory. Use this instead of `process.env.HOME`, which is
+ * unset on Windows (where the home is `USERPROFILE`); `os.homedir()` resolves
+ * correctly on all three platforms.
+ */
+export function homeDir() {
+    return os.homedir();
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Process liveness / control, platform-aware.
+ */
+/**
+ * Is a process with this PID currently alive?
+ *
+ * Uses the signal-0 probe, which is cross-platform in Node (Windows included —
+ * it maps to OpenProcess). Returns false on any error (no such process, or no
+ * permission to signal it), matching the long-standing call sites that treat a
+ * throw from `process.kill(pid, 0)` as "not running".
+ */
+export declare function isAlive(pid: number): boolean;

package/dist/lib/platform/process.js

@@ -0,0 +1,22 @@
+/**
+ * Process liveness / control, platform-aware.
+ */
+/**
+ * Is a process with this PID currently alive?
+ *
+ * Uses the signal-0 probe, which is cross-platform in Node (Windows included —
+ * it maps to OpenProcess). Returns false on any error (no such process, or no
+ * permission to signal it), matching the long-standing call sites that treat a
+ * throw from `process.kill(pid, 0)` as "not running".
+ */
+export function isAlive(pid) {
+    if (!pid || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/lib/pty-client.js

@@ -12,6 +12,7 @@ import * as path from 'path';
 import { getSocketPath, getPtyLogPath, isPtyServerRunning } from './pty-server.js';
 const CONNECT_TIMEOUT_MS = 5000;
 const RESPONSE_TIMEOUT_MS = 30000;
+const IS_WINDOWS = process.platform === 'win32';
 /**
  * Send a request to the PTY server and return the response.
  * Auto-starts the server if not running.
@@ -41,11 +42,13 @@ async function ensureServer() {
     });
     child.unref();
     fs.closeSync(logFd);
-    // Wait for socket to appear
+    // Wait for the server to become reachable. On Unix the socket file appearing is
+    // a cheap readiness signal; on Windows the named pipe is not a filesystem object
+    // (fs.existsSync always returns false), so we just attempt the ping directly.
     const socketPath = getSocketPath();
     const deadline = Date.now() + 5000;
     while (Date.now() < deadline) {
-        if (fs.existsSync(socketPath)) {
+        if (IS_WINDOWS || fs.existsSync(socketPath)) {
             // Verify we can connect
             try {
                 await sendRequest({ action: 'ping' });
@@ -70,9 +73,11 @@ function getServerSpawnArgs() {
         }
     }
     catch { }
-    // Fallback: use the globally installed agents command
+    // Fallback: use the globally installed agents command. `which` is Unix-only;
+    // Windows uses `where`, which can return multiple lines — take the first.
     try {
-        const agentsBin = execSync('which agents', { encoding: 'utf-8' }).trim();
+        const lookup = IS_WINDOWS ? 'where agents' : 'which agents';
+        const agentsBin = execSync(lookup, { encoding: 'utf-8' }).split(/\r?\n/)[0].trim();
         if (agentsBin) {
             return { bin: agentsBin, args: ['pty', '_server'] };
         }
@@ -86,7 +91,10 @@ function getServerSpawnArgs() {
 function sendRequest(req) {
     return new Promise((resolve, reject) => {
         const socketPath = getSocketPath();
-        if (!fs.existsSync(socketPath)) {
+        // On Unix a missing socket file means the server isn't up — fail fast with a
+        // clear message. On Windows the named pipe isn't a filesystem object, so we
+        // skip the probe and let createConnection surface ENOENT/connection errors.
+        if (!IS_WINDOWS && !fs.existsSync(socketPath)) {
             reject(new Error('PTY server socket not found. Is the server running?'));
             return;
         }

package/dist/lib/pty-server.d.ts

@@ -18,7 +18,30 @@
  * Returns null on any error so callers can skip the guard rather than crash.
  */
 export declare function captureProcessStartTime(pid: number): string | null;
-/** Get the unix socket path for the PTY server. */
+/**
+ * Wrap a user command so a `__SENTINEL__:<exit>` line is printed after it
+ * finishes — that line drives completion detection in the exec/read flow.
+ * The separator and exit-code variable are shell-family specific:
+ *   POSIX sh/zsh/bash : `cmd; echo "S:$?"`
+ *   PowerShell        : `cmd; echo "S:$LASTEXITCODE"`
+ *   cmd.exe           : `cmd & echo S:%errorlevel%`  (`&` always runs the echo)
+ * Only the completion marker matters; the numeric exit code is informational
+ * (the authoritative code comes from node-pty's onExit).
+ */
+export declare function buildSentinelCommand(shell: string, command: string): string;
+/**
+ * Resolve the IPC endpoint for a given platform + PTY scratch dir. Pure so both
+ * branches are testable without stubbing process.platform.
+ *
+ * Unix: an AF_UNIX socket file inside the scratch dir.
+ * Windows: a named pipe (`\\.\pipe\…`). Named pipes are NOT filesystem objects,
+ * so the name is derived from a hash of the (per-user) scratch dir to keep it
+ * stable across invocations and isolated per user — and callers must never probe
+ * it with fs.existsSync (it always reports false). Both forms are accepted by
+ * net.createServer/createConnection.
+ */
+export declare function derivePtyEndpoint(platform: NodeJS.Platform, ptyDir: string): string;
+/** Get the IPC endpoint the PTY server listens on / clients connect to. */
 export declare function getSocketPath(): string;
 /** Get the path to the PTY server PID file. */
 export declare function getPtyPidPath(): string;