@phnx-labs/agents-cli 1.22.38 → 1.22.40

package/dist/lib/agents.d.ts

@@ -35,6 +35,45 @@ interface NativeBinaryResolutionOptions {
  */
 export declare function resolveNativeBinaryPath(command: string, candidate: string, options?: NativeBinaryResolutionOptions): string | null;
 export declare function findInPath(command: string, options?: NativeBinaryResolutionOptions): string | null;
+/**
+ * Per-harness dispatch data that used to live in `if (agentId === …)` /
+ * `switch (agentId)` arms inside this file. These are stable properties of a
+ * harness, not per-call-site quirks — a new AgentId must declare every field
+ * (the completeness test in agents.test.ts pins that).
+ *
+ * Left as call-site specials (not registry data): `getAccountInfo` and
+ * `readAuthAccountIdentity` — those are parsers, not flags.
+ */
+export type VersionStdoutMatch = 'semver' | 'openclaw';
+export type UnmanagedBinaryResolver = 'path' | 'grok-downloads';
+export type McpRegisterPath = 'cli' | 'config';
+export type McpAddHttpStyle = 'transport' | 'url';
+export type McpAddStdioStyle = 'scope' | 'simple';
+export type McpConfigWriteStyle = 'json-mcpServers' | 'yaml-mcp_servers';
+export interface AgentRegistryConfig extends AgentConfig {
+    /**
+     * Session-transcript directory as path segments under a HOME root, or null
+     * when this harness has no local session tree `agents` can walk.
+     */
+    sessionDir: string[] | null;
+    /** File extension of session transcripts, or null when unknown. */
+    sessionFileExt: '.jsonl' | '.json' | null;
+    /** How to parse `cli --version` stdout. */
+    versionStdoutMatch: VersionStdoutMatch;
+    /** How to find an unmanaged (non-version-home) binary. */
+    unmanagedBinary: UnmanagedBinaryResolver;
+    /**
+     * How `registerMcp` / `unregisterMcp` talk to the harness. `config` writes
+     * the file directly (no `mcp add` CLI); `cli` shells out.
+     */
+    mcpRegister: McpRegisterPath;
+    /** Argv shape for `mcp add` over HTTP. */
+    mcpAddHttp: McpAddHttpStyle;
+    /** Argv shape for `mcp add` over stdio. */
+    mcpAddStdio: McpAddStdioStyle;
+    /** On-disk map key + serialization when writing MCP config directly. */
+    mcpConfigWrite: McpConfigWriteStyle;
+}
 /**
  * Master registry of all supported agents keyed by AgentId.
  *
@@ -42,7 +81,7 @@ export declare function findInPath(command: string, options?: NativeBinaryResolu
  * 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>;
+export declare const AGENTS: Record<AgentId, AgentRegistryConfig>;
 /** All current and legacy agent IDs derived from the AGENTS registry. */
 export declare const ALL_AGENT_IDS: AgentId[];
 /**
@@ -119,9 +158,8 @@ export interface UnmanagedInstall {
 }
 /**
  * Agents that `agents setup` probes for pre-existing native installations
- * (i.e., a config dir present before agents-cli took over). Add an agent here
- * once its `cliCommand` reports a usable `--version` and its session dir is
- * wired into `getSessionDir`.
+ * (i.e., a config dir present before agents-cli took over). Derived from
+ * `sessionDir` so a new harness cannot be walkable yet missing from setup.
  */
 export declare const UNMANAGED_DETECTION_CANDIDATES: AgentId[];
 /**
@@ -462,8 +500,24 @@ interface McpConfigEntry {
     type?: string;
     url?: string;
 }
+/**
+ * Strip JSON comments for JSONC parsing.
+ * Only removes comments outside of strings.
+ *
+ * Exported because the MCP writer needs the SAME parser the reader uses: a
+ * naive `//`-to-end-of-line regex eats the `//` inside
+ * `"$schema": "https://opencode.ai/config.json"`, which every opencode-generated
+ * config carries.
+ */
+export declare function stripJsonComments(content: string): string;
 /**
  * Get user-scoped MCP config path for an agent.
+ *
+ * All three MCP path resolvers read `MCP_TARGETS`, so the file the writer
+ * targets, the file the parser reads, and the file the staleness detector
+ * watches cannot drift apart. An agent with no MCP target (the hard-deprecated
+ * `gemini`) keeps the historical settings.json default so old configs still
+ * parse.
  */
 export declare function getUserMcpConfigPath(agentId: AgentId): string;
 /**
@@ -497,6 +551,20 @@ export declare const AGENT_NAME_ALIASES: Record<string, 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;
+/**
+ * Split a CLI-provided `<agent>[@<version>]` spec into its bare agent id and
+ * optional exact version token, the same way `agents run` does
+ * (commands/exec.ts parses its positional with a plain `split('@')`) — NOT the
+ * agent-spec qualifier engine (`@latest`/`@all`), which enumerates installed
+ * versions for read/diagnostic commands, not a single launch target. Returns an
+ * error message rather than throwing so callers decide exit-vs-continue.
+ */
+export declare function parseAgentVersionSpec(raw: string): {
+    agent: AgentId;
+    version?: string;
+} | {
+    error: string;
+};
 /**
  * Build the deprecation notice lines for an agent, or null if it isn't
  * deprecated. Split from the printer so tests can assert the content without