macro-agent 0.1.1 → 0.1.3

package/src/acp/map-bridge.ts

@@ -0,0 +1,193 @@
+/**
+ * MAP Protocol Bridge
+ *
+ * Exposes MAP-compatible JSON-RPC methods on top of InboxAdapter,
+ * allowing external MAP clients to interact with the macro-agent
+ * messaging system.
+ *
+ * Since agent-inbox already speaks MAP natively (via MapClient),
+ * this bridge translates MAP send/inbox/thread commands to
+ * InboxAdapter calls and returns messages in MAP-compatible format.
+ *
+ * @module acp/map-bridge
+ */
+
+import type { InboxAdapter } from "../adapters/types.js";
+import type { AgentStore } from "../agent/agent-store.js";
+
+// ─────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────
+
+export interface MAPBridgeConfig {
+  /** Default scope for MAP messages. */
+  scope?: string;
+}
+
+export interface MAPBridgeDeps {
+  inboxAdapter: InboxAdapter;
+  agentStore: AgentStore;
+}
+
+/**
+ * MAP-compatible message format returned by the bridge.
+ */
+export interface MAPMessage {
+  id: string;
+  from: string;
+  to: string | string[];
+  payload: unknown;
+  timestamp: string;
+  meta?: Record<string, unknown>;
+}
+
+/**
+ * MAP Bridge instance exposing JSON-RPC-style method handlers.
+ */
+export interface MAPBridge {
+  /**
+   * Handle a MAP JSON-RPC request.
+   * Supports methods: mail/send, mail/inbox, mail/thread, mail/agents
+   */
+  handleRequest(method: string, params: Record<string, unknown>): Promise<unknown>;
+
+  /** List supported MAP methods. */
+  listMethods(): string[];
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Factory
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Create a MAP protocol bridge that translates MAP JSON-RPC methods
+ * to InboxAdapter calls.
+ *
+ * Supported methods:
+ * - `mail/send` — Send a message via InboxAdapter
+ * - `mail/inbox` — Check an agent's inbox
+ * - `mail/thread` — Read a message thread
+ * - `mail/agents` — List registered agents
+ *
+ * TODO: Full MAP SDK integration when @multi-agent-protocol/sdk
+ * is available as a peer dependency. Currently this is a lightweight
+ * compatibility layer for basic MAP interop.
+ */
+export function createMAPBridge(
+  deps: MAPBridgeDeps,
+  config: MAPBridgeConfig = {}
+): MAPBridge {
+  const { inboxAdapter, agentStore } = deps;
+  const scope = config.scope ?? "default";
+
+  const methods: Record<string, (params: Record<string, unknown>) => Promise<unknown>> = {
+    "mail/send": async (params) => {
+      const from = params.from as string;
+      const to = params.to as string | string[];
+      const payload = params.payload;
+      const meta = params.meta as Record<string, unknown> | undefined;
+
+      if (!from || !to) {
+        throw new Error("mail/send requires 'from' and 'to' parameters");
+      }
+
+      const content = typeof payload === "string"
+        ? { type: "text" as const, text: payload }
+        : payload as { type: string; text: string };
+
+      const messageId = await inboxAdapter.send(from, to, content, {
+        scope: (meta?.scope as string) ?? scope,
+        importance: meta?.priority === "high" ? "high" : "normal",
+        subject: meta?.subject as string | undefined,
+        threadTag: meta?.threadTag as string | undefined,
+        inReplyTo: meta?.inReplyTo as string | undefined,
+      });
+
+      return { messageId, success: true };
+    },
+
+    "mail/inbox": async (params) => {
+      const agentId = params.agentId as string;
+      if (!agentId) {
+        throw new Error("mail/inbox requires 'agentId' parameter");
+      }
+
+      const limit = params.limit as number | undefined;
+      const unreadOnly = params.unreadOnly as boolean | undefined;
+
+      const messages = await inboxAdapter.checkInbox(agentId, {
+        limit,
+        unreadOnly,
+      });
+
+      return {
+        messages: messages.map((msg) => toMAPMessage(msg)),
+        count: messages.length,
+      };
+    },
+
+    "mail/thread": async (params) => {
+      const threadTag = params.threadTag as string;
+      if (!threadTag) {
+        throw new Error("mail/thread requires 'threadTag' parameter");
+      }
+
+      const threadScope = (params.scope as string) ?? scope;
+      const messages = await inboxAdapter.readThread(threadTag, threadScope);
+
+      return {
+        messages: messages.map((msg) => toMAPMessage(msg)),
+        count: messages.length,
+      };
+    },
+
+    "mail/agents": async (_params) => {
+      const agents = agentStore.listAgents({ state: "running" });
+      return {
+        agents: agents.map((a) => ({
+          agentId: a.id,
+          name: a.name,
+          role: a.role,
+          scope: a.scope,
+          state: a.state,
+        })),
+        count: agents.length,
+      };
+    },
+  };
+
+  function toMAPMessage(msg: {
+    id?: string;
+    sender_id?: string;
+    recipients?: Array<{ agent_id: string }>;
+    content?: unknown;
+    created_at?: string | number;
+    metadata?: Record<string, unknown>;
+  }): MAPMessage {
+    const recipients = msg.recipients?.map((r) => r.agent_id) ?? [];
+    return {
+      id: msg.id ?? "",
+      from: msg.sender_id ?? "",
+      to: recipients.length === 1 ? recipients[0] : recipients,
+      payload: msg.content,
+      timestamp: typeof msg.created_at === "number"
+        ? new Date(msg.created_at).toISOString()
+        : (msg.created_at as string) ?? new Date().toISOString(),
+      meta: msg.metadata,
+    };
+  }
+
+  return {
+    async handleRequest(method: string, params: Record<string, unknown>): Promise<unknown> {
+      const handler = methods[method];
+      if (!handler) {
+        throw new Error(`Unknown MAP method: ${method}. Supported: ${Object.keys(methods).join(", ")}`);
+      }
+      return handler(params);
+    },
+
+    listMethods(): string[] {
+      return Object.keys(methods);
+    },
+  };
+}

package/src/acp/session-mapper.ts

@@ -1,349 +1,116 @@
 /**
- * SessionMapper - Maps ACP sessions to macro-agent agents
+ * SessionMapper — In-memory ACP session ↔ agent mapping.
  *
- * Tracks the relationship between ACP session IDs and the macro-agent
- * agents they control. Supports:
- * - Default mapping to head manager on session creation
- * - Remapping via mount to control different agents
- * - Multiple concurrent sessions with independent mappings
- * - Persistent session lifecycle events via EventStore
- * - Recovery of session state from EventStore after restart
+ * Tracks which macro-agent agent each ACP session is currently
+ * pointing at. Supports mount/unmount for switching between
+ * the head manager and child agents within a single session.
+ *
+ * No persistence needed — mappings are ephemeral per-connection.
+ *
+ * @module acp/session-mapper
  */
 
-import type { AgentId } from "../store/types/index.js";
-import type { EventStore } from "../store/event-store.js";
 import type { ACPSessionId, SessionMapping } from "./types.js";
-import { ACPError } from "./types.js";
 
 export class SessionMapper {
-  /** Map of ACP session ID to mapping info */
-  private mappings: Map<ACPSessionId, SessionMapping> = new Map();
-
-  /** Optional EventStore for persisting session lifecycle events */
-  private eventStore: EventStore | null;
-
-  constructor(eventStore?: EventStore) {
-    this.eventStore = eventStore ?? null;
-  }
+  private readonly mappings = new Map<ACPSessionId, SessionMapping>();
 
   /**
-   * Register a new ACP session with its head manager
-   *
-   * @param acpSessionId - The ACP session ID
-   * @param headManagerId - The head manager agent ID for this session
-   * @returns The created mapping
+   * Create a new session mapping.
+   * Initially points at the head manager.
    */
-  createMapping(
-    acpSessionId: ACPSessionId,
-    headManagerId: AgentId
-  ): SessionMapping {
-    const now = Date.now();
+  createMapping(acpSessionId: ACPSessionId, headManagerId: string): SessionMapping {
     const mapping: SessionMapping = {
       acpSessionId,
       agentId: headManagerId,
       headManagerId,
       isMounted: false,
-      createdAt: now,
-      updatedAt: now,
+      createdAt: Date.now(),
       isProcessing: false,
-      lastProcessingChangeAt: now,
     };
-
     this.mappings.set(acpSessionId, mapping);
-
-    // Persist session creation event
-    this.emitSessionEvent("created", acpSessionId, {
-      head_manager_id: headManagerId,
-    });
-
     return mapping;
   }
 
   /**
-   * Get the mapping for an ACP session
-   *
-   * @param acpSessionId - The ACP session ID
-   * @returns The mapping or undefined if not found
+   * Get the full mapping for a session.
    */
   getMapping(acpSessionId: ACPSessionId): SessionMapping | undefined {
     return this.mappings.get(acpSessionId);
   }
 
   /**
-   * Get the mapping for an ACP session, throwing if not found
-   *
-   * @param acpSessionId - The ACP session ID
-   * @returns The mapping
-   * @throws ACPError if session not found
-   */
-  getMappingOrThrow(acpSessionId: ACPSessionId): SessionMapping {
-    const mapping = this.mappings.get(acpSessionId);
-    if (!mapping) {
-      throw new ACPError(
-        `ACP session not found: ${acpSessionId}`,
-        "SESSION_NOT_FOUND",
-        { acpSessionId }
-      );
-    }
-    return mapping;
-  }
-
-  /**
-   * Get the currently mapped agent ID for a session
-   *
-   * @param acpSessionId - The ACP session ID
-   * @returns The agent ID or undefined if session not found
+   * Get the currently active agent ID for a session.
    */
-  getAgentId(acpSessionId: ACPSessionId): AgentId | undefined {
+  getAgentId(acpSessionId: ACPSessionId): string | undefined {
     return this.mappings.get(acpSessionId)?.agentId;
   }
 
   /**
-   * Get the currently mapped agent ID, throwing if not found
-   *
-   * @param acpSessionId - The ACP session ID
-   * @returns The agent ID
-   * @throws ACPError if session not found
+   * Get the head manager ID for a session.
    */
-  getAgentIdOrThrow(acpSessionId: ACPSessionId): AgentId {
-    const mapping = this.getMappingOrThrow(acpSessionId);
-    return mapping.agentId;
-  }
-
-  /**
-   * Get the head manager for a session
-   *
-   * @param acpSessionId - The ACP session ID
-   * @returns The head manager agent ID or undefined
-   */
-  getHeadManagerId(acpSessionId: ACPSessionId): AgentId | undefined {
+  getHeadManagerId(acpSessionId: ACPSessionId): string | undefined {
     return this.mappings.get(acpSessionId)?.headManagerId;
   }
 
   /**
-   * Mount a session to a different agent
-   *
-   * This changes which agent receives prompts for this session.
-   * The original head manager is preserved for unmounting.
-   *
-   * @param acpSessionId - The ACP session ID
-   * @param agentId - The agent ID to mount to
-   * @returns The previous agent ID
-   * @throws ACPError if session not found
+   * Mount a different agent onto this session.
+   * Returns the previous agent ID (for logging/debugging).
    */
-  mount(acpSessionId: ACPSessionId, agentId: AgentId): AgentId {
-    const mapping = this.getMappingOrThrow(acpSessionId);
-    const previousAgentId = mapping.agentId;
+  mount(acpSessionId: ACPSessionId, agentId: string): string | undefined {
+    const mapping = this.mappings.get(acpSessionId);
+    if (!mapping) return undefined;
 
+    const previousAgentId = mapping.agentId;
     mapping.agentId = agentId;
-    mapping.isMounted = agentId !== mapping.headManagerId;
-    mapping.updatedAt = Date.now();
-
-    // Persist mount event
-    if (mapping.isMounted) {
-      this.emitSessionEvent("mounted", acpSessionId, {
-        target_agent_id: agentId,
-        previous_agent_id: previousAgentId,
-      });
-    } else {
-      // Mounting back to head manager is effectively an unmount
-      this.emitSessionEvent("unmounted", acpSessionId, {
-        previous_agent_id: previousAgentId,
-      });
-    }
-
+    mapping.isMounted = true;
     return previousAgentId;
   }
 
   /**
-   * Unmount a session back to its head manager
-   *
-   * @param acpSessionId - The ACP session ID
-   * @returns The previous agent ID (the one that was mounted)
-   * @throws ACPError if session not found
+   * Unmount the current agent, restoring the head manager.
+   * Returns the agent ID that was unmounted.
    */
-  unmount(acpSessionId: ACPSessionId): AgentId {
-    const mapping = this.getMappingOrThrow(acpSessionId);
-    const previousAgentId = mapping.agentId;
+  unmount(acpSessionId: ACPSessionId): string | undefined {
+    const mapping = this.mappings.get(acpSessionId);
+    if (!mapping) return undefined;
 
+    const unmountedAgentId = mapping.agentId;
     mapping.agentId = mapping.headManagerId;
     mapping.isMounted = false;
-    mapping.updatedAt = Date.now();
-
-    // Persist unmount event
-    this.emitSessionEvent("unmounted", acpSessionId, {
-      previous_agent_id: previousAgentId,
-    });
-
-    return previousAgentId;
-  }
-
-  /**
-   * Check if a session is mounted to a non-head-manager agent
-   *
-   * @param acpSessionId - The ACP session ID
-   * @returns True if mounted, false otherwise
-   */
-  isMounted(acpSessionId: ACPSessionId): boolean {
-    return this.mappings.get(acpSessionId)?.isMounted ?? false;
+    return unmountedAgentId;
   }
 
   /**
-   * Remove a session mapping and emit a close event
-   *
-   * @param acpSessionId - The ACP session ID
-   * @returns True if removed, false if not found
+   * Remove a session mapping entirely.
    */
   removeMapping(acpSessionId: ACPSessionId): boolean {
-    const existed = this.mappings.has(acpSessionId);
-    if (existed) {
-      // Persist close event before removing
-      this.emitSessionEvent("closed", acpSessionId, {});
-    }
     return this.mappings.delete(acpSessionId);
   }
 
   /**
-   * Get all session mappings
-   *
-   * @returns Array of all mappings
-   */
-  getAllMappings(): SessionMapping[] {
-    return Array.from(this.mappings.values());
-  }
-
-  /**
-   * Get all sessions mapped to a specific agent
-   *
-   * @param agentId - The agent ID to find sessions for
-   * @returns Array of ACP session IDs mapped to this agent
-   */
-  getSessionsForAgent(agentId: AgentId): ACPSessionId[] {
-    const sessions: ACPSessionId[] = [];
-    for (const [sessionId, mapping] of this.mappings) {
-      if (mapping.agentId === agentId) {
-        sessions.push(sessionId);
-      }
-    }
-    return sessions;
-  }
-
-  /**
-   * Update the processing status of a session
-   *
-   * Called when a prompt starts (isProcessing=true) or ends (isProcessing=false).
-   * Used by health monitoring to detect idle vs active sessions.
-   *
-   * @param acpSessionId - The ACP session ID
-   * @param isProcessing - Whether the session is currently processing a prompt
+   * Set the processing (prompting) status for a session.
    */
   setProcessing(acpSessionId: ACPSessionId, isProcessing: boolean): void {
     const mapping = this.mappings.get(acpSessionId);
-    if (mapping && mapping.isProcessing !== isProcessing) {
+    if (mapping) {
       mapping.isProcessing = isProcessing;
-      mapping.lastProcessingChangeAt = Date.now();
-      mapping.updatedAt = Date.now();
-    }
-  }
-
-  /**
-   * Get the session status for an agent (for health monitoring)
-   *
-   * @param agentId - The agent ID to get session status for
-   * @returns Session status or undefined if no session mapped
-   */
-  getSessionStatus(agentId: AgentId): { isProcessing: boolean; sessionId: ACPSessionId; lastProcessingChangeAt: number } | undefined {
-    for (const [sessionId, mapping] of this.mappings) {
-      if (mapping.agentId === agentId) {
-        return {
-          isProcessing: mapping.isProcessing,
-          sessionId,
-          lastProcessingChangeAt: mapping.lastProcessingChangeAt,
-        };
-      }
-    }
-    return undefined;
-  }
-
-  /**
-   * Recover session mappings from the EventStore.
-   *
-   * Loads all non-closed sessions and rebuilds the in-memory mapping state.
-   * Called during initialization to restore sessions after a restart.
-   *
-   * @returns Number of sessions recovered
-   */
-  recoverFromStore(): number {
-    if (!this.eventStore || typeof this.eventStore.listSessions !== "function") {
-      return 0;
     }
-
-    const activeSessions = this.eventStore.listSessions({ state: "active" });
-    const mountedSessions = this.eventStore.listSessions({ state: "mounted" });
-    const allSessions = [...activeSessions, ...mountedSessions];
-
-    let recovered = 0;
-    for (const session of allSessions) {
-      const now = Date.now();
-      const mapping: SessionMapping = {
-        acpSessionId: session.id,
-        agentId: session.current_agent_id,
-        headManagerId: session.head_manager_id,
-        isMounted: session.state === "mounted",
-        createdAt: session.created_at,
-        updatedAt: now,
-        isProcessing: false,
-        lastProcessingChangeAt: now,
-      };
-      this.mappings.set(session.id, mapping);
-      recovered++;
-    }
-
-    return recovered;
   }
 
   /**
-   * Get the number of active session mappings
+   * Get all active session mappings.
    */
-  get size(): number {
-    return this.mappings.size;
-  }
-
-  /**
-   * Clear all session mappings
-   */
-  clear(): void {
-    this.mappings.clear();
+  getAllMappings(): SessionMapping[] {
+    return Array.from(this.mappings.values());
   }
 
   /**
-   * Emit a session lifecycle event to the EventStore
+   * Get all sessions currently pointing at a given agent ID.
    */
-  private emitSessionEvent(
-    action: string,
-    sessionId: ACPSessionId,
-    details: Record<string, unknown>
-  ): void {
-    if (!this.eventStore || typeof this.eventStore.emit !== "function") {
-      return;
-    }
-
-    try {
-      this.eventStore.emit({
-        type: "session",
-        source: {},
-        payload: {
-          action,
-          session_id: sessionId,
-          ...details,
-        },
-      });
-    } catch (error) {
-      // Log but don't fail — session events are supplementary
-      console.warn(
-        `[SessionMapper] Failed to emit session ${action} event:`,
-        error instanceof Error ? error.message : String(error)
-      );
-    }
+  getSessionsForAgent(agentId: string): SessionMapping[] {
+    return Array.from(this.mappings.values()).filter(
+      (m) => m.agentId === agentId,
+    );
   }
 }