@phnx-labs/agents-cli 1.20.6 → 1.20.8

package/dist/lib/pty-server.js

@@ -15,6 +15,7 @@ import * as crypto from 'crypto';
 import { execFileSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { getPtyDir as getPtyDirRoot } from './state.js';
+import { isAlive } from './platform/index.js';
 /**
  * Capture a stable identifier for a process at the moment it was started.
  * Used to defeat PID reuse: a kill(pid, ...) is only safe when the process
@@ -52,6 +53,7 @@ export function captureProcessStartTime(pid) {
     }
 }
 // --- Constants ---
+const IS_WINDOWS = process.platform === 'win32';
 const SENTINEL = '__AGENTS_PTY_DONE__';
 const SOCKET_NAME = 'pty.sock';
 const PID_FILE = 'pty.pid';
@@ -72,24 +74,81 @@ const PTY_ENV_ALLOWLIST = [
     'EDITOR', 'VISUAL', 'PAGER', 'LESS',
     'NO_COLOR', 'FORCE_COLOR',
 ];
+/**
+ * Windows allowlist. cmd.exe / PowerShell refuse to start (or misbehave) without
+ * SystemRoot, ComSpec, PATHEXT and the USERPROFILE/APPDATA family, so a Unix-style
+ * allowlist would spawn a broken shell. PATH/TERM/color/NODE vars are shared with
+ * the Unix list; the rest are Windows-specific.
+ */
+const PTY_ENV_ALLOWLIST_WIN = [
+    'SystemRoot', 'SystemDrive', 'windir', 'ComSpec', 'PATH', 'PATHEXT',
+    'TEMP', 'TMP', 'USERPROFILE', 'HOMEDRIVE', 'HOMEPATH', 'HOME',
+    'APPDATA', 'LOCALAPPDATA', 'PROGRAMFILES', 'PROGRAMDATA',
+    'USERNAME', 'USERDOMAIN', 'COMPUTERNAME', 'OS',
+    'PROCESSOR_ARCHITECTURE', 'NUMBER_OF_PROCESSORS',
+    'TERM', 'COLORTERM', 'NO_COLOR', 'FORCE_COLOR',
+    'NODE_PATH', 'BUN_INSTALL',
+];
 function buildPtyEnv() {
     const env = {};
-    for (const key of PTY_ENV_ALLOWLIST) {
+    const allowlist = IS_WINDOWS ? PTY_ENV_ALLOWLIST_WIN : PTY_ENV_ALLOWLIST;
+    for (const key of allowlist) {
         const v = process.env[key];
         if (v !== undefined)
             env[key] = v;
     }
     return env;
 }
+/**
+ * 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 function buildSentinelCommand(shell, command) {
+    // Split on both separators: a Windows shell path (`C:\…\cmd.exe`) must be
+    // recognized even when this code runs under POSIX path.basename, which does
+    // not treat `\` as a separator.
+    const name = (shell.split(/[\\/]/).pop() || shell).toLowerCase();
+    if (name === 'cmd.exe' || name === 'cmd') {
+        return `${command} & echo ${SENTINEL}:%errorlevel%`;
+    }
+    if (name === 'powershell.exe' || name === 'powershell' || name === 'pwsh.exe' || name === 'pwsh') {
+        return `${command}; echo "${SENTINEL}:$LASTEXITCODE"`;
+    }
+    return `${command}; echo "${SENTINEL}:$?"`;
+}
 /** Get the PTY helper directory, creating it if needed. */
 function getPtyDir() {
     const dir = getPtyDirRoot();
     fs.mkdirSync(dir, { recursive: true });
     return dir;
 }
-/** Get the unix socket path for the PTY server. */
+/**
+ * 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 function derivePtyEndpoint(platform, ptyDir) {
+    if (platform === 'win32') {
+        const hash = crypto.createHash('sha1').update(ptyDir).digest('hex').slice(0, 16);
+        return `\\\\.\\pipe\\agents-pty-${hash}`;
+    }
+    return path.join(ptyDir, SOCKET_NAME);
+}
+/** Get the IPC endpoint the PTY server listens on / clients connect to. */
 export function getSocketPath() {
-    return path.join(getPtyDir(), SOCKET_NAME);
+    return derivePtyEndpoint(process.platform, getPtyDir());
 }
 /** Get the path to the PTY server PID file. */
 export function getPtyPidPath() {
@@ -109,16 +168,17 @@ export function isPtyServerRunning() {
         const pid = parseInt(fs.readFileSync(pidPath, 'utf-8').trim(), 10);
         if (isNaN(pid))
             return false;
-        process.kill(pid, 0);
-        return true;
+        if (isAlive(pid))
+            return true;
     }
     catch {
-        try {
-            fs.unlinkSync(pidPath);
-        }
-        catch { }
-        return false;
+        // read failed — fall through and treat the pid file as stale
     }
+    try {
+        fs.unlinkSync(pidPath);
+    }
+    catch { }
+    return false;
 }
 // --- Logging ---
 function rotateLogsIfNeeded(logPath) {
@@ -221,8 +281,10 @@ export async function runPtyServer() {
         fs.unlinkSync(pidPath);
     }
     catch { } });
-    // Remove stale socket from a prior crashed server. Safe now that we hold the PID slot.
-    if (fs.existsSync(socketPath)) {
+    // Remove stale socket from a prior crashed server. Safe now that we hold the PID
+    // slot. Windows named pipes are not filesystem inodes — they vanish with their
+    // owning process, so there's nothing to unlink (and existsSync always reports false).
+    if (!IS_WINDOWS && fs.existsSync(socketPath)) {
         try {
             fs.unlinkSync(socketPath);
         }
@@ -286,8 +348,10 @@ export async function runPtyServer() {
             case 'start': {
                 const rows = req.params?.rows || 24;
                 const cols = req.params?.cols || 120;
-                const shell = req.params?.shell || process.env.SHELL || 'zsh';
-                const cwd = req.params?.cwd || process.env.HOME || '/';
+                const shell = req.params?.shell
+                    || (IS_WINDOWS ? (process.env.ComSpec || 'powershell.exe') : (process.env.SHELL || 'zsh'));
+                const cwd = req.params?.cwd
+                    || (IS_WINDOWS ? (process.env.USERPROFILE || process.env.HOME || process.cwd()) : (process.env.HOME || '/'));
                 const id = generateId();
                 let ptyProcess;
                 try {
@@ -358,7 +422,9 @@ export async function runPtyServer() {
                 session.appActive = true;
                 session.activeCommand = command;
                 session.pendingOutput = '';
-                session.pty.write(`${command}; echo "${SENTINEL}:$?"\n`);
+                // Windows conpty submits on CR; POSIX line discipline expects LF.
+                const submit = IS_WINDOWS ? '\r' : '\n';
+                session.pty.write(`${buildSentinelCommand(session.shell, command)}${submit}`);
                 session.lastActivity = Date.now();
                 return { ok: true, submitted: true };
             }
@@ -525,20 +591,28 @@ export async function runPtyServer() {
     // any local user with execute on the parent dir could connect to the socket
     // during the listen()-to-chmod() window. macOS BSD AF_UNIX semantics make
     // socket mode advisory only, so the parent dir is the real boundary.
+    //
+    // On Windows the transport is a named pipe, not a filesystem inode: chmod/umask
+    // are no-ops (and umask throws in some Node builds), and pipe ACLs default to
+    // the creating user. So we skip the Unix hardening entirely there.
     const agentsDir = getPtyDirRoot();
     fs.mkdirSync(agentsDir, { recursive: true });
-    fs.chmodSync(agentsDir, 0o700);
-    // umask covers any inherited group/other bits while listen() is creating
-    // the socket inode — it only matters for the unobservable instant before
-    // we can chmod the inode itself.
-    process.umask(0o077);
+    if (!IS_WINDOWS) {
+        fs.chmodSync(agentsDir, 0o700);
+        // umask covers any inherited group/other bits while listen() is creating
+        // the socket inode — it only matters for the unobservable instant before
+        // we can chmod the inode itself.
+        process.umask(0o077);
+    }
     await new Promise((resolve) => {
         server.listen(socketPath, () => resolve());
     });
     // Surface chmod failures: a 0o600 socket is a load-bearing security
     // assumption, not a nice-to-have. If we can't lock it down, refuse to
-    // start so the caller learns immediately.
-    fs.chmodSync(socketPath, 0o600);
+    // start so the caller learns immediately. (No-op on Windows named pipes.)
+    if (!IS_WINDOWS) {
+        fs.chmodSync(socketPath, 0o600);
+    }
     log('INFO', `PTY server started (PID: ${process.pid}, socket: ${socketPath})`);
     // Shutdown handler
     function shutdown() {
@@ -549,10 +623,13 @@ export async function runPtyServer() {
         sessions.clear();
         clearInterval(cleanupInterval);
         server.close();
-        try {
-            fs.unlinkSync(socketPath);
+        // Named pipes are reclaimed by the OS on close; only Unix sockets leave a file.
+        if (!IS_WINDOWS) {
+            try {
+                fs.unlinkSync(socketPath);
+            }
+            catch { }
         }
-        catch { }
         try {
             fs.unlinkSync(getPtyPidPath());
         }

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/session/artifacts.js

@@ -8,6 +8,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { parseSession } from './parse.js';
+import { toComparablePath } from '../platform/index.js';
 /** Tool names that produce file artifacts (writes, edits, patches). */
 const WRITE_TOOLS = new Set([
     'Write', 'Edit', 'write_file', 'edit_file', 'create_file', 'replace', 'patch',
@@ -87,8 +88,13 @@ export function resolveArtifact(artifacts, name) {
         return byBase[0];
     if (byBase.length > 1)
         return byBase[0];
-    // Path suffix match (e.g. "src/foo.ts")
-    const bySuffix = artifacts.filter(a => a.path.endsWith('/' + name) || a.path === name);
+    // Path suffix match (e.g. "src/foo.ts"). Normalize so Windows `\` paths match
+    // a forward-slash query too; on POSIX this is identical to the old comparison.
+    const target = toComparablePath(name);
+    const bySuffix = artifacts.filter(a => {
+        const ap = toComparablePath(a.path);
+        return ap.endsWith('/' + target) || ap === target;
+    });
     if (bySuffix.length >= 1)
         return bySuffix[0];
     return null;

package/dist/lib/shims.d.ts

@@ -248,20 +248,25 @@ export declare function isShimsInPath(): boolean;
  * Get shell configuration instructions for adding shims to PATH.
  */
 export declare function getPathSetupInstructions(): string;
+interface ShimPathResult {
+    success: boolean;
+    alreadyPresent?: boolean;
+    rcFile?: string;
+    /** Human label of where the entry landed, e.g. `~/.zshrc` or `your user PATH`. */
+    location?: string;
+    /** Per-platform "how to pick it up" hint, e.g. `source ~/.zshrc` / open a new terminal. */
+    reloadHint?: string;
+    error?: string;
+}
 /**
- * Add shims directory to shell PATH configuration.
- * Returns true if added, false if already present or failed.
+ * Add the shims directory to PATH: edits the shell rc file on POSIX, or registers
+ * it on the Windows User PATH (registry + WM_SETTINGCHANGE). Idempotent.
  */
 export declare function addShimsToPath(overrides?: {
     homeDir?: string;
     shell?: string;
     shimsDir?: string;
-}): {
-    success: boolean;
-    alreadyPresent?: boolean;
-    rcFile?: string;
-    error?: string;
-};
+}): ShimPathResult;
 export declare function listAgentsWithInstalledVersions(): AgentId[];
 /**
  * Resource diff between two versions. Each field lists resources present in

package/dist/lib/shims.js

@@ -11,8 +11,10 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
+import { execFileSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { confirm, select } from '@inquirer/prompts';
+import { IS_WINDOWS } from './platform/index.js';
 import { getShimsDir, getVersionsDir, getBackupsDir, ensureAgentsDir } from './state.js';
 export { getShimsDir };
 import { AGENTS } from './agents.js';
@@ -521,8 +523,28 @@ export function createShim(agent) {
     const shimPath = path.join(shimsDir, agentConfig.cliCommand);
     const script = generateShimScript(agent);
     fs.writeFileSync(shimPath, script, { mode: 0o755 });
+    // Windows can't execute the bash shim directly. Drop a `.cmd` companion next
+    // to it that delegates to the node-side transparent resolver (`agents __shim`),
+    // so the version resolution stays single-sourced instead of reimplemented in batch.
+    if (IS_WINDOWS) {
+        writeWindowsCmdShim(shimPath + '.cmd', agentConfig.cliCommand);
+    }
     return shimPath;
 }
+/**
+ * Generate a Windows `.cmd` launcher that delegates to `agents __shim <spec>`.
+ * `spec` is the agent's cliCommand for the default-version shim, or
+ * `cliCommand@version` for a versioned alias. node + the dist entrypoint are
+ * resolved at generation time so the launcher does not depend on `agents`
+ * already being on PATH.
+ */
+function writeWindowsCmdShim(cmdPath, spec) {
+    const indexJs = getAgentsBinForGeneratedShim();
+    const content = `@echo off\r\n` +
+        `rem Auto-generated by agents-cli - do not edit\r\n` +
+        `node "${indexJs}" __shim ${spec} %*\r\n`;
+    fs.writeFileSync(cmdPath, content);
+}
 /**
  * Remove the shim for an agent.
  */
@@ -532,6 +554,12 @@ export function removeShim(agent) {
     const shimPath = path.join(shimsDir, agentConfig.cliCommand);
     if (fs.existsSync(shimPath)) {
         fs.unlinkSync(shimPath);
+        if (IS_WINDOWS) {
+            try {
+                fs.unlinkSync(shimPath + '.cmd');
+            }
+            catch { }
+        }
         return true;
     }
     return false;
@@ -682,6 +710,9 @@ export function createVersionedAlias(agent, version) {
     const aliasPath = path.join(shimsDir, `${agentConfig.cliCommand}@${version}`);
     const script = generateVersionedAliasScript(agent, version);
     fs.writeFileSync(aliasPath, script, { mode: 0o755 });
+    if (IS_WINDOWS) {
+        writeWindowsCmdShim(aliasPath + '.cmd', `${agentConfig.cliCommand}@${version}`);
+    }
     return aliasPath;
 }
 /**
@@ -693,6 +724,12 @@ export function removeVersionedAlias(agent, version) {
     const aliasPath = path.join(shimsDir, `${agentConfig.cliCommand}@${version}`);
     if (fs.existsSync(aliasPath)) {
         fs.unlinkSync(aliasPath);
+        if (IS_WINDOWS) {
+            try {
+                fs.unlinkSync(aliasPath + '.cmd');
+            }
+            catch { }
+        }
         return true;
     }
     return false;
@@ -1484,10 +1521,16 @@ Then restart your shell or run:
   source ~/${rcFile}`;
 }
 /**
- * Add shims directory to shell PATH configuration.
- * Returns true if added, false if already present or failed.
+ * Add the shims directory to PATH: edits the shell rc file on POSIX, or registers
+ * it on the Windows User PATH (registry + WM_SETTINGCHANGE). Idempotent.
  */
 export function addShimsToPath(overrides) {
+    // Windows has no shell rc file to edit. Register the shims dir on the User PATH
+    // via the platform-native mechanism instead. (The `shell` override is the test
+    // hook for exercising the POSIX path, so it bypasses this branch.)
+    if (IS_WINDOWS && !overrides?.shell) {
+        return addShimsToWindowsUserPath(overrides?.shimsDir || getShimsDir());
+    }
     const shimsDir = overrides?.shimsDir || getShimsDir();
     const { rcFile, rcPath, shell } = getShellRcFile(overrides);
     // Read current rc file content
@@ -1520,16 +1563,53 @@ export function addShimsToPath(overrides) {
         const separator = contentWithoutShimLines.length > 0 && !contentWithoutShimLines.endsWith('\n') ? '\n' : '';
         let newContent = contentWithoutShimLines + separator + exportBlock;
         newContent = newContent.replace(/\n{2,}$/g, '\n');
+        const location = `~/${rcFile}`;
+        const reloadHint = `Restart your shell or run: source ~/${rcFile}`;
         if (newContent === content) {
-            return { success: true, alreadyPresent: true, rcFile };
+            return { success: true, alreadyPresent: true, rcFile, location, reloadHint };
         }
         fs.writeFileSync(rcPath, newContent, 'utf-8');
-        return { success: true, rcFile };
+        return { success: true, rcFile, location, reloadHint };
     }
     catch (err) {
         return { success: false, error: `Could not write ${rcFile}: ${err.message}` };
     }
 }
+/**
+ * Register the shims dir on the Windows User PATH via the .NET environment API,
+ * which writes the registry AND broadcasts WM_SETTINGCHANGE — the correct analog
+ * of editing a shell rc file (no `setx` truncation, no manual step). Idempotent:
+ * a no-op when the dir is already present. The shims dir is passed via an env var
+ * so it is never interpolated into the PowerShell script text.
+ */
+function addShimsToWindowsUserPath(shimsDir) {
+    const script = [
+        '$d = $env:AGENTS_SHIMS_DIR',
+        "$u = [Environment]::GetEnvironmentVariable('Path','User')",
+        "if ($null -eq $u) { $u = '' }",
+        "$parts = @($u -split ';' | Where-Object { $_ -ne '' })",
+        "if ($parts -contains $d) { 'present' } else {",
+        "  [Environment]::SetEnvironmentVariable('Path', (($parts + $d) -join ';'), 'User')",
+        "  'added'",
+        '}',
+    ].join('\n');
+    try {
+        const out = execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], {
+            encoding: 'utf-8',
+            env: { ...process.env, AGENTS_SHIMS_DIR: shimsDir },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        }).trim();
+        return {
+            success: true,
+            alreadyPresent: out.includes('present'),
+            location: 'your user PATH',
+            reloadHint: 'Open a new terminal for the change to take effect.',
+        };
+    }
+    catch (err) {
+        return { success: false, error: `Could not update the Windows user PATH: ${err.message}` };
+    }
+}
 export function listAgentsWithInstalledVersions() {
     const versionsDir = getVersionsDir();
     if (!fs.existsSync(versionsDir)) {

package/dist/lib/teams/agents.js

@@ -14,6 +14,7 @@ import * as path from 'path';
 import * as os from 'os';
 import { randomUUID } from 'crypto';
 import { resolveAgentsDir } from './persistence.js';
+import { findExecutable } from '../platform/index.js';
 import { normalizeEvents } from './parsers.js';
 import { debug } from './debug.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from '../gemini-settings.js';
@@ -300,13 +301,10 @@ export function checkCliAvailable(agentType) {
     if (!executable) {
         return [false, `Unknown agent type: ${agentType}`];
     }
-    try {
-        const whichPath = execFileSync('which', [executable], { encoding: 'utf-8' }).trim();
-        return [true, whichPath];
-    }
-    catch {
-        return [false, `CLI tool '${executable}' not found in PATH. Install it first.`];
-    }
+    const resolved = findExecutable(executable);
+    return resolved
+        ? [true, resolved]
+        : [false, `CLI tool '${executable}' not found in PATH. Install it first.`];
 }
 /** Check availability of all known agent CLIs. Returns a map of agent type to install status. */
 export function checkAllClis() {

package/package.json

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

package/scripts/postinstall.js

@@ -95,6 +95,11 @@ function writeAliasShims() {
     const target = path.join(SHIMS_DIR, name);
     const script = `#!/bin/sh\nAGENTS_BIN=${shellQuote(AGENTS_BIN)}\nif [ -z "$AGENTS_BIN" ] || [ ! -x "$AGENTS_BIN" ]; then\n  echo "agents: agents-cli entrypoint missing or not executable: $AGENTS_BIN" >&2\n  exit 127\nfi\nexec "$AGENTS_BIN" ${name} "$@"\n`;
     fs.writeFileSync(target, script, { mode: 0o755 });
+    // Windows can't run the POSIX shim; drop a `.cmd` companion that invokes the
+    // entrypoint via node so the bare shorthand works in a Windows shell.
+    if (process.platform === 'win32') {
+      fs.writeFileSync(target + '.cmd', `@echo off\r\nnode "${AGENTS_BIN}" ${name} %*\r\n`);
+    }
     written.push(name);
   }
   return written;
@@ -139,8 +144,20 @@ function isAlreadyConfigured(rcFile) {
 }
 
 async function main() {
+  // Windows has no shell rc files to edit. Write the `.cmd` shorthands here; the
+  // shims dir gets registered on the User PATH by `agents setup` (via the native
+  // registry API), so we point the user there instead of mutating PATH from an
+  // npm lifecycle script. The primary `agents` command is already on PATH via
+  // npm's global bin and works immediately.
+  if (process.platform === 'win32') {
+    console.log(`\nagents-cli installed.`);
+    const written = writeAliasShims();
+    console.log(`  Installed shorthands: ${written.join(', ')}`);
+    console.log(`\nNext: run  agents setup  — it finishes setup and adds the shims dir to your PATH`);
+    console.log(`(so the bare shorthands ${ALIASES.join(', ')} and versioned aliases work in a new terminal).`);
+  }
   // Opt-in: AGENTS_INIT_SHELL=1 npm install -g @phnx-labs/agents-cli
-  if (process.env.AGENTS_INIT_SHELL === '1') {
+  else if (process.env.AGENTS_INIT_SHELL === '1') {
     const rcFile = getShellRc();
     if (!isAlreadyConfigured(rcFile)) {
       const addition = `\n# agents-cli: version switching for AI coding agents\n${exportLine}\n`;