macro-agent 0.2.5 → 0.2.6

package/src/map/coordination-handler.ts

@@ -1,232 +0,0 @@
-/**
- * Coordination Handler — dispatches inbound coordination messages from the MAP hub.
- *
- * Handles x-openhive/* JSON-RPC notifications for task assignment, status updates,
- * context sharing, messaging, and workspace execution.
- *
- * @module map/coordination-handler
- */
-
-import type { AgentManager } from "../agent/agent-manager.js";
-import type { InboxAdapter, TasksAdapter } from "../adapters/types.js";
-import type {
-  CoordinationTaskAssign,
-  CoordinationTaskStatus,
-  CoordinationContextShare,
-  CoordinationMessage,
-  TrajectoryReporter,
-} from "./types.js";
-
-export interface CoordinationConnection {
-  onNotification(
-    method: string,
-    handler: (params: unknown) => void | Promise<void>,
-  ): void;
-  offNotification(
-    method: string,
-    handler: (params: unknown) => void | Promise<void>,
-  ): void;
-  sendNotification(method: string, params: unknown): Promise<void>;
-}
-
-export interface CoordinationDeps {
-  connection: CoordinationConnection;
-  agentManager: AgentManager;
-  inboxAdapter: InboxAdapter;
-  tasksAdapter: TasksAdapter;
-  trajectoryReporter?: TrajectoryReporter;
-  /** Workspace handler from cognitive module (if available) */
-  workspaceHandler?: {
-    handleWorkspaceExecute(params: unknown): Promise<void>;
-    isWorkspaceExecuteMessage(msg: { method?: string }): boolean;
-  };
-}
-
-/** Coordination method constants */
-const METHODS = {
-  TASK_ASSIGN: "x-openhive/task.assign",
-  TASK_STATUS: "x-openhive/task.status",
-  CONTEXT_SHARE: "x-openhive/context.share",
-  MESSAGE_SEND: "x-openhive/message.send",
-  WORKSPACE_EXECUTE: "x-openhive/learning.workspace.execute",
-} as const;
-
-/**
- * Register coordination notification handlers on the MAP connection.
- * Returns a cleanup function that removes all handlers.
- */
-export function setupCoordinationHandlers(
-  deps: CoordinationDeps,
-): () => void {
-  const { connection, agentManager, inboxAdapter, tasksAdapter } = deps;
-  const handlers: Array<{ method: string; handler: (params: unknown) => void | Promise<void> }> = [];
-
-  const register = (
-    method: string,
-    handler: (params: unknown) => void | Promise<void>,
-  ): void => {
-    connection.onNotification(method, handler);
-    handlers.push({ method, handler });
-  };
-
-  // --- Task Assignment ---
-  register(METHODS.TASK_ASSIGN, async (params: unknown) => {
-    const p = params as CoordinationTaskAssign;
-    if (!p?.title) return;
-
-    try {
-      // Extract tags and metadata from OpenHive context
-      const context = p.context ?? {};
-      const tags = Array.isArray(context.tags) ? context.tags as string[] : undefined;
-      const metadata: Record<string, unknown> = {
-        ...context,
-        ...(p.assigned_by ? { assigned_by: p.assigned_by } : {}),
-        ...(p.deadline ? { deadline: p.deadline } : {}),
-      };
-      // Remove tags from metadata (already a top-level field)
-      delete metadata.tags;
-
-      const taskId = await tasksAdapter.createTask({
-        title: p.title,
-        content: p.description,
-        assignee: p.assigned_to,
-        tags,
-        priority: p.priority === "critical" ? 1 : p.priority === "high" ? 2 : p.priority === "low" ? 4 : 3,
-        metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
-      });
-
-      // Optionally spawn an agent to work on the task
-      if (p.assigned_to) {
-        try {
-          await inboxAdapter.send("system", p.assigned_to, {
-            type: "event",
-            event: "TASK_ASSIGNED",
-            data: { taskId, title: p.title, description: p.description },
-          });
-        } catch {
-          // Agent may not exist locally — that's fine
-        }
-      }
-    } catch (err) {
-      console.warn(
-        `[map-sidecar] Failed to handle task.assign: ${(err as Error).message}`,
-      );
-    }
-  });
-
-  // --- Task Status ---
-  register(METHODS.TASK_STATUS, async (params: unknown) => {
-    const p = params as CoordinationTaskStatus;
-    if (!p?.task_id || !p?.status) return;
-
-    try {
-      const actionMap: Record<string, string> = {
-        in_progress: "start",
-        completed: "complete",
-        closed: "complete",
-        failed: "fail",
-        blocked: "block",
-        open: "reopen",
-      };
-      const action = actionMap[p.status];
-      if (action) {
-        await tasksAdapter.transitionTask(p.task_id, action as any);
-      }
-    } catch (err) {
-      console.warn(
-        `[map-sidecar] Failed to handle task.status: ${(err as Error).message}`,
-      );
-    }
-  });
-
-  // --- Context Share ---
-  register(METHODS.CONTEXT_SHARE, async (params: unknown) => {
-    const p = params as CoordinationContextShare;
-    if (!p?.context_type || !p?.data) return;
-
-    try {
-      // Deliver context to all running agents via inbox
-      const agents = agentManager.list()
-        .filter((a: any) => a.state === "running");
-      for (const agent of agents) {
-        await inboxAdapter
-          .send("system", agent.id, {
-            type: "event",
-            event: "CONTEXT_SHARED",
-            data: {
-              context_type: p.context_type,
-              data: p.data,
-              source: p.source_swarm_id,
-            },
-          })
-          .catch(() => {});
-      }
-    } catch (err) {
-      console.warn(
-        `[map-sidecar] Failed to handle context.share: ${(err as Error).message}`,
-      );
-    }
-  });
-
-  // --- Message Send ---
-  register(METHODS.MESSAGE_SEND, async (params: unknown) => {
-    const p = params as CoordinationMessage;
-    if (!p?.content) return;
-
-    try {
-      const agents = agentManager.list()
-        .filter((a: any) => a.state === "running");
-      if (agents.length === 0) return;
-
-      // Route to the best target:
-      // 1. If to_swarm_id matches a local agent ID, send directly
-      // 2. If metadata has a target_agent hint, use it
-      // 3. Otherwise, send to the coordinator/head manager (parentless agent)
-      // 4. Fallback: first running agent
-      const targetId = p.to_swarm_id;
-      const directTarget = targetId
-        ? agents.find((a: any) => a.id === targetId)
-        : undefined;
-      const coordinator = agents.find((a: any) => !a.parent);
-      const target = directTarget ?? coordinator ?? agents[0];
-
-      await inboxAdapter.send("system", target.id, {
-        type: "event",
-        event: "EXTERNAL_MESSAGE",
-        data: {
-          from: p.from_swarm_id,
-          content_type: p.content_type,
-          content: p.content,
-          reply_to: p.reply_to,
-          metadata: p.metadata,
-        },
-      });
-    } catch (err) {
-      console.warn(
-        `[map-sidecar] Failed to handle message.send: ${(err as Error).message}`,
-      );
-    }
-  });
-
-  // --- Workspace Execute (delegate to cognitive module) ---
-  if (deps.workspaceHandler) {
-    const wh = deps.workspaceHandler;
-    register(METHODS.WORKSPACE_EXECUTE, async (params: unknown) => {
-      try {
-        await wh.handleWorkspaceExecute(params);
-      } catch (err) {
-        console.warn(
-          `[map-sidecar] Failed to handle workspace.execute: ${(err as Error).message}`,
-        );
-      }
-    });
-  }
-
-  // Return cleanup function
-  return () => {
-    for (const { method, handler } of handlers) {
-      connection.offNotification(method, handler);
-    }
-    handlers.length = 0;
-  };
-}

package/src/map/index.ts

@@ -1,18 +0,0 @@
-/**
- * MAP Sidecar — connects macro-agent to an OpenHive MAP hub.
- *
- * @module map
- */
-
-export { createMAPSidecar } from "./sidecar.js";
-export { createMAPServerInstance } from "./server.js";
-
-export type {
-  MAPSidecar,
-  MAPSidecarConfig,
-  MAPSidecarDeps,
-  MAPServerInstance,
-  MapServerConfig,
-  TrajectoryCheckpointPayload,
-  TrajectoryCheckpointResult,
-} from "./types.js";

package/src/map/lifecycle-bridge.ts

@@ -1,236 +0,0 @@
-/**
- * Lifecycle Bridge — translates AgentManager lifecycle events to MAP agent primitives.
- *
- * When agents are spawned or terminated in macro-agent, this bridge registers/unregisters
- * them with the MAP hub so they appear in OpenHive's agent discovery.
- *
- * @module map/lifecycle-bridge
- */
-
-import type { AgentLifecycleCallback } from "../agent/types.js";
-import type { AgentStore } from "../agent/agent-store.js";
-import type { TaskBridge } from "./types.js";
-
-/** Minimal interface for the MAP connection methods we need */
-export interface LifecycleBridgeConnection {
-  callExtension(method: string, params?: unknown): Promise<unknown>;
-  get isConnected(): boolean;
-}
-
-interface RegisteredAgent {
-  id: string;
-  name: string;
-  role: string;
-  /** MAP-assigned agent ID (ULID) from the hub, used for unregistration */
-  mapId?: string;
-}
-
-/**
- * Create a lifecycle bridge that translates agent lifecycle events to MAP calls.
- *
- * Returns an `AgentLifecycleCallback` to register via `agentManager.onLifecycleEvent()`,
- * plus a `cleanup()` function to unregister all tracked agents on shutdown.
- */
-export function createLifecycleBridge(
-  connection: LifecycleBridgeConnection,
-  agentStore: AgentStore,
-  scope: string,
-  taskBridge?: TaskBridge,
-  getLocalMapId?: (localAgentId: string) => string | undefined,
-): {
-  callback: AgentLifecycleCallback;
-  cleanup: () => Promise<void>;
-  /**
-   * Resolve true once the named agent has completed `map/agents/register`
-   * with the hub (its entry.mapId is populated). Used by the dispatch
-   * spawn-agent handler to barrier-wait for hub-side registration before
-   * returning, so the orchestrator's subsequent `findAcpAgentInfo` lookup
-   * doesn't race the registration.
-   *
-   * Returns false if the timeout elapses before registration completes.
-   */
-  awaitRegistration: (agentId: string, timeoutMs?: number) => Promise<boolean>;
-  /**
-   * Reverse-lookup: hub-assigned MAP ULID → local agent id. Used by the
-   * `map/dispatch/message` handler in the sidecar to translate envelope
-   * recipients (which the hub addresses by MAP ULID) into local agent ids
-   * (which the inbox addresses messages by). Returns undefined when no
-   * registered agent matches.
-   */
-  findLocalAgentByMapId: (mapId: string) => string | undefined;
-} {
-  const registered = new Map<string, RegisteredAgent>();
-
-  /**
-   * Poll for the local MAP server's assigned ID for an agent.
-   * The local MAP server and the lifecycle bridge both listen to the same
-   * lifecycle callback, so they may fire in any order. Poll briefly to handle
-   * the race.
-   */
-  async function waitForLocalMapId(localAgentId: string, timeoutMs = 500): Promise<string | undefined> {
-    if (!getLocalMapId) return undefined;
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-      const id = getLocalMapId(localAgentId);
-      if (id) return id;
-      await new Promise((r) => setTimeout(r, 20));
-    }
-    return getLocalMapId(localAgentId);
-  }
-
-  const callback: AgentLifecycleCallback = (event) => {
-    if (!connection.isConnected) return;
-
-    switch (event.type) {
-      case "spawned": {
-        const agent = event.agent;
-        const name = agent.name ?? agent.id;
-        const role = agent.role ?? "worker";
-        const entry: RegisteredAgent = { id: agent.id, name, role };
-        registered.set(agent.id, entry);
-
-        // Build per-agent capabilities.
-        // Coordinators (head managers) support ACP for interactive chat.
-        const capabilities: Record<string, unknown> = {
-          messaging: { canReceive: true },
-        };
-        if (role === "coordinator") {
-          capabilities.protocols = ["acp"];
-          capabilities.acp = { version: "2024-10-07" };
-        }
-
-        // Register agent with MAP hub (use map/agents/register to preserve
-        // per-agent capabilities; map/agents/spawn drops them).
-        // Include the local MAP server's ID in metadata so clients can route
-        // ACP messages to the correct agent on the macro-agent's own MAP server.
-        // Also include provider_session_id so OpenHive can find the underlying
-        // Claude Code JSONL transcript on disk for history recovery.
-        const agentMetadata = (agent as any).metadata as Record<string, unknown> | undefined;
-        const providerSessionId =
-          typeof agentMetadata?.provider_session_id === "string"
-            ? agentMetadata.provider_session_id
-            : undefined;
-        (async () => {
-          const peerMapId = await waitForLocalMapId(agent.id);
-          try {
-            const result: any = await connection.callExtension("map/agents/register", {
-              name,
-              role,
-              capabilities,
-              metadata: {
-                // From the hub's perspective these IDs identify this agent on
-                // the macro-agent (peer) side. `peerAgentId` is macro-agent's
-                // internal store id; `peerMapId` is its local MAP server ULID.
-                // Hub callers use these to address the agent in routing
-                // (ACP streams target peerMapId, lifecycle ops use peerAgentId).
-                peerAgentId: agent.id,
-                peerMapId,
-                provider_session_id: providerSessionId,
-                parent: (agent as any).parent_id ?? undefined,
-                team: (agent as any).team ?? undefined,
-                cwd: (agent as any).cwd ?? undefined,
-              },
-            });
-            // Track the MAP-assigned agent ID for unregistration
-            const mapId = result?.agent?.id ?? result?.id;
-            if (mapId) {
-              entry.mapId = mapId;
-            }
-          } catch {
-            // Silent — MAP hub may be temporarily unavailable
-          }
-        })();
-
-        // Bridge task creation if agent has a task
-        if (taskBridge && (agent as any).task_id) {
-          taskBridge
-            .taskCreated({
-              id: (agent as any).task_id,
-              title: (agent as any).task ?? agent.name,
-              status: "open",
-              assignee: agent.id,
-            })
-            .catch(() => {});
-        }
-        break;
-      }
-
-      case "stopped": {
-        const agent = event.agent;
-        const entry = registered.get(agent.id);
-        registered.delete(agent.id);
-
-        // Unregister agent from MAP hub (use MAP-assigned ID if available)
-        const unregId = entry?.mapId ?? agent.id;
-        connection
-          .callExtension("map/agents/unregister", {
-            agentId: unregId,
-            reason: event.reason ?? "stopped",
-          })
-          .catch(() => {
-            // Silent fallback
-          });
-
-        // Bridge task completion
-        if (taskBridge && (agent as any).task_id) {
-          const status =
-            event.reason === "completed" ? "completed" : "failed";
-          taskBridge
-            .taskStatusChanged(
-              (agent as any).task_id,
-              "in_progress",
-              status,
-              agent.id,
-            )
-            .catch(() => {});
-        }
-        break;
-      }
-    }
-  };
-
-  const cleanup = async (): Promise<void> => {
-    if (!connection.isConnected) {
-      registered.clear();
-      return;
-    }
-    // Unregister all tracked agents (use MAP-assigned IDs)
-    const promises = Array.from(registered.values()).map((entry) =>
-      connection
-        .callExtension("map/agents/unregister", {
-          agentId: entry.mapId ?? entry.id,
-          reason: "sidecar_shutdown",
-        })
-        .catch(() => {}),
-    );
-    await Promise.allSettled(promises);
-    registered.clear();
-  };
-
-  /**
-   * Block until the named agent's hub-side registration completes (entry
-   * has been assigned a mapId by the `map/agents/register` response) or
-   * the timeout elapses. Polls the local `registered` map.
-   */
-  const awaitRegistration = async (
-    agentId: string,
-    timeoutMs = 5000,
-  ): Promise<boolean> => {
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-      const entry = registered.get(agentId);
-      if (entry?.mapId) return true;
-      await new Promise((r) => setTimeout(r, 50));
-    }
-    return Boolean(registered.get(agentId)?.mapId);
-  };
-
-  const findLocalAgentByMapId = (mapId: string): string | undefined => {
-    for (const [localId, entry] of registered) {
-      if (entry.mapId === mapId) return localId;
-    }
-    return undefined;
-  };
-
-  return { callback, cleanup, awaitRegistration, findLocalAgentByMapId };
-}