macro-agent 0.2.4 → 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 };
-}

package/src/map/mail-bridge.ts

@@ -1,215 +0,0 @@
-/**
- * Mail Bridge — connects OpenHive's hub-side mail to macro-agent's local inbox.
- *
- * OpenHive's mail module (src/mail/index.ts) calls forwardTurnToSwarms() when
- * a new mail turn lands in a conversation a swarm participates in. The hub
- * sends a `mail/turn.received` JSON-RPC notification to the connected swarm
- * sidecar via MAP. macro-agent's sidecar (this module) receives the
- * notification, parses the turn content, and forwards it into the local
- * agent-inbox so:
- *
- *   1. swarm-dispatch's MessagePort (boot-v2 wires `createAgentInboxPort`)
- *      sees the inbox delivery event and runs its classifier on the message.
- *   2. The classifier recognizes `x-dispatch/work` schema and routes the
- *      prompt to a worker agent (existing or freshly spawned).
- *
- * Without this bridge, hub-side mail turns never reach macro-agent's
- * dispatcher. The MessagePort is wired to local inbox events only.
- */
-import type { InboxAdapter } from "../adapters/types.js";
-
-/**
- * Subset of MAPClient surface this module needs. Mirrors the shape used by
- * trajectory-reporter / coordination-handler — keeps the bridge testable
- * without dragging in the full SDK type.
- */
-export interface MailBridgeConnection {
-  onNotification(
-    method: string,
-    handler: (params: unknown) => void | Promise<void>,
-  ): void;
-  offNotification(
-    method: string,
-    handler: (params: unknown) => void | Promise<void>,
-  ): void;
-}
-
-/**
- * Synthetic recipient registered on the local inbox to receive bridged
- * turns. Choosing a stable name lets the macro-agent dispatcher (or any
- * other inbox observer) filter on `to: BRIDGE_RECIPIENT_ID` if it cares
- * about the source — but normally it doesn't, since the dispatcher's
- * MessagePort matches on the `x-dispatch/work` schema in the payload, not
- * on the recipient id.
- */
-const BRIDGE_RECIPIENT_ID = "openhive-mail-bridge";
-
-interface MailTurnReceivedParams {
-  conversation_id?: string;
-  turn_id?: string;
-  participant_id?: string;
-  content_type?: string;
-  content?: unknown;
-  thread_id?: string;
-  created_at?: string;
-  /** Importance hint from the hub. When present, drives wake/interrupt
-   *  decisions via TriggerSystemV2's mapImportanceToWakeAction. */
-  importance?: string;
-}
-
-/**
- * Parse the turn content into a JS object suitable for inbox routing.
- * Returns null when the content is not parseable as JSON or doesn't look
- * like an object payload (e.g., plain text mail turns).
- */
-function parseTurnContent(
-  content: unknown,
-  contentType: string | undefined,
-): Record<string, unknown> | null {
-  if (typeof content === "object" && content !== null) {
-    return content as Record<string, unknown>;
-  }
-  if (typeof content !== "string") return null;
-  // The hub serializes envelope objects via JSON.stringify and tags them
-  // application/json. We accept either explicit content type or a leading
-  // `{` to handle clients that omit the header.
-  if (
-    contentType === "application/json" ||
-    content.startsWith("{") ||
-    content.startsWith("[")
-  ) {
-    try {
-      const parsed = JSON.parse(content);
-      return typeof parsed === "object" && parsed !== null
-        ? (parsed as Record<string, unknown>)
-        : null;
-    } catch {
-      return null;
-    }
-  }
-  return null;
-}
-
-export interface MailBridgeOptions {
-  connection: MailBridgeConnection;
-  inboxAdapter: InboxAdapter;
-  /**
-   * The dispatcher agent ID used by swarm-dispatch's createAgentInboxPort.
-   * Messages must be delivered TO this ID so the MessagePort's onIncoming
-   * filter (event.agentId === dispatcherAgentId) fires correctly.
-   * When omitted the bridge falls back to BRIDGE_RECIPIENT_ID (inert —
-   * the MessagePort will never see the message).
-   */
-  dispatcherAgentId?: string;
-  /**
-   * Optional logger for diagnostic output. The sidecar currently logs via
-   * console; swap if you want structured output.
-   */
-  log?: (msg: string) => void;
-}
-
-/**
- * Wire the mail bridge. Returns a cleanup function that detaches the
- * notification handler.
- *
- * Idempotent registration: register is called exactly once; the handler
- * itself is best-effort (errors are caught and logged so a malformed turn
- * doesn't break subsequent ones).
- */
-export async function setupMailBridge(
-  opts: MailBridgeOptions,
-): Promise<() => void> {
-  const { connection, inboxAdapter, dispatcherAgentId, log = () => {} } = opts;
-
-  // Determine the inbox recipient. When a dispatcherAgentId is provided we
-  // deliver directly to the dispatcher so createAgentInboxPort.onIncoming
-  // (which filters event.agentId === dispatcherAgentId) picks it up.
-  const recipientId = dispatcherAgentId ?? BRIDGE_RECIPIENT_ID;
-
-  // Register the recipient on the local inbox so routeMessage accepts the
-  // forwarded turn. Idempotent — registerAgent putAgent is an upsert.
-  await inboxAdapter.registerAgent(recipientId, {
-    name: dispatcherAgentId ? "OpenHive Dispatcher (bridged)" : "OpenHive Mail Bridge",
-    role: dispatcherAgentId ? "dispatcher" : "mail-bridge",
-    scope: "default",
-    metadata: { source: "openhive-mail-forward" },
-  });
-
-  const handler = async (params: unknown): Promise<void> => {
-    const turn = (params ?? {}) as MailTurnReceivedParams;
-    const raw = parseTurnContent(turn.content, turn.content_type);
-    if (!raw) {
-      log(
-        `[mail-bridge] Dropping non-JSON turn (conv=${turn.conversation_id ?? "?"} ` +
-          `participant=${turn.participant_id ?? "?"})`,
-      );
-      return;
-    }
-
-    // Translate hub envelope shape { type, body } → canonical inbox shape
-    // { schema, data } that classifyMessage in boot-v2 expects.
-    // Hub sends: { type: "x-dispatch/work", body: { prompt, taskId, role } }
-    // Classifier expects: { schema: "x-dispatch/work", data: { prompt, taskId, role } }
-    const hubType = (raw as { type?: string }).type;
-    const hubBody = (raw as { body?: Record<string, unknown> }).body;
-    const content: Record<string, unknown> =
-      hubType && hubBody
-        ? { schema: hubType, data: hubBody }
-        : raw;
-
-    // Attach conversation_id as a top-level field in the payload so
-    // the mail-inbound consumer can thread it into the worker spawn.
-    // This lets the reply bridge look up which hub conversation to post
-    // the worker's output back to.
-    //
-    // IMPORTANT: include `type: "data"` so agent-inbox's normalizeContent()
-    // passes the object through unchanged. Without it, an object lacking
-    // a `type` string is re-wrapped as `{ type:"data", data: original }`,
-    // burying `schema` one level deeper and breaking the consumer's filter.
-    const contentWithConvId: Record<string, unknown> = {
-      type: "data",
-      ...content,
-      ...(turn.conversation_id ? { _conversationId: turn.conversation_id } : {}),
-    };
-
-    // Derive importance from the hub's wire params. Default to "normal"
-    // when the hub doesn't tag the turn (backward compat).
-    const VALID_IMPORTANCE = ["low", "normal", "high", "urgent"];
-    const wireImportance =
-      typeof turn.importance === "string" &&
-      VALID_IMPORTANCE.includes(turn.importance)
-        ? (turn.importance as "low" | "normal" | "high" | "urgent")
-        : "normal";
-
-    try {
-      await inboxAdapter.send(
-        turn.participant_id ?? "openhive-hub",
-        recipientId,
-        contentWithConvId as never,
-        {
-          threadTag: turn.thread_id,
-          importance: wireImportance,
-        },
-      );
-      log(
-        `[mail-bridge] Forwarded turn ${turn.turn_id ?? "?"} into local inbox ` +
-          `(schema=${(content as { schema?: string }).schema ?? "n/a"})`,
-      );
-    } catch (err) {
-      log(
-        `[mail-bridge] Forward failed for turn ${turn.turn_id ?? "?"}: ` +
-          `${(err as Error).message}`,
-      );
-    }
-  };
-
-  connection.onNotification("mail/turn.received", handler);
-
-  return () => {
-    try {
-      connection.offNotification("mail/turn.received", handler);
-    } catch {
-      // best effort
-    }
-  };
-}