macro-agent 0.1.0 → 0.1.2

package/src/config/project-config.ts

@@ -1,12 +1,16 @@
 /**
- * Project Configuration Loader
+ * Configuration Loader
  *
- * Reads .macro-agent/config.json for project-level settings.
+ * Layered configuration system with priority (highest to lowest):
+ * 1. Environment variables (MACRO_*, OPENTASKS_*)
+ * 2. Project config: .multiagent/config.json
+ * 3. Global config: ~/.multiagent/config.json
  *
  * @module config/project-config
  */
 
 import * as fs from "fs";
+import * as os from "os";
 import * as path from "path";
 
 // =============================================================================
@@ -14,9 +18,62 @@ import * as path from "path";
 // =============================================================================
 
 /**
- * Project-level configuration schema.
+ * 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.
  *
- * Loaded from .macro-agent/config.json in the project root.
+ * Loaded from .multiagent/config.json (project or global).
+ * Environment variables override file-based config.
+ */
+export interface MultiagentConfig {
+  /** 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;
+
+  /** Server host (default: "localhost") */
+  host?: string;
+
+  /** Authentication config */
+  auth?: {
+    /** Disable auth entirely */
+    disabled?: boolean;
+    /** Server secret token */
+    secret?: string;
+  };
+
+  /** Task backend config */
+  task?: {
+    /** Backend type: "memory" | "opentasks" */
+    backend?: string;
+    /** OpenTasks-specific config */
+    opentasks?: {
+      /** Path to OpenTasks daemon socket */
+      socket_path?: string;
+      /** Auto-start central daemon (default: true) */
+      auto_start?: boolean;
+      /** Central daemon location (default: ~/.multiagent/opentasks) */
+      central_path?: string;
+      /** Auto-connect project .opentasks/ on agent spawn (default: true) */
+      connect_on_spawn?: boolean;
+    };
+  };
+}
+
+/**
+ * Legacy project config interface (backwards compatibility).
  */
 export interface ProjectConfig {
   /** Team template name to load on startup */
@@ -31,38 +88,21 @@ export interface ProjectConfig {
 // =============================================================================
 
 /** Config directory name */
-export const CONFIG_DIR = ".macro-agent";
+export const CONFIG_DIR = ".multiagent";
 
 /** Config file name */
 export const CONFIG_FILE = "config.json";
 
 // =============================================================================
-// Loader
+// JSON Loader (shared)
 // =============================================================================
 
 /**
- * Get the project config file path.
- *
- * @param projectPath - Project root directory (default: process.cwd())
- * @returns Absolute path to .macro-agent/config.json
- */
-export function getProjectConfigPath(projectPath?: string): string {
-  const root = projectPath ?? process.cwd();
-  return path.join(root, CONFIG_DIR, CONFIG_FILE);
-}
-
-/**
- * Load project configuration from .macro-agent/config.json.
- *
- * Returns empty config if the file doesn't exist.
+ * Load and parse a JSON config file.
+ * Returns empty object if file doesn't exist.
  * Throws on invalid JSON.
- *
- * @param projectPath - Project root directory (default: process.cwd())
- * @returns Parsed ProjectConfig
  */
-export function loadProjectConfig(projectPath?: string): ProjectConfig {
-  const configPath = getProjectConfigPath(projectPath);
-
+function loadJsonConfig(configPath: string): Record<string, unknown> {
   if (!fs.existsSync(configPath)) {
     return {};
   }
@@ -78,7 +118,7 @@ export function loadProjectConfig(projectPath?: string): ProjectConfig {
         configPath
       );
     }
-    return parsed as ProjectConfig;
+    return parsed as Record<string, unknown>;
   } catch (error) {
     if (error instanceof ProjectConfigError) throw error;
     throw new ProjectConfigError(
@@ -89,6 +129,153 @@ export function loadProjectConfig(projectPath?: string): ProjectConfig {
   }
 }
 
+// =============================================================================
+// Path Resolution
+// =============================================================================
+
+/**
+ * Get the project config file path.
+ *
+ * @param projectPath - Project root directory (default: process.cwd())
+ * @returns Absolute path to .multiagent/config.json
+ */
+export function getProjectConfigPath(projectPath?: string): string {
+  const root = projectPath ?? process.cwd();
+  return path.join(root, CONFIG_DIR, CONFIG_FILE);
+}
+
+/**
+ * Get the global config file path.
+ *
+ * @returns Absolute path to ~/.multiagent/config.json (or MACRO_AGENT_HOME/config.json)
+ */
+export function getGlobalConfigPath(): string {
+  const globalDir = process.env.MACRO_AGENT_HOME || path.join(os.homedir(), CONFIG_DIR);
+  return path.join(globalDir, CONFIG_FILE);
+}
+
+// =============================================================================
+// Individual Loaders
+// =============================================================================
+
+/**
+ * Load project configuration from .multiagent/config.json.
+ *
+ * Returns empty config if the file doesn't exist.
+ * Throws on invalid JSON.
+ *
+ * @param projectPath - Project root directory (default: process.cwd())
+ * @returns Parsed ProjectConfig
+ */
+export function loadProjectConfig(projectPath?: string): ProjectConfig {
+  return loadJsonConfig(getProjectConfigPath(projectPath)) as ProjectConfig;
+}
+
+/**
+ * Load global configuration from ~/.multiagent/config.json.
+ *
+ * Returns empty config if the file doesn't exist.
+ * Throws on invalid JSON.
+ *
+ * @returns Parsed config
+ */
+export function loadGlobalConfig(): MultiagentConfig {
+  return loadJsonConfig(getGlobalConfigPath()) as MultiagentConfig;
+}
+
+// =============================================================================
+// Merged Config (layered)
+// =============================================================================
+
+/**
+ * Deep merge two objects. Source values override target values.
+ * Only merges plain objects recursively; arrays and primitives are replaced.
+ */
+function deepMerge<T extends Record<string, unknown>>(target: T, source: Record<string, unknown>): T {
+  const result = { ...target };
+
+  for (const key of Object.keys(source)) {
+    const sourceVal = source[key];
+    const targetVal = (result as Record<string, unknown>)[key];
+
+    if (
+      sourceVal !== undefined &&
+      sourceVal !== null &&
+      typeof sourceVal === "object" &&
+      !Array.isArray(sourceVal) &&
+      typeof targetVal === "object" &&
+      targetVal !== null &&
+      !Array.isArray(targetVal)
+    ) {
+      (result as Record<string, unknown>)[key] = deepMerge(
+        targetVal as Record<string, unknown>,
+        sourceVal as Record<string, unknown>
+      );
+    } else if (sourceVal !== undefined) {
+      (result as Record<string, unknown>)[key] = sourceVal;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Load merged configuration with layered priority:
+ * 1. Environment variables (highest)
+ * 2. Project .multiagent/config.json
+ * 3. Global ~/.multiagent/config.json (lowest)
+ *
+ * Only server-level settings are merged. Agent-level env vars
+ * (MACRO_AGENT_ID, MACRO_SERVER_URL, etc.) are internal wiring
+ * and not part of this config.
+ *
+ * @param projectPath - Project root directory (default: process.cwd())
+ * @returns Fully merged MultiagentConfig
+ */
+export function loadMergedConfig(projectPath?: string): MultiagentConfig {
+  const globalConfig = loadGlobalConfig();
+  const projectConfig = loadProjectConfig(projectPath);
+
+  // Layer 1: global (lowest priority)
+  // Layer 2: project overrides global
+  const merged: MultiagentConfig = deepMerge(
+    globalConfig as Record<string, unknown>,
+    projectConfig as Record<string, unknown>,
+  ) as MultiagentConfig;
+
+  // Layer 3: env vars override everything (server-level only)
+  if (process.env.MACRO_TASK_BACKEND) {
+    merged.task = { ...(merged.task ?? {}), backend: process.env.MACRO_TASK_BACKEND };
+  }
+  if (process.env.OPENTASKS_SOCKET_PATH) {
+    merged.task = {
+      ...(merged.task ?? {}),
+      opentasks: {
+        ...(merged.task?.opentasks ?? {}),
+        socket_path: process.env.OPENTASKS_SOCKET_PATH,
+      },
+    };
+  }
+  if (process.env.MACRO_SERVER_SECRET) {
+    merged.auth = { ...(merged.auth ?? {}), secret: process.env.MACRO_SERVER_SECRET };
+  }
+  if (process.env.MACRO_NO_AUTH === "true") {
+    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;
+}
+
 // =============================================================================
 // Errors
 // =============================================================================

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__/cascade-termination.test.ts

@@ -74,7 +74,7 @@ function createCascadeAdapter(harness: TestHarness): CascadeAgentManager {
       }
       // Update agent state in EventStore
       harness.eventStore.emit({
-        type: "terminate",
+        type: "stop",
         source: { agent_id: agentId },
         payload: { agent_id: agentId, reason },
       });

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[];
 }
 
 /**

package/src/map/adapter/__tests__/acp-over-map-cancel.test.ts

@@ -742,8 +742,26 @@ describe("MAPAdapter handleStopAgent (map/agents/stop)", () => {
     ).rejects.toThrow("Failed to stop agent: Agent not found");
   });
 
-  it("should emit agent.state.changed event via emitEvent", async () => {
-    await setupAdapter();
+  it("should emit agent.state.changed event via lifecycle listener", async () => {
+    // Capture lifecycle callback so we can fire it from the mock terminate
+    let lifecycleCallback: ((event: unknown) => void) | undefined;
+
+    await setupAdapter({
+      onLifecycleEvent: vi.fn().mockImplementation((cb: (event: unknown) => void) => {
+        lifecycleCallback = cb;
+        return () => {};
+      }),
+      terminate: vi.fn().mockImplementation(async () => {
+        // Simulate what real agentManager.terminate() does: fire lifecycle
+        if (lifecycleCallback) {
+          lifecycleCallback({
+            type: "stopped",
+            agent: { id: "agent-1", name: "test-agent", role: "worker", state: "stopped" },
+            reason: "user stopped",
+          });
+        }
+      }),
+    } as unknown as Partial<AgentManager>);
 
     const impl = adapter as unknown as {
       handleStopAgent: (
@@ -761,10 +779,10 @@ describe("MAPAdapter handleStopAgent (map/agents/stop)", () => {
       { agentId: "agent-1" as AgentId, reason: "user stopped" },
     );
 
-    // Verify emitEvent was called with the right event shape
+    // Verify emitEvent was called with the right event shape via lifecycle
     expect(emitSpy).toHaveBeenCalledWith(
       expect.objectContaining({
-        type: "agent.state.changed",
+        type: "agent_state_changed",
         agentId: "agent-1",
         data: expect.objectContaining({
           agentId: "agent-1",