macro-agent 0.1.0 → 0.1.1

package/src/agent/types.ts

@@ -380,4 +380,6 @@ export type AgentManagerErrorCode =
   | "NOT_RUNNING"
   | "INVALID_STATE"
   | "PERMISSION_DENIED"
-  | "CAPABILITY_DENIED";
+  | "CAPABILITY_DENIED"
+  | "SHUTDOWN_IN_PROGRESS"
+  | "FORK_NOT_SUPPORTED";

package/src/api/server.ts

@@ -56,6 +56,7 @@ import {
   type InjectionDeps,
 } from "../steering/index.js";
 import type { AgentId } from "../store/types/index.js";
+import { secureCompare } from "../auth/token.js";
 
 // ─────────────────────────────────────────────────────────────────
 // Server Configuration
@@ -73,6 +74,9 @@ export interface APIServerConfig {
 
   /** Grace period in milliseconds for in-flight work during shutdown (default: 5000) */
   shutdownGracePeriodMs?: number;
+
+  /** Server token for Bearer auth on API routes. When set, all routes except /health require auth. */
+  serverToken?: string;
 }
 
 export interface APIServices {
@@ -351,7 +355,7 @@ export function createAPIServer(
   services: APIServices,
   config: APIServerConfig = {}
 ): APIServer {
-  const { port = 3000, host = "localhost", cors = true, shutdownGracePeriodMs = 5000 } = config;
+  const { port = 3000, host = "localhost", cors = true, shutdownGracePeriodMs = 5000, serverToken } = config;
   const { eventStore, agentManager, taskManager } = services;
 
   // Server state
@@ -374,12 +378,27 @@ export function createAPIServer(
   if (cors) {
     app.use((_req: Request, res: Response, next: NextFunction) => {
       res.header("Access-Control-Allow-Origin", "*");
-      res.header("Access-Control-Allow-Headers", "Content-Type");
+      res.header("Access-Control-Allow-Headers", "Content-Type, Authorization");
       res.header("Access-Control-Allow-Methods", "GET, POST, DELETE");
       next();
     });
   }
 
+  // Bearer token auth middleware (skip /health)
+  if (serverToken) {
+    app.use((req: Request, res: Response, next: NextFunction) => {
+      if (req.path === "/health") return next();
+      const authHeader = req.headers.authorization;
+      const token = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : undefined;
+      if (!token || !secureCompare(token, serverToken)) {
+        const error: APIError = { error: "Unauthorized", code: "AUTH_REQUIRED" };
+        res.status(401).json(error);
+        return;
+      }
+      next();
+    });
+  }
+
   // ─────────────────────────────────────────────────────────────────
   // Helper Functions
   // ─────────────────────────────────────────────────────────────────
@@ -438,7 +457,7 @@ export function createAPIServer(
       case "spawn":
         summary = `Agent ${event.payload.agent_id} spawned`;
         break;
-      case "terminate":
+      case "stop":
         summary = `Agent terminated: ${event.payload.reason}`;
         break;
       case "status":
@@ -1241,9 +1260,9 @@ export function createAPIServer(
  */
 export function createAPIApp(
   services: Pick<APIServices, "eventStore" | "agentManager" | "taskManager" | "messageRouter"> & Pick<Partial<APIServices>, "mailService" | "conversationMap">,
-  config: { cors?: boolean } = {}
+  config: { cors?: boolean; serverToken?: string } = {}
 ): Express {
-  const { cors = true } = config;
+  const { cors = true, serverToken } = config;
   const { agentManager, taskManager, messageRouter } = services;
 
   // Create shared state
@@ -1262,12 +1281,27 @@ export function createAPIApp(
   if (cors) {
     app.use((_req: Request, res: Response, next: NextFunction) => {
       res.header("Access-Control-Allow-Origin", "*");
-      res.header("Access-Control-Allow-Headers", "Content-Type");
+      res.header("Access-Control-Allow-Headers", "Content-Type, Authorization");
       res.header("Access-Control-Allow-Methods", "GET, POST, DELETE");
       next();
     });
   }
 
+  // Bearer token auth middleware (skip /health)
+  if (serverToken) {
+    app.use((req: Request, res: Response, next: NextFunction) => {
+      if (req.path === "/health") return next();
+      const authHeader = req.headers.authorization;
+      const token = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : undefined;
+      if (!token || !secureCompare(token, serverToken)) {
+        const error: APIError = { error: "Unauthorized", code: "AUTH_REQUIRED" };
+        res.status(401).json(error);
+        return;
+      }
+      next();
+    });
+  }
+
   // ─────────────────────────────────────────────────────────────────
   // Helper Functions
   // ─────────────────────────────────────────────────────────────────
@@ -1326,7 +1360,7 @@ export function createAPIApp(
       case "spawn":
         summary = `Agent ${event.payload.agent_id} spawned`;
         break;
-      case "terminate":
+      case "stop":
         summary = `Agent terminated: ${event.payload.reason}`;
         break;
       case "status":

package/src/auth/__tests__/token.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect } from "vitest";
+import { generateToken, secureCompare, AgentTokenManager } from "../token.js";
+
+describe("generateToken", () => {
+  it("generates a hex string of expected length", () => {
+    const token = generateToken();
+    // 32 bytes = 64 hex chars
+    expect(token).toHaveLength(64);
+    expect(token).toMatch(/^[0-9a-f]+$/);
+  });
+
+  it("generates different tokens each time", () => {
+    const a = generateToken();
+    const b = generateToken();
+    expect(a).not.toBe(b);
+  });
+
+  it("respects custom byte length", () => {
+    const token = generateToken(16);
+    expect(token).toHaveLength(32); // 16 bytes = 32 hex chars
+  });
+});
+
+describe("secureCompare", () => {
+  it("returns true for identical strings", () => {
+    expect(secureCompare("abc123", "abc123")).toBe(true);
+  });
+
+  it("returns false for different strings of same length", () => {
+    expect(secureCompare("abc123", "xyz789")).toBe(false);
+  });
+
+  it("returns false for different length strings", () => {
+    expect(secureCompare("short", "longer-string")).toBe(false);
+  });
+
+  it("returns true for empty strings", () => {
+    expect(secureCompare("", "")).toBe(true);
+  });
+});
+
+describe("AgentTokenManager", () => {
+  it("creates and verifies a token", () => {
+    const mgr = new AgentTokenManager();
+    const token = mgr.createToken("agent-1");
+    expect(token).toHaveLength(64);
+    expect(mgr.verifyToken("agent-1", token)).toBe(true);
+  });
+
+  it("rejects wrong token", () => {
+    const mgr = new AgentTokenManager();
+    mgr.createToken("agent-1");
+    expect(mgr.verifyToken("agent-1", "wrong-token")).toBe(false);
+  });
+
+  it("rejects unknown agent", () => {
+    const mgr = new AgentTokenManager();
+    expect(mgr.verifyToken("unknown", "any-token")).toBe(false);
+  });
+
+  it("revokes a token", () => {
+    const mgr = new AgentTokenManager();
+    const token = mgr.createToken("agent-1");
+    expect(mgr.revokeToken("agent-1")).toBe(true);
+    expect(mgr.verifyToken("agent-1", token)).toBe(false);
+    expect(mgr.hasToken("agent-1")).toBe(false);
+  });
+
+  it("revoke returns false for unknown agent", () => {
+    const mgr = new AgentTokenManager();
+    expect(mgr.revokeToken("unknown")).toBe(false);
+  });
+
+  it("hasToken returns correct state", () => {
+    const mgr = new AgentTokenManager();
+    expect(mgr.hasToken("agent-1")).toBe(false);
+    mgr.createToken("agent-1");
+    expect(mgr.hasToken("agent-1")).toBe(true);
+  });
+
+  it("createToken overwrites previous token", () => {
+    const mgr = new AgentTokenManager();
+    const token1 = mgr.createToken("agent-1");
+    const token2 = mgr.createToken("agent-1");
+    expect(token1).not.toBe(token2);
+    expect(mgr.verifyToken("agent-1", token1)).toBe(false);
+    expect(mgr.verifyToken("agent-1", token2)).toBe(true);
+  });
+
+  it("manages multiple agents independently", () => {
+    const mgr = new AgentTokenManager();
+    const t1 = mgr.createToken("agent-1");
+    const t2 = mgr.createToken("agent-2");
+    expect(mgr.verifyToken("agent-1", t1)).toBe(true);
+    expect(mgr.verifyToken("agent-2", t2)).toBe(true);
+    // Cross-validation fails
+    expect(mgr.verifyToken("agent-1", t2)).toBe(false);
+    expect(mgr.verifyToken("agent-2", t1)).toBe(false);
+  });
+});

package/src/auth/index.ts

@@ -0,0 +1 @@
+export { generateToken, secureCompare, AgentTokenManager } from "./token.js";

package/src/auth/token.ts

@@ -0,0 +1,82 @@
+/**
+ * Authentication Token Utilities
+ *
+ * Provides token generation, secure comparison, and per-agent
+ * token management for the macro-agent server.
+ */
+
+import * as crypto from "crypto";
+
+// =============================================================================
+// Token Generation
+// =============================================================================
+
+/**
+ * Generate a cryptographically random hex token.
+ */
+export function generateToken(bytes = 32): string {
+  return crypto.randomBytes(bytes).toString("hex");
+}
+
+// =============================================================================
+// Secure Comparison
+// =============================================================================
+
+/**
+ * Constant-time string comparison to prevent timing attacks.
+ */
+export function secureCompare(a: string, b: string): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+  const bufA = Buffer.from(a);
+  const bufB = Buffer.from(b);
+  return crypto.timingSafeEqual(bufA, bufB);
+}
+
+// =============================================================================
+// Agent Token Manager
+// =============================================================================
+
+/**
+ * Manages per-agent authentication tokens.
+ *
+ * Each spawned agent gets a unique token at spawn time. The token is
+ * passed to the subprocess via environment variable and validated on
+ * every MCP bridge RPC call.
+ */
+export class AgentTokenManager {
+  private tokens = new Map<string, string>();
+
+  /**
+   * Create and store a token for an agent. Returns the generated token.
+   */
+  createToken(agentId: string): string {
+    const token = generateToken();
+    this.tokens.set(agentId, token);
+    return token;
+  }
+
+  /**
+   * Verify that a token matches the one stored for an agent.
+   */
+  verifyToken(agentId: string, token: string): boolean {
+    const stored = this.tokens.get(agentId);
+    if (!stored) return false;
+    return secureCompare(stored, token);
+  }
+
+  /**
+   * Revoke an agent's token (e.g., on terminate).
+   */
+  revokeToken(agentId: string): boolean {
+    return this.tokens.delete(agentId);
+  }
+
+  /**
+   * Check if an agent has a registered token.
+   */
+  hasToken(agentId: string): boolean {
+    return this.tokens.has(agentId);
+  }
+}

package/src/cli/__tests__/acp.test.ts

@@ -6,7 +6,7 @@
  */
 
 import { describe, it, expect } from "vitest";
-import { parseArgs, type ACPServerOptions } from "../acp.js";
+import { parseArgs, type ACPServerOptions } from "../parse-args.js";
 
 // ─────────────────────────────────────────────────────────────────
 // parseArgs Tests

package/src/cli/__tests__/stable-instance-id.test.ts

@@ -7,7 +7,7 @@
 
 import { describe, it, expect } from "vitest";
 import { resolve } from "node:path";
-import { getStableInstanceId } from "../acp.js";
+import { getStableInstanceId } from "../stable-instance-id.js";
 
 describe("getStableInstanceId", () => {
   it("should return the same ID for the same path", () => {

package/src/cli/acp.ts

@@ -38,11 +38,7 @@
  *   });
  */
 
-import { readFileSync } from "node:fs";
-import { createHash } from "node:crypto";
-import { dirname, join, resolve } from "node:path";
 import { Readable } from "node:stream";
-import { fileURLToPath } from "node:url";
 import {
   AgentSideConnection,
   ndJsonStream,
@@ -73,63 +69,13 @@ import type { AgentId, EventId } from "../store/types/index.js";
 // Configuration
 // ─────────────────────────────────────────────────────────────────
 
-export interface ACPServerOptions {
-  /** Working directory for agents */
-  cwd?: string;
-  /** Stdio ACP-only mode (for embedded use with acp-factory) */
-  acp?: boolean;
-  /** Port for server (default: 3001) */
-  port?: number;
-  /** Host for server (default: localhost) */
-  host?: string;
-  /** Instance ID to reuse an existing event store (omit for new instance) */
-  instanceId?: string;
-}
-
-/**
- * Parse command line arguments.
- * @param argv Optional array of arguments (defaults to process.argv.slice(2))
- */
-export function parseArgs(argv?: string[]): ACPServerOptions {
-  const args = argv ?? process.argv.slice(2);
-  const options: ACPServerOptions = {};
-
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--version" || args[i] === "-v") {
-      const __dirname = dirname(fileURLToPath(import.meta.url));
-      const pkg = JSON.parse(readFileSync(join(__dirname, "../../package.json"), "utf-8"));
-      console.log(pkg.version);
-      process.exit(0);
-    } else if (args[i] === "--cwd" && args[i + 1]) {
-      options.cwd = args[i + 1];
-      i++;
-    } else if (args[i] === "--acp") {
-      options.acp = true;
-    } else if (args[i] === "--port" && args[i + 1]) {
-      options.port = parseInt(args[i + 1], 10);
-      i++;
-    } else if (args[i] === "--host" && args[i + 1]) {
-      options.host = args[i + 1];
-      i++;
-    } else if (args[i] === "--instance-id" && args[i + 1]) {
-      options.instanceId = args[i + 1];
-      i++;
-    }
-  }
-
-  return options;
-}
+import { parseArgs } from "./parse-args.js";
+import { getStableInstanceId } from "./stable-instance-id.js";
+import { loadMergedConfig } from "../config/project-config.js";
 
-/**
- * Generate a stable instance ID from the working directory.
- * This ensures the same project always uses the same EventStore,
- * so agents and sessions persist across server restarts.
- */
-export function getStableInstanceId(cwd: string): string {
-  const normalizedPath = resolve(cwd);
-  const hash = createHash("sha256").update(normalizedPath).digest("hex").slice(0, 12);
-  return `inst_${hash}`;
-}
+// Re-export utilities for backwards compatibility
+export { parseArgs, type ACPServerOptions } from "./parse-args.js";
+export { getStableInstanceId } from "./stable-instance-id.js";
 
 // ─────────────────────────────────────────────────────────────────
 // Stream Setup
@@ -272,10 +218,92 @@ async function main() {
     wakeHandler: routerWakeHandler,
   });
 
+  // Load merged config (global → project → env vars)
+  const mergedConfig = loadMergedConfig(defaultCwd);
+
+  // Compute server URL for thin-client MCP mode (only in server mode, not stdio ACP)
+  const serverUrl = options.acp
+    ? undefined
+    : `http://${options.host ?? mergedConfig.host ?? "localhost"}:${options.port ?? mergedConfig.port ?? 3001}`;
+
+  // Set up authentication tokens from merged config
+  const noAuth = options.noAuth || mergedConfig.auth?.disabled === true;
+  let serverToken: string | undefined;
+  let agentTokenManager: import("../auth/token.js").AgentTokenManager | undefined;
+
+  if (!noAuth && mergedConfig.auth?.secret) {
+    const { AgentTokenManager } = await import("../auth/token.js");
+    serverToken = mergedConfig.auth.secret;
+    agentTokenManager = new AgentTokenManager();
+  }
+
   // Now create the agentManager with the real router
-  agentManager = createAgentManager(eventStore, messageRouter);
+  agentManager = createAgentManager(eventStore, messageRouter, {
+    serverUrl,
+    serverToken: serverUrl ? serverToken : undefined,
+    agentTokenManager: serverUrl ? agentTokenManager : undefined,
+    taskBackend: mergedConfig.task?.backend,
+    openTasksSocketPath: mergedConfig.task?.opentasks?.socket_path,
+  });
   const taskManager = createTaskManager(eventStore);
 
+  // Create task backend for dynamic task tools (create_task, get_task, etc.)
+  const { createTaskBackend, loadTaskConfigFromMerged } = await import("../task/backend/index.js");
+  const { UnifiedTaskToolProvider } = await import("../task/backend/unified-tool-provider.js");
+
+  let taskBackend: import("../task/backend/types.js").TaskBackend | undefined;
+  let taskToolProvider: import("../task/backend/types.js").TaskToolProvider | undefined;
+  let taskBackendShutdown: (() => Promise<void>) | undefined;
+
+  // Mutable context holder for the task tool provider. Bridge handlers set
+  // this before each tool call so the provider uses the calling agent's ID.
+  // Safe because Node.js is single-threaded.
+  const taskToolContext = { agent_id: "" as string };
+
+  // Connect-on-spawn callback: auto-connect project .opentasks/ dirs to central daemon
+  let connectProject: ((projectPath: string) => Promise<void>) | undefined;
+  let getConnectedProjects: (() => string[]) | undefined;
+
+  try {
+    const taskConfig = loadTaskConfigFromMerged(mergedConfig);
+    const result = await createTaskBackend(taskConfig, eventStore);
+    taskBackend = result.backend;
+    taskBackendShutdown = result.shutdown;
+    connectProject = result.connectProject;
+    getConnectedProjects = result.getConnectedProjects;
+
+    taskToolProvider = new UnifiedTaskToolProvider(
+      taskBackend,
+      () => taskToolContext,
+      result.openTasksClient
+    );
+    console.error(`[acp] Task backend created: ${taskConfig.backend.type}`);
+
+    // Propagate runtime socket path to child agents so they skip daemon discovery
+    if (result.socketPath) {
+      agentManager.setOpenTasksSocketPath(result.socketPath);
+    }
+
+    // Auto-connect the server's own project directory on startup
+    if (connectProject) {
+      connectProject(defaultCwd).catch(() => {});
+    }
+  } catch (err) {
+    // Fall back to in-memory backend if opentasks connection fails
+    console.error(`[acp] Failed to create task backend (${err}), falling back to memory`);
+    try {
+      const fallbackResult = await createTaskBackend({ backend: { type: "memory" } }, eventStore);
+      taskBackend = fallbackResult.backend;
+      taskToolProvider = new UnifiedTaskToolProvider(
+        taskBackend,
+        () => taskToolContext,
+      );
+      console.error(`[acp] Task backend created: memory (fallback)`);
+    } catch (fallbackErr) {
+      console.error(`[acp] Memory fallback also failed: ${fallbackErr}. Task tools will be unavailable.`);
+    }
+  }
+
   // Create ActivityWatcher for event-driven agent waking
   const sessionProvider = createSessionProviderFromAgentManager(agentManager);
   const wakeHandler = createWakeHandler(sessionProvider, agentManager);
@@ -332,9 +360,11 @@ async function main() {
   activityWatcher.start();
 
   // Auto-subscribe Monitor agents to health events when they spawn
+  // and auto-connect project .opentasks/ directories to central daemon
   agentManager.onLifecycleEvent((event) => {
     if (event.type === "spawned") {
       const agent = event.agent;
+
       // Check if this is a Monitor agent
       if (agent.role === "monitor" || agent.role?.startsWith("monitor.")) {
         subscribeAgentToEvents(
@@ -346,23 +376,44 @@ async function main() {
         );
         console.error(`[acp] Auto-subscribed Monitor ${agent.id} to health events`);
       }
+
+      // Connect-on-spawn: auto-connect project .opentasks/ to central daemon
+      if (connectProject && agent.cwd) {
+        connectProject(agent.cwd).catch(() => {
+          // Non-fatal — logged inside connectProject
+        });
+      }
     }
   });
 
   // Combined server (when --ws is enabled)
   let combinedServer: CombinedServer | undefined;
 
-  // Cleanup function
+  // Cleanup function — best-effort, each step isolated
   const cleanup = async () => {
-    // Stop ActivityWatcher
-    activityWatcher.stop();
+    try { activityWatcher.stop(); } catch (err) {
+      console.error(`[cleanup] ActivityWatcher stop failed: ${err}`);
+    }
 
-    // Stop combined server if running
     if (combinedServer) {
-      await combinedServer.stop();
+      try { await combinedServer.stop(); } catch (err) {
+        console.error(`[cleanup] Combined server stop failed: ${err}`);
+      }
+    }
+
+    try { await agentManager.close(); } catch (err) {
+      console.error(`[cleanup] AgentManager close failed: ${err}`);
+    }
+
+    if (taskBackendShutdown) {
+      try { await taskBackendShutdown(); } catch (err) {
+        console.error(`[cleanup] Task backend shutdown failed: ${err}`);
+      }
+    }
+
+    try { await eventStore.close(); } catch (err) {
+      console.error(`[cleanup] EventStore close failed: ${err}`);
     }
-    await agentManager.close();
-    await eventStore.close();
   };
 
   try {
@@ -401,15 +452,22 @@ async function main() {
       await cleanup();
     } else {
       // Full server mode (default): WebSocket ACP + MAP + REST API
-      const host = options.host ?? "localhost";
-      const port = options.port ?? 3001;
+      const host = options.host ?? mergedConfig.host ?? "localhost";
+      const port = options.port ?? mergedConfig.port ?? 3001;
 
       combinedServer = createCombinedServer(
-        { eventStore, agentManager, taskManager, messageRouter, activityWatcher },
-        { port, host, defaultCwd }
+        { eventStore, agentManager, taskManager, messageRouter, activityWatcher, taskBackend, taskToolProvider, taskToolContext, agentTokenManager, getConnectedProjects },
+        { port, host, defaultCwd, serverToken, noAuth }
       );
 
       await combinedServer.start();
+      if (serverToken) {
+        console.error(`[acp] Server token: ${serverToken.substring(0, 8)}...`);
+      } else if (noAuth) {
+        console.error(`[acp] Auth: explicitly disabled`);
+      } else {
+        console.error(`[acp] Auth: off (set auth.secret in config or MACRO_SERVER_SECRET to enable)`);
+      }
 
       // Keep process alive - will exit via SIGINT/SIGTERM handlers
       await new Promise<void>(() => {