macro-agent 0.0.10 → 0.0.12

package/src/agent-detection/registry.ts

@@ -0,0 +1,200 @@
+/**
+ * CLI Agent Definitions Registry
+ *
+ * Maintains a registry of known CLI coding agents with their
+ * detection and headless invocation configurations.
+ */
+
+import type { CLIAgentDefinition } from "./types.js";
+
+// =============================================================================
+// Built-in Agent Definitions
+// =============================================================================
+
+const CLAUDE_CODE: CLIAgentDefinition = {
+  id: "claude-code",
+  name: "Claude Code",
+  description: "Anthropic's CLI coding agent",
+  binary: "claude",
+  versionArgs: ["--version"],
+  headless: {
+    promptFlag: "-p",
+    defaultFlags: ["--output-format", "stream-json"],
+  },
+  modelFlag: "--model",
+  cwdFlag: "--cwd",
+  vendor: "Anthropic",
+};
+
+const CODEX: CLIAgentDefinition = {
+  id: "codex",
+  name: "Codex",
+  description: "OpenAI's CLI coding agent",
+  binary: "codex",
+  versionArgs: ["--version"],
+  headless: {
+    subcommand: "exec",
+    promptFlag: "",
+    defaultFlags: ["--full-auto"],
+  },
+  modelFlag: "--model",
+  cwdFlag: "--path",
+  vendor: "OpenAI",
+};
+
+const GEMINI_CLI: CLIAgentDefinition = {
+  id: "gemini-cli",
+  name: "Gemini CLI",
+  description: "Google's CLI coding agent",
+  binary: "gemini",
+  versionArgs: ["--version"],
+  headless: {
+    promptFlag: "-p",
+  },
+  modelFlag: "--model",
+  vendor: "Google",
+};
+
+const OPENCODE: CLIAgentDefinition = {
+  id: "opencode",
+  name: "OpenCode",
+  description: "Anomaly's CLI coding agent",
+  binary: "opencode",
+  versionArgs: ["--version"],
+  headless: {
+    subcommand: "run",
+    promptFlag: "",
+  },
+  modelFlag: "--model",
+  vendor: "Anomaly",
+};
+
+const AIDER: CLIAgentDefinition = {
+  id: "aider",
+  name: "Aider",
+  description: "AI pair programming in your terminal",
+  binary: "aider",
+  versionArgs: ["--version"],
+  headless: {
+    promptFlag: "--message",
+    defaultFlags: ["--yes"],
+  },
+  modelFlag: "--model",
+  vendor: "Aider",
+};
+
+const GOOSE: CLIAgentDefinition = {
+  id: "goose",
+  name: "Goose",
+  description: "Block's CLI coding agent",
+  binary: "goose",
+  versionArgs: ["--version"],
+  headless: {
+    subcommand: "run",
+    promptFlag: "-t",
+    defaultFlags: ["--no-session"],
+  },
+  modelFlag: "--model",
+  vendor: "Block",
+};
+
+/**
+ * All built-in agent definitions.
+ */
+export const BUILTIN_AGENTS: readonly CLIAgentDefinition[] = [
+  CLAUDE_CODE,
+  CODEX,
+  GEMINI_CLI,
+  OPENCODE,
+  AIDER,
+  GOOSE,
+];
+
+// =============================================================================
+// Agent Registry
+// =============================================================================
+
+/**
+ * Registry of known CLI coding agent definitions.
+ *
+ * Provides lookup by ID and supports adding custom agent definitions.
+ */
+export class AgentRegistry {
+  private readonly agents: Map<string, CLIAgentDefinition> = new Map();
+
+  constructor(definitions?: CLIAgentDefinition[]) {
+    // Register built-in agents
+    for (const def of BUILTIN_AGENTS) {
+      this.agents.set(def.id, def);
+    }
+
+    // Register additional definitions
+    if (definitions) {
+      for (const def of definitions) {
+        this.agents.set(def.id, def);
+      }
+    }
+  }
+
+  /**
+   * Get an agent definition by ID.
+   */
+  get(id: string): CLIAgentDefinition | undefined {
+    return this.agents.get(id);
+  }
+
+  /**
+   * Check if an agent definition exists.
+   */
+  has(id: string): boolean {
+    return this.agents.has(id);
+  }
+
+  /**
+   * Register a new agent definition (or override an existing one).
+   */
+  register(definition: CLIAgentDefinition): void {
+    this.agents.set(definition.id, definition);
+  }
+
+  /**
+   * Remove an agent definition by ID.
+   */
+  remove(id: string): boolean {
+    return this.agents.delete(id);
+  }
+
+  /**
+   * List all registered agent definitions.
+   */
+  list(): CLIAgentDefinition[] {
+    return Array.from(this.agents.values());
+  }
+
+  /**
+   * List agent definitions, optionally excluding disabled agents.
+   */
+  listEnabled(disabledIds?: string[]): CLIAgentDefinition[] {
+    if (!disabledIds || disabledIds.length === 0) {
+      return this.list();
+    }
+    const disabled = new Set(disabledIds);
+    return this.list().filter((def) => !disabled.has(def.id));
+  }
+
+  /**
+   * Get the number of registered agent definitions.
+   */
+  get size(): number {
+    return this.agents.size;
+  }
+}
+
+/**
+ * Create a new AgentRegistry with built-in agents and optional custom definitions.
+ */
+export function createAgentRegistry(
+  additionalAgents?: CLIAgentDefinition[]
+): AgentRegistry {
+  return new AgentRegistry(additionalAgents);
+}

package/src/agent-detection/types.ts

@@ -0,0 +1,184 @@
+/**
+ * CLI Agent Auto-Detection Types
+ *
+ * Type definitions for detecting installed CLI coding agents
+ * and constructing headless invocation commands.
+ */
+
+// =============================================================================
+// Agent Definition
+// =============================================================================
+
+/**
+ * Headless invocation configuration for a CLI agent.
+ */
+export interface HeadlessConfig {
+  /** Subcommand before prompt (e.g., "exec" for codex, "run" for goose) */
+  subcommand?: string;
+
+  /** Flag to pass the prompt. Empty string means prompt is positional. */
+  promptFlag: string;
+
+  /** Default flags always included in headless mode */
+  defaultFlags?: string[];
+}
+
+/**
+ * Definition of a known CLI coding agent.
+ * Describes how to detect and invoke the agent in headless mode.
+ */
+export interface CLIAgentDefinition {
+  /** Unique identifier (e.g., "claude-code", "codex") */
+  id: string;
+
+  /** Human-readable display name */
+  name: string;
+
+  /** Short description */
+  description: string;
+
+  /** The binary/command name to invoke */
+  binary: string;
+
+  /** Arguments to check version (typically ["--version"]) */
+  versionArgs: string[];
+
+  /** Headless invocation configuration */
+  headless: HeadlessConfig;
+
+  /** Flag for model selection (e.g., "--model") */
+  modelFlag?: string;
+
+  /** Flag for working directory (e.g., "--cwd", "--path") */
+  cwdFlag?: string;
+
+  /** Provider/vendor name */
+  vendor: string;
+}
+
+// =============================================================================
+// Detection Results
+// =============================================================================
+
+/**
+ * Result of detecting a single CLI agent on the system.
+ */
+export interface DetectedAgent {
+  /** Agent definition ID */
+  id: string;
+
+  /** Human-readable name */
+  name: string;
+
+  /** Whether the binary was found on PATH */
+  installed: boolean;
+
+  /** Parsed version string (e.g., "1.2.3") */
+  version?: string;
+
+  /** Absolute path to binary */
+  path?: string;
+
+  /** The full agent definition (for client display) */
+  definition: CLIAgentDefinition;
+
+  /** When detection was performed (epoch ms) */
+  detectedAt: number;
+}
+
+/**
+ * Result of a full detection scan across all known agents.
+ */
+export interface DetectionResult {
+  /** All agents (installed and not installed) */
+  agents: DetectedAgent[];
+
+  /** Number of agents scanned */
+  scanned: number;
+
+  /** Detection duration in milliseconds */
+  durationMs: number;
+
+  /** Whether detection is still in progress */
+  pending?: boolean;
+}
+
+// =============================================================================
+// Command Builder
+// =============================================================================
+
+/**
+ * Options for building a spawn command.
+ */
+export interface SpawnCommandOptions {
+  /** Model to use (passed via modelFlag) */
+  model?: string;
+
+  /** Working directory (passed via cwdFlag) */
+  cwd?: string;
+}
+
+/**
+ * Result of building a spawn command.
+ */
+export interface SpawnCommand {
+  /** The binary/command to execute */
+  command: string;
+
+  /** Arguments to pass to the command */
+  args: string[];
+}
+
+// =============================================================================
+// Detection Configuration
+// =============================================================================
+
+/**
+ * Configuration for the agent detection system.
+ */
+export interface AgentDetectionConfig {
+  /** Whether agent detection is enabled (default: true) */
+  enabled?: boolean;
+
+  /** Cache TTL in milliseconds (default: 60000) */
+  cacheTtlMs?: number;
+
+  /** Timeout for `which` calls in milliseconds (default: 5000) */
+  whichTimeoutMs?: number;
+
+  /** Timeout for version checks in milliseconds (default: 10000) */
+  versionTimeoutMs?: number;
+
+  /** Additional custom agent definitions to include */
+  additionalAgents?: CLIAgentDefinition[];
+
+  /** Agent IDs to exclude from detection */
+  disabledAgents?: string[];
+}
+
+// =============================================================================
+// Errors
+// =============================================================================
+
+/**
+ * Error codes for agent detection operations.
+ */
+export type AgentDetectionErrorCode =
+  | "UNKNOWN_AGENT"
+  | "AGENT_NOT_INSTALLED"
+  | "DETECTION_FAILED"
+  | "DETECTION_TIMEOUT";
+
+/**
+ * Error thrown by agent detection operations.
+ */
+export class AgentDetectionError extends Error {
+  constructor(
+    message: string,
+    public readonly code: AgentDetectionErrorCode,
+    public readonly agentId?: string
+  ) {
+    super(message);
+    this.name = "AgentDetectionError";
+  }
+}