macro-agent 0.0.11 → 0.0.12

package/src/agent-detection/__tests__/registry.test.ts

@@ -0,0 +1,254 @@
+/**
+ * Agent Registry Tests
+ */
+
+import { describe, it, expect } from "vitest";
+
+import {
+  AgentRegistry,
+  createAgentRegistry,
+  BUILTIN_AGENTS,
+} from "../registry.js";
+import type { CLIAgentDefinition } from "../types.js";
+
+describe("AgentRegistry", () => {
+  // ===========================================================================
+  // Built-in Agents
+  // ===========================================================================
+
+  describe("BUILTIN_AGENTS", () => {
+    it("contains all 6 known agents", () => {
+      expect(BUILTIN_AGENTS).toHaveLength(6);
+    });
+
+    it("includes claude-code", () => {
+      const agent = BUILTIN_AGENTS.find((a) => a.id === "claude-code");
+      expect(agent).toBeDefined();
+      expect(agent!.binary).toBe("claude");
+      expect(agent!.vendor).toBe("Anthropic");
+    });
+
+    it("includes codex", () => {
+      const agent = BUILTIN_AGENTS.find((a) => a.id === "codex");
+      expect(agent).toBeDefined();
+      expect(agent!.binary).toBe("codex");
+      expect(agent!.vendor).toBe("OpenAI");
+    });
+
+    it("includes gemini-cli", () => {
+      const agent = BUILTIN_AGENTS.find((a) => a.id === "gemini-cli");
+      expect(agent).toBeDefined();
+      expect(agent!.binary).toBe("gemini");
+      expect(agent!.vendor).toBe("Google");
+    });
+
+    it("includes opencode", () => {
+      const agent = BUILTIN_AGENTS.find((a) => a.id === "opencode");
+      expect(agent).toBeDefined();
+      expect(agent!.binary).toBe("opencode");
+      expect(agent!.vendor).toBe("Anomaly");
+    });
+
+    it("includes aider", () => {
+      const agent = BUILTIN_AGENTS.find((a) => a.id === "aider");
+      expect(agent).toBeDefined();
+      expect(agent!.binary).toBe("aider");
+      expect(agent!.vendor).toBe("Aider");
+    });
+
+    it("includes goose", () => {
+      const agent = BUILTIN_AGENTS.find((a) => a.id === "goose");
+      expect(agent).toBeDefined();
+      expect(agent!.binary).toBe("goose");
+      expect(agent!.vendor).toBe("Block");
+    });
+
+    it("all agents have required fields", () => {
+      for (const agent of BUILTIN_AGENTS) {
+        expect(agent.id).toBeTruthy();
+        expect(agent.name).toBeTruthy();
+        expect(agent.description).toBeTruthy();
+        expect(agent.binary).toBeTruthy();
+        expect(agent.versionArgs).toBeDefined();
+        expect(agent.versionArgs.length).toBeGreaterThan(0);
+        expect(agent.headless).toBeDefined();
+        expect(agent.headless.promptFlag).toBeDefined();
+        expect(agent.vendor).toBeTruthy();
+      }
+    });
+  });
+
+  // ===========================================================================
+  // Registry Operations
+  // ===========================================================================
+
+  describe("constructor", () => {
+    it("creates registry with built-in agents", () => {
+      const registry = new AgentRegistry();
+      expect(registry.size).toBe(6);
+    });
+
+    it("creates registry with additional custom agents", () => {
+      const custom: CLIAgentDefinition = {
+        id: "custom-agent",
+        name: "Custom Agent",
+        description: "A custom agent",
+        binary: "custom",
+        versionArgs: ["--version"],
+        headless: { promptFlag: "--prompt" },
+        vendor: "Custom",
+      };
+      const registry = new AgentRegistry([custom]);
+      expect(registry.size).toBe(7);
+      expect(registry.get("custom-agent")).toEqual(custom);
+    });
+
+    it("custom agents can override built-in agents", () => {
+      const override: CLIAgentDefinition = {
+        id: "claude-code",
+        name: "Custom Claude",
+        description: "Overridden",
+        binary: "custom-claude",
+        versionArgs: ["--version"],
+        headless: { promptFlag: "-p" },
+        vendor: "Custom",
+      };
+      const registry = new AgentRegistry([override]);
+      expect(registry.get("claude-code")!.binary).toBe("custom-claude");
+    });
+  });
+
+  describe("get()", () => {
+    it("returns agent definition by ID", () => {
+      const registry = new AgentRegistry();
+      const agent = registry.get("claude-code");
+      expect(agent).toBeDefined();
+      expect(agent!.id).toBe("claude-code");
+    });
+
+    it("returns undefined for unknown ID", () => {
+      const registry = new AgentRegistry();
+      expect(registry.get("nonexistent")).toBeUndefined();
+    });
+  });
+
+  describe("has()", () => {
+    it("returns true for existing agent", () => {
+      const registry = new AgentRegistry();
+      expect(registry.has("claude-code")).toBe(true);
+    });
+
+    it("returns false for unknown agent", () => {
+      const registry = new AgentRegistry();
+      expect(registry.has("nonexistent")).toBe(false);
+    });
+  });
+
+  describe("register()", () => {
+    it("adds a new agent definition", () => {
+      const registry = new AgentRegistry();
+      const custom: CLIAgentDefinition = {
+        id: "new-agent",
+        name: "New Agent",
+        description: "Newly added",
+        binary: "new",
+        versionArgs: ["--version"],
+        headless: { promptFlag: "--prompt" },
+        vendor: "New",
+      };
+      registry.register(custom);
+      expect(registry.has("new-agent")).toBe(true);
+      expect(registry.get("new-agent")).toEqual(custom);
+    });
+
+    it("overrides existing agent definition", () => {
+      const registry = new AgentRegistry();
+      const override: CLIAgentDefinition = {
+        id: "claude-code",
+        name: "Custom Claude",
+        description: "Overridden",
+        binary: "custom",
+        versionArgs: ["--version"],
+        headless: { promptFlag: "-p" },
+        vendor: "Custom",
+      };
+      registry.register(override);
+      expect(registry.get("claude-code")!.name).toBe("Custom Claude");
+    });
+  });
+
+  describe("remove()", () => {
+    it("removes an existing agent definition", () => {
+      const registry = new AgentRegistry();
+      expect(registry.remove("claude-code")).toBe(true);
+      expect(registry.has("claude-code")).toBe(false);
+      expect(registry.size).toBe(5);
+    });
+
+    it("returns false for non-existent agent", () => {
+      const registry = new AgentRegistry();
+      expect(registry.remove("nonexistent")).toBe(false);
+    });
+  });
+
+  describe("list()", () => {
+    it("returns all registered agents", () => {
+      const registry = new AgentRegistry();
+      const agents = registry.list();
+      expect(agents).toHaveLength(6);
+      const ids = agents.map((a) => a.id);
+      expect(ids).toContain("claude-code");
+      expect(ids).toContain("codex");
+      expect(ids).toContain("gemini-cli");
+      expect(ids).toContain("opencode");
+      expect(ids).toContain("aider");
+      expect(ids).toContain("goose");
+    });
+  });
+
+  describe("listEnabled()", () => {
+    it("returns all agents when no disabled list", () => {
+      const registry = new AgentRegistry();
+      expect(registry.listEnabled()).toHaveLength(6);
+    });
+
+    it("returns all agents when disabled list is empty", () => {
+      const registry = new AgentRegistry();
+      expect(registry.listEnabled([])).toHaveLength(6);
+    });
+
+    it("excludes disabled agents", () => {
+      const registry = new AgentRegistry();
+      const enabled = registry.listEnabled(["goose", "aider"]);
+      expect(enabled).toHaveLength(4);
+      const ids = enabled.map((a) => a.id);
+      expect(ids).not.toContain("goose");
+      expect(ids).not.toContain("aider");
+    });
+  });
+
+  // ===========================================================================
+  // Factory
+  // ===========================================================================
+
+  describe("createAgentRegistry()", () => {
+    it("creates registry with defaults", () => {
+      const registry = createAgentRegistry();
+      expect(registry.size).toBe(6);
+    });
+
+    it("creates registry with additional agents", () => {
+      const custom: CLIAgentDefinition = {
+        id: "extra",
+        name: "Extra",
+        description: "Extra agent",
+        binary: "extra",
+        versionArgs: ["--version"],
+        headless: { promptFlag: "--prompt" },
+        vendor: "Extra",
+      };
+      const registry = createAgentRegistry([custom]);
+      expect(registry.size).toBe(7);
+    });
+  });
+});

package/src/agent-detection/command-builder.ts

@@ -0,0 +1,90 @@
+/**
+ * Command Builder
+ *
+ * Constructs headless invocation commands for CLI coding agents
+ * based on their definitions.
+ */
+
+import type {
+  CLIAgentDefinition,
+  SpawnCommand,
+  SpawnCommandOptions,
+} from "./types.js";
+import { AgentDetectionError } from "./types.js";
+
+/**
+ * Build a headless spawn command for a CLI agent.
+ *
+ * Constructs the command and arguments array based on the agent definition's
+ * headless configuration, model flag, and working directory flag.
+ *
+ * @param definition - The CLI agent definition
+ * @param task - The prompt/task to pass to the agent
+ * @param options - Optional model and cwd overrides
+ * @returns The command and args array ready for child_process.spawn()
+ *
+ * @example
+ * ```ts
+ * const cmd = buildSpawnCommand(claudeCode, "Fix the auth bug", { model: "claude-sonnet-4-5" });
+ * // { command: "claude", args: ["-p", "Fix the auth bug", "--output-format", "stream-json", "--model", "claude-sonnet-4-5"] }
+ * ```
+ */
+export function buildSpawnCommand(
+  definition: CLIAgentDefinition,
+  task: string,
+  options?: SpawnCommandOptions
+): SpawnCommand {
+  if (!task) {
+    throw new AgentDetectionError(
+      "Task prompt is required",
+      "DETECTION_FAILED"
+    );
+  }
+
+  const args: string[] = [];
+
+  // 1. Subcommand (e.g., "exec", "run")
+  if (definition.headless.subcommand) {
+    args.push(definition.headless.subcommand);
+  }
+
+  // 2. Default flags (e.g., "--full-auto", "--yes")
+  if (definition.headless.defaultFlags) {
+    args.push(...definition.headless.defaultFlags);
+  }
+
+  // 3. Model flag
+  if (options?.model && definition.modelFlag) {
+    args.push(definition.modelFlag, options.model);
+  }
+
+  // 4. Working directory flag
+  if (options?.cwd && definition.cwdFlag) {
+    args.push(definition.cwdFlag, options.cwd);
+  }
+
+  // 5. Prompt (flag-based or positional)
+  if (definition.headless.promptFlag) {
+    args.push(definition.headless.promptFlag, task);
+  } else {
+    args.push(task);
+  }
+
+  return { command: definition.binary, args };
+}
+
+/**
+ * Format a spawn command as a single shell string (for display/logging).
+ */
+export function formatSpawnCommand(spawnCommand: SpawnCommand): string {
+  const parts = [spawnCommand.command];
+  for (const arg of spawnCommand.args) {
+    // Quote arguments that contain spaces
+    if (arg.includes(" ")) {
+      parts.push(`"${arg}"`);
+    } else {
+      parts.push(arg);
+    }
+  }
+  return parts.join(" ");
+}

package/src/agent-detection/detector.ts

@@ -0,0 +1,307 @@
+/**
+ * CLI Agent Detector
+ *
+ * Detects installed CLI coding agents by checking PATH availability
+ * and querying version information. Results are cached with configurable TTL.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+import type {
+  CLIAgentDefinition,
+  DetectedAgent,
+  DetectionResult,
+  AgentDetectionConfig,
+} from "./types.js";
+import { AgentDetectionError } from "./types.js";
+import { AgentRegistry, createAgentRegistry } from "./registry.js";
+
+const execFileAsync = promisify(execFile);
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const DEFAULT_CACHE_TTL_MS = 60_000;
+const DEFAULT_WHICH_TIMEOUT_MS = 5_000;
+const DEFAULT_VERSION_TIMEOUT_MS = 10_000;
+
+/** Regex to parse version strings like "1.2.3", "0.82.1-beta", etc. */
+const VERSION_REGEX = /\d+\.\d+[\.\d]*/;
+
+// =============================================================================
+// Agent Detector
+// =============================================================================
+
+/**
+ * Detects installed CLI coding agents on the system.
+ *
+ * Runs binary lookups and version checks in parallel, caches results,
+ * and provides query methods for available agents.
+ */
+export class AgentDetector {
+  private readonly registry: AgentRegistry;
+  private readonly cacheTtlMs: number;
+  private readonly whichTimeoutMs: number;
+  private readonly versionTimeoutMs: number;
+  private readonly disabledAgents: Set<string>;
+
+  private cachedResult: DetectionResult | null = null;
+  private detectionInProgress: Promise<DetectionResult> | null = null;
+
+  constructor(config?: AgentDetectionConfig) {
+    this.cacheTtlMs = config?.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+    this.whichTimeoutMs = config?.whichTimeoutMs ?? DEFAULT_WHICH_TIMEOUT_MS;
+    this.versionTimeoutMs =
+      config?.versionTimeoutMs ?? DEFAULT_VERSION_TIMEOUT_MS;
+    this.disabledAgents = new Set(config?.disabledAgents ?? []);
+
+    this.registry = createAgentRegistry(config?.additionalAgents);
+  }
+
+  /**
+   * Get the underlying agent registry.
+   */
+  getRegistry(): AgentRegistry {
+    return this.registry;
+  }
+
+  /**
+   * Detect all installed agents.
+   *
+   * Returns cached results if available and not expired.
+   * If a detection is already in progress, returns its promise.
+   */
+  async detect(options?: { refresh?: boolean }): Promise<DetectionResult> {
+    // Return cached result if valid
+    if (!options?.refresh && this.cachedResult && !this.isCacheExpired()) {
+      return this.cachedResult;
+    }
+
+    // If detection is already running, return the in-progress promise
+    if (this.detectionInProgress) {
+      return this.detectionInProgress;
+    }
+
+    // Start a new detection scan
+    this.detectionInProgress = this.runDetection();
+
+    try {
+      const result = await this.detectionInProgress;
+      this.cachedResult = result;
+      return result;
+    } finally {
+      this.detectionInProgress = null;
+    }
+  }
+
+  /**
+   * Get available agents (installed only by default).
+   */
+  async getAvailableAgents(options?: {
+    refresh?: boolean;
+    includeNotInstalled?: boolean;
+  }): Promise<DetectionResult> {
+    const result = await this.detect({ refresh: options?.refresh });
+
+    if (options?.includeNotInstalled) {
+      return result;
+    }
+
+    return {
+      ...result,
+      agents: result.agents.filter((a) => a.installed),
+    };
+  }
+
+  /**
+   * Get a specific detected agent by ID.
+   */
+  async getAgent(id: string): Promise<DetectedAgent | undefined> {
+    const result = await this.detect();
+    return result.agents.find((a) => a.id === id);
+  }
+
+  /**
+   * Check if a specific agent is installed.
+   */
+  async isInstalled(id: string): Promise<boolean> {
+    const agent = await this.getAgent(id);
+    return agent?.installed ?? false;
+  }
+
+  /**
+   * Get the definition for an agent, throwing if not found.
+   */
+  getDefinition(id: string): CLIAgentDefinition {
+    const def = this.registry.get(id);
+    if (!def) {
+      throw new AgentDetectionError(
+        `Unknown agent backend: ${id}`,
+        "UNKNOWN_AGENT",
+        id
+      );
+    }
+    return def;
+  }
+
+  /**
+   * Invalidate the detection cache.
+   */
+  invalidateCache(): void {
+    this.cachedResult = null;
+  }
+
+  /**
+   * Get partial results if detection is in progress, or cached results.
+   * Returns null if no results are available yet.
+   */
+  getCachedResult(): DetectionResult | null {
+    return this.cachedResult;
+  }
+
+  /**
+   * Whether a detection scan is currently running.
+   */
+  isDetecting(): boolean {
+    return this.detectionInProgress !== null;
+  }
+
+  // ===========================================================================
+  // Private
+  // ===========================================================================
+
+  private isCacheExpired(): boolean {
+    if (!this.cachedResult) return true;
+    const maxAge = Math.max(...this.cachedResult.agents.map((a) => a.detectedAt));
+    return Date.now() - maxAge > this.cacheTtlMs;
+  }
+
+  private async runDetection(): Promise<DetectionResult> {
+    const definitions = this.registry.listEnabled(
+      Array.from(this.disabledAgents)
+    );
+    const startTime = Date.now();
+
+    const results = await Promise.allSettled(
+      definitions.map((def) => this.detectAgent(def))
+    );
+
+    const agents: DetectedAgent[] = results.map((result, i) => {
+      if (result.status === "fulfilled") {
+        return result.value;
+      }
+      // On failure, return a not-installed entry
+      return {
+        id: definitions[i].id,
+        name: definitions[i].name,
+        installed: false,
+        definition: definitions[i],
+        detectedAt: Date.now(),
+      };
+    });
+
+    return {
+      agents,
+      scanned: definitions.length,
+      durationMs: Date.now() - startTime,
+    };
+  }
+
+  private async detectAgent(
+    definition: CLIAgentDefinition
+  ): Promise<DetectedAgent> {
+    const detectedAt = Date.now();
+
+    // Step 1: Check if binary exists on PATH
+    const binaryPath = await this.findBinary(definition.binary);
+
+    if (!binaryPath) {
+      return {
+        id: definition.id,
+        name: definition.name,
+        installed: false,
+        definition,
+        detectedAt,
+      };
+    }
+
+    // Step 2: Get version string
+    const version = await this.getVersion(definition);
+
+    return {
+      id: definition.id,
+      name: definition.name,
+      installed: true,
+      version: version ?? undefined,
+      path: binaryPath,
+      definition,
+      detectedAt,
+    };
+  }
+
+  private async findBinary(binary: string): Promise<string | null> {
+    try {
+      const { stdout } = await execFileAsync("which", [binary], {
+        timeout: this.whichTimeoutMs,
+      });
+      const path = stdout.trim();
+      return path || null;
+    } catch {
+      // Binary not found or which failed
+      try {
+        // Fallback to command -v
+        const { stdout } = await execFileAsync(
+          "/bin/sh",
+          ["-c", `command -v ${binary}`],
+          { timeout: this.whichTimeoutMs }
+        );
+        const path = stdout.trim();
+        return path || null;
+      } catch {
+        return null;
+      }
+    }
+  }
+
+  private async getVersion(
+    definition: CLIAgentDefinition
+  ): Promise<string | null> {
+    try {
+      const { stdout, stderr } = await execFileAsync(
+        definition.binary,
+        definition.versionArgs,
+        { timeout: this.versionTimeoutMs }
+      );
+
+      // Some tools output version to stderr
+      const output = stdout || stderr;
+      return parseVersion(output);
+    } catch {
+      return null;
+    }
+  }
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/**
+ * Parse a version string from command output.
+ * Extracts the first semver-like pattern (e.g., "1.2.3").
+ */
+export function parseVersion(output: string): string | null {
+  const match = output.match(VERSION_REGEX);
+  return match ? match[0] : null;
+}
+
+/**
+ * Create a new AgentDetector with the given configuration.
+ */
+export function createAgentDetector(
+  config?: AgentDetectionConfig
+): AgentDetector {
+  return new AgentDetector(config);
+}

package/src/agent-detection/index.ts

@@ -0,0 +1,36 @@
+/**
+ * CLI Agent Auto-Detection Module
+ *
+ * Detects installed CLI coding agents, exposes them via a registry,
+ * and provides command construction for headless invocation.
+ */
+
+// Types
+export type {
+  CLIAgentDefinition,
+  HeadlessConfig,
+  DetectedAgent,
+  DetectionResult,
+  SpawnCommand,
+  SpawnCommandOptions,
+  AgentDetectionConfig,
+  AgentDetectionErrorCode,
+} from "./types.js";
+export { AgentDetectionError } from "./types.js";
+
+// Registry
+export {
+  AgentRegistry,
+  createAgentRegistry,
+  BUILTIN_AGENTS,
+} from "./registry.js";
+
+// Detector
+export {
+  AgentDetector,
+  createAgentDetector,
+  parseVersion,
+} from "./detector.js";
+
+// Command builder
+export { buildSpawnCommand, formatSpawnCommand } from "./command-builder.js";