macro-agent 0.0.11 → 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";
+  }
+}

package/src/api/server.ts

@@ -549,6 +549,116 @@ export function createAPIServer(
     res.json(status);
   });
 
+  // GET /api/team - Get active team info
+  app.get("/api/team", (_req: Request, res: Response) => {
+    // Check for team config in EventStore
+    const statusEvents = eventStore.query({ type: "status", limit: 50 });
+    const teamConfigEvent = statusEvents.find(
+      (e) => e.payload?.team_config != null
+    );
+
+    if (!teamConfigEvent?.payload?.team_config) {
+      res.json({ active: false });
+      return;
+    }
+
+    const tc = teamConfigEvent.payload.team_config as Record<string, unknown>;
+    res.json({
+      active: true,
+      name: tc.teamName,
+      strategy: tc.strategy,
+      taskMode: tc.taskMode,
+      enforcement: tc.enforcement,
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────
+  // Metrics Endpoints (Phase 5)
+  // ─────────────────────────────────────────────────────────────────
+
+  // GET /api/metrics/throughput - Task throughput metrics
+  app.get("/api/metrics/throughput", (req: Request, res: Response) => {
+    const windowMs = req.query.window_ms
+      ? Number(req.query.window_ms)
+      : 5 * 60 * 1000;
+    const after = Date.now() - windowMs;
+
+    const taskEvents = eventStore.query({ type: "task", after });
+    let completed = 0, failed = 0, created = 0;
+    for (const e of taskEvents) {
+      const action = e.payload?.action as string | undefined;
+      if (action === "created") created++;
+      else if (action === "completed") completed++;
+      else if (action === "failed") failed++;
+    }
+    const windowMin = windowMs / 60000;
+
+    res.json({
+      tasksCompleted: completed,
+      tasksFailed: failed,
+      tasksCreated: created,
+      completedPerMinute: windowMin > 0 ? Math.round((completed / windowMin) * 100) / 100 : 0,
+      windowMs,
+    });
+  });
+
+  // GET /api/metrics/utilization - Agent utilization metrics
+  app.get("/api/metrics/utilization", (_req: Request, res: Response) => {
+    const allAgents = eventStore.listAgents();
+    const active = allAgents.filter(
+      (a) => a.state === "running" || a.state === "spawning"
+    );
+    const byRole: Record<string, number> = {};
+    const byState: Record<string, number> = {};
+    for (const a of active) {
+      const role = a.role ?? "unknown";
+      byRole[role] = (byRole[role] ?? 0) + 1;
+    }
+    for (const a of allAgents) {
+      byState[a.state] = (byState[a.state] ?? 0) + 1;
+    }
+
+    res.json({
+      activeAgents: active.length,
+      totalAgents: allAgents.length,
+      agentsByRole: byRole,
+      agentsByState: byState,
+    });
+  });
+
+  // GET /api/metrics/errors - Error metrics
+  app.get("/api/metrics/errors", (req: Request, res: Response) => {
+    const windowMs = req.query.window_ms
+      ? Number(req.query.window_ms)
+      : 30 * 60 * 1000;
+    const limit = req.query.limit ? Number(req.query.limit) : 20;
+
+    const statusEvents = eventStore.query({
+      type: "status",
+      after: Date.now() - windowMs,
+    });
+
+    const errors: Array<{ timestamp: number; agentId: string; type: string; summary: string }> = [];
+    const byType: Record<string, number> = {};
+
+    for (const e of statusEvents) {
+      if (e.payload?.status_type !== "failed") continue;
+      const agentId = (e.source as { agent_id?: string })?.agent_id ?? "unknown";
+      const summary = (e.payload?.summary as string) ?? "Unknown error";
+      const errorType = ((e.payload?.details as Record<string, unknown>)?.signal as string) ?? "agent_failed";
+      errors.push({ timestamp: e.timestamp, agentId, type: errorType, summary });
+      byType[errorType] = (byType[errorType] ?? 0) + 1;
+    }
+
+    errors.sort((a, b) => b.timestamp - a.timestamp);
+
+    res.json({
+      totalErrors: errors.length,
+      errorsByType: byType,
+      recentErrors: errors.slice(0, limit),
+    });
+  });
+
   // POST /api/conversation/message - Send message to head manager
   app.post("/api/conversation/message", async (req: Request, res: Response) => {
     // Reject new messages during shutdown

package/src/cli/index.ts

@@ -16,6 +16,8 @@ import { createAgentManager } from "../agent/agent-manager.js";
 import { createTaskManager } from "../task/task-manager.js";
 import { createMessageRouter } from "../router/message-router.js";
 import { createAPIServer } from "../api/server.js";
+import { loadProjectConfig } from "../config/project-config.js";
+import { loadTeam, TeamRuntime } from "../teams/index.js";
 import type { Agent, Task } from "../store/types/index.js";
 
 // ─────────────────────────────────────────────────────────────────
@@ -120,6 +122,7 @@ program
   .option("-p, --port <port>", "Port to listen on", "3000")
   .option("-h, --host <host>", "Host to bind to", "localhost")
   .option("--cwd <path>", "Working directory for agents")
+  .option("--team <name>", "Load team template")
   .action(async (options) => {
     console.log(chalk.blue("Starting multi-agent server..."));
 
@@ -130,6 +133,32 @@ program
       const agentManager = createAgentManager(eventStore, messageRouter);
       const taskManager = createTaskManager(eventStore);
 
+      // Determine team name: CLI flag > project config > none
+      const projectConfig = loadProjectConfig(options.cwd);
+      const teamName = options.team ?? projectConfig.team;
+
+      // Load and initialize team if specified
+      let teamRuntime: TeamRuntime | null = null;
+      if (teamName) {
+        console.log(chalk.blue(`Loading team template '${teamName}'...`));
+        const manifest = await loadTeam(
+          teamName,
+          agentManager.getRoleRegistry(),
+          options.cwd
+        );
+        teamRuntime = new TeamRuntime(manifest, {
+          agentManager,
+          messageRouter,
+          eventStore,
+        });
+        await teamRuntime.initialize();
+        console.log(
+          chalk.green(
+            `Team '${teamName}' loaded: ${manifest.roles.join(", ")}`
+          )
+        );
+      }
+
       // Create API server
       const server = createAPIServer(
         { eventStore, agentManager, taskManager, messageRouter },
@@ -142,11 +171,26 @@ program
       console.log(
         chalk.green(`Server running at http://${options.host}:${options.port}`)
       );
+
+      // Bootstrap team agents after server is running
+      if (teamRuntime) {
+        const { rootId, companionIds } = await teamRuntime.bootstrap();
+        console.log(
+          chalk.green(
+            `Team '${teamName}' bootstrapped: root=${rootId}` +
+              (companionIds.length > 0
+                ? `, companions=${companionIds.join(", ")}`
+                : "")
+          )
+        );
+      }
+
       console.log(chalk.gray("Press Ctrl+C to stop"));
 
       // Handle shutdown
       process.on("SIGINT", async () => {
         console.log(chalk.yellow("\nShutting down..."));
+        if (teamRuntime) await teamRuntime.teardown();
         await server.stop();
         await agentManager.close();
         await eventStore.close();

package/src/cli/mcp.ts

@@ -176,6 +176,50 @@ async function main() {
       }
     });
 
+    // Read team config from EventStore (stored by TeamRuntime.initialize)
+    let teamTaskMode: string | undefined;
+    const teamEvents = eventStore.query({ type: "status", limit: 50 });
+    const teamConfigEvent = teamEvents.find(
+      (e) => e.payload?.team_config != null
+    );
+    if (teamConfigEvent?.payload?.team_config) {
+      const tc = teamConfigEvent.payload.team_config as Record<string, unknown>;
+      teamTaskMode = tc.taskMode as string | undefined;
+      debugLog(`[MCP] Found team config: team=${tc.teamName}, strategy=${tc.strategy}, taskMode=${tc.taskMode}`);
+    }
+
+    // Register team roles in local RoleRegistry for capability checks
+    const roleRegistry = agentManager.getRoleRegistry();
+    let integrationStrategy: import("../workspace/strategies/types.js").IntegrationStrategy | undefined;
+
+    if (teamConfigEvent?.payload?.team_config) {
+      const tc = teamConfigEvent.payload.team_config as Record<string, unknown>;
+
+      // Register serialized team roles (stored by TeamRuntime.initialize)
+      const roles = tc.roles as Record<string, { name: string; capabilities: string[] }> | undefined;
+      if (roles) {
+        for (const roleDef of Object.values(roles)) {
+          roleRegistry.registerRole(roleDef as import("../roles/types.js").RoleDefinition);
+        }
+        debugLog(`[MCP] Registered ${Object.keys(roles).length} team roles in RoleRegistry`);
+      }
+
+      // Instantiate integration strategy from team config
+      const strategyName = tc.strategy as string | undefined;
+      if (strategyName) {
+        try {
+          const { defaultStrategyRegistry } = await import("../workspace/strategies/registry.js");
+          integrationStrategy = defaultStrategyRegistry.get(
+            strategyName,
+            tc.strategyConfig as Record<string, unknown> | undefined
+          );
+          debugLog(`[MCP] Instantiated '${strategyName}' integration strategy`);
+        } catch (err) {
+          debugLog(`[MCP] Failed to instantiate strategy '${strategyName}': ${err}`);
+        }
+      }
+    }
+
     // Create MCP server with agent context
     const mcpServer = createMCPServer(
       {
@@ -191,6 +235,9 @@ async function main() {
         taskManager,
         messageRouter,
         activityWatcher,
+        taskMode: teamTaskMode as "push" | "pull" | undefined,
+        roleRegistry,
+        integrationStrategy,
       }
     );
 

package/src/config/index.ts

@@ -0,0 +1,9 @@
+export {
+  loadProjectConfig,
+  getProjectConfigPath,
+  ProjectConfigError,
+  type ProjectConfig,
+  type ProjectConfigErrorCode,
+  CONFIG_DIR,
+  CONFIG_FILE,
+} from "./project-config.js";