macro-agent 0.1.1 → 0.1.3

package/src/control/control-server.ts

@@ -0,0 +1,298 @@
+/**
+ * Control Socket Server
+ *
+ * NDJSON over UNIX socket. Exposes AgentManager lifecycle operations
+ * to MCP subprocesses. Runs in the main macro-agent process.
+ *
+ * Protocol: One JSON object per line. Request → Response.
+ * Same pattern as agent-inbox's IPC server.
+ *
+ * @module control/control-server
+ */
+
+import * as net from "node:net";
+import * as fs from "node:fs";
+import type { AgentManager } from "../agent/agent-manager.js";
+import type { ControlCommand, ControlResponse } from "./types.js";
+
+// =============================================================================
+// Server
+// =============================================================================
+
+export interface ControlServerConfig {
+  socketPath: string;
+}
+
+export interface AgentHealthStatus {
+  healthy: boolean;
+  lastSeen: number;
+  pid: number;
+}
+
+export class ControlServer {
+  private server: net.Server | null = null;
+  private readonly socketPath: string;
+  private readonly agentManager: AgentManager;
+  private readonly heartbeats: Map<string, { pid: number; lastSeen: number }> = new Map();
+  private readonly connections: Set<net.Socket> = new Set();
+
+  constructor(agentManager: AgentManager, config: ControlServerConfig) {
+    this.agentManager = agentManager;
+    this.socketPath = config.socketPath;
+  }
+
+  async start(): Promise<void> {
+    // Clean up stale socket file
+    if (fs.existsSync(this.socketPath)) {
+      fs.unlinkSync(this.socketPath);
+    }
+
+    this.server = net.createServer((socket) => {
+      this.handleConnection(socket);
+    });
+
+    return new Promise((resolve, reject) => {
+      this.server!.on("error", reject);
+      this.server!.listen(this.socketPath, () => {
+        resolve();
+      });
+    });
+  }
+
+  async stop(): Promise<void> {
+    if (this.server) {
+      // Destroy all active client connections so they receive close events
+      for (const socket of this.connections) {
+        socket.destroy();
+      }
+      this.connections.clear();
+
+      return new Promise((resolve) => {
+        this.server!.close(() => {
+          if (fs.existsSync(this.socketPath)) {
+            try {
+              fs.unlinkSync(this.socketPath);
+            } catch {
+              // Best effort
+            }
+          }
+          this.server = null;
+          resolve();
+        });
+      });
+    }
+  }
+
+  // ── Connection Handler ───────────────────────────────────────
+
+  private handleConnection(socket: net.Socket): void {
+    this.connections.add(socket);
+    let buffer = "";
+
+    socket.on("close", () => {
+      this.connections.delete(socket);
+    });
+
+    socket.on("data", (data) => {
+      buffer += data.toString();
+
+      // Process complete lines
+      let newlineIdx: number;
+      while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+        const line = buffer.slice(0, newlineIdx).trim();
+        buffer = buffer.slice(newlineIdx + 1);
+
+        if (!line) continue;
+
+        this.handleLine(line).then(
+          (response) => {
+            try {
+              socket.write(JSON.stringify(response) + "\n");
+            } catch {
+              // Socket may have closed
+            }
+          },
+          (err) => {
+            try {
+              socket.write(
+                JSON.stringify({ ok: false, error: String(err) }) + "\n"
+              );
+            } catch {
+              // Socket may have closed
+            }
+          }
+        );
+      }
+    });
+
+    socket.on("error", () => {
+      // Client disconnected — ignore
+    });
+  }
+
+  // ── Command Dispatch ─────────────────────────────────────────
+
+  private async handleLine(line: string): Promise<ControlResponse & { _seq?: number }> {
+    let cmd: ControlCommand & { _seq?: number };
+    try {
+      cmd = JSON.parse(line);
+    } catch {
+      return { ok: false, error: "Invalid JSON" };
+    }
+
+    if (!cmd || typeof cmd !== "object" || !("action" in cmd)) {
+      return { ok: false, error: "Missing 'action' field" };
+    }
+
+    // Preserve sequence ID for response matching
+    const seq = cmd._seq;
+
+    let response: ControlResponse;
+    try {
+      switch (cmd.action) {
+        case "ping":
+          response = { ok: true, result: { pid: process.pid } };
+          break;
+        case "spawn":
+          response = await this.handleSpawn(cmd);
+          break;
+        case "terminate":
+          response = await this.handleTerminate(cmd);
+          break;
+        case "get_agent":
+          response = this.handleGetAgent(cmd);
+          break;
+        case "list_agents":
+          response = this.handleListAgents(cmd);
+          break;
+        case "get_children":
+          response = this.handleGetChildren(cmd);
+          break;
+        case "get_hierarchy":
+          response = this.handleGetHierarchy(cmd);
+          break;
+        case "health_check":
+          response = this.handleHealthCheck(cmd);
+          break;
+        default:
+          response = {
+            ok: false,
+            error: `Unknown action: ${(cmd as any).action}`,
+          };
+      }
+    } catch (err) {
+      response = {
+        ok: false,
+        error: err instanceof Error ? err.message : String(err),
+        code: (err as any)?.code,
+      };
+    }
+
+    // Attach sequence ID for client response matching
+    return seq !== undefined ? { ...response, _seq: seq } : response;
+  }
+
+  // ── Handlers ─────────────────────────────────────────────────
+
+  private async handleSpawn(
+    cmd: Extract<ControlCommand, { action: "spawn" }>
+  ): Promise<ControlResponse> {
+    const spawned = await this.agentManager.spawn({
+      task: cmd.task,
+      parent: cmd.parent ?? undefined,
+      role: cmd.role,
+      cwd: cmd.cwd,
+      team_instance: cmd.team_instance,
+      customPrompt: cmd.customPrompt,
+    });
+
+    return {
+      ok: true,
+      result: {
+        agent_id: spawned.id,
+        name: spawned.agent.name,
+        session_id: spawned.session_id,
+        task_id: spawned.agent.task_id,
+        role: spawned.agent.role,
+        state: spawned.agent.state,
+      },
+    };
+  }
+
+  private async handleTerminate(
+    cmd: Extract<ControlCommand, { action: "terminate" }>
+  ): Promise<ControlResponse> {
+    await this.agentManager.terminate(cmd.agentId, cmd.reason);
+    return { ok: true };
+  }
+
+  private handleGetAgent(
+    cmd: Extract<ControlCommand, { action: "get_agent" }>
+  ): ControlResponse {
+    const agent = this.agentManager.get(cmd.agentId);
+    if (!agent) {
+      return { ok: false, error: `Agent not found: ${cmd.agentId}`, code: "AGENT_NOT_FOUND" };
+    }
+    return { ok: true, result: agent };
+  }
+
+  private handleListAgents(
+    cmd: Extract<ControlCommand, { action: "list_agents" }>
+  ): ControlResponse {
+    const agents = this.agentManager.list(cmd.filter as any);
+    return { ok: true, result: agents };
+  }
+
+  private handleGetChildren(
+    cmd: Extract<ControlCommand, { action: "get_children" }>
+  ): ControlResponse {
+    const children = this.agentManager.getChildren(cmd.agentId);
+    return { ok: true, result: children };
+  }
+
+  private handleGetHierarchy(
+    cmd: Extract<ControlCommand, { action: "get_hierarchy" }>
+  ): ControlResponse {
+    const hierarchy = this.agentManager.getHierarchy(cmd.agentId, {
+      depth: cmd.depth,
+    });
+    return { ok: true, result: hierarchy };
+  }
+
+  // ── Health Check ────────────────────────────────────────────
+
+  private handleHealthCheck(
+    cmd: Extract<ControlCommand, { action: "health_check" }>
+  ): ControlResponse {
+    this.heartbeats.set(cmd.agentId, {
+      pid: cmd.mcpPid,
+      lastSeen: Date.now(),
+    });
+    return { ok: true };
+  }
+
+  getHealthStatus(agentId: string): AgentHealthStatus | null {
+    const entry = this.heartbeats.get(agentId);
+    if (!entry) return null;
+    return {
+      healthy: true,
+      lastSeen: entry.lastSeen,
+      pid: entry.pid,
+    };
+  }
+
+  getUnhealthyAgents(timeoutMs: number): Array<{ agentId: string; lastSeen: number; pid: number }> {
+    const now = Date.now();
+    const unhealthy: Array<{ agentId: string; lastSeen: number; pid: number }> = [];
+    for (const [agentId, entry] of this.heartbeats) {
+      if (now - entry.lastSeen > timeoutMs) {
+        unhealthy.push({
+          agentId,
+          lastSeen: entry.lastSeen,
+          pid: entry.pid,
+        });
+      }
+    }
+    return unhealthy;
+  }
+}

package/src/control/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Control Socket — lifecycle RPC for MCP subprocesses
+ *
+ * @module control
+ */
+
+export { ControlServer, type ControlServerConfig, type AgentHealthStatus } from "./control-server.js";
+export { ControlClient } from "./control-client.js";
+export type {
+  ControlCommand,
+  ControlResponse,
+  ControlSuccessResponse,
+  ControlErrorResponse,
+  SpawnCommand,
+  TerminateCommand,
+  HealthCheckCommand,
+} from "./types.js";

package/src/control/types.ts

@@ -0,0 +1,95 @@
+/**
+ * Control Socket Types
+ *
+ * NDJSON protocol for MCP subprocess → main process lifecycle RPC.
+ * Separate from agent-inbox (messaging) — this is the control plane.
+ *
+ * @module control/types
+ */
+
+import type { AgentId } from "../store/types/primitives.js";
+import type { AgentStopReason } from "../agent/types.js";
+
+// =============================================================================
+// Commands (subprocess → main process)
+// =============================================================================
+
+export type ControlCommand =
+  | SpawnCommand
+  | TerminateCommand
+  | GetAgentCommand
+  | ListAgentsCommand
+  | GetChildrenCommand
+  | GetHierarchyCommand
+  | PingCommand
+  | HealthCheckCommand;
+
+export interface SpawnCommand {
+  action: "spawn";
+  task: string;
+  parent?: string | null;
+  role?: string;
+  cwd?: string;
+  team_instance?: string;
+  customPrompt?: string;
+}
+
+export interface TerminateCommand {
+  action: "terminate";
+  agentId: string;
+  reason: AgentStopReason;
+}
+
+export interface GetAgentCommand {
+  action: "get_agent";
+  agentId: string;
+}
+
+export interface ListAgentsCommand {
+  action: "list_agents";
+  filter?: {
+    state?: string;
+    parent?: string | null;
+    headManagersOnly?: boolean;
+  };
+}
+
+export interface GetChildrenCommand {
+  action: "get_children";
+  agentId: string;
+}
+
+export interface GetHierarchyCommand {
+  action: "get_hierarchy";
+  agentId: string;
+  depth?: number;
+}
+
+export interface PingCommand {
+  action: "ping";
+}
+
+export interface HealthCheckCommand {
+  action: "health_check";
+  agentId: string;
+  mcpPid: number;
+}
+
+// =============================================================================
+// Responses (main process → subprocess)
+// =============================================================================
+
+export type ControlResponse =
+  | ControlSuccessResponse
+  | ControlErrorResponse;
+
+export interface ControlSuccessResponse {
+  ok: true;
+  result?: unknown;
+}
+
+export interface ControlErrorResponse {
+  ok: false;
+  error: string;
+  code?: string;
+}

package/src/index.ts

@@ -1,17 +1,8 @@
 /**
- * macro-agent - Multi-agent orchestration system
+ * macro-agent - Multi-agent orchestration system (V2)
  */
 
-// Store - core event store and types
-export {
-  createEventStore,
-  type EventStore,
-  type AgentChangeCallback,
-  type TaskChangeCallback,
-  type MessageCallback,
-  type Unsubscribe,
-} from './store/event-store.js';
-
+// Store types (primitives used everywhere)
 export {
   type Agent,
   type AgentState,
@@ -37,15 +28,16 @@ export {
   type QueuedMessage,
   type Subscription,
   type SubscriptionType,
-  type StoreConfig,
   CURRENT_EVENT_VERSION,
 } from './store/types/index.js';
 
-// Agent manager
+// Agent manager (interface + V2 factory)
 export {
   createAgentManager,
+  createAgentManagerV2,
   type AgentManager,
   type AgentManagerConfig,
+  type SpawnInterceptor,
 } from './agent/agent-manager.js';
 
 export {
@@ -68,227 +60,56 @@ export {
 
 export { generateSystemPrompt } from './agent/system-prompt.js';
 
-// Task manager
-export {
-  createTaskManager,
-  type TaskManager,
-} from './task/task-manager.js';
+// Agent store (V2 lifecycle state)
+export { AgentStore } from './agent/agent-store.js';
 
+// Adapters (V2 messaging + tasks)
 export {
-  type CreateTaskOptions,
-  type UpdateTaskOptions,
-  type TaskFilter,
-  type SubtaskStatus,
-  TaskManagerError,
-  type TaskManagerErrorCode,
-  VALID_STATUS_TRANSITIONS,
-} from './task/types.js';
+  DefaultInboxAdapter,
+} from './adapters/inbox-adapter.js';
 
-// Message router
 export {
-  createMessageRouter,
-  type MessageRouter,
-  type MessageRouterConfig,
-} from './router/message-router.js';
+  DefaultTasksAdapter,
+} from './adapters/tasks-adapter.js';
 
 export {
-  type MessageTarget,
-  type MessageSender,
-  type SendMessageRequest,
-  type SentMessage,
-  type ReceivedMessage,
-  type GetMessagesOptions,
-  type Channel,
-  type ChannelType,
-  type DefaultSubscriptionOptions,
-  type StatusType as RouterStatusType,
-  type EmitStatusRequest,
-  type StatusNotification,
-  type TruncationConfig,
-  RoutingError,
-  type RoutingErrorCode,
-  DEFAULT_TRUNCATION_CONFIG,
-} from './router/types.js';
+  type InboxAdapter,
+  type TasksAdapter,
+} from './adapters/types.js';
 
-// MCP server
+// Boot V2
 export {
-  createMCPServer,
-  type MCPServerConfig,
-  type MCPServices,
-  type MCPServerInstance,
-} from './mcp/mcp-server.js';
+  bootV2,
+  type BootV2Config,
+  type MacroAgentSystemV2,
+} from './boot-v2.js';
 
+// Roles
 export {
-  type ToolContext,
-  type SpawnAgentInput,
-  type SpawnAgentOutput,
-  type EmitStatusInput,
-  type EmitStatusOutput,
-  type SendMessageInput,
-  type SendMessageOutput,
-  type CheckMessagesInput,
-  type CheckMessagesOutput,
-  type QueryIndexInput,
-  type QueryIndexOutput,
-  type GetHierarchyInput,
-  type GetHierarchyOutput,
-  type HierarchyNode as MCPHierarchyNode,
-  type GetAgentSummaryInput,
-  type GetAgentSummaryOutput,
-  type StopAgentInput,
-  type StopAgentOutput,
-  type CreateTaskInput,
-  type CreateTaskOutput,
-  type GetTaskInput,
-  type GetTaskOutput,
-  MCPToolError,
-  type MCPToolErrorCode,
-  // Peer communication tools
-  type SendPeerMessageInput,
-  type SendPeerMessageOutput,
-  type SendPeerRequestInput,
-  type SendPeerRequestOutput,
-  type RespondToPeerRequestInput,
-  type RespondToPeerRequestOutput,
-} from './mcp/types.js';
+  type RoleDefinition,
+  type RoleRegistry,
+  type Capability,
+} from './roles/types.js';
 
-// API server
-export {
-  createAPIServer,
-  type APIServer,
-  type APIServerConfig,
-  type APIServices,
-} from './api/server.js';
+export { DefaultRoleRegistry } from './roles/registry.js';
+export { AGENT_CAPABILITIES } from './roles/capabilities.js';
 
+// Workspace
 export {
-  type SystemStatus,
-  type InitRequest,
-  type InitResponse,
-  type ConversationMessageRequest,
-  type ConversationMessageResponse,
-  type ConversationHistoryEntry,
-  type ConversationHistoryResponse,
-  type AgentSummary,
-  type AgentDetail,
-  type AgentListResponse,
-  type HierarchyNode as APIHierarchyNode,
-  type HierarchyResponse,
-  type TaskSummary,
-  type TaskDetail,
-  type TaskListResponse,
-  type EventSummary,
-  type EventListResponse,
-  type WSMessage,
-  type WSMessageType,
-  type WSSubscribeMessage,
-  type WSAgentUpdate,
-  type WSTaskUpdate,
-  type WSConversationMessage,
-  type AgentQueryParams,
-  type TaskQueryParams,
-  type EventQueryParams,
-  type APIError,
-} from './api/types.js';
+  type WorkspaceManager,
+  type Workspace,
+} from './workspace/types.js';
 
-// ACP - Agent Communication Protocol support
-export {
-  // Registration helper
-  registerMacroAgent,
-  type RegisterOptions,
-  // Classes
-  SessionMapper,
-  MacroAgent,
-  ACPError,
-  // Types
-  type MacroAgentConfig,
-  type ACPSessionId,
-  type SessionMapping,
-  // Initialization config types
-  type MacroAgentInitConfig,
-  type SubAgentConfig,
-  type ACPMCPServerConfig,
-  type ACPPermissionMode,
-  // Extension request/response types
-  type SpawnAgentRequest as ACPSpawnAgentRequest,
-  type SpawnAgentResponse as ACPSpawnAgentResponse,
-  type GetHierarchyRequest as ACPGetHierarchyRequest,
-  type GetHierarchyResponse as ACPGetHierarchyResponse,
-  type GetTaskRequest as ACPGetTaskRequest,
-  type GetTaskResponse as ACPGetTaskResponse,
-  type MountAgentRequest,
-  type MountAgentResponse,
-  type ForkAgentRequest,
-  type ForkAgentResponse,
-  type ACPExtensionMethod,
-  type ACPExtensionRequests,
-  type ACPExtensionResponses,
-  type ACPErrorCode,
-} from './acp/index.js';
-
-// Peer communication
-export {
-  createPeerManager,
-  type PeerManager,
-  type PeerTransport,
-  type PeerHandler,
-  type PeerConfig,
-  type PeerMessage,
-  type PeerRequest,
-  type PeerResponse,
-  type PeerAddress,
-  type ParsedPeerAddress,
-  type PeerInboxMessage,
-  PeerError,
-  type PeerErrorCode,
-} from './peer/index.js';
+// Teams - template seeding
+export { seedDefaultTemplates } from './teams/seed-defaults.js';
 
-// Activity module - event-driven agent waking
-export {
-  // Types
-  type Activity,
-  type ActivityEventType,
-  type ActivitySource,
-  type ActivityTarget,
-  type EventSubscription,
-  type EventSubscriptionScope,
-  type WakeResult,
-  type WakeMethod,
-  type WaitForActivityResult,
-  MONITOR_DEFAULT_EVENT_TYPES,
-
-  // Activity watcher
-  createActivityWatcher,
-  subscribeAgentToEvents,
-  type ActivityWatcher,
-  type ActivityListener,
-  type WakeHandler,
-
-  // Relevance detection
-  findRelevantAgents,
-  matchesRole,
-  matchesSubscriptionScope,
-  getAncestors,
-  isInSubtree,
-  getAgentsByRole,
-  type RelevanceAgentInfo,
-  type RelevanceAgentSource,
-  type RelevanceSubscriptionSource,
-  type RelevanceOptions,
-
-  // Deduplication
-  ActivityDeduplicator,
-  createDeduplicator,
-  type DeduplicationKey,
-  type DeduplicationConfig,
-} from './activity/index.js';
-
-// Agent wake mechanism
-export {
-  wakeAgent,
-  createWakeHandler,
-  createSessionProviderFromAgentManager,
-  formatActivityContext,
-  type WakeSessionInfo,
-  type WakeSessionProvider,
-  type WakeAgentOptions,
-} from './agent/wake.js';
+// MAP (sidecar + server)
+export { createMAPSidecar, createMAPServerInstance } from './map/index.js';
+export type {
+  MAPSidecar,
+  MAPSidecarConfig,
+  MAPServerInstance,
+  MapServerConfig,
+  TrajectoryCheckpointPayload,
+  TrajectoryCheckpointResult,
+} from './map/types.js';