macro-agent 0.2.4 → 0.2.6

package/src/control/control-client.ts

@@ -1,337 +0,0 @@
-/**
- * Control Socket Client
- *
- * Connects to the main process control socket from MCP subprocesses.
- * Provides typed methods for lifecycle operations (spawn, terminate, etc.)
- * Supports auto-reconnect with exponential backoff on socket close.
- *
- * @module control/control-client
- */
-
-import * as net from "node:net";
-import type { ControlCommand, ControlResponse } from "./types.js";
-
-// =============================================================================
-// Types
-// =============================================================================
-
-export interface ControlClientOptions {
-  timeout?: number;
-  reconnect?: boolean;
-  maxRetries?: number;
-  onReconnected?: () => void;
-}
-
-// =============================================================================
-// Client
-// =============================================================================
-
-export class ControlClient {
-  private socket: net.Socket | null = null;
-  private buffer = "";
-  private pending: Map<
-    number,
-    { resolve: (r: ControlResponse) => void; reject: (e: Error) => void }
-  > = new Map();
-  private seq = 0;
-  private _connected = false;
-  private _reconnecting = false;
-  private _permanentlyDisconnected = false;
-  private readonly socketPath: string;
-  private readonly timeout: number;
-  private readonly reconnectEnabled: boolean;
-  private readonly maxRetries: number;
-  private readonly onReconnected?: () => void;
-  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
-
-  constructor(socketPath: string, options?: ControlClientOptions | number) {
-    this.socketPath = socketPath;
-    if (typeof options === "number") {
-      // Legacy signature: constructor(socketPath, timeout)
-      this.timeout = options;
-      this.reconnectEnabled = false;
-      this.maxRetries = 10;
-    } else {
-      this.timeout = options?.timeout ?? 30_000;
-      this.reconnectEnabled = options?.reconnect ?? true;
-      this.maxRetries = options?.maxRetries ?? 10;
-      this.onReconnected = options?.onReconnected;
-    }
-  }
-
-  get connected(): boolean {
-    return this._connected;
-  }
-
-  get reconnecting(): boolean {
-    return this._reconnecting;
-  }
-
-  async connect(): Promise<void> {
-    if (this._connected) return;
-
-    this._permanentlyDisconnected = false;
-    return this.connectInternal();
-  }
-
-  private connectInternal(): Promise<void> {
-    return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
-        reject(new Error(`Control socket connection timeout: ${this.socketPath}`));
-      }, 5000);
-
-      this.socket = net.createConnection(this.socketPath, () => {
-        clearTimeout(timer);
-        this._connected = true;
-        this._reconnecting = false;
-        resolve();
-      });
-
-      this.socket.on("error", (err) => {
-        clearTimeout(timer);
-        if (!this._connected) {
-          // Connection failed during initial connect
-          reject(err);
-        }
-        // If already connected, error will be followed by close
-      });
-
-      this.socket.on("data", (data) => {
-        this.buffer += data.toString();
-        this.processBuffer();
-      });
-
-      this.socket.on("close", () => {
-        const wasConnected = this._connected;
-        this._connected = false;
-        this.socket = null;
-        this.buffer = "";
-
-        if (wasConnected && this.reconnectEnabled && !this._permanentlyDisconnected) {
-          // Reject pending requests — they won't get responses
-          for (const [, p] of this.pending) {
-            p.reject(new Error("Control socket closed"));
-          }
-          this.pending.clear();
-
-          // Start reconnect loop
-          this.startReconnect();
-        } else if (!this._reconnecting) {
-          // No reconnect — reject all pending
-          for (const [, p] of this.pending) {
-            p.reject(new Error("Control socket closed"));
-          }
-          this.pending.clear();
-        }
-      });
-    });
-  }
-
-  private startReconnect(): void {
-    if (this._reconnecting || this._permanentlyDisconnected) return;
-    this._reconnecting = true;
-    this.attemptReconnect(0, 100);
-  }
-
-  private attemptReconnect(attempt: number, delay: number): void {
-    if (this._permanentlyDisconnected || this._connected) {
-      this._reconnecting = false;
-      return;
-    }
-
-    if (attempt >= this.maxRetries) {
-      this._reconnecting = false;
-      this._permanentlyDisconnected = true;
-      // Reject any pending that accumulated
-      for (const [, p] of this.pending) {
-        p.reject(new Error("Control socket reconnect failed after max retries"));
-      }
-      this.pending.clear();
-      return;
-    }
-
-    this.reconnectTimer = setTimeout(async () => {
-      this.reconnectTimer = null;
-
-      if (this._permanentlyDisconnected || this._connected) {
-        this._reconnecting = false;
-        return;
-      }
-
-      try {
-        await this.connectInternal();
-        // Success
-        this._reconnecting = false;
-        this.onReconnected?.();
-      } catch {
-        // Failed — retry with exponential backoff (cap at 5s)
-        const nextDelay = Math.min(delay * 2, 5000);
-        this.attemptReconnect(attempt + 1, nextDelay);
-      }
-    }, delay);
-  }
-
-  disconnect(): void {
-    this._permanentlyDisconnected = true;
-    this._reconnecting = false;
-    if (this.reconnectTimer) {
-      clearTimeout(this.reconnectTimer);
-      this.reconnectTimer = null;
-    }
-    if (this.socket) {
-      this.socket.destroy();
-      this.socket = null;
-      this._connected = false;
-    }
-    // Reject any pending
-    for (const [, p] of this.pending) {
-      p.reject(new Error("Control socket disconnected"));
-    }
-    this.pending.clear();
-  }
-
-  // ── Typed Methods ────────────────────────────────────────────
-
-  async spawn(options: {
-    task: string;
-    parent?: string | null;
-    role?: string;
-    cwd?: string;
-    team_instance?: string;
-    customPrompt?: string;
-  }): Promise<{
-    agent_id: string;
-    name?: string;
-    session_id: string;
-    task_id?: string;
-    role?: string;
-  }> {
-    const resp = await this.send({ action: "spawn", ...options });
-    return resp.result as any;
-  }
-
-  async terminate(agentId: string, reason: string): Promise<void> {
-    await this.send({ action: "terminate", agentId, reason } as any);
-  }
-
-  async getAgent(agentId: string): Promise<unknown> {
-    const resp = await this.send({ action: "get_agent", agentId });
-    return resp.result;
-  }
-
-  async listAgents(filter?: Record<string, unknown>): Promise<unknown[]> {
-    const resp = await this.send({ action: "list_agents", filter } as any);
-    return (resp.result as unknown[]) ?? [];
-  }
-
-  async getChildren(agentId: string): Promise<unknown[]> {
-    const resp = await this.send({ action: "get_children", agentId });
-    return (resp.result as unknown[]) ?? [];
-  }
-
-  async getHierarchy(
-    agentId: string,
-    depth?: number
-  ): Promise<unknown> {
-    const resp = await this.send({
-      action: "get_hierarchy",
-      agentId,
-      depth,
-    });
-    return resp.result;
-  }
-
-  async ping(): Promise<boolean> {
-    try {
-      const resp = await this.send({ action: "ping" });
-      return resp.ok;
-    } catch {
-      return false;
-    }
-  }
-
-  async healthCheck(agentId: string, mcpPid: number): Promise<boolean> {
-    try {
-      const resp = await this.send({ action: "health_check", agentId, mcpPid });
-      return resp.ok;
-    } catch {
-      return false;
-    }
-  }
-
-  // ── Internal ─────────────────────────────────────────────────
-
-  private async send(cmd: ControlCommand): Promise<ControlResponse & { ok: true }> {
-    if (!this.socket || !this._connected) {
-      throw new Error("Control socket not connected");
-    }
-
-    const resp = await this.sendRaw(cmd);
-    if (!resp.ok) {
-      const err = new Error((resp as any).error ?? "Control socket error");
-      (err as any).code = (resp as any).code;
-      throw err;
-    }
-    return resp as ControlResponse & { ok: true };
-  }
-
-  private sendRaw(cmd: ControlCommand): Promise<ControlResponse> {
-    return new Promise((resolve, reject) => {
-      const id = this.seq++;
-
-      const timer = setTimeout(() => {
-        this.pending.delete(id);
-        reject(new Error(`Control socket timeout (${this.timeout}ms)`));
-      }, this.timeout);
-
-      this.pending.set(id, {
-        resolve: (resp) => {
-          clearTimeout(timer);
-          resolve(resp);
-        },
-        reject: (err) => {
-          clearTimeout(timer);
-          reject(err);
-        },
-      });
-
-      try {
-        // Tag the command with a sequence ID for response matching
-        this.socket!.write(JSON.stringify({ ...cmd, _seq: id }) + "\n");
-      } catch (err) {
-        this.pending.delete(id);
-        clearTimeout(timer);
-        reject(err instanceof Error ? err : new Error(String(err)));
-      }
-    });
-  }
-
-  private processBuffer(): void {
-    let newlineIdx: number;
-    while ((newlineIdx = this.buffer.indexOf("\n")) !== -1) {
-      const line = this.buffer.slice(0, newlineIdx).trim();
-      this.buffer = this.buffer.slice(newlineIdx + 1);
-
-      if (!line) continue;
-
-      try {
-        const resp = JSON.parse(line) as ControlResponse & { _seq?: number };
-        const seq = resp._seq;
-
-        if (seq !== undefined && this.pending.has(seq)) {
-          this.pending.get(seq)!.resolve(resp);
-          this.pending.delete(seq);
-        } else {
-          // No matching request — resolve oldest pending
-          const oldest = this.pending.entries().next();
-          if (!oldest.done) {
-            oldest.value[1].resolve(resp);
-            this.pending.delete(oldest.value[0]);
-          }
-        }
-      } catch {
-        // Invalid JSON — ignore
-      }
-    }
-  }
-}

package/src/control/control-server.ts

@@ -1,298 +0,0 @@
-/**
- * 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

@@ -1,17 +0,0 @@
-/**
- * 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";