@phnx-labs/agents-cli 1.12.0 → 1.14.1

package/dist/lib/acp/run.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Headless ACP runner.
+ *
+ * Glue between the `agents run <agent> "prompt" --acp` command and the ACP
+ * client. Emits either a human-readable stream of agent messages or newline-
+ * delimited JSON events, depending on `--json`.
+ */
+import type { AgentId } from '../types.js';
+import type { ExecMode } from '../exec.js';
+export interface HeadlessAcpOptions {
+    agent: AgentId;
+    prompt: string;
+    cwd: string;
+    mode: ExecMode;
+    json: boolean;
+}
+/** Runs a prompt turn over ACP, streaming output to stdout per `json` mode. */
+export declare function runAcpHeadless(opts: HeadlessAcpOptions): Promise<number>;

package/dist/lib/acp/run.js

@@ -0,0 +1,39 @@
+/**
+ * Headless ACP runner.
+ *
+ * Glue between the `agents run <agent> "prompt" --acp` command and the ACP
+ * client. Emits either a human-readable stream of agent messages or newline-
+ * delimited JSON events, depending on `--json`.
+ */
+import { runAcp } from './client.js';
+/** Runs a prompt turn over ACP, streaming output to stdout per `json` mode. */
+export async function runAcpHeadless(opts) {
+    const onUpdate = opts.json ? emitJsonLine : emitTextChunk;
+    const result = await runAcp({
+        agent: opts.agent,
+        prompt: opts.prompt,
+        cwd: opts.cwd,
+        mode: opts.mode,
+        onUpdate,
+    });
+    if (opts.json) {
+        emitJsonLine({
+            sessionId: result.sessionId,
+            update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: '' } },
+            _meta: { stopReason: result.stopReason },
+        });
+    }
+    else {
+        process.stdout.write('\n');
+    }
+    return result.stopReason === 'end_turn' ? 0 : 1;
+}
+function emitJsonLine(n) {
+    process.stdout.write(JSON.stringify(n) + '\n');
+}
+function emitTextChunk(n) {
+    const upd = n.update;
+    if (upd.sessionUpdate === 'agent_message_chunk' && upd.content.type === 'text') {
+        process.stdout.write(upd.content.text);
+    }
+}

package/dist/lib/agents.d.ts

@@ -1,29 +1,74 @@
 import type { AgentConfig, AgentId } from './types.js';
+/** Represents the installation state of an agent's CLI binary. */
 export interface CliState {
     installed: boolean;
     version: string | null;
     path: string | null;
 }
+/**
+ * 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 declare const CODEX_HOOKS_MIN_VERSION = "0.116.0";
+/** Minimum Gemini CLI version that supports the hooks system (v0.26.0, Jan 2026). */
+export declare const GEMINI_HOOKS_MIN_VERSION = "0.26.0";
+/**
+ * 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 declare const AGENTS: Record<AgentId, AgentConfig>;
+/** All registered agent IDs derived from the AGENTS registry. */
 export declare const ALL_AGENT_IDS: AgentId[];
+/** Agents that support MCP (Model Context Protocol) server integration. */
 export declare const MCP_CAPABLE_AGENTS: AgentId[];
+/** Agents that support skills (SKILL.md + rules/ bundles). */
 export declare const SKILLS_CAPABLE_AGENTS: AgentId[];
+/** Agents that support file-based slash commands. */
 export declare const COMMANDS_CAPABLE_AGENTS: AgentId[];
-export declare const HOOKS_CAPABLE_AGENTS: readonly ["claude", "codex", "gemini", "openclaw"];
+/** Agents that support event hooks (pre/post lifecycle callbacks). */
+export declare const HOOKS_CAPABLE_AGENTS: readonly AgentId[];
+/** Agents that support the plugin system. */
 export declare const PLUGINS_CAPABLE_AGENTS: AgentId[];
 /** Get the chalk color function for an agent. Works for any AgentId or SessionAgentId. */
 export declare function colorAgent(agentId: string): (s: string) => string;
 /** Return the agent's display name, colored. */
 export declare function agentLabel(agentId: string): string;
+/** Check whether the given agent's CLI binary is present on PATH. */
 export declare function isCliInstalled(agentId: AgentId): Promise<boolean>;
+/** Return the installed CLI version for the given agent, or null if not found. */
 export declare function getCliVersion(agentId: AgentId): Promise<string | null>;
+/** Return the absolute path to the agent's CLI binary on PATH, or null. */
 export declare function getCliPath(agentId: AgentId): Promise<string | null>;
+/**
+ * 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 declare function getCliState(agentId: AgentId): Promise<CliState>;
+/** Resolve CLI state for all registered agents in parallel. */
 export declare function getAllCliStates(): Promise<Partial<Record<AgentId, CliState>>>;
+/** Check whether the agent's config directory exists on disk. */
 export declare function isConfigured(agentId: AgentId): boolean;
+/** Info about an existing unmanaged agent installation. */
+export interface UnmanagedInstall {
+    agentId: AgentId;
+    configDir: string;
+    version: string | null;
+}
+/**
+ * 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 declare function getUnmanagedAgentInstalls(): Promise<UnmanagedInstall[]>;
+/** Create the agent's slash-commands directory if it does not exist. */
 export declare function ensureCommandsDir(agentId: AgentId): void;
+/** Create the agent's skills directory if it does not exist. */
 export declare function ensureSkillsDir(agentId: AgentId): void;
+/** Account identity and billing information extracted from an agent's auth config. */
 export interface AccountInfo {
     accountKey: string | null;
     usageKey: string | null;
@@ -39,9 +84,21 @@ export interface AccountInfo {
     } | null;
     lastActive: Date | null;
 }
+/** Return the email address associated with the agent's auth config, or null. */
 export declare function getAccountEmail(agentId: AgentId, home?: string): Promise<string | null>;
+/**
+ * Extract full account information (identity, plan, usage status, credits) from
+ * the agent's local auth/config files. Supports Claude, Codex, and Gemini.
+ */
 export declare function getAccountInfo(agentId: AgentId, home?: string): Promise<AccountInfo>;
+/**
+ * Quick count of session files for an agent (without full DB scan).
+ * Used during init to show approximate session count to user.
+ */
+export declare function countSessionFiles(agentId: AgentId): number;
+/** Check whether a named MCP server is registered with the agent's CLI. */
 export declare function isMcpRegistered(agentId: AgentId, mcpName: string): Promise<boolean>;
+/** Register an MCP server with an agent's CLI via `mcp add`. */
 export declare function registerMcp(agentId: AgentId, name: string, command: string, scope?: 'user' | 'project', transport?: string, options?: {
     home?: string;
     binary?: string;
@@ -49,6 +106,7 @@ export declare function registerMcp(agentId: AgentId, name: string, command: str
     success: boolean;
     error?: string;
 }>;
+/** Unregister (remove) a named MCP server from an agent's CLI config. */
 export declare function unregisterMcp(agentId: AgentId, name: string, options?: {
     home?: string;
     binary?: string;
@@ -56,21 +114,32 @@ export declare function unregisterMcp(agentId: AgentId, name: string, options?:
     success: boolean;
     error?: string;
 }>;
+/** Result of an MCP registration or removal operation targeting a specific agent and optional version. */
 export interface McpTargetOperationResult {
     agentId: AgentId;
     version?: string;
     success: boolean;
     error?: string;
 }
+/**
+ * Register an MCP server across multiple agent targets, including both direct
+ * (non-version-managed) agents and specific version-managed installs.
+ */
 export declare function registerMcpToTargets(targets: {
     directAgents: AgentId[];
     versionSelections: Map<AgentId, string[]>;
 }, name: string, command: string, scope?: 'user' | 'project', transport?: string): Promise<McpTargetOperationResult[]>;
+/**
+ * Unregister an MCP server from multiple agent targets, including both direct
+ * agents and specific version-managed installs.
+ */
 export declare function unregisterMcpFromTargets(targets: {
     directAgents: AgentId[];
     versionSelections: Map<AgentId, string[]>;
 }, name: string): Promise<McpTargetOperationResult[]>;
+/** Scope at which an MCP server is registered: user-global or per-project. */
 export type McpScope = 'user' | 'project';
+/** Describes an MCP server discovered in an agent's config, with its scope and command. */
 export interface InstalledMcp {
     name: string;
     scope: McpScope;
@@ -99,9 +168,12 @@ export declare function parseMcpConfig(agentId: AgentId, configPath: string): Re
 export declare function listInstalledMcpsWithScope(agentId: AgentId, cwd?: string, options?: {
     home?: string;
 }): InstalledMcp[];
+/** Map of agent name aliases and shorthand identifiers to canonical AgentId values. */
 export declare const AGENT_NAME_ALIASES: Record<string, AgentId>;
+/** Resolve a user-provided agent name (alias, shorthand, or canonical) to its AgentId. */
 export declare function resolveAgentName(input: string): AgentId | null;
+/** Check whether the input string matches any known agent name or alias. */
 export declare function isAgentName(input: string): boolean;
+/** Format an error message for an unrecognized agent name, listing valid options. */
 export declare function formatAgentError(agentName: string, validAgents?: AgentId[]): string;
 export {};
-//# sourceMappingURL=agents.d.ts.map