macro-agent 0.2.4 → 0.2.6

package/dist/map/adapter/map-adapter.js

@@ -0,0 +1,1199 @@
+/**
+ * MAPAdapter - External MAP Protocol Interface
+ *
+ * ## Routing Architecture Role
+ *
+ * MAPAdapter is the **external protocol translation layer** for MAP clients.
+ * It translates MAP protocol messages into internal routing calls.
+ *
+ * ```
+ * External → MAPAdapter → MessageRouter → EventStore
+ * (MAP RPC)   (this)      (routing)       (persistence)
+ * ```
+ *
+ * **Responsibilities:**
+ * - Accept MAP protocol connections (JSON-RPC over WebSocket/streams)
+ * - Manage participant lifecycle (connect, disconnect, capabilities)
+ * - Handle authentication and permission enforcement (Layer 1)
+ * - Translate MAP addresses to internal routing
+ * - Stream events to subscribed participants
+ * - Dispatch extension method calls (spawn, wake, tasks, etc.)
+ *
+ * **Delegates to internal components:**
+ * - MessageRouter: For message routing and delivery (sendToAddress)
+ * - AgentManager: For agent lifecycle operations
+ * - EventStore: For event persistence and subscription
+ *
+ * **Not responsible for:**
+ * - Internal agent-to-agent messaging (use MessageRouter directly)
+ * - Batch event delivery (use TriggerRouter/WakeManager)
+ * - Legacy channel-based routing (use MessageRouter.send())
+ *
+ * @see specs/s-5qir_map_integration_for_macro_agent.md
+ */
+import { ulid } from "ulid";
+import { isAgentAddress, } from "../types.js";
+import { createConnectionManager, } from "./connection-manager.js";
+import { createSubscriptionManager, } from "./subscription-manager.js";
+import { createRPCHandler, RPCError, createCapabilityMiddleware, createNotification, } from "./rpc-handler.js";
+import { EXTENSION_CAPABILITIES } from "./extensions/index.js";
+import { ACPOverMAPHandler } from "./acp-over-map.js";
+import { createMailHandlers } from "./mail-handler-adapter.js";
+import { EventLog, dotToUnderscore } from "./event-log.js";
+// =============================================================================
+// MAPAdapter Implementation
+// =============================================================================
+/**
+ * MAPAdapter implementation.
+ */
+export class MAPAdapterImpl {
+    config;
+    connections;
+    subscriptions;
+    sessions = new Map();
+    extensions = new Map();
+    scopes = new Map();
+    eventHandlers = new Set();
+    services;
+    acpOverMapHandler = null;
+    /** Sequence numbers per subscription for proper event ordering */
+    subscriptionSequences = new Map();
+    /** In-memory event log for map/replay support */
+    eventLog;
+    running = false;
+    constructor(config = {}, services = {}) {
+        this.config = {
+            name: config.name ?? "macro-agent",
+            version: config.version ?? "1.0.0",
+            ...config,
+        };
+        this.services = services;
+        // Initialize ACP-over-MAP handler if services are available
+        if (services.agentManager && services.eventStore && services.taskManager) {
+            this.acpOverMapHandler = new ACPOverMAPHandler({
+                agentManager: services.agentManager,
+                eventStore: services.eventStore,
+                taskManager: services.taskManager,
+                defaultCwd: services.defaultCwd,
+                // Note: agent_registered events are now emitted by the lifecycle
+                // listener below, which covers ALL spawn paths (ACP, MCP, etc.)
+            });
+            console.error("[MAPAdapter] ACP-over-MAP handler initialized");
+        }
+        // Listen for agent lifecycle events so spawns/stops happening in THIS
+        // process (main server) emit MAP events to subscribers immediately.
+        if (services.agentManager) {
+            services.agentManager.onLifecycleEvent((event) => {
+                if (event.type === "spawned" && event.agent) {
+                    const agentId = event.agent.id;
+                    this.emitEvent({
+                        eventId: ulid(),
+                        type: "agent_registered",
+                        timestamp: Date.now(),
+                        agentId,
+                        data: {
+                            agentId: event.agent.id,
+                            name: event.agent.name ?? "",
+                            role: event.agent.role ?? "worker",
+                            state: event.agent.state ?? "spawning",
+                            parent: event.agent.parent ?? undefined,
+                            metadata: event.agent.metadata ?? {},
+                        },
+                    });
+                }
+                else if (event.type === "stopped" && event.agent) {
+                    const agentId = event.agent.id;
+                    this.emitEvent({
+                        eventId: ulid(),
+                        type: "agent_state_changed",
+                        timestamp: Date.now(),
+                        agentId,
+                        data: {
+                            agentId: event.agent.id,
+                            current: "stopped",
+                            previous: "running",
+                            reason: event.reason,
+                        },
+                    });
+                    this.emitEvent({
+                        eventId: ulid(),
+                        type: "agent_unregistered",
+                        timestamp: Date.now(),
+                        agentId,
+                        data: {
+                            agentId: event.agent.id,
+                            reason: event.reason,
+                        },
+                    });
+                }
+            });
+        }
+        // Listen for EventStore task changes to emit MAP task events.
+        // Task mutations from MCP bridge handlers run in-process, so
+        // onTaskChange fires immediately when tasks are created/updated.
+        if (services.eventStore) {
+            services.eventStore.onTaskChange((taskId, task) => {
+                if (!task)
+                    return;
+                // Map task status to MAP event type
+                const eventTypeMap = {
+                    pending: "task_created",
+                    assigned: "task_assigned",
+                    in_progress: "task_assigned",
+                    completed: "task_completed",
+                    failed: "task_failed",
+                    // OpenTasks statuses (defensive — normally mapped before reaching here)
+                    closed: "task_completed",
+                    open: "task_created",
+                };
+                const mapEventType = eventTypeMap[task.status];
+                if (mapEventType) {
+                    this.emitEvent({
+                        eventId: ulid(),
+                        type: mapEventType,
+                        timestamp: Date.now(),
+                        agentId: (task.assigned_agent ?? undefined),
+                        data: {
+                            taskId,
+                            description: task.description,
+                            status: task.status,
+                            assignee: task.assigned_agent,
+                        },
+                    });
+                }
+            });
+        }
+        // Initialize connection manager
+        this.connections = createConnectionManager({
+            limits: config.limits,
+            anonymousCapabilities: config.anonymousCapabilities,
+            defaultClientCapabilities: config.defaultClientCapabilities,
+            defaultAgentCapabilities: config.defaultAgentCapabilities,
+        });
+        // Initialize subscription manager
+        this.subscriptions = createSubscriptionManager({
+            limits: config.limits,
+            getAncestors: services.getAncestors,
+            getDescendants: services.getDescendants,
+        });
+        // Initialize event log for replay support
+        this.eventLog = new EventLog({
+            maxSize: config.limits?.maxReplayBufferSize ?? 10_000,
+        });
+        // Forward connection events
+        this.connections.onEvent((event) => {
+            if (event.type === "participant.connected") {
+                this.emitAdapterEvent({
+                    type: "participant.connected",
+                    participant: event.participant,
+                });
+            }
+            else if (event.type === "participant.disconnected") {
+                this.emitAdapterEvent({
+                    type: "participant.disconnected",
+                    participantId: event.participantId,
+                    reason: event.reason,
+                });
+            }
+        });
+        // Forward subscription events
+        this.subscriptions.onEvent((event) => {
+            if (event.type === "subscription.created") {
+                this.emitAdapterEvent({
+                    type: "subscription.created",
+                    subscriptionId: event.subscription.id,
+                });
+            }
+            else if (event.type === "subscription.removed") {
+                this.emitAdapterEvent({
+                    type: "subscription.removed",
+                    subscriptionId: event.subscriptionId,
+                });
+            }
+        });
+    }
+    // ===========================================================================
+    // Connection Management
+    // ===========================================================================
+    async acceptConnection(stream) {
+        if (!this.running) {
+            throw new Error("Adapter not running");
+        }
+        // Create participant with default client type (will be updated after connect handshake)
+        const participant = this.connections.connect({
+            type: "client",
+        });
+        // Create RPC handler for this connection
+        const rpcHandler = this.createRPCHandler(participant.id);
+        // Get writer for sending responses
+        const writer = stream.writable.getWriter();
+        // Create abort controller for this session
+        const abortController = new AbortController();
+        // Track session
+        const session = {
+            participantId: participant.id,
+            participant,
+            rpcHandler,
+            stream,
+            writer,
+            abortController,
+        };
+        this.sessions.set(participant.id, session);
+        // Start message processing
+        this.processMessages(session).catch((error) => {
+            if (!abortController.signal.aborted) {
+                console.error("[MAPAdapter] Message processing error:", error);
+                this.disconnectParticipant(participant.id, "processing_error");
+            }
+        });
+        return participant;
+    }
+    async disconnectParticipant(id, reason) {
+        const session = this.sessions.get(id);
+        if (!session) {
+            return;
+        }
+        // Abort message processing
+        session.abortController.abort();
+        // Clean up subscriptions
+        this.subscriptions.removeAllForParticipant(id);
+        // Close writer
+        try {
+            session.writer.releaseLock();
+            const writer = session.stream.writable.getWriter();
+            await writer.close();
+        }
+        catch {
+            // Ignore close errors
+        }
+        // Remove session
+        this.sessions.delete(id);
+        // Disconnect from connection manager
+        this.connections.disconnect(id, reason);
+    }
+    getParticipants() {
+        return this.connections.getParticipants();
+    }
+    getParticipant(id) {
+        return this.connections.getParticipant(id);
+    }
+    // ===========================================================================
+    // Messaging
+    // ===========================================================================
+    async sendMessage(participantId, to, payload, options) {
+        const participant = this.connections.getParticipant(participantId);
+        if (!participant) {
+            throw RPCError.notFound("participant", participantId);
+        }
+        if (!participant.capabilities.canMessage) {
+            throw RPCError.permissionDenied("Messaging not allowed");
+        }
+        // For external clients, use a virtual sender ID
+        const senderId = `external:${participantId}`;
+        if (!this.services.sendMessage) {
+            throw RPCError.internalError("Message routing not available");
+        }
+        const result = await this.services.sendMessage(senderId, to, typeof payload.content === "string"
+            ? payload.content
+            : JSON.stringify(payload.content), options);
+        return {
+            messageId: `msg-${ulid()}`,
+            delivered: result.delivered,
+        };
+    }
+    // ===========================================================================
+    // Subscriptions
+    // ===========================================================================
+    async createSubscription(participantId, filter) {
+        const participant = this.connections.getParticipant(participantId);
+        if (!participant) {
+            throw RPCError.notFound("participant", participantId);
+        }
+        if (!participant.capabilities.canSubscribe) {
+            throw RPCError.permissionDenied("Subscriptions not allowed");
+        }
+        return this.subscriptions.subscribe(participantId, filter);
+    }
+    async removeSubscription(subscriptionId) {
+        this.subscriptions.unsubscribe(subscriptionId);
+        this.subscriptionSequences.delete(subscriptionId);
+    }
+    getSubscriptions(participantId) {
+        return this.subscriptions.getSubscriptionIds(participantId);
+    }
+    async pauseSubscription(subscriptionId) {
+        this.subscriptions.pause(subscriptionId);
+    }
+    async resumeSubscription(subscriptionId) {
+        this.subscriptions.resume(subscriptionId);
+    }
+    // ===========================================================================
+    // Queries
+    // ===========================================================================
+    listAgents(participantId, filter) {
+        const participant = this.connections.getParticipant(participantId);
+        if (!participant) {
+            return [];
+        }
+        if (!participant.capabilities.canQuery) {
+            return [];
+        }
+        if (!this.services.listAgents) {
+            return [];
+        }
+        const agents = this.services.listAgents(filter);
+        return agents.map((agent) => this.toAgentInfo(agent));
+    }
+    getAgent(participantId, agentId) {
+        const participant = this.connections.getParticipant(participantId);
+        if (!participant) {
+            return undefined;
+        }
+        if (!participant.capabilities.canQuery) {
+            return undefined;
+        }
+        if (!this.services.getAgent) {
+            return undefined;
+        }
+        const agent = this.services.getAgent(agentId);
+        return agent ? this.toAgentInfo(agent) : undefined;
+    }
+    listScopes(participantId) {
+        const participant = this.connections.getParticipant(participantId);
+        if (!participant) {
+            return [];
+        }
+        if (!participant.capabilities.canQuery) {
+            return [];
+        }
+        return Array.from(this.scopes.values()).map((scope) => this.toScopeInfo(scope));
+    }
+    getScope(participantId, scopeId) {
+        const participant = this.connections.getParticipant(participantId);
+        if (!participant) {
+            return undefined;
+        }
+        if (!participant.capabilities.canQuery) {
+            return undefined;
+        }
+        const scope = this.scopes.get(scopeId);
+        return scope ? this.toScopeInfo(scope) : undefined;
+    }
+    // ===========================================================================
+    // Events
+    // ===========================================================================
+    emitEvent(event) {
+        // Log event for replay support
+        this.eventLog.append({
+            eventId: event.eventId,
+            timestamp: event.timestamp,
+            type: event.type,
+            data: event.data,
+            causedBy: event.causedBy,
+            agentId: event.agentId,
+            scopeId: event.scopeId,
+        });
+        // Match event against subscriptions
+        const { subscriptions: matchingSubs } = this.subscriptions.match(event);
+        // Send to each matched subscription with proper SDK format
+        // SDK EventNotificationParams: { subscriptionId, sequenceNumber, eventId?, timestamp?, event, causedBy? }
+        for (const subscription of matchingSubs) {
+            const session = this.sessions.get(subscription.participantId);
+            if (session) {
+                // Get and increment sequence number for this subscription
+                const currentSeq = this.subscriptionSequences.get(subscription.id) ?? 0;
+                this.subscriptionSequences.set(subscription.id, currentSeq + 1);
+                // Build params in SDK EventNotificationParams format
+                const params = {
+                    subscriptionId: subscription.id,
+                    sequenceNumber: currentSeq,
+                    eventId: event.eventId, // For deduplication
+                    timestamp: event.timestamp, // Envelope timestamp
+                    event: {
+                        // The actual event object
+                        id: event.eventId,
+                        type: event.type,
+                        timestamp: event.timestamp,
+                        data: event.data,
+                    },
+                    ...(event.causedBy && { causedBy: event.causedBy }),
+                };
+                const notification = createNotification("map/event", params);
+                this.sendToSession(session, notification).catch((error) => {
+                    console.error("[MAPAdapter] Failed to send event:", error);
+                });
+            }
+        }
+    }
+    onEvent(handler) {
+        this.eventHandlers.add(handler);
+        return () => this.eventHandlers.delete(handler);
+    }
+    // ===========================================================================
+    // Extensions
+    // ===========================================================================
+    registerExtension(method, handler) {
+        if (!method.startsWith("_macro/")) {
+            throw new Error(`Extension method must start with "_macro/": ${method}`);
+        }
+        this.extensions.set(method, handler);
+    }
+    unregisterExtension(method) {
+        this.extensions.delete(method);
+    }
+    getExtensions() {
+        return Array.from(this.extensions.keys());
+    }
+    hasExtension(method) {
+        return this.extensions.has(method);
+    }
+    // ===========================================================================
+    // Lifecycle
+    // ===========================================================================
+    async start() {
+        if (this.running) {
+            return;
+        }
+        this.running = true;
+    }
+    async stop(graceful = true) {
+        if (!this.running) {
+            return;
+        }
+        this.running = false;
+        // Disconnect all participants
+        const reason = graceful ? "server_shutdown" : "server_stopped";
+        this.connections.disconnectAll(reason);
+        // Clear sessions
+        for (const session of this.sessions.values()) {
+            session.abortController.abort();
+        }
+        this.sessions.clear();
+    }
+    isRunning() {
+        return this.running;
+    }
+    // ===========================================================================
+    // Scope Management (internal)
+    // ===========================================================================
+    /**
+     * Create a scope (internal use by RPC handlers).
+     */
+    createScope(name, metadata) {
+        const id = `scope-${ulid()}`;
+        this.scopes.set(id, {
+            id,
+            name,
+            members: new Set(),
+            createdAt: Date.now(),
+            metadata,
+        });
+        return id;
+    }
+    /**
+     * Delete a scope.
+     */
+    deleteScope(scopeId) {
+        return this.scopes.delete(scopeId);
+    }
+    /**
+     * Add agent to scope.
+     */
+    joinScope(scopeId, agentId) {
+        const scope = this.scopes.get(scopeId);
+        if (!scope) {
+            return false;
+        }
+        scope.members.add(agentId);
+        return true;
+    }
+    /**
+     * Remove agent from scope.
+     */
+    leaveScope(scopeId, agentId) {
+        const scope = this.scopes.get(scopeId);
+        if (!scope) {
+            return false;
+        }
+        return scope.members.delete(agentId);
+    }
+    // ===========================================================================
+    // Private Methods
+    // ===========================================================================
+    createRPCHandler(participantId) {
+        const handlers = {
+            // Connection
+            "map/connect": async (params) => this.handleConnect(participantId, params),
+            "map/disconnect": async () => this.handleDisconnect(participantId),
+            // Subscriptions
+            "map/subscribe": async (params) => this.handleSubscribe(participantId, params),
+            "map/unsubscribe": async (params) => this.handleUnsubscribe(participantId, params),
+            // Replay
+            "map/replay": async (params) => this.handleReplay(participantId, params),
+            // Messaging
+            "map/send": async (params, ctx) => this.handleSend(participantId, params, ctx),
+            // Agent queries
+            "map/agents/list": async (params) => this.handleListAgents(participantId, params),
+            "map/agents/get": async (params) => this.handleGetAgent(participantId, params),
+            // Agent lifecycle
+            "map/agents/stop": async (params) => this.handleStopAgent(participantId, params),
+            // Scope queries
+            "map/scopes/list": async () => this.handleListScopes(participantId),
+            "map/scopes/get": async (params) => this.handleGetScope(participantId, params),
+            "map/scopes/create": async (params, ctx) => this.handleCreateScope(participantId, params, ctx),
+            "map/scopes/join": async (params) => this.handleJoinScope(participantId, params),
+            "map/scopes/leave": async (params) => this.handleLeaveScope(participantId, params),
+            // Federation methods
+            "map/federation/connect": async (params) => this.handleFederationConnect(participantId, params),
+            "map/federation/disconnect": async (params) => this.handleFederationDisconnect(participantId, params),
+            "map/federation/list": async () => this.handleFederationList(participantId),
+            "map/federation/capabilities": async (params) => this.handleFederationCapabilities(participantId, params),
+        };
+        // Add extension method handlers
+        for (const [method, handler] of this.extensions) {
+            handlers[method] = async (params, ctx) => {
+                const extCtx = {
+                    participantId: ctx.participantId,
+                    capabilities: ctx.capabilities,
+                    sessionId: this.sessions.get(ctx.participantId)?.participant.sessionId ?? "",
+                };
+                return handler(extCtx, params);
+            };
+        }
+        // Add mail protocol handlers if mail service is available
+        if (this.services.mailService) {
+            const mailHandlers = createMailHandlers(this.services.mailService);
+            for (const [method, handler] of Object.entries(mailHandlers)) {
+                handlers[method] = handler;
+            }
+        }
+        // Capability requirements for methods
+        const capabilityRequirements = {
+            "map/subscribe": "canSubscribe",
+            "map/replay": "canSubscribe",
+            "map/send": "canMessage",
+            "map/agents/list": "canQuery",
+            "map/agents/get": "canQuery",
+            "map/agents/stop": "canStop",
+            "map/scopes/list": "canQuery",
+            "map/scopes/get": "canQuery",
+            "map/scopes/create": "canManageScopes",
+            // Federation methods
+            "map/federation/connect": "canManageFederation",
+            "map/federation/disconnect": "canManageFederation",
+            "map/federation/list": "canQuery",
+            "map/federation/capabilities": "canQuery",
+        };
+        // Add capability requirements for registered extension methods
+        for (const method of this.extensions.keys()) {
+            const capability = EXTENSION_CAPABILITIES[method];
+            if (capability) {
+                capabilityRequirements[method] =
+                    capability;
+            }
+        }
+        return createRPCHandler({
+            handlers,
+            middleware: [createCapabilityMiddleware(capabilityRequirements)],
+        });
+    }
+    async processMessages(session) {
+        const reader = session.stream.readable.getReader();
+        try {
+            while (!session.abortController.signal.aborted) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    break;
+                }
+                // Process the message
+                const participant = this.connections.getParticipant(session.participantId);
+                if (!participant) {
+                    break;
+                }
+                // Process messages concurrently (same pattern as toad reference).
+                // The message loop must not block on any handler, otherwise
+                // session/cancel can't be delivered while session/prompt is running.
+                // The stream writer queues writes safely, so concurrent responses
+                // don't interleave.
+                const processAndRespond = async () => {
+                    const result = await session.rpcHandler.process(value, {
+                        participantId: session.participantId,
+                        capabilities: participant.capabilities,
+                        signal: session.abortController.signal,
+                    });
+                    if (result.type === "response") {
+                        await this.sendToSession(session, result.response);
+                    }
+                };
+                processAndRespond().catch((err) => {
+                    if (!session.abortController.signal.aborted) {
+                        console.error(`[MAPAdapter] Error processing message:`, err);
+                    }
+                });
+            }
+        }
+        catch (error) {
+            if (!session.abortController.signal.aborted) {
+                throw error;
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    async sendToSession(session, message) {
+        try {
+            // Use the existing writer from the session (acquired in acceptConnection)
+            await session.writer.write(message);
+        }
+        catch (error) {
+            console.error("[MAPAdapter] Failed to send message:", error);
+            throw error;
+        }
+    }
+    emitAdapterEvent(event) {
+        for (const handler of this.eventHandlers) {
+            try {
+                handler(event);
+            }
+            catch (error) {
+                console.error("[MAPAdapter] Event handler error:", error);
+            }
+        }
+    }
+    // ===========================================================================
+    // RPC Handlers
+    // ===========================================================================
+    async handleConnect(participantId, params) {
+        const participant = this.connections.getParticipant(participantId);
+        if (!participant) {
+            throw RPCError.notFound("participant", participantId);
+        }
+        // Parse connect request parameters
+        const connectParams = params;
+        const requestedType = connectParams?.type ?? connectParams?.participantType ?? participant.type;
+        const credentials = connectParams?.credentials;
+        // Handle authentication if handler is configured and credentials provided
+        if (this.config.authenticate && credentials) {
+            const authResult = await this.config.authenticate(requestedType, credentials);
+            if (!authResult.allowed) {
+                throw RPCError.authenticationFailed(authResult.error ?? "Authentication failed");
+            }
+            // Update capabilities based on auth result
+            const newCapabilities = authResult.capabilities ?? this.getDefaultCapabilities(requestedType);
+            this.connections.updateCapabilities(participantId, newCapabilities);
+            // Return updated participant info
+            const updatedParticipant = this.connections.getParticipant(participantId);
+            return {
+                participantId: participant.id,
+                capabilities: updatedParticipant?.capabilities ?? newCapabilities,
+            };
+        }
+        // Start with default capabilities for the requested type
+        const baseCapabilities = this.getDefaultCapabilities(requestedType);
+        // Merge client-requested capabilities (SDK nested format → flat format).
+        // Clients can request additional capabilities; the server grants them
+        // by merging with the type defaults.
+        if (connectParams?.capabilities) {
+            const req = connectParams.capabilities;
+            const requested = {};
+            if (req.observation?.canQuery !== undefined)
+                requested.canQuery = req.observation.canQuery;
+            if (req.observation?.canObserve !== undefined)
+                requested.canSubscribe = req.observation.canObserve;
+            if (req.messaging?.canSend !== undefined)
+                requested.canMessage = req.messaging.canSend;
+            if (req.lifecycle?.canSpawn !== undefined)
+                requested.canSpawn = req.lifecycle.canSpawn;
+            if (req.lifecycle?.canStop !== undefined)
+                requested.canStop = req.lifecycle.canStop;
+            if (req.scopes?.canManageScopes !== undefined)
+                requested.canManageScopes = req.scopes.canManageScopes;
+            if (req.management?.canManageTasks !== undefined)
+                requested.canManageTasks = req.management.canManageTasks;
+            if (req.management?.canManageLifecycle !== undefined)
+                requested.canManageLifecycle = req.management.canManageLifecycle;
+            const mergedCapabilities = { ...baseCapabilities, ...requested };
+            this.connections.updateCapabilities(participantId, mergedCapabilities);
+            const updatedParticipant = this.connections.getParticipant(participantId);
+            return {
+                participantId: participant.id,
+                capabilities: updatedParticipant?.capabilities ?? mergedCapabilities,
+            };
+        }
+        // No client-requested capabilities — apply type defaults if type changed
+        if (requestedType !== participant.type) {
+            this.connections.updateCapabilities(participantId, baseCapabilities);
+            const updatedParticipant = this.connections.getParticipant(participantId);
+            return {
+                participantId: participant.id,
+                capabilities: updatedParticipant?.capabilities ?? baseCapabilities,
+            };
+        }
+        return {
+            participantId: participant.id,
+            capabilities: participant.capabilities,
+        };
+    }
+    /**
+     * Get default capabilities for a participant type.
+     */
+    getDefaultCapabilities(type) {
+        switch (type) {
+            case "agent":
+                return (this.config.defaultAgentCapabilities ?? {
+                    canQuery: true,
+                    canSubscribe: true,
+                    canMessage: true,
+                    canSpawn: true,
+                    canStop: true,
+                    canManageScopes: true,
+                    canManageTasks: true,
+                    canManageFederation: true,
+                    canManageLifecycle: true,
+                });
+            case "gateway":
+                return {
+                    canQuery: true,
+                    canSubscribe: true,
+                    canMessage: true,
+                    canSpawn: false,
+                    canStop: false,
+                    canManageScopes: false,
+                    canManageTasks: false,
+                    canManageFederation: true,
+                    canManageLifecycle: false,
+                };
+            case "client":
+            default:
+                return (this.config.defaultClientCapabilities ?? {
+                    canQuery: true,
+                    canSubscribe: true,
+                    canMessage: true,
+                    canSpawn: false,
+                    canStop: false,
+                    canManageScopes: false,
+                    canManageTasks: false,
+                    canManageLifecycle: false,
+                });
+        }
+    }
+    async handleDisconnect(participantId) {
+        await this.disconnectParticipant(participantId, "client_disconnect");
+        return { success: true };
+    }
+    async handleSubscribe(participantId, params) {
+        // Extract filter and translate SDK field names to internal format
+        // SDK uses 'fromAgents', macro-agent uses 'agents'
+        const rawFilter = params?.filter;
+        let filter;
+        if (rawFilter) {
+            filter = {
+                eventTypes: rawFilter.eventTypes,
+                agents: (rawFilter.fromAgents ?? rawFilter.agents),
+                scopes: rawFilter.scopes,
+                subtree: rawFilter.subtree,
+                lineage: rawFilter.lineage,
+            };
+        }
+        const subscriptionId = await this.createSubscription(participantId, filter);
+        return { subscriptionId };
+    }
+    async handleUnsubscribe(participantId, params) {
+        const subscriptionId = params
+            ?.subscriptionId;
+        if (!subscriptionId) {
+            throw RPCError.invalidParams("subscriptionId required");
+        }
+        await this.removeSubscription(subscriptionId);
+        return { success: true };
+    }
+    async handleReplay(_participantId, params) {
+        const { afterEventId, fromTimestamp, toTimestamp, filter, limit } = (params ?? {});
+        // Translate SDK filter field names to internal format
+        // SDK uses 'fromAgents', macro-agent uses 'agents'
+        const internalFilter = filter
+            ? {
+                eventTypes: filter.eventTypes,
+                agents: (filter.fromAgents ?? filter.agents),
+                scopes: filter.scopes,
+            }
+            : undefined;
+        const result = this.eventLog.query({
+            afterEventId,
+            fromTimestamp,
+            toTimestamp,
+            filter: internalFilter,
+            limit,
+        });
+        // Transform events to SDK response format
+        const events = result.events.map((e) => ({
+            eventId: e.eventId,
+            timestamp: e.timestamp,
+            ...(e.causedBy && { causedBy: e.causedBy }),
+            event: {
+                id: e.eventId,
+                type: dotToUnderscore(e.type),
+                timestamp: e.timestamp,
+                data: e.data,
+            },
+        }));
+        return {
+            events,
+            hasMore: result.hasMore,
+        };
+    }
+    async handleSend(participantId, params, ctx) {
+        const { to, payload, options } = params;
+        if (!to) {
+            throw RPCError.invalidParams("to address required");
+        }
+        if (!payload) {
+            throw RPCError.invalidParams("payload required");
+        }
+        // Check if this is an ACP-over-MAP message
+        // SDK sends ACP envelope directly as payload (not wrapped in content)
+        const rawPayload = payload;
+        if (rawPayload &&
+            typeof rawPayload === "object" &&
+            "acp" in rawPayload &&
+            "acpContext" in rawPayload) {
+            // This is an ACP envelope - route through ACP-over-MAP handler
+            return this.handleACPOverMAP(participantId, to, rawPayload, ctx);
+        }
+        return this.sendMessage(participantId, to, payload, options);
+    }
+    /**
+     * Handle ACP-over-MAP messages.
+     * These are ACP protocol messages sent via MAP to an agent.
+     */
+    async handleACPOverMAP(participantId, to, envelope, ctx) {
+        if (!this.acpOverMapHandler) {
+            throw RPCError.internalError("ACP-over-MAP not available - missing services");
+        }
+        const acp = envelope.acp;
+        const acpContext = envelope.acpContext;
+        console.error(`[ACP-over-MAP] Received - method=${acp.method} to=${JSON.stringify(to)}`);
+        // For now, we only support messages to specific agents
+        if (!isAgentAddress(to)) {
+            throw RPCError.invalidParams("ACP-over-MAP requires agent target");
+        }
+        const targetAgentId = to.agent;
+        // Check if this is a request (has method) or response (has result/error)
+        if (!acp.method) {
+            // This is a response - route it normally
+            console.error(`[ACP-over-MAP] Routing response back`);
+            return this.sendMessage(participantId, to, { content: envelope }, undefined);
+        }
+        // Emit client→agent ACP request as a message_sent event so other
+        // TUI clients can observe user prompts and other ACP operations.
+        // Include from/to at top level of data for extractACPFromMessageEvent()
+        // which reads data.from/data.to for targetAgent resolution.
+        this.emitEvent({
+            eventId: ulid(),
+            type: "message_sent",
+            timestamp: Date.now(),
+            agentId: targetAgentId,
+            data: {
+                from: participantId,
+                to: targetAgentId,
+                message: {
+                    id: `acp-req-${Date.now()}`,
+                    from: participantId,
+                    to: targetAgentId,
+                    payload: envelope,
+                },
+            },
+        });
+        // Create notification emitter to stream session updates
+        const emitNotification = (notification) => {
+            this.emitEvent({
+                eventId: ulid(),
+                type: "message_delivered",
+                timestamp: Date.now(),
+                agentId: targetAgentId,
+                data: {
+                    from: targetAgentId,
+                    to: participantId,
+                    message: {
+                        id: `acp-notif-${Date.now()}`,
+                        from: targetAgentId,
+                        payload: notification,
+                    },
+                },
+            });
+        };
+        // Process the ACP request through the handler
+        const acpEnvelope = {
+            acp: acp,
+            acpContext: acpContext,
+        };
+        // Helper to emit the final ACP response to the participant via subscription
+        const emitResponse = (responseEnvelope) => {
+            const participant = this.connections.getParticipant(participantId);
+            if (participant) {
+                this.emitEvent({
+                    eventId: ulid(),
+                    type: "message_delivered",
+                    timestamp: Date.now(),
+                    agentId: targetAgentId,
+                    data: {
+                        from: targetAgentId,
+                        to: participantId,
+                        message: {
+                            id: `acp-resp-${Date.now()}`,
+                            from: targetAgentId,
+                            payload: responseEnvelope,
+                        },
+                    },
+                });
+            }
+        };
+        // session/prompt can run for minutes — process it asynchronously so the
+        // map/send RPC returns immediately.  The ACP response will arrive via
+        // subscription (message_delivered event) when the prompt finishes.
+        // Other ACP methods (initialize, session/new, session/load, etc.) are
+        // fast and can be awaited normally.
+        const isLongRunning = acp.method === "session/prompt";
+        if (isLongRunning) {
+            this.acpOverMapHandler
+                .processRequest(targetAgentId, acpEnvelope, emitNotification)
+                .then((responseEnvelope) => {
+                console.error(`[ACP-over-MAP] Async prompt completed - method=${acp.method}`);
+                emitResponse(responseEnvelope);
+            })
+                .catch((error) => {
+                console.error(`[ACP-over-MAP] Async prompt error:`, error);
+                // Emit error response so the client's ACP pending request resolves
+                emitResponse({
+                    acp: {
+                        jsonrpc: "2.0",
+                        id: acp.id,
+                        error: {
+                            code: -32603,
+                            message: error instanceof Error ? error.message : String(error),
+                        },
+                    },
+                    acpContext: {
+                        streamId: acpContext.streamId,
+                        sessionId: acpContext.sessionId ?? null,
+                        direction: "agent-to-client",
+                    },
+                });
+            });
+        }
+        else {
+            const responseEnvelope = await this.acpOverMapHandler.processRequest(targetAgentId, acpEnvelope, emitNotification);
+            console.error(`[ACP-over-MAP] Request processed - method=${acp.method}`);
+            emitResponse(responseEnvelope);
+        }
+        return {
+            messageId: `acp-${acp.id}`,
+            delivered: [targetAgentId],
+        };
+    }
+    async handleListAgents(participantId, params) {
+        const filter = params?.filter;
+        const agents = this.listAgents(participantId, filter);
+        return { agents };
+    }
+    async handleGetAgent(participantId, params) {
+        const agentId = params?.agentId;
+        if (!agentId) {
+            throw RPCError.invalidParams("agentId required");
+        }
+        const agent = this.getAgent(participantId, agentId);
+        return { agent: agent ?? null };
+    }
+    async handleStopAgent(_participantId, params) {
+        const { agentId, reason, force } = params ?? {};
+        if (!agentId) {
+            throw RPCError.invalidParams("agentId required");
+        }
+        if (!this.services.agentManager) {
+            throw RPCError.internalError("Agent manager not available");
+        }
+        // Abort any active ACP streams for this agent
+        if (this.acpOverMapHandler) {
+            this.acpOverMapHandler.abortStreamsForAgent(agentId);
+        }
+        // Terminate the agent
+        try {
+            await this.services.agentManager.terminate(agentId, (reason ?? "cancelled"));
+        }
+        catch (error) {
+            console.error(`[MAPAdapter] Error stopping agent ${agentId}:`, error);
+            throw RPCError.internalError(`Failed to stop agent: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        // Note: agent_state_changed and agent_unregistered events are now
+        // emitted by the lifecycle listener (covers all stop paths).
+        return { stopping: true };
+    }
+    async handleListScopes(participantId) {
+        const scopes = this.listScopes(participantId);
+        return { scopes };
+    }
+    async handleGetScope(participantId, params) {
+        const scopeId = params?.scopeId;
+        if (!scopeId) {
+            throw RPCError.invalidParams("scopeId required");
+        }
+        const scope = this.getScope(participantId, scopeId);
+        return { scope: scope ?? null };
+    }
+    async handleCreateScope(participantId, params, ctx) {
+        const { name, metadata } = params ?? {};
+        const scopeId = this.createScope(name, metadata);
+        return { scopeId };
+    }
+    async handleJoinScope(participantId, params) {
+        const { scopeId, agentId } = params;
+        if (!scopeId) {
+            throw RPCError.invalidParams("scopeId required");
+        }
+        if (!agentId) {
+            throw RPCError.invalidParams("agentId required");
+        }
+        const success = this.joinScope(scopeId, agentId);
+        if (!success) {
+            throw RPCError.notFound("scope", scopeId);
+        }
+        return { success };
+    }
+    async handleLeaveScope(participantId, params) {
+        const { scopeId, agentId } = params;
+        if (!scopeId) {
+            throw RPCError.invalidParams("scopeId required");
+        }
+        if (!agentId) {
+            throw RPCError.invalidParams("agentId required");
+        }
+        const success = this.leaveScope(scopeId, agentId);
+        if (!success) {
+            throw RPCError.notFound("scope", scopeId);
+        }
+        return { success };
+    }
+    // ===========================================================================
+    // Federation Handlers
+    // ===========================================================================
+    async handleFederationConnect(participantId, params) {
+        if (!this.services.federationHandler) {
+            throw RPCError.internalError("Federation not available");
+        }
+        const { systemId, endpoint, auth } = (params ?? {});
+        if (!systemId) {
+            throw RPCError.invalidParams("systemId is required");
+        }
+        if (!endpoint) {
+            throw RPCError.invalidParams("endpoint is required");
+        }
+        try {
+            const capabilities = await this.services.federationHandler.connect({
+                systemId,
+                endpoint,
+                auth,
+            });
+            return { capabilities };
+        }
+        catch (err) {
+            throw RPCError.internalError(err instanceof Error ? err.message : "Failed to connect");
+        }
+    }
+    async handleFederationDisconnect(participantId, params) {
+        if (!this.services.federationHandler) {
+            throw RPCError.internalError("Federation not available");
+        }
+        const { systemId } = (params ?? {});
+        if (!systemId) {
+            throw RPCError.invalidParams("systemId is required");
+        }
+        try {
+            await this.services.federationHandler.disconnect(systemId);
+            return { success: true };
+        }
+        catch (err) {
+            if (err instanceof Error && err.message.includes("Not connected")) {
+                throw RPCError.notFound("peer", systemId);
+            }
+            throw RPCError.internalError(err instanceof Error ? err.message : "Failed to disconnect");
+        }
+    }
+    async handleFederationList(participantId) {
+        if (!this.services.federationHandler) {
+            return { peers: [] };
+        }
+        const peers = this.services.federationHandler.listPeers();
+        return {
+            peers: peers.map((peer) => ({
+                systemId: peer.systemId,
+                status: peer.status,
+                connectedAt: peer.connectedAt,
+            })),
+        };
+    }
+    async handleFederationCapabilities(participantId, params) {
+        if (!this.services.federationHandler) {
+            throw RPCError.internalError("Federation not available");
+        }
+        const { systemId } = (params ?? {});
+        if (!systemId) {
+            throw RPCError.invalidParams("systemId is required");
+        }
+        const capabilities = this.services.federationHandler.getCapabilities(systemId);
+        if (!capabilities) {
+            throw RPCError.notFound("peer", systemId);
+        }
+        return { capabilities };
+    }
+    // ===========================================================================
+    // Type Conversions
+    // ===========================================================================
+    toAgentInfo(agent) {
+        return {
+            id: agent.id,
+            name: agent.name,
+            role: agent.role,
+            state: agent.state,
+            parent: agent.parent,
+            scopes: this.getAgentScopes(agent.id),
+            metadata: agent.metadata,
+            createdAt: agent.createdAt,
+            // All macro-agent agents support ACP (they're Claude Code sessions)
+            capabilities: {
+                protocols: ["acp"],
+                acp: {
+                    features: ["streaming"],
+                },
+            },
+        };
+    }
+    toScopeInfo(scope) {
+        return {
+            id: scope.id,
+            name: scope.name,
+            members: Array.from(scope.members),
+            createdAt: scope.createdAt,
+            metadata: scope.metadata,
+        };
+    }
+    getAgentScopes(agentId) {
+        const result = [];
+        for (const scope of this.scopes.values()) {
+            if (scope.members.has(agentId)) {
+                result.push(scope.id);
+            }
+        }
+        return result;
+    }
+}
+// =============================================================================
+// Factory
+// =============================================================================
+/**
+ * Create a MAPAdapter instance.
+ */
+export function createMAPAdapter(config, services) {
+    return new MAPAdapterImpl(config, services);
+}
+//# sourceMappingURL=map-adapter.js.map