@phnx-labs/agents-cli 1.12.0 → 1.14.1

package/dist/lib/agents.js

@@ -1,17 +1,35 @@
-import { exec } from 'child_process';
+/**
+ * Core agent configuration and detection module.
+ *
+ * Defines the canonical registry of all supported AI coding agents (Claude, Codex,
+ * Gemini, Cursor, OpenCode, OpenClaw, Copilot, Amp, Kiro, Goose, Roo) with their
+ * CLI commands, config paths, capability flags, and MCP integration points.
+ *
+ * Provides functions for detecting installed CLIs, resolving version-managed binaries,
+ * reading account/auth info, and managing MCP server registrations across agents.
+ */
+import { execFile } from 'child_process';
 import { promisify } from 'util';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as TOML from 'smol-toml';
 import chalk from 'chalk';
-import { walkForFiles } from './session/discover.js';
-import { getVersionsDir, getShimsDir } from './state.js';
+import { walkForFiles } from './fs-walk.js';
+import { getVersionsDir, getShimsDir, getAgentsDir } from './state.js';
 import { resolveVersion, getVersionHomePath, getBinaryPath } from './versions.js';
-const execAsync = promisify(exec);
+import { loadClaudeOauth } from './usage.js';
+const execFileAsync = promisify(execFile);
 const HOME = os.homedir();
+/**
+ * Minimum Codex CLI version that supports hooks.
+ * Mirrored on `AGENTS.codex.capabilities.hooks.since` -- kept exported for
+ * legacy import sites that haven't migrated to `supports()` yet.
+ */
 export const CODEX_HOOKS_MIN_VERSION = '0.116.0';
-const CLI_VERSION_CACHE_PATH = path.join(HOME, '.agents', '.cli-version-cache.json');
+/** Minimum Gemini CLI version that supports the hooks system (v0.26.0, Jan 2026). */
+export const GEMINI_HOOKS_MIN_VERSION = '0.26.0';
+const CLI_VERSION_CACHE_PATH = path.join(getAgentsDir(), '.cli-version-cache.json');
 let cliVersionCache = null;
 function loadCliVersionCache() {
     if (cliVersionCache)
@@ -38,7 +56,7 @@ function saveCliVersionCache() {
         /* best-effort cache persist */
     }
 }
-/** Synchronous PATH search — no subprocess. Returns first matching binary path. */
+/** Synchronous PATH search -- no subprocess. Returns first matching binary path. */
 function findInPath(command) {
     const pathEnv = process.env.PATH || '';
     const pathExt = process.platform === 'win32' ? (process.env.PATHEXT || '').split(';') : [''];
@@ -59,6 +77,67 @@ function findInPath(command) {
     }
     return null;
 }
+function splitCommandLine(command) {
+    const args = [];
+    let current = '';
+    let quote = null;
+    let tokenStarted = false;
+    for (let i = 0; i < command.length; i++) {
+        const char = command[i];
+        if (quote) {
+            if (char === quote) {
+                quote = null;
+                tokenStarted = true;
+            }
+            else if (char === '\\' && quote === '"' && i + 1 < command.length) {
+                current += command[++i];
+                tokenStarted = true;
+            }
+            else {
+                current += char;
+                tokenStarted = true;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            tokenStarted = true;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            if (tokenStarted) {
+                args.push(current);
+                current = '';
+                tokenStarted = false;
+            }
+            continue;
+        }
+        if (char === '\\' && i + 1 < command.length) {
+            current += command[++i];
+            tokenStarted = true;
+            continue;
+        }
+        current += char;
+        tokenStarted = true;
+    }
+    if (quote) {
+        throw new Error('Unterminated quote in MCP command');
+    }
+    if (tokenStarted) {
+        args.push(current);
+    }
+    if (args.length === 0) {
+        throw new Error('MCP command is required');
+    }
+    return args;
+}
+/**
+ * Master registry of all supported agents keyed by AgentId.
+ *
+ * Each entry defines the agent's CLI command, npm package, config directory layout,
+ * instructions file name, slash-command format, and capability flags. This is the
+ * single source of truth for agent metadata consumed throughout the codebase.
+ */
 export const AGENTS = {
     claude: {
         id: 'claude',
@@ -78,6 +157,7 @@ export const AGENTS = {
         supportsHooks: true,
         capabilities: { hooks: true, mcp: true, allowlist: true, skills: true, commands: true, plugins: true, memoryImports: true },
     },
+    // codex hooks: gated to >= 0.116.0 (introduced [features] codex_hooks flag).
     codex: {
         id: 'codex',
         name: 'Codex',
@@ -93,7 +173,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
-        capabilities: { hooks: true, mcp: true, allowlist: false, skills: true, commands: true, plugins: false },
+        capabilities: { hooks: { since: '0.116.0' }, mcp: true, allowlist: false, skills: true, commands: { until: '0.117.0' }, plugins: false },
     },
     gemini: {
         id: 'gemini',
@@ -111,7 +191,8 @@ export const AGENTS = {
         variableSyntax: '{{args}}',
         supportsHooks: true,
         nativeAgentsSkillsDir: true,
-        capabilities: { hooks: true, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, memoryImports: true },
+        // gemini hooks: shipped in v0.26.0 (Jan 2026); older binaries silently ignore the `hooks` key.
+        capabilities: { hooks: { since: '0.26.0' }, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, memoryImports: true },
     },
     cursor: {
         id: 'cursor',
@@ -254,12 +335,18 @@ export const AGENTS = {
         capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false },
     },
 };
+/** All registered agent IDs derived from the AGENTS registry. */
 export const ALL_AGENT_IDS = Object.keys(AGENTS);
+/** Agents that support MCP (Model Context Protocol) server integration. */
 export const MCP_CAPABLE_AGENTS = ALL_AGENT_IDS.filter((id) => AGENTS[id].capabilities.mcp);
+/** Agents that support skills (SKILL.md + rules/ bundles). */
 export const SKILLS_CAPABLE_AGENTS = ALL_AGENT_IDS.filter((id) => AGENTS[id].capabilities.skills);
+/** Agents that support file-based slash commands. */
 export const COMMANDS_CAPABLE_AGENTS = ALL_AGENT_IDS.filter((id) => AGENTS[id].capabilities.commands);
-export const HOOKS_CAPABLE_AGENTS = ['claude', 'codex', 'gemini', 'openclaw'];
-export const PLUGINS_CAPABLE_AGENTS = ALL_AGENT_IDS.filter((id) => AGENTS[id].capabilities.plugins);
+/** Agents that support event hooks (pre/post lifecycle callbacks). */
+export const HOOKS_CAPABLE_AGENTS = ALL_AGENT_IDS.filter((id) => AGENTS[id].capabilities.hooks !== false);
+/** Agents that support the plugin system. */
+export const PLUGINS_CAPABLE_AGENTS = ALL_AGENT_IDS.filter((id) => AGENTS[id].capabilities.plugins !== false);
 /** Get the chalk color function for an agent. Works for any AgentId or SessionAgentId. */
 export function colorAgent(agentId) {
     const agent = AGENTS[agentId];
@@ -274,10 +361,12 @@ export function agentLabel(agentId) {
         return agentId;
     return chalk[agent.color](agent.name);
 }
+/** Check whether the given agent's CLI binary is present on PATH. */
 export async function isCliInstalled(agentId) {
     const agent = AGENTS[agentId];
     return findInPath(agent.cliCommand) !== null;
 }
+/** Return the installed CLI version for the given agent, or null if not found. */
 export async function getCliVersion(agentId) {
     const agent = AGENTS[agentId];
     const binaryPath = findInPath(agent.cliCommand);
@@ -285,6 +374,7 @@ export async function getCliVersion(agentId) {
         return null;
     return getCachedVersionForBinary(agentId, binaryPath);
 }
+/** Return the absolute path to the agent's CLI binary on PATH, or null. */
 export async function getCliPath(agentId) {
     return findInPath(AGENTS[agentId].cliCommand);
 }
@@ -306,7 +396,7 @@ async function getCachedVersionForBinary(agentId, binaryPath) {
     const agent = AGENTS[agentId];
     let version = null;
     try {
-        const { stdout } = await execAsync(`${agent.cliCommand} --version`, { timeout: 3000 });
+        const { stdout } = await execFileAsync(agent.cliCommand, ['--version'], { timeout: 3000 });
         if (agentId === 'openclaw') {
             const match = stdout.match(/openclaw\/(\d+\.\d+\.\d+)/);
             version = match ? match[1] : stdout.trim();
@@ -324,6 +414,11 @@ async function getCachedVersionForBinary(agentId, binaryPath) {
     saveCliVersionCache();
     return version;
 }
+/**
+ * Resolve the full CLI state for an agent: whether it is installed, its version,
+ * and the path to the binary. Checks version-managed installs first, then falls
+ * back to a plain PATH lookup.
+ */
 export async function getCliState(agentId) {
     // Fast path: if version-managed, derive state from filesystem (no subprocesses)
     const agent = AGENTS[agentId];
@@ -369,6 +464,7 @@ export async function getCliState(agentId) {
         path: binaryPath,
     };
 }
+/** Resolve CLI state for all registered agents in parallel. */
 export async function getAllCliStates() {
     const states = {};
     const results = await Promise.all(ALL_AGENT_IDS.map(async (agentId) => ({
@@ -380,26 +476,56 @@ export async function getAllCliStates() {
     }
     return states;
 }
+/** Check whether the agent's config directory exists on disk. */
 export function isConfigured(agentId) {
     const agent = AGENTS[agentId];
     return fs.existsSync(agent.configDir);
 }
+/**
+ * Detect existing agent installations that are NOT yet managed by agents-cli.
+ * Returns agents whose config dir exists as a real directory (not a symlink).
+ */
+export async function getUnmanagedAgentInstalls() {
+    const unmanaged = [];
+    const candidates = ['claude', 'codex', 'gemini'];
+    for (const agentId of candidates) {
+        const agent = AGENTS[agentId];
+        try {
+            const stat = fs.lstatSync(agent.configDir);
+            if (stat.isDirectory() && !stat.isSymbolicLink()) {
+                const version = await getCliVersion(agentId);
+                unmanaged.push({ agentId, configDir: agent.configDir, version });
+            }
+        }
+        catch {
+            // Config dir doesn't exist
+        }
+    }
+    return unmanaged;
+}
+/** Create the agent's slash-commands directory if it does not exist. */
 export function ensureCommandsDir(agentId) {
     const agent = AGENTS[agentId];
     if (!fs.existsSync(agent.commandsDir)) {
         fs.mkdirSync(agent.commandsDir, { recursive: true });
     }
 }
+/** Create the agent's skills directory if it does not exist. */
 export function ensureSkillsDir(agentId) {
     const agent = AGENTS[agentId];
     if (!fs.existsSync(agent.skillsDir)) {
         fs.mkdirSync(agent.skillsDir, { recursive: true });
     }
 }
+/** Return the email address associated with the agent's auth config, or null. */
 export async function getAccountEmail(agentId, home) {
     const info = await getAccountInfo(agentId, home);
     return info.email;
 }
+/**
+ * Extract full account information (identity, plan, usage status, credits) from
+ * the agent's local auth/config files. Supports Claude, Codex, and Gemini.
+ */
 export async function getAccountInfo(agentId, home) {
     const base = home || os.homedir();
     const empty = {
@@ -441,10 +567,17 @@ export async function getAccountInfo(agentId, home) {
                 ]);
                 const usageKey = buildIdentityKey(agentId, [['org', organizationId]]);
                 let plan = null;
-                if (oa?.billingType === 'stripe_subscription')
+                const keychainOauth = await loadClaudeOauth(home);
+                if (keychainOauth?.subscriptionType) {
+                    plan = keychainOauth.subscriptionType.charAt(0).toUpperCase()
+                        + keychainOauth.subscriptionType.slice(1);
+                }
+                else if (oa?.billingType === 'stripe_subscription') {
                     plan = 'Pro';
-                else if (oa?.billingType)
+                }
+                else if (oa?.billingType) {
                     plan = oa.billingType;
+                }
                 let usageStatus = null;
                 const reason = data.cachedExtraUsageDisabledReason;
                 if (reason === 'out_of_credits')
@@ -529,6 +662,7 @@ export async function getAccountInfo(agentId, home) {
         return { ...empty, lastActive };
     }
 }
+/** Determine when the agent was last used by checking session file mtimes, falling back to config mtime. */
 function resolveLastActive(agentId, base, configPath) {
     const sessionDir = getSessionDir(agentId, base);
     const sessionExt = getSessionExtension(agentId);
@@ -547,6 +681,7 @@ function resolveLastActive(agentId, base, configPath) {
         return null;
     }
 }
+/** Return the root directory where the agent stores session files, or null if unknown. */
 function getSessionDir(agentId, base) {
     switch (agentId) {
         case 'claude':
@@ -559,6 +694,7 @@ function getSessionDir(agentId, base) {
             return null;
     }
 }
+/** Return the file extension used for session files by the given agent. */
 function getSessionExtension(agentId) {
     switch (agentId) {
         case 'claude':
@@ -570,6 +706,36 @@ function getSessionExtension(agentId) {
             return null;
     }
 }
+/**
+ * Quick count of session files for an agent (without full DB scan).
+ * Used during init to show approximate session count to user.
+ */
+export function countSessionFiles(agentId) {
+    const sessionDir = getSessionDir(agentId, HOME);
+    const ext = getSessionExtension(agentId);
+    if (!sessionDir || !ext || !fs.existsSync(sessionDir))
+        return 0;
+    let count = 0;
+    const walk = (dir) => {
+        try {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    walk(path.join(dir, entry.name));
+                }
+                else if (entry.isFile() && entry.name.endsWith(ext)) {
+                    count++;
+                }
+            }
+        }
+        catch {
+            // Permission denied or other error
+        }
+    };
+    walk(sessionDir);
+    return count;
+}
+/** Walk a directory for files matching the extension and return the mtime of the most recent one. */
 function getLatestFileMtime(dir, ext) {
     if (!fs.existsSync(dir))
         return null;
@@ -583,6 +749,7 @@ function getLatestFileMtime(dir, ext) {
         return null;
     }
 }
+/** Decode the payload section of a JWT token without verifying its signature. */
 function decodeJwtPayload(token) {
     const payload = token.split('.')[1];
     if (!payload)
@@ -594,6 +761,7 @@ function decodeJwtPayload(token) {
         return null;
     }
 }
+/** Extract the default organization ID from a Codex/OpenAI auth claim. */
 function getCodexDefaultOrgId(authClaim) {
     const organizations = authClaim?.organizations;
     if (!Array.isArray(organizations))
@@ -601,12 +769,14 @@ function getCodexDefaultOrgId(authClaim) {
     const first = organizations[0];
     return typeof first?.id === 'string' ? first.id : null;
 }
+/** Trim and normalize an identity string, returning null for empty or non-string values. */
 function normalizeIdentityPart(value) {
     if (typeof value !== 'string')
         return null;
     const trimmed = value.trim();
     return trimmed || null;
 }
+/** Build a composite identity key like "claude:account=abc:org=xyz" from labeled parts. */
 function buildIdentityKey(agentId, parts) {
     const encoded = parts
         .filter(([, value]) => value)
@@ -615,13 +785,14 @@ function buildIdentityKey(agentId, parts) {
         return null;
     return `${agentId}:${encoded.join(':')}`;
 }
+/** Check whether a named MCP server is registered with the agent's CLI. */
 export async function isMcpRegistered(agentId, mcpName) {
     const agent = AGENTS[agentId];
     if (!agent.capabilities.mcp || !(await isCliInstalled(agentId))) {
         return false;
     }
     try {
-        const { stdout } = await execAsync(`${agent.cliCommand} mcp list`);
+        const { stdout } = await execFileAsync(agent.cliCommand, ['mcp', 'list']);
         return stdout.toLowerCase().includes(mcpName.toLowerCase());
     }
     catch {
@@ -629,6 +800,7 @@ export async function isMcpRegistered(agentId, mcpName) {
         return false;
     }
 }
+/** Register an MCP server with an agent's CLI via `mcp add`. */
 export async function registerMcp(agentId, name, command, scope = 'user', transport = 'stdio', options) {
     const agent = AGENTS[agentId];
     if (!agent.capabilities.mcp) {
@@ -640,22 +812,24 @@ export async function registerMcp(agentId, name, command, scope = 'user', transp
     try {
         // Use explicit binary path when provided (bypasses shim for version-managed agents)
         const bin = options?.binary || agent.cliCommand;
-        let cmd;
+        let args;
+        const commandArgs = splitCommandLine(command);
         if (agentId === 'claude') {
-            cmd = `${bin} mcp add --transport ${transport} --scope ${scope} "${name}" -- ${command}`;
+            args = ['mcp', 'add', '--transport', transport, '--scope', scope, name, '--', ...commandArgs];
         }
         else {
-            cmd = `${bin} mcp add "${name}" -- ${command}`;
+            args = ['mcp', 'add', name, '--', ...commandArgs];
         }
         // When home is specified, override HOME so MCP config writes to the version's config dir
         const env = options?.home ? { ...process.env, HOME: options.home } : undefined;
-        await execAsync(cmd, env ? { env } : undefined);
+        await execFileAsync(bin, args, env ? { env } : undefined);
         return { success: true };
     }
     catch (err) {
         return { success: false, error: err.message };
     }
 }
+/** Unregister (remove) a named MCP server from an agent's CLI config. */
 export async function unregisterMcp(agentId, name, options) {
     const agent = AGENTS[agentId];
     if (!agent.capabilities.mcp) {
@@ -667,13 +841,17 @@ export async function unregisterMcp(agentId, name, options) {
     try {
         const bin = options?.binary || agent.cliCommand;
         const env = options?.home ? { ...process.env, HOME: options.home } : undefined;
-        await execAsync(`${bin} mcp remove "${name}"`, env ? { env } : undefined);
+        await execFileAsync(bin, ['mcp', 'remove', name], env ? { env } : undefined);
         return { success: true };
     }
     catch (err) {
         return { success: false, error: err.message };
     }
 }
+/**
+ * Register an MCP server across multiple agent targets, including both direct
+ * (non-version-managed) agents and specific version-managed installs.
+ */
 export async function registerMcpToTargets(targets, name, command, scope = 'user', transport = 'stdio') {
     const results = [];
     for (const agentId of targets.directAgents) {
@@ -691,6 +869,10 @@ export async function registerMcpToTargets(targets, name, command, scope = 'user
     }
     return results;
 }
+/**
+ * Unregister an MCP server from multiple agent targets, including both direct
+ * agents and specific version-managed installs.
+ */
 export async function unregisterMcpFromTargets(targets, name) {
     const results = [];
     for (const agentId of targets.directAgents) {
@@ -710,8 +892,8 @@ export async function unregisterMcpFromTargets(targets, name) {
 }
 /**
  * Extract version from npm package specification.
- * Examples: @swarmify/agents-mcp@latest -> latest
- *           @swarmify/agents-mcp@1.2.3 -> 1.2.3
+ * Examples: @scope/package@latest -> latest
+ *           @scope/package@1.2.3 -> 1.2.3
  *           some-package -> undefined
  */
 function extractNpmVersion(args) {
@@ -1043,7 +1225,7 @@ export function listInstalledMcpsWithScope(agentId, cwd = process.cwd(), options
     }
     return results;
 }
-// Agent name aliases for flexible input
+/** Map of agent name aliases and shorthand identifiers to canonical AgentId values. */
 export const AGENT_NAME_ALIASES = {
     claude: 'claude',
     'claude-code': 'claude',
@@ -1076,13 +1258,15 @@ export const AGENT_NAME_ALIASES = {
     'roo-code': 'roo',
     roocode: 'roo',
 };
+/** Resolve a user-provided agent name (alias, shorthand, or canonical) to its AgentId. */
 export function resolveAgentName(input) {
     return AGENT_NAME_ALIASES[input.toLowerCase()] || null;
 }
+/** Check whether the input string matches any known agent name or alias. */
 export function isAgentName(input) {
     return resolveAgentName(input) !== null;
 }
+/** Format an error message for an unrecognized agent name, listing valid options. */
 export function formatAgentError(agentName, validAgents = ALL_AGENT_IDS) {
     return `Unknown agent '${agentName}'. Valid agents: ${validAgents.join(', ')}`;
 }
-//# sourceMappingURL=agents.js.map

package/dist/lib/artifact-actions.d.ts

@@ -1,22 +1,26 @@
 /**
- * Artifact action types and validation
- * Ported from agents/halo/cli/pkg/config
+ * Artifact action types and validation.
+ * Ported from agents/halo/cli/pkg/config.
+ *
+ * Artifact actions map tool invocations to artifact labels, allowing agents to
+ * trigger tools automatically when specific artifacts are produced.
  */
+/** A single action that binds a tool invocation to matching artifact labels. */
 export interface ArtifactAction {
     tool: string;
     label: string;
     matches?: string[];
     input?: Record<string, string>;
 }
+/** Agent-level configuration block containing artifact action definitions. */
 export interface AgentArtifactConfig {
     artifact_actions?: ArtifactAction[];
 }
 /**
- * Validate artifact actions configuration
+ * Validate artifact actions configuration.
  * @param actions - List of artifact actions to validate
  * @param httpToolNames - Set of tool names defined in http_tools section
  * @param applicationTools - Set of valid application tool names
  * @returns Array of validation errors (empty if valid)
  */
 export declare function validateArtifactActions(actions: ArtifactAction[], httpToolNames: Set<string>, applicationTools: Set<string>): string[];
-//# sourceMappingURL=artifact-actions.d.ts.map

package/dist/lib/artifact-actions.js

@@ -1,9 +1,12 @@
 /**
- * Artifact action types and validation
- * Ported from agents/halo/cli/pkg/config
+ * Artifact action types and validation.
+ * Ported from agents/halo/cli/pkg/config.
+ *
+ * Artifact actions map tool invocations to artifact labels, allowing agents to
+ * trigger tools automatically when specific artifacts are produced.
  */
 /**
- * Validate artifact actions configuration
+ * Validate artifact actions configuration.
  * @param actions - List of artifact actions to validate
  * @param httpToolNames - Set of tool names defined in http_tools section
  * @param applicationTools - Set of valid application tool names
@@ -38,8 +41,8 @@ export function validateArtifactActions(actions, httpToolNames, applicationTools
     return errors;
 }
 /**
- * Validate template string uses only allowed patterns
- * Only allows {{artifact.X}} and {{preflight.X}} patterns
+ * Validate template string uses only allowed patterns.
+ * Only allows {{artifact.X}} and {{preflight.X}} patterns.
  */
 function validateTemplate(tmpl) {
     const re = /\{\{(\w+)\.(\w+)\}\}/g;
@@ -52,4 +55,3 @@ function validateTemplate(tmpl) {
     }
     return null;
 }
-//# sourceMappingURL=artifact-actions.js.map

package/dist/lib/auto-pull-worker.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Detached worker entry point for background sync. See auto-pull.ts for the public API.
+ *
+ * For the system repo: fast-forward pull (safe — repo is read-only locally).
+ * For the user repo + enabled extras: `git fetch` + write a status marker the foreground
+ * CLI surfaces on its next invocation.
+ *
+ * Per-repo lock files at ~/.agents-system/.fetch/<alias>.lock prevent concurrent fetches.
+ * Lock mtime under 5 min => skip (another invocation already in flight).
+ */
+export {};