macro-agent 0.1.1 → 0.1.2

package/src/api/server.ts

@@ -57,6 +57,7 @@ import {
 } from "../steering/index.js";
 import type { AgentId } from "../store/types/index.js";
 import { secureCompare } from "../auth/token.js";
+import type { TeamManager } from "../teams/team-manager.js";
 
 // ─────────────────────────────────────────────────────────────────
 // Server Configuration
@@ -88,6 +89,8 @@ export interface APIServices {
   mailService?: import("../mail/mail-service.js").MailService;
   /** Optional conversation map for agent-to-conversation tracking */
   conversationMap?: import("../mail/conversation-map.js").ConversationMap;
+  /** Optional team manager for dynamic team management */
+  teamManager?: TeamManager;
 }
 
 // ─────────────────────────────────────────────────────────────────
@@ -347,6 +350,113 @@ function registerConversationRoutes(
   });
 }
 
+// ─────────────────────────────────────────────────────────────────
+// Shared Team Routes Helper
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Register team management REST endpoints on an Express app.
+ * Shared between standalone and shared API modes.
+ *
+ * Endpoints:
+ *   POST   /api/teams      — Start a team instance
+ *   GET    /api/teams      — List running team instances
+ *   GET    /api/teams/:id  — Get team instance details
+ *   DELETE /api/teams/:id  — Teardown a team instance
+ */
+function registerTeamRoutes(
+  app: Express,
+  teamManager: TeamManager | undefined,
+  defaultCwd: string,
+  sendError: (res: Response, status: number, code: string, message: string) => void,
+  broadcast?: (channel: string, message: WSMessage) => void,
+): void {
+  if (!teamManager) return;
+
+  // POST /api/teams — Start a team instance
+  app.post("/api/teams", async (req: Request, res: Response) => {
+    const { template, overrides } = req.body ?? {};
+    if (!template || typeof template !== "string") {
+      return sendError(res, 400, "INVALID_REQUEST", "Missing required field: template");
+    }
+
+    try {
+      const instance = await teamManager.startTeam(template, defaultCwd, overrides);
+      const result = {
+        id: instance.id,
+        templateName: instance.templateName,
+        rootAgentId: instance.result.rootId,
+        companionAgentIds: instance.result.companionIds,
+        taskMode: instance.runtime.getTaskMode(),
+        strategy: instance.runtime.getStrategyName(),
+      };
+
+      if (broadcast) {
+        broadcast("teams", { type: "team_started", data: result });
+      }
+
+      res.status(201).json(result);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return sendError(res, 500, "TEAM_START_FAILED", message);
+    }
+  });
+
+  // GET /api/teams — List running team instances
+  app.get("/api/teams", (_req: Request, res: Response) => {
+    const instances = teamManager.getInstances();
+    res.json(instances.map((inst) => ({
+      id: inst.id,
+      templateName: inst.templateName,
+      rootAgentId: inst.result.rootId,
+      companionAgentIds: inst.result.companionIds,
+      taskMode: inst.runtime.getTaskMode(),
+      strategy: inst.runtime.getStrategyName(),
+    })));
+  });
+
+  // GET /api/teams/:id — Get team instance details
+  app.get("/api/teams/:id", (req: Request, res: Response) => {
+    const instance = teamManager.getInstance(req.params.id);
+    if (!instance) {
+      return sendError(res, 404, "TEAM_NOT_FOUND", `No team instance '${req.params.id}'`);
+    }
+
+    const manifest = instance.runtime.getManifest();
+    res.json({
+      id: instance.id,
+      templateName: instance.templateName,
+      rootAgentId: instance.result.rootId,
+      companionAgentIds: instance.result.companionIds,
+      taskMode: instance.runtime.getTaskMode(),
+      strategy: instance.runtime.getStrategyName(),
+      roles: manifest.roles,
+      communication: manifest.communication,
+    });
+  });
+
+  // DELETE /api/teams/:id — Teardown a team instance
+  app.delete("/api/teams/:id", async (req: Request, res: Response) => {
+    const instance = teamManager.getInstance(req.params.id);
+    if (!instance) {
+      return sendError(res, 404, "TEAM_NOT_FOUND", `No team instance '${req.params.id}'`);
+    }
+
+    try {
+      await teamManager.stopTeam(req.params.id);
+
+      if (broadcast) {
+        broadcast("teams", { type: "team_stopped", data: { id: req.params.id } });
+      }
+
+      res.json({ success: true });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return sendError(res, 500, "TEAM_STOP_FAILED", message);
+    }
+  });
+}
+
 // ─────────────────────────────────────────────────────────────────
 // Create API Server
 // ─────────────────────────────────────────────────────────────────
@@ -568,8 +678,11 @@ export function createAPIServer(
     res.json(status);
   });
 
-  // GET /api/team - Get active team info
+  // GET /api/team - Get active team info (DEPRECATED: use GET /api/teams)
   app.get("/api/team", (_req: Request, res: Response) => {
+    res.set("Deprecation", "true");
+    res.set("Link", '</api/teams>; rel="successor-version"');
+
     // Check for team config in EventStore
     const statusEvents = eventStore.query({ type: "status", limit: 50 });
     const teamConfigEvent = statusEvents.find(
@@ -591,6 +704,9 @@ export function createAPIServer(
     });
   });
 
+  // Register dynamic team management routes
+  registerTeamRoutes(app, services.teamManager, process.cwd(), sendError, broadcastToChannel);
+
   // ─────────────────────────────────────────────────────────────────
   // Metrics Endpoints (Phase 5)
   // ─────────────────────────────────────────────────────────────────
@@ -1175,7 +1291,7 @@ export function createAPIServer(
     const gracePeriod = options?.force ? 0 : shutdownGracePeriodMs;
 
     // 1. Stop accepting new connections
-    server.close();
+    await new Promise<void>((resolve) => server.close(() => resolve()));
 
     // 2. Wait grace period for in-flight work
     if (gracePeriod > 0) {
@@ -1259,10 +1375,10 @@ export function createAPIServer(
  * @returns Express app
  */
 export function createAPIApp(
-  services: Pick<APIServices, "eventStore" | "agentManager" | "taskManager" | "messageRouter"> & Pick<Partial<APIServices>, "mailService" | "conversationMap">,
-  config: { cors?: boolean; serverToken?: string } = {}
+  services: Pick<APIServices, "eventStore" | "agentManager" | "taskManager" | "messageRouter"> & Pick<Partial<APIServices>, "mailService" | "conversationMap" | "teamManager">,
+  config: { cors?: boolean; serverToken?: string; defaultCwd?: string } = {}
 ): Express {
-  const { cors = true, serverToken } = config;
+  const { cors = true, serverToken, defaultCwd } = config;
   const { agentManager, taskManager, messageRouter } = services;
 
   // Create shared state
@@ -1823,6 +1939,15 @@ export function createAPIApp(
   // Register conversation API routes (if mail service available)
   registerConversationRoutes(app, services, sendError);
 
+  // Register dynamic team management routes
+  registerTeamRoutes(
+    app,
+    services.teamManager,
+    defaultCwd ?? process.cwd(),
+    sendError,
+    state.broadcast,
+  );
+
   return app;
 }
 

package/src/api/types.ts

@@ -184,7 +184,9 @@ export type WSMessageType =
   | "status"
   | "error"
   | "conversation_update"
-  | "turn_added";
+  | "turn_added"
+  | "team_started"
+  | "team_stopped";
 
 export interface WSMessage {
   type: WSMessageType;

package/src/cli/acp.ts

@@ -48,6 +48,7 @@ import { createAgentManager } from "../agent/agent-manager.js";
 import { createTaskManager } from "../task/task-manager.js";
 import { createMessageRouter } from "../router/message-router.js";
 import { MacroAgent } from "../acp/macro-agent.js";
+import { TeamManager } from "../teams/team-manager.js";
 import {
   createCombinedServer,
   type CombinedServer,
@@ -237,6 +238,24 @@ async function main() {
     agentTokenManager = new AgentTokenManager();
   }
 
+  // Create WorkspaceManager for workspace isolation (optional — requires git repo)
+  let workspaceManager: import("../workspace/types.js").WorkspaceManager | undefined;
+  try {
+    const { createWorkspaceManager } = await import("../workspace/workspace-manager.js");
+    const poolSize = parseInt(process.env.MACRO_WORKSPACE_POOL_SIZE ?? "10", 10);
+    workspaceManager = createWorkspaceManager({
+      enabled: true,
+      repoPath: defaultCwd,
+      pool: {
+        enabled: poolSize > 0,
+        maxSize: poolSize,
+      },
+    });
+    console.error(`[acp] WorkspaceManager created (pool: ${poolSize})`);
+  } catch (err) {
+    console.error(`[acp] WorkspaceManager not available: ${err instanceof Error ? err.message : err}`);
+  }
+
   // Now create the agentManager with the real router
   agentManager = createAgentManager(eventStore, messageRouter, {
     serverUrl,
@@ -244,6 +263,7 @@ async function main() {
     agentTokenManager: serverUrl ? agentTokenManager : undefined,
     taskBackend: mergedConfig.task?.backend,
     openTasksSocketPath: mergedConfig.task?.opentasks?.socket_path,
+    workspaceManager,
   });
   const taskManager = createTaskManager(eventStore);
 
@@ -304,6 +324,49 @@ async function main() {
     }
   }
 
+  // Create TeamManager for dynamic team loading (server mode only)
+  const teamManager = new TeamManager({ agentManager, messageRouter, eventStore, workspaceManager, taskBackend });
+  teamManager.install(); // Composite interceptor/filter/validator
+
+  // Seed default team templates if they don't exist yet
+  try {
+    const { seedDefaultTemplates } = await import("../teams/seed-defaults.js");
+    const seeded = await seedDefaultTemplates(defaultCwd);
+    if (seeded.length > 0) {
+      console.error(`[acp] Seeded default team templates: ${seeded.join(", ")}`);
+    }
+  } catch (err) {
+    console.error(`[acp] Failed to seed default templates: ${err}`);
+  }
+
+  // Auto-start teams from config
+  if (!options.acp) {
+    // Default team (backward compat)
+    if (mergedConfig.team) {
+      try {
+        const instance = await teamManager.startTeam(mergedConfig.team, defaultCwd);
+        console.error(`[acp] Team '${mergedConfig.team}' started (${instance.id}): root=${instance.result.rootId}, companions=[${instance.result.companionIds.join(", ")}]`);
+      } catch (err) {
+        console.error(`[acp] Failed to start team '${mergedConfig.team}': ${err}`);
+      }
+    }
+
+    // Additional teams with autoStart (skip if already started as default team)
+    if (mergedConfig.teams) {
+      for (const [name, entry] of Object.entries(mergedConfig.teams)) {
+        if (!entry.autoStart) continue;
+        const template = entry.template ?? name;
+        if (template === mergedConfig.team) continue; // Already started above
+        try {
+          const instance = await teamManager.startTeam(template, defaultCwd);
+          console.error(`[acp] Team '${template}' started (${instance.id}): root=${instance.result.rootId}, companions=[${instance.result.companionIds.join(", ")}]`);
+        } catch (err) {
+          console.error(`[acp] Failed to start team '${template}': ${err}`);
+        }
+      }
+    }
+  }
+
   // Create ActivityWatcher for event-driven agent waking
   const sessionProvider = createSessionProviderFromAgentManager(agentManager);
   const wakeHandler = createWakeHandler(sessionProvider, agentManager);
@@ -401,6 +464,10 @@ async function main() {
       }
     }
 
+    try { await teamManager.teardownAll(); } catch (err) {
+      console.error(`[cleanup] TeamManager teardown failed: ${err}`);
+    }
+
     try { await agentManager.close(); } catch (err) {
       console.error(`[cleanup] AgentManager close failed: ${err}`);
     }
@@ -456,7 +523,7 @@ async function main() {
       const port = options.port ?? mergedConfig.port ?? 3001;
 
       combinedServer = createCombinedServer(
-        { eventStore, agentManager, taskManager, messageRouter, activityWatcher, taskBackend, taskToolProvider, taskToolContext, agentTokenManager, getConnectedProjects },
+        { eventStore, agentManager, taskManager, messageRouter, activityWatcher, taskBackend, taskToolProvider, taskToolContext, agentTokenManager, getConnectedProjects, teamManager, workspaceManager },
         { port, host, defaultCwd, serverToken, noAuth }
       );
 

package/src/cli/index.ts

@@ -170,6 +170,9 @@ program
       }
 
       // Determine team name: CLI flag > merged config
+      if (options.team) {
+        console.warn(chalk.yellow("[DEPRECATED] --team flag on multiagent-cli start is deprecated. Use 'multiagent' with .multiagent/config.json instead."));
+      }
       const teamName = options.team ?? mergedConfig.team;
 
       // Load and initialize team if specified
@@ -715,7 +718,8 @@ program
       const path = await import("path");
       const os = await import("os");
 
-      const storagePath = path.join(os.homedir(), ".multiagent", "store.json");
+      const baseDir = process.env.MACRO_AGENT_HOME || path.join(os.homedir(), ".multiagent");
+      const storagePath = path.join(baseDir, "store.json");
 
       if (fs.existsSync(storagePath)) {
         fs.unlinkSync(storagePath);

package/src/cli/mcp.ts

@@ -253,12 +253,18 @@ async function startLegacy() {
     }
   });
 
-  // Read team config from EventStore
+  // Read team config from EventStore (scoped by MACRO_TEAM_NAME for multi-team)
   let teamTaskMode: string | undefined;
+  const myTeamName = process.env.MACRO_TEAM_NAME;
   const teamEvents = eventStore.query({ type: "status", limit: 50 });
-  const teamConfigEvent = teamEvents.find(
-    (e) => e.payload?.team_config != null
-  );
+  const teamConfigEvent = teamEvents.find((e) => {
+    const tc = e.payload?.team_config as Record<string, unknown> | undefined;
+    if (!tc) return false;
+    // If agent has a team name, find that specific team's config
+    if (myTeamName) return tc.teamName === myTeamName;
+    // Fallback: first team_config found (backward compat)
+    return true;
+  });
   if (teamConfigEvent?.payload?.team_config) {
     const tc = teamConfigEvent.payload.team_config as Record<string, unknown>;
     teamTaskMode = tc.taskMode as string | undefined;
@@ -282,15 +288,23 @@ async function startLegacy() {
 
     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}`);
+      // Queue strategy requires merge queue which is only available in the main process.
+      // Skip it so the worker handler falls through to MERGE_REQUEST signal emission,
+      // which the main server's TeamRuntime polls for and submits to the real merge queue.
+      if (strategyName === "queue") {
+        debugLog(`[MCP] Skipping queue strategy in subprocess (no merge queue available). ` +
+          `Worker done() will emit MERGE_REQUEST signal for main process to handle.`);
+      } else {
+        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}`);
+        }
       }
     }
   }

package/src/config/project-config.ts

@@ -17,6 +17,16 @@ import * as path from "path";
 // Types
 // =============================================================================
 
+/**
+ * Entry in the `teams` config for declaring additional team templates.
+ */
+export interface TeamConfigEntry {
+  /** Template name (defaults to the key) */
+  template?: string;
+  /** Auto-start on server boot (default: false) */
+  autoStart?: boolean;
+}
+
 /**
  * Typed configuration schema for multiagent.
  *
@@ -24,9 +34,12 @@ import * as path from "path";
  * Environment variables override file-based config.
  */
 export interface MultiagentConfig {
-  /** Team template name to load on startup */
+  /** Default team template name to load on startup */
   team?: string;
 
+  /** Additional teams available for dynamic or auto-start loading */
+  teams?: Record<string, TeamConfigEntry>;
+
   /** Server port (default: 3001) */
   port?: number;
 
@@ -134,10 +147,11 @@ export function getProjectConfigPath(projectPath?: string): string {
 /**
  * Get the global config file path.
  *
- * @returns Absolute path to ~/.multiagent/config.json
+ * @returns Absolute path to ~/.multiagent/config.json (or MACRO_AGENT_HOME/config.json)
  */
 export function getGlobalConfigPath(): string {
-  return path.join(os.homedir(), CONFIG_DIR, CONFIG_FILE);
+  const globalDir = process.env.MACRO_AGENT_HOME || path.join(os.homedir(), CONFIG_DIR);
+  return path.join(globalDir, CONFIG_FILE);
 }
 
 // =============================================================================
@@ -249,6 +263,16 @@ export function loadMergedConfig(projectPath?: string): MultiagentConfig {
     merged.auth = { ...(merged.auth ?? {}), disabled: true };
   }
 
+  // MACRO_TEAMS: comma-separated template names to auto-start
+  if (process.env.MACRO_TEAMS) {
+    const names = process.env.MACRO_TEAMS.split(",").map(s => s.trim()).filter(Boolean);
+    const teams: Record<string, TeamConfigEntry> = { ...(merged.teams ?? {}) };
+    for (const name of names) {
+      teams[name] = { ...teams[name], autoStart: true };
+    }
+    merged.teams = teams;
+  }
+
   return merged;
 }
 

package/src/index.ts

@@ -292,3 +292,6 @@ export {
   type WakeSessionProvider,
   type WakeAgentOptions,
 } from './agent/wake.js';
+
+// Teams - template seeding
+export { seedDefaultTemplates } from './teams/seed-defaults.js';

package/src/lifecycle/__tests__/handlers.test.ts

@@ -1752,6 +1752,37 @@ describe("handlers", () => {
 
       expect(handler).toBeDefined();
     });
+
+    it("should return worker handler for team role with workspace.worktree capability", () => {
+      const deps = createMockDeps();
+      const registry = createHandlerRegistry(deps as any);
+
+      // "developer" extends "worker" — gets workspace.worktree capability
+      const handler = getHandler("developer", registry, deps as any, ["workspace.worktree"]);
+
+      // Should be the worker handler, not generic
+      expect(handler).toBe(registry.get("worker"));
+    });
+
+    it("should return integrator handler for team role with workspace.integrate capability", () => {
+      const deps = createMockDeps();
+      const registry = createHandlerRegistry(deps as any);
+
+      const handler = getHandler("merger", registry, deps as any, ["workspace.integrate"]);
+
+      expect(handler).toBe(registry.get("integrator"));
+    });
+
+    it("should return generic handler when capabilities have no workspace match", () => {
+      const deps = createMockDeps();
+      const registry = createHandlerRegistry(deps as any);
+
+      const handler = getHandler("watcher", registry, deps as any, ["msg.send", "file.read"]);
+
+      // No workspace capability → falls through to generic
+      expect(handler).not.toBe(registry.get("worker"));
+      expect(handler).not.toBe(registry.get("integrator"));
+    });
   });
 
   describe("dispatchDone", () => {
@@ -1795,6 +1826,28 @@ describe("handlers", () => {
       expect(result.signalsEmitted).toContain("STATUS");
     });
 
+    it("should dispatch team role with workspace.worktree to worker handler", async () => {
+      const deps = createMockDeps();
+      const context: LifecycleContext = {
+        agentId: "developer-1",
+        role: "developer",
+        capabilities: ["workspace.worktree", "lifecycle.done", "file.read"],
+      };
+      const args: DoneArgs = { status: "completed" };
+      const cleanupStatus: CleanupStatus = { ready: true };
+
+      const result = await dispatchDone(
+        context,
+        args,
+        cleanupStatus,
+        deps as any,
+      );
+
+      // Should have gone through the worker handler path
+      expect(result.shouldTerminate).toBe(true);
+      expect(result.signalsEmitted).toContain("WORKER_DONE");
+    });
+
     it("should use custom registry when provided", async () => {
       const deps = createMockDeps();
       const customHandler = vi.fn().mockResolvedValue({

package/src/lifecycle/handlers/index.ts

@@ -111,29 +111,46 @@ export function createHandlerRegistry(
 }
 
 /**
- * Get the handler for a given role
+ * Get the handler for a given role.
  *
- * Falls back to the generic handler if no role-specific handler exists.
+ * Resolution order:
+ * 1. Exact role name match (e.g., "worker", "integrator")
+ * 2. Dot-prefix match (e.g., "worker.resolver" → "worker")
+ * 3. Capability-based match (e.g., "developer" with workspace.worktree → worker handler)
+ * 4. Generic fallback handler
  */
 export function getHandler(
   role: string,
   registry: DoneHandlerRegistry,
-  deps: AllHandlerDeps
+  deps: AllHandlerDeps,
+  capabilities?: string[],
 ): DoneHandler {
-  // Check for exact match
+  // 1. Exact match
   const handler = registry.get(role);
   if (handler) {
     return handler;
   }
 
-  // Check for role prefix match (e.g., "worker.resolver" matches "worker")
+  // 2. Dot-prefix match (e.g., "worker.resolver" → "worker")
   const baseRole = role.split(".")[0];
   const baseHandler = registry.get(baseRole);
   if (baseHandler) {
     return baseHandler;
   }
 
-  // Fall back to generic handler
+  // 3. Capability-based match (for team-defined roles like "developer" extending "worker")
+  if (capabilities) {
+    if (capabilities.includes("workspace.worktree")) {
+      const workerHandler = registry.get("worker");
+      if (workerHandler) return workerHandler;
+    }
+    if (capabilities.includes("workspace.integrate")) {
+      const integratorHandler = registry.get("integrator");
+      if (integratorHandler) return integratorHandler;
+    }
+  }
+
+  // 4. Generic fallback
   const genericDeps: GenericHandlerDeps = {
     messageRouter: deps.messageRouter,
   };
@@ -158,8 +175,8 @@ export async function dispatchDone(
   // Use provided registry or create default
   const handlers = registry ?? createHandlerRegistry(deps);
 
-  // Get the handler for this role
-  const handler = getHandler(context.role, handlers, deps);
+  // Get the handler for this role (pass capabilities for team role resolution)
+  const handler = getHandler(context.role, handlers, deps, context.capabilities);
 
   // Execute the handler
   return handler(context, args, cleanupStatus);

package/src/lifecycle/types.ts

@@ -117,6 +117,9 @@ export interface LifecycleContext {
 
   /** Merge request ID (for resolver workers to track which MR they're resolving) */
   mrId?: string;
+
+  /** Resolved capabilities for the agent's role (for capability-based handler dispatch) */
+  capabilities?: string[];
 }
 
 /**