macro-agent 0.1.1 → 0.1.3

package/dist/acp/macro-agent.js

@@ -1,1306 +1,668 @@
 /**
- * MacroAgent - ACP-compliant agent implementation for macro-agent
+ * MacroAgent — ACP Agent implementation for macro-agent.
  *
- * Implements the Agent interface from @agentclientprotocol/sdk to allow
- * macro-agent to be spawned and controlled via the Agent Communication Protocol.
+ * Bridges the ACP protocol to macro-agent's V2 services:
+ * - session/new → agentManager.getOrCreateHeadManager()
+ * - session/prompt → agentManager.prompt() with streaming
+ * - Extension methods → spawn, mount, fork, hierarchy, tasks, etc.
+ *
+ * @module acp/macro-agent
  */
+import { RequestError } from "@agentclientprotocol/sdk";
 import { SessionMapper } from "./session-mapper.js";
 import { ACPError } from "./types.js";
-import { AGENT_CAPABILITIES } from "../roles/capabilities.js";
-import { DefaultRoleRegistry } from "../roles/registry.js";
-// ─────────────────────────────────────────────────────────────────
-// Helpers
-// ─────────────────────────────────────────────────────────────────
-/** Extract a plain-text output string from `rawOutput` (string | ContentBlock[] | undefined). */
-function extractToolOutput(rawOutput) {
-    if (typeof rawOutput === "string")
-        return rawOutput;
-    if (Array.isArray(rawOutput)) {
-        return rawOutput
-            .filter((item) => item.type === "text" && typeof item.text === "string")
-            .map((item) => item.text)
-            .join("\n") || undefined;
-    }
-    return undefined;
-}
+import { execSync } from "node:child_process";
 // ─────────────────────────────────────────────────────────────────
-// Protocol Constants
+// Extension method names
 // ─────────────────────────────────────────────────────────────────
-const PROTOCOL_VERSION = 1;
 const SUPPORTED_EXTENSIONS = [
     "_macro/spawnAgent",
     "_macro/getHierarchy",
     "_macro/getTask",
     "_macro/mountAgent",
     "_macro/forkAgent",
-    "_macro/sendPeerMessage",
-    "_macro/sendPeerRequest",
-    "_macro/deliverPeerMessage",
-    "_macro/deliverPeerRequest",
-    "_macro/grantCapability",
-    "_macro/revokeCapability",
-    "_macro/getCapabilities",
-    "_macro/checkCapability",
-    "_macro/respondToPermission",
-    "_macro/cancelPermission",
-    "_macro/setPermissionMode",
     "_macro/resume",
     "_macro/getHistory",
     "_macro/getModels",
+    "_macro/respondToPermission",
+    "_macro/cancelPermission",
+    "_macro/setPermissionMode",
+];
+const STUBBED_PEER_EXTENSIONS = [
+    "_macro/listPeers",
+    "_macro/getPeer",
+    "_macro/sendToPeer",
+    "_macro/subscribePeer",
+    "_macro/unsubscribePeer",
+    "_macro/getCapabilities",
+    "_macro/setCapabilities",
+    "_macro/negotiateCapabilities",
 ];
 // ─────────────────────────────────────────────────────────────────
-// Helpers
+// Type Guards
 // ─────────────────────────────────────────────────────────────────
+/** ACP-standard session update type discriminants. */
+const ACP_SESSION_UPDATE_TYPES = new Set([
+    "user_message_chunk",
+    "agent_message_chunk",
+    "agent_thought_chunk",
+    "tool_call",
+    "tool_call_update",
+    "plan",
+    "available_commands_update",
+    "current_mode_update",
+    "config_option_update",
+    "session_info_update",
+]);
 /**
- * Build a SessionModelState from the acp-factory Session.models (string[]).
- * Returns null if the models array is empty or missing.
+ * Type guard: returns true if the update is an ACP-standard SessionUpdate
+ * (not an acp-factory extension like PermissionRequestUpdate or CompactionUpdate).
  */
-function buildModelState(models) {
-    if (!models || models.length === 0)
-        return null;
-    return {
-        currentModelId: models[0],
-        availableModels: models.map((id) => ({ modelId: id, name: id })),
-    };
+function isACPSessionUpdate(update) {
+    return ("sessionUpdate" in update &&
+        ACP_SESSION_UPDATE_TYPES.has(update.sessionUpdate));
+}
+/**
+ * Type guard: returns true if the update is a PermissionRequestUpdate
+ * from acp-factory (emitted when the agent is in interactive permission mode).
+ */
+function isPermissionRequestUpdate(update) {
+    return ("sessionUpdate" in update &&
+        update.sessionUpdate === "permission_request");
 }
 // ─────────────────────────────────────────────────────────────────
-// MacroAgent Implementation
+// Factory
 // ─────────────────────────────────────────────────────────────────
 /**
- * MacroAgent implements the ACP Agent interface to expose macro-agent
- * as an ACP-compliant agent that can be spawned by external systems.
+ * Create a macro-agent ACP handler for an AgentSideConnection.
+ *
+ * Usage:
+ * ```ts
+ * new AgentSideConnection(
+ *   (conn) => createMacroAgent(conn, { system }),
+ *   stream,
+ * );
+ * ```
  */
-export class MacroAgent {
-    connection;
-    agentManager;
-    eventStore;
-    taskManager;
-    peerManager;
-    capabilityManager;
-    roleRegistry;
-    sessionMapper;
-    defaultCwd;
-    /** Configuration from ACP initialization */
-    initConfig = {};
-    /** Map of ACP session ID to cancellation abort controllers */
-    cancellationControllers = new Map();
-    /** Accumulates assistant response parts during prompt streaming for history persistence */
-    promptBuffers = new Map();
-    /** Caches tool info (title, name, input) from initial tool_call events per session */
-    toolInfoCaches = new Map();
-    constructor(connection, config) {
-        this.connection = connection;
-        this.agentManager = config.agentManager;
-        this.eventStore = config.eventStore;
-        this.taskManager = config.taskManager;
-        this.peerManager = config.peerManager;
-        this.capabilityManager = config.capabilityManager;
-        this.roleRegistry = config.roleRegistry ?? new DefaultRoleRegistry();
-        this.sessionMapper = new SessionMapper(config.eventStore);
-        this.defaultCwd = config.defaultCwd ?? process.cwd();
-        // Recover persisted sessions from the EventStore
-        const recovered = this.sessionMapper.recoverFromStore();
-        if (recovered > 0) {
-            console.log(`[MacroAgent] Recovered ${recovered} session(s) from EventStore`);
-        }
-    }
-    // ─────────────────────────────────────────────────────────────────
-    // Core ACP Methods
-    // ─────────────────────────────────────────────────────────────────
-    /**
-     * Initialize the connection and advertise capabilities
-     *
-     * Reads configuration from `params._meta?.macroConfig` if provided.
-     * This allows each macro-agent instance to have different settings.
-     */
-    async initialize(params) {
-        // Extract macro-agent config from _meta if provided
-        const meta = params._meta;
-        if (meta?.macroConfig) {
-            this.initConfig = meta.macroConfig;
-            // Apply defaultCwd from init config if provided
-            if (this.initConfig.defaultCwd) {
-                this.defaultCwd = this.initConfig.defaultCwd;
+export function createMacroAgent(connection, config) {
+    const { system, initConfig } = config;
+    const { agentManager, inboxAdapter, tasksAdapter } = system;
+    const sessionMapper = new SessionMapper();
+    const defaultCwd = initConfig?.defaultCwd ?? process.cwd();
+    // Per-session state for trajectory tracking
+    let checkpointCounter = 0;
+    let firstPrompt = null;
+    const sessionStartedAt = new Date().toISOString();
+    // Git info (cached — read once per session)
+    let gitInfo = null;
+    function getGitInfo(cwd) {
+        if (gitInfo)
+            return gitInfo;
+        try {
+            const branch = execSync("git rev-parse --abbrev-ref HEAD", { cwd, timeout: 3000 }).toString().trim() || null;
+            const commitHash = execSync("git rev-parse HEAD", { cwd, timeout: 3000 }).toString().trim() || null;
+            let remoteUrl = null;
+            try {
+                remoteUrl = execSync("git remote get-url origin", { cwd, timeout: 3000 }).toString().trim() || null;
             }
+            catch { /* no remote */ }
+            gitInfo = { branch, commitHash, remoteUrl };
         }
-        return {
-            protocolVersion: PROTOCOL_VERSION,
-            agentCapabilities: {
-                loadSession: true,
-                _meta: {
-                    extensions: SUPPORTED_EXTENSIONS,
-                    agentType: "macro-agent",
-                    // Echo back the config so client knows what was applied
-                    appliedConfig: this.initConfig,
-                },
-            },
-        };
-    }
-    /**
-     * Create a new session by spawning a head manager
-     */
-    async newSession(params) {
-        const cwd = params.cwd ?? this.defaultCwd;
-        // Build head manager options from init config
-        const defaultConfig = this.initConfig.defaultSubAgentConfig;
-        const permissionModeToUse = defaultConfig?.permissionMode;
-        // Spawn a new head manager for this session
-        const spawned = await this.agentManager.getOrCreateHeadManager({
-            cwd,
-            forceNew: true, // Always create new for newSession
-            permissionMode: permissionModeToUse,
-            systemPrompt: this.buildSystemPrompt(),
-        });
-        // Create session mapping
-        const acpSessionId = spawned.session_id;
-        this.sessionMapper.createMapping(acpSessionId, spawned.id);
-        // Create abort controller for cancellation
-        this.cancellationControllers.set(acpSessionId, new AbortController());
-        // Create a conversation in EventStore for history tracking
-        this.ensureConversation(acpSessionId, spawned.id);
-        // Emit session_info_update so client has title/timestamps
-        await this.emitSessionInfo(acpSessionId);
-        return {
-            sessionId: acpSessionId,
-            models: buildModelState(spawned.session.models),
-        };
+        catch {
+            gitInfo = { branch: null, commitHash: null, remoteUrl: null };
+        }
+        return gitInfo;
     }
-    /**
-     * Load an existing session from EventStore
-     */
-    async loadSession(params) {
-        let acpSessionId = params.sessionId;
-        const cwd = params.cwd ?? this.defaultCwd;
-        // DEBUG: Log loadSession params
-        // Extension: If _meta.agentId provided, look up session from agent record
-        // This allows resuming a stopped head manager by MAP agent ID
-        // when the TUI doesn't know the ACP session ID
-        const metaAgentId = params._meta
-            ?.agentId;
-        if (metaAgentId) {
-            const agent = this.eventStore.getAgent(metaAgentId);
-            if (!agent) {
-                throw new Error(`Agent not found: ${metaAgentId}`);
+    // ── Helpers ──────────────────────────────────────────────────
+    function getSessionOrThrow(sessionId) {
+        const mapping = sessionMapper.getMapping(sessionId);
+        if (!mapping) {
+            throw RequestError.invalidParams({ sessionId }, `Session not found: ${sessionId}`);
+        }
+        return mapping;
+    }
+    // ── Extension dispatcher ────────────────────────────────────
+    async function handleExtension(method, params) {
+        // Check if it's a stubbed peer method
+        if (STUBBED_PEER_EXTENSIONS.includes(method)) {
+            throw new ACPError(`Peer manager not available: ${method}`, "NO_PEER_MANAGER", { method });
+        }
+        switch (method) {
+            case "_macro/spawnAgent": {
+                const task = params.task;
+                if (!task)
+                    throw RequestError.invalidParams(params, "task is required");
+                const spawned = await agentManager.spawn({
+                    task,
+                    parent: params.parent,
+                    cwd: params.cwd ?? defaultCwd,
+                    role: params.role,
+                    permissionMode: params.permissionMode,
+                });
+                return {
+                    agentId: spawned.id,
+                    sessionId: spawned.session_id,
+                    role: spawned.agent.role,
+                    state: spawned.agent.state,
+                };
             }
-            acpSessionId = agent.session_id;
-            console.log(`[MacroAgent] loadSession: Resolved agentId ${metaAgentId} to session ${acpSessionId}`);
-        }
-        // Try to find an existing head manager with this session ID
-        const headManagers = this.agentManager.listHeadManagers();
-        const existing = headManagers.find((hm) => hm.session_id === acpSessionId);
-        if (existing) {
-            // Check if the agent already has an active session
-            if (this.agentManager.hasActiveSession(existing.id)) {
-                console.log(`[MacroAgent] loadSession: Agent ${existing.id} already has active session, reusing`);
-                // Reuse the existing active session - just update mappings
-                this.sessionMapper.createMapping(acpSessionId, existing.id);
-                if (!this.cancellationControllers.has(acpSessionId)) {
-                    this.cancellationControllers.set(acpSessionId, new AbortController());
+            case "_macro/getHierarchy": {
+                const agentId = params.agentId;
+                if (!agentId)
+                    throw RequestError.invalidParams(params, "agentId is required");
+                const hierarchy = agentManager.getHierarchy(agentId, {
+                    depth: params.depth,
+                });
+                return { hierarchy: hierarchy ?? null };
+            }
+            case "_macro/getTask": {
+                const taskId = params.taskId;
+                if (!taskId)
+                    throw RequestError.invalidParams(params, "taskId is required");
+                const task = await tasksAdapter.getTask(taskId);
+                return { task };
+            }
+            case "_macro/mountAgent": {
+                const sessionId = params.sessionId;
+                const agentId = params.agentId;
+                if (!sessionId || !agentId) {
+                    throw RequestError.invalidParams(params, "sessionId and agentId are required");
+                }
+                // Verify the agent exists
+                const agent = agentManager.get(agentId);
+                if (!agent) {
+                    throw new ACPError(`Agent not found: ${agentId}`, "AGENT_NOT_FOUND", { agentId });
                 }
-                this.ensureConversation(acpSessionId, existing.id);
-                await this.emitSessionInfo(acpSessionId);
-                const activeSession = this.agentManager.getSession(existing.id);
+                const previousAgentId = sessionMapper.mount(sessionId, agentId);
                 return {
-                    models: activeSession ? buildModelState(activeSession.models) : null,
+                    mounted: true,
+                    agentId,
+                    previousAgentId: previousAgentId ?? null,
                 };
             }
-            // Agent exists but no active session - resume it
-            console.log(`[MacroAgent] loadSession: Resuming stopped agent ${existing.id}`);
-            const defaultConfig = this.initConfig.defaultSubAgentConfig;
-            const spawned = await this.agentManager.resume(existing.id, defaultConfig?.permissionMode);
-            // Create session mapping
-            this.sessionMapper.createMapping(acpSessionId, spawned.id);
-            this.cancellationControllers.set(acpSessionId, new AbortController());
-            this.ensureConversation(acpSessionId, spawned.id);
-            await this.emitSessionInfo(acpSessionId);
-            return {
-                models: buildModelState(spawned.session.models),
-            };
-        }
-        // No existing agent found - try to get or create with the specific session ID
-        console.log(`[MacroAgent] loadSession: No existing agent for session ${acpSessionId}, creating new`);
-        const defaultConfig = this.initConfig.defaultSubAgentConfig;
-        const spawned = await this.agentManager.getOrCreateHeadManager({
-            cwd,
-            sessionId: acpSessionId,
-            permissionMode: defaultConfig?.permissionMode,
-        });
-        // Create session mapping
-        this.sessionMapper.createMapping(acpSessionId, spawned.id);
-        this.cancellationControllers.set(acpSessionId, new AbortController());
-        this.ensureConversation(acpSessionId, spawned.id);
-        await this.emitSessionInfo(acpSessionId);
-        return {
-            models: buildModelState(spawned.session.models),
-        };
-    }
-    /**
-     * Authenticate - macro-agent doesn't require authentication
-     */
-    async authenticate(_params) {
-        // No authentication required
-        return {};
-    }
-    /**
-     * Process a prompt by routing to the mapped agent
-     */
-    async prompt(params) {
-        const acpSessionId = params.sessionId;
-        // Get the mapped agent
-        const agentId = this.sessionMapper.getAgentIdOrThrow(acpSessionId);
-        // Get or set up abort controller
-        let abortController = this.cancellationControllers.get(acpSessionId);
-        if (!abortController || abortController.signal.aborted) {
-            abortController = new AbortController();
-            this.cancellationControllers.set(acpSessionId, abortController);
-        }
-        // Extract message content from prompt blocks
-        const messageContent = this.extractMessageContent(params.prompt);
-        // Mark session as processing (for health monitoring)
-        this.sessionMapper.setProcessing(acpSessionId, true);
-        // Initialize prompt buffer and tool info cache for history accumulation
-        this.promptBuffers.set(acpSessionId, { parts: [] });
-        this.toolInfoCaches.set(acpSessionId, new Map());
-        try {
-            // Stream responses from the agent
-            for await (const update of this.agentManager.prompt(agentId, messageContent)) {
-                // Check for cancellation
-                if (abortController.signal.aborted) {
+            case "_macro/forkAgent": {
+                const sourceAgentId = params.sourceAgentId;
+                if (!sourceAgentId) {
+                    throw RequestError.invalidParams(params, "sourceAgentId is required");
+                }
+                try {
+                    const forked = await agentManager.forkAgent(sourceAgentId, {
+                        name: params.name,
+                        prompt: params.prompt,
+                        cwd: params.cwd,
+                    });
                     return {
-                        stopReason: "cancelled",
+                        agentId: forked.id,
+                        sessionId: forked.session_id,
                     };
                 }
-                // Forward session updates to the client
-                await this.forwardSessionUpdate(acpSessionId, update);
-            }
-            // Persist conversation turns for history
-            this.recordPromptTurns(acpSessionId, agentId, messageContent);
-            // Emit updated session info after prompt completes
-            await this.emitSessionInfo(acpSessionId);
-            return {
-                stopReason: "end_turn",
-            };
-        }
-        catch (error) {
-            // Handle errors
-            const errorMessage = error instanceof Error ? error.message : "Unknown error";
-            // Send error as session update
-            await this.connection.sessionUpdate({
-                sessionId: acpSessionId,
-                update: {
-                    sessionUpdate: "agent_message_chunk",
-                    content: { type: "text", text: `Error: ${errorMessage}` },
-                },
-            });
-            return {
-                stopReason: "end_turn",
-            };
-        }
-        finally {
-            // Mark session as not processing (for health monitoring)
-            this.sessionMapper.setProcessing(acpSessionId, false);
-        }
-    }
-    /**
-     * Cancel ongoing operations for a session
-     */
-    async cancel(params) {
-        const acpSessionId = params.sessionId;
-        // Signal cancellation
-        const controller = this.cancellationControllers.get(acpSessionId);
-        if (controller) {
-            controller.abort();
-        }
-        // Get the mapped agent ID for this session
-        const agentId = this.sessionMapper.getAgentId(acpSessionId);
-        if (!agentId) {
-            // No agent mapped - just clean up the controller
-            this.cancellationControllers.delete(acpSessionId);
-            return;
-        }
-        // Terminate the agent (which kills the subprocess)
-        try {
-            await this.agentManager.terminate(agentId, "cancelled");
-        }
-        catch (error) {
-            // Agent may already be stopped - log but don't throw
-            console.warn(`[MacroAgent] Error terminating agent ${agentId}:`, error instanceof Error ? error.message : String(error));
-        }
-        // Clean up resources
-        this.cancellationControllers.delete(acpSessionId);
-        this.sessionMapper.removeMapping(acpSessionId);
-    }
-    // ─────────────────────────────────────────────────────────────────
-    // Extension Methods
-    // ─────────────────────────────────────────────────────────────────
-    /**
-     * Route extension method calls to handlers
-     */
-    async extMethod(method, params) {
-        // Method may come with or without underscore prefix depending on caller
-        // SDK calls with full name (e.g., "_macro/spawnAgent"), direct calls may omit it
-        const fullMethod = (method.startsWith("_") ? method : `_${method}`);
-        switch (fullMethod) {
-            case "_macro/spawnAgent":
-                return this.handleSpawnAgent(params);
-            case "_macro/getHierarchy":
-                return this.handleGetHierarchy(params);
-            case "_macro/getTask":
-                return this.handleGetTask(params);
-            case "_macro/mountAgent":
-                return this.handleMountAgent(params);
-            case "_macro/forkAgent":
-                return this.handleForkAgent(params);
-            case "_macro/sendPeerMessage":
-                return this.handleSendPeerMessage(params);
-            case "_macro/sendPeerRequest":
-                return this.handleSendPeerRequest(params);
-            case "_macro/deliverPeerMessage":
-                return this.handleDeliverPeerMessage(params);
-            case "_macro/deliverPeerRequest":
-                return this.handleDeliverPeerRequest(params);
-            case "_macro/grantCapability":
-                return this.handleGrantCapability(params);
-            case "_macro/revokeCapability":
-                return this.handleRevokeCapability(params);
-            case "_macro/getCapabilities":
-                return this.handleGetCapabilities(params);
-            case "_macro/checkCapability":
-                return this.handleCheckCapability(params);
-            case "_macro/respondToPermission":
-                return this.handleRespondToPermission(params);
-            case "_macro/cancelPermission":
-                return this.handleCancelPermission(params);
-            case "_macro/setPermissionMode":
-                return this.handleSetPermissionMode(params);
-            case "_macro/resume":
-                return this.handleResumeAgent(params);
-            case "_macro/getHistory":
-                return this.handleGetHistory(params);
-            case "_macro/getModels":
-                return this.handleGetModels(params);
-            default:
-                throw new ACPError(`Unknown extension method: ${method}`, "INVALID_EXTENSION");
-        }
-    }
-    // ─────────────────────────────────────────────────────────────────
-    // Extension Handlers
-    // ─────────────────────────────────────────────────────────────────
-    /**
-     * Spawn a new child agent
-     */
-    async handleSpawnAgent(params) {
-        // Determine parent - use provided parentId or fall back to a session's mapped agent
-        let parentId = params.parentId;
-        // If no parentId provided, we need to find a suitable parent
-        // This would typically come from an ACP session context
-        if (!parentId) {
-            // Get the first head manager as default parent
-            const headManagers = this.agentManager.listHeadManagers();
-            if (headManagers.length > 0) {
-                parentId = headManagers[0].id;
-            }
-        }
-        // Check spawn capability if parent exists
-        if (parentId) {
-            const parentAgent = this.eventStore.getAgent(parentId);
-            if (parentAgent) {
-                const childRole = params.role ?? "worker";
-                const requiredCapability = this.getSpawnCapability(childRole);
-                // Check if parent has the required spawn capability
-                const parentRole = parentAgent.role ?? "worker";
-                if (!this.roleRegistry.hasCapability(parentRole, requiredCapability)) {
-                    throw new ACPError(`Parent agent with role '${parentRole}' does not have capability to spawn '${childRole}' agents. ` +
-                        `Required capability: ${requiredCapability}`, "CAPABILITY_DENIED", {
-                        parentId,
-                        parentRole,
-                        childRole,
-                        requiredCapability,
-                    });
+                catch (err) {
+                    throw new ACPError(`Fork failed: ${err.message}`, "FORK_FAILED", { sourceAgentId });
                 }
             }
-        }
-        // Merge default config with per-spawn override
-        const mergedConfig = this.mergeSubAgentConfig(this.initConfig.defaultSubAgentConfig, params.config);
-        // Spawn the agent with merged config
-        const spawned = await this.agentManager.spawn({
-            task: params.task_description,
-            parent: parentId ?? null,
-            role: params.role,
-            cwd: params.options?.cwd ?? this.defaultCwd,
-            subscribeParent: params.options?.subscribeParent ?? true,
-            topics: params.options?.topics,
-            permissionMode: mergedConfig?.permissionMode,
-            agentType: mergedConfig?.agentType,
-            config: this.toAgentConfig(mergedConfig),
-        });
-        return {
-            agentId: spawned.id,
-            taskId: spawned.agent.task_id,
-            sessionId: spawned.session_id,
-        };
-    }
-    /**
-     * Map a child role name to the required spawn capability.
-     * Handles subroles like "worker.resolver" by checking base role.
-     */
-    getSpawnCapability(childRole) {
-        // Extract base role (e.g., "worker.resolver" -> "worker")
-        const baseRole = childRole.split(".")[0];
-        switch (baseRole) {
-            case "worker":
-                return AGENT_CAPABILITIES.SPAWN_WORKER;
-            case "integrator":
-                return AGENT_CAPABILITIES.SPAWN_INTEGRATOR;
-            case "monitor":
-                return AGENT_CAPABILITIES.SPAWN_MONITOR;
-            case "coordinator":
-                // Coordinators require special handling - typically only other coordinators
-                // or system-level agents can spawn coordinators
-                return AGENT_CAPABILITIES.SPAWN_CUSTOM;
-            default:
-                // For custom roles, check against the custom spawn capability
-                return AGENT_CAPABILITIES.SPAWN_CUSTOM;
-        }
-    }
-    /**
-     * Get the agent hierarchy tree
-     */
-    async handleGetHierarchy(params) {
-        let rootAgentId = params.rootAgentId;
-        // If no root specified, use the first head manager
-        if (!rootAgentId) {
-            const headManagers = this.agentManager.listHeadManagers();
-            if (headManagers.length === 0) {
-                // Return empty hierarchy if no agents
+            case "_macro/resume": {
+                const agentId = params.agentId;
+                if (!agentId)
+                    throw RequestError.invalidParams(params, "agentId is required");
+                const resumed = await agentManager.resume(agentId);
                 return {
-                    hierarchy: {
-                        agent: null,
-                        children: [],
-                    },
-                    totalAgents: 0,
-                    depth: 0,
+                    agentId: resumed.id,
+                    sessionId: resumed.session_id,
+                    state: resumed.agent.state,
                 };
             }
-            rootAgentId = headManagers[0].id;
-        }
-        // Get hierarchy from agent manager
-        const hierarchy = this.agentManager.getHierarchy(rootAgentId);
-        if (!hierarchy) {
-            throw new ACPError(`Agent not found: ${rootAgentId}`, "AGENT_NOT_FOUND", {
-                agentId: rootAgentId,
-            });
-        }
-        return {
-            hierarchy: hierarchy.root,
-            totalAgents: hierarchy.totalAgents,
-            depth: hierarchy.depth,
-        };
-    }
-    /**
-     * Get task details by ID
-     */
-    async handleGetTask(params) {
-        const task = this.taskManager.get(params.taskId);
-        if (!task) {
-            throw new ACPError(`Task not found: ${params.taskId}`, "TASK_NOT_FOUND", {
-                taskId: params.taskId,
-            });
-        }
-        return {
-            task,
-        };
-    }
-    /**
-     * Mount (attach to) an existing agent
-     *
-     * Remaps an ACP session to point to a different agent.
-     * Subsequent prompts will go to the mounted agent.
-     */
-    async handleMountAgent(params) {
-        const { sessionId, agentId } = params;
-        // Verify the target agent exists
-        const agent = this.agentManager.get(agentId);
-        if (!agent) {
-            throw new ACPError(`Agent not found: ${agentId}`, "AGENT_NOT_FOUND", {
-                agentId,
-            });
-        }
-        // Verify the session exists in our mapper
-        const mapping = this.sessionMapper.getMapping(sessionId);
-        if (!mapping) {
-            throw new ACPError(`Session not found: ${sessionId}`, "SESSION_NOT_FOUND", { sessionId });
-        }
-        // Get the previous agent before mounting
-        const previousAgentId = mapping.agentId;
-        // Remap the session to the target agent
-        this.sessionMapper.mount(sessionId, agentId);
-        return {
-            sessionId,
-            agent,
-            previousAgentId,
-        };
-    }
-    /**
-     * Fork an agent (create a branch with same conversation context)
-     *
-     * Creates a new agent that starts from the same point as the original.
-     * Uses native fork if available, otherwise falls back to loadSession.
-     */
-    async handleForkAgent(params) {
-        const { agentId, name, prompt, cwd } = params;
-        // Validate source agent exists
-        const originalAgent = this.agentManager.get(agentId);
-        if (!originalAgent) {
-            throw new ACPError(`Agent not found: ${agentId}`, "AGENT_NOT_FOUND", {
-                agentId,
-            });
-        }
-        // Check forkable: needs active session or persisted provider_session_id
-        if (!this.agentManager.hasActiveSession(agentId) &&
-            !originalAgent.provider_session_id) {
-            throw new ACPError(`Agent has no session to fork: ${agentId}`, "FORK_NOT_SUPPORTED", { agentId });
-        }
-        // Fork via AgentManager (handles forkWithFlush + new process + loadSession)
-        const forked = await this.agentManager.forkAgent(agentId, {
-            name,
-            cwd: cwd ?? originalAgent.cwd ?? this.defaultCwd,
-        });
-        // Fire-and-forget initial prompt if provided
-        if (prompt) {
-            (async () => {
-                try {
-                    for await (const _update of this.agentManager.prompt(forked.id, prompt)) {
-                        // Drain the async iterable
-                    }
+            case "_macro/getHistory": {
+                const agentId = params.agentId;
+                if (!agentId)
+                    throw RequestError.invalidParams(params, "agentId is required");
+                if (params.threadTag) {
+                    const thread = await inboxAdapter.readThread(params.threadTag, params.scope);
+                    return { messages: thread };
                 }
-                catch (err) {
-                    console.warn(`[MacroAgent] Failed to send initial prompt to forked agent ${forked.id}:`, err);
+                const messages = await inboxAdapter.checkInbox(agentId, {
+                    limit: params.limit,
+                });
+                return { messages };
+            }
+            case "_macro/getModels": {
+                // Models are not centrally tracked; return empty
+                return { models: [] };
+            }
+            case "_macro/respondToPermission": {
+                const agentId = params.agentId;
+                const requestId = params.requestId;
+                const optionId = params.optionId;
+                if (!agentId || !requestId || !optionId) {
+                    throw RequestError.invalidParams(params, "agentId, requestId, and optionId are required");
+                }
+                const success = agentManager.respondToPermission(agentId, requestId, optionId);
+                return { success };
+            }
+            case "_macro/cancelPermission": {
+                const agentId = params.agentId;
+                const requestId = params.requestId;
+                if (!agentId || !requestId) {
+                    throw RequestError.invalidParams(params, "agentId and requestId are required");
                 }
-            })();
+                const success = agentManager.cancelPermission(agentId, requestId);
+                return { success };
+            }
+            case "_macro/setPermissionMode": {
+                const agentId = params.agentId;
+                const mode = params.mode;
+                if (!agentId || !mode) {
+                    throw RequestError.invalidParams(params, "agentId and mode are required");
+                }
+                const success = agentManager.setPermissionMode(agentId, mode);
+                return { success };
+            }
+            default:
+                throw new ACPError(`Unknown extension: ${method}`, "INVALID_EXTENSION", { method });
         }
-        return {
-            newAgentId: forked.id,
-            newSessionId: forked.session_id,
-            originalAgentId: agentId,
-            providerSessionId: forked.session.id,
-        };
     }
-    // ─────────────────────────────────────────────────────────────────
-    // Peer Communication Extension Handlers
-    // ─────────────────────────────────────────────────────────────────
-    /**
-     * Send a peer message (outbound, fire-and-forget)
-     *
-     * Called by external clients to have an agent send a message to a peer.
-     */
-    async handleSendPeerMessage(params) {
-        if (!this.peerManager) {
-            throw new ACPError("PeerManager not configured for this macro-agent", "NO_PEER_MANAGER");
-        }
-        // Determine which agent is sending (use head manager by default)
-        const headManagers = this.agentManager.listHeadManagers();
-        if (headManagers.length === 0) {
-            throw new ACPError("No agents available to send peer message", "AGENT_NOT_FOUND");
-        }
-        const sendingAgentId = headManagers[0].id;
-        try {
-            await this.peerManager.sendMessage(sendingAgentId, params.to, {
-                type: params.type,
-                payload: params.payload,
-                metadata: params.correlationId
-                    ? { correlationId: params.correlationId }
-                    : undefined,
-            });
+    // ── ACP Agent Implementation ────────────────────────────────
+    const agent = {
+        async initialize(_params) {
             return {
-                success: true,
-                timestamp: Date.now(),
+                protocolVersion: 1,
+                agentInfo: {
+                    name: "macro-agent",
+                    version: "2.0.0",
+                },
+                agentCapabilities: {
+                    loadSession: true,
+                    sessionCapabilities: {
+                        resume: {},
+                    },
+                },
+                extensions: [
+                    ...SUPPORTED_EXTENSIONS.map((name) => ({
+                        name,
+                        description: `macro-agent extension: ${name}`,
+                    })),
+                    ...STUBBED_PEER_EXTENSIONS.map((name) => ({
+                        name,
+                        description: `Peer extension (stub): ${name}`,
+                    })),
+                ],
             };
-        }
-        catch (error) {
-            throw new ACPError(`Failed to send peer message: ${error instanceof Error ? error.message : String(error)}`, "PEER_SEND_FAILED", { to: params.to, error });
-        }
-    }
-    /**
-     * Send a peer request (outbound, request-response)
-     *
-     * Called by external clients to have an agent send a request to a peer
-     * and wait for a response.
-     */
-    async handleSendPeerRequest(params) {
-        if (!this.peerManager) {
-            throw new ACPError("PeerManager not configured for this macro-agent", "NO_PEER_MANAGER");
-        }
-        // Determine which agent is sending (use head manager by default)
-        const headManagers = this.agentManager.listHeadManagers();
-        if (headManagers.length === 0) {
-            throw new ACPError("No agents available to send peer request", "AGENT_NOT_FOUND");
-        }
-        const sendingAgentId = headManagers[0].id;
-        try {
-            const response = await this.peerManager.sendRequest(sendingAgentId, params.to, {
-                method: params.method,
-                params: params.params,
-                timeout: params.timeout,
+        },
+        async newSession(params) {
+            const cwd = params.cwd ?? defaultCwd;
+            // Get or create a head manager for this workspace
+            const headManager = await agentManager.getOrCreateHeadManager({
+                cwd,
             });
-            return response;
-        }
-        catch (error) {
-            throw new ACPError(`Failed to send peer request: ${error instanceof Error ? error.message : String(error)}`, "PEER_SEND_FAILED", { to: params.to, error });
-        }
-    }
-    /**
-     * Deliver a peer message (inbound, fire-and-forget)
-     *
-     * Called by external clients to route an inbound message from a peer
-     * to this macro-agent. The message is queued for the target agent.
-     */
-    async handleDeliverPeerMessage(params) {
-        if (!this.peerManager) {
-            throw new ACPError("PeerManager not configured for this macro-agent", "NO_PEER_MANAGER");
-        }
-        // Use PeerManager's deliverMessage to queue the message
-        const messageId = this.peerManager.deliverMessage(params.from, {
-            type: params.type,
-            payload: params.payload,
-            metadata: params.correlationId
-                ? { correlationId: params.correlationId }
-                : undefined,
-        }, params.targetAgentId);
-        return {
-            success: true,
-            messageId,
-        };
-    }
-    /**
-     * Deliver a peer request (inbound, request-response)
-     *
-     * Called by external clients to route an inbound request from a peer
-     * to this macro-agent. The request is queued and this waits for the
-     * internal agent to respond.
-     */
-    async handleDeliverPeerRequest(params) {
-        if (!this.peerManager) {
-            throw new ACPError("PeerManager not configured for this macro-agent", "NO_PEER_MANAGER");
-        }
-        // Use PeerManager's deliverRequest which returns a promise
-        // that resolves when the internal agent responds
-        const response = await this.peerManager.deliverRequest(params.from, {
-            method: params.method,
-            params: params.params,
-            timeout: params.timeout,
-        }, params.targetAgentId);
-        return response;
-    }
-    // ─────────────────────────────────────────────────────────────────
-    // Capability Extension Handlers
-    // ─────────────────────────────────────────────────────────────────
-    /**
-     * Grant capabilities to a peer
-     */
-    async handleGrantCapability(params) {
-        if (!this.capabilityManager) {
-            throw new ACPError("CapabilityManager not configured for this macro-agent", "NO_PEER_MANAGER");
-        }
-        const capabilities = this.capabilityManager.grant(params.peerId, params.grants, {
-            expiresIn: params.expiresIn,
-            issuedBy: params.issuedBy,
-        });
-        return { capabilities };
-    }
-    /**
-     * Revoke capabilities from a peer
-     */
-    async handleRevokeCapability(params) {
-        if (!this.capabilityManager) {
-            throw new ACPError("CapabilityManager not configured for this macro-agent", "NO_PEER_MANAGER");
-        }
-        this.capabilityManager.revoke(params.peerId, params.grantTypes);
-        return {
-            success: true,
-            remainingCapabilities: this.capabilityManager.getCapabilities(params.peerId),
-        };
-    }
-    /**
-     * Get capabilities for a peer or list all authorized peers
-     */
-    async handleGetCapabilities(params) {
-        if (!this.capabilityManager) {
-            throw new ACPError("CapabilityManager not configured for this macro-agent", "NO_PEER_MANAGER");
-        }
-        if (params.peerId) {
-            return {
-                capabilities: this.capabilityManager.getCapabilities(params.peerId),
-            };
-        }
-        return {
-            authorizedPeers: this.capabilityManager.listAuthorizedPeers(),
-        };
-    }
-    /**
-     * Check if a peer has a required capability
-     */
-    async handleCheckCapability(params) {
-        if (!this.capabilityManager) {
-            throw new ACPError("CapabilityManager not configured for this macro-agent", "NO_PEER_MANAGER");
-        }
-        return {
-            hasCapability: this.capabilityManager.hasCapability(params.peerId, params.required),
-        };
-    }
-    // ─────────────────────────────────────────────────────────────────
-    // Permission Extension Handlers
-    // ─────────────────────────────────────────────────────────────────
-    /**
-     * Respond to a permission request for a session
-     *
-     * Routes the response through the session mapper to find the agent,
-     * then calls the agent manager to resolve the pending permission.
-     */
-    async handleRespondToPermission(params) {
-        const { sessionId, requestId, optionId } = params;
-        // Get the agent ID from session mapper
-        const agentId = this.sessionMapper.getAgentId(sessionId);
-        if (!agentId) {
-            return {
-                success: false,
-                error: `No agent found for session: ${sessionId}`,
-            };
-        }
-        // Respond via agent manager
-        const success = this.agentManager.respondToPermission(agentId, requestId, optionId);
-        if (success) {
-            console.log(`[MacroAgent] Responded to permission ${requestId} for session ${sessionId} with ${optionId}`);
-            return { success: true };
-        }
-        else {
-            return {
-                success: false,
-                error: `Failed to respond to permission ${requestId} for agent ${agentId}`,
-            };
-        }
-    }
-    /**
-     * Cancel a permission request for a session
-     *
-     * Routes the cancellation through the session mapper to find the agent,
-     * then calls the agent manager to cancel the pending permission.
-     */
-    async handleCancelPermission(params) {
-        const { sessionId, requestId } = params;
-        // Get the agent ID from session mapper
-        const agentId = this.sessionMapper.getAgentId(sessionId);
-        if (!agentId) {
-            return {
-                success: false,
-                error: `No agent found for session: ${sessionId}`,
-            };
-        }
-        // Cancel via agent manager
-        const success = this.agentManager.cancelPermission(agentId, requestId);
-        if (success) {
-            console.log(`[MacroAgent] Cancelled permission ${requestId} for session ${sessionId}`);
-            return { success: true };
-        }
-        else {
-            return {
-                success: false,
-                error: `Failed to cancel permission ${requestId} for agent ${agentId}`,
-            };
-        }
-    }
-    /**
-     * Change the permission mode for a running agent at runtime
-     */
-    async handleSetPermissionMode(params) {
-        const { agentId, permissionMode } = params;
-        // Get the current mode before changing
-        const previousMode = this.agentManager.getPermissionMode(agentId);
-        // Set the new mode via agent manager
-        const success = this.agentManager.setPermissionMode(agentId, permissionMode);
-        if (success) {
-            console.log(`[MacroAgent] Set permission mode for agent ${agentId} from ${previousMode} to ${permissionMode}`);
-            return {
-                success: true,
-                previousMode: previousMode ?? undefined,
-            };
-        }
-        else {
+            // Create session mapping
+            const mapping = sessionMapper.createMapping(headManager.session_id, headManager.id);
+            // Annotate sessionlog with swarm metadata (best effort)
+            try {
+                const { annotateSession } = await import("../integrations/sessionlog.js");
+                annotateSession(cwd, {
+                    swarmId: headManager.id,
+                    scope: "macro-agent",
+                });
+            }
+            catch {
+                // sessionlog not available — non-fatal
+            }
             return {
-                success: false,
-                error: `No active session found for agent ${agentId}`,
+                sessionId: mapping.acpSessionId,
             };
-        }
-    }
-    /**
-     * Resume a stopped/failed agent
-     */
-    async handleResumeAgent(params) {
-        const { agentId } = params;
-        if (!agentId) {
-            throw new ACPError("agentId is required", "INVALID_EXTENSION");
-        }
-        // Verify agent exists
-        const agent = this.eventStore.getAgent(agentId);
-        if (!agent) {
-            throw new ACPError(`Agent not found: ${agentId}`, "AGENT_NOT_FOUND");
-        }
-        // Only resume stopped/failed agents
-        if (agent.state !== "stopped" && agent.state !== "failed") {
-            throw new ACPError(`Agent ${agentId} is ${agent.state} — only stopped or failed agents can be resumed`, "INVALID_EXTENSION");
-        }
-        console.log(`[MacroAgent] Resuming agent ${agentId}`);
-        const spawned = await this.agentManager.resume(agentId);
-        return {
-            success: true,
-            agentId: spawned.id,
-            sessionId: spawned.session_id,
-        };
-    }
-    // ─────────────────────────────────────────────────────────────────
-    // Helper Methods
-    // ─────────────────────────────────────────────────────────────────
-    /**
-     * Extract text content from prompt content blocks
-     */
-    extractMessageContent(prompt) {
-        // Handle content blocks array
-        if (Array.isArray(prompt)) {
-            return prompt
-                .map((block) => {
-                if ("text" in block) {
-                    return block.text;
-                }
-                return "";
-            })
-                .filter(Boolean)
-                .join("\n");
-        }
-        return "";
-    }
-    /**
-     * Forward session updates from child agents to the ACP client
-     *
-     * acp-factory already sends updates in ACP SDK format, so we forward
-     * all updates directly. This handles all update types including:
-     * - agent_message_chunk: Text content from agent
-     * - agent_thought_chunk: Agent thinking/reasoning (if enabled)
-     * - user_message_chunk: Echo of user messages
-     * - tool_call: Tool invocation start
-     * - tool_call_update: Tool execution progress/completion
-     * - plan: Plan updates
-     * - available_commands_update: Available slash commands
-     * - current_mode_update: Mode changes (code/plan/etc)
-     * - config_option_update: Configuration changes
-     * - session_info_update: Session title and timestamps
-     *
-     * Permission requests are handled separately via the requestPermission RPC.
-     */
-    async forwardSessionUpdate(acpSessionId, update) {
-        const sessionUpdate = update;
-        // Check if this is a valid session update with the sessionUpdate discriminator
-        if (!("sessionUpdate" in sessionUpdate)) {
-            console.warn(`[MacroAgent] Received update without sessionUpdate field:`, JSON.stringify(update).substring(0, 200));
-            return;
-        }
-        const updateType = sessionUpdate.sessionUpdate;
-        // Log update details based on type (verbose logging for debugging)
-        switch (updateType) {
-            case "agent_message_chunk":
-            case "agent_thought_chunk":
-            case "user_message_chunk": {
-                const content = sessionUpdate.content;
-                const text = content?.text ?? "";
-                if (text) {
-                    console.log(`[MacroAgent] Forwarding ${updateType} (${text.length} chars): "${text.substring(0, 80)}${text.length > 80 ? "..." : ""}"`);
+        },
+        async loadSession(params) {
+            const sessionId = params.sessionId;
+            // Check if we already have a mapping for this session
+            let mapping = sessionMapper.getMapping(sessionId);
+            if (mapping) {
+                return {};
+            }
+            // Try to resume the agent associated with this session
+            // The session ID might be an agent ID in our system
+            const agent = agentManager.get(sessionId);
+            if (agent) {
+                const resumed = await agentManager.resume(sessionId);
+                mapping = sessionMapper.createMapping(resumed.session_id, resumed.id);
+                return {};
+            }
+            throw RequestError.invalidParams({ sessionId }, `Session not found: ${sessionId}`);
+        },
+        async authenticate(_params) {
+            // No-op: macro-agent does not require authentication
+            return {};
+        },
+        async prompt(params) {
+            const mapping = getSessionOrThrow(params.sessionId);
+            const agentId = mapping.agentId;
+            // Extract text content from prompt blocks
+            const textParts = [];
+            for (const block of params.prompt) {
+                if ("text" in block && typeof block.text === "string") {
+                    textParts.push(block.text);
                 }
-                break;
             }
-            case "tool_call": {
-                const toolCallId = sessionUpdate.toolCallId;
-                const title = sessionUpdate.title;
-                const status = sessionUpdate.status;
-                console.log(`[MacroAgent] Forwarding tool_call: id=${toolCallId}, title="${title}", status=${status}`);
-                break;
+            const message = textParts.join("\n") || "";
+            sessionMapper.setProcessing(params.sessionId, true);
+            // Capture first prompt for trajectory metadata (used as session description in OpenHive UI)
+            if (!firstPrompt) {
+                firstPrompt = message.slice(0, 200);
             }
-            case "tool_call_update": {
-                const toolCallId = sessionUpdate.toolCallId;
-                const status = sessionUpdate.status;
-                console.log(`[MacroAgent] Forwarding tool_call_update: id=${toolCallId}, status=${status}`);
-                break;
+            // Track data for trajectory checkpoint
+            const filesTouched = new Set();
+            let toolCallCount = 0;
+            const promptStartTime = Date.now();
+            let tokenUsage = { input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_creation_tokens: 0 };
+            // Update agent state to "busy" — both local MAP server and upstream sidecar
+            try {
+                const mapServer = system.mapServerInstance;
+                if (mapServer) {
+                    const agents = mapServer.agents?.list?.() ?? [];
+                    const mapAgent = agents.find((a) => a.metadata?.localAgentId === agentId);
+                    if (mapAgent) {
+                        mapServer.agents.updateState(mapAgent.id, "busy");
+                    }
+                }
             }
-            case "permission_request": {
-                // Handle permission_request specially - ACP SDK doesn't recognize it as a session update
-                // We need to call requestPermission on the connection to forward to the client
-                // Extract permission request data
-                const permReq = sessionUpdate;
-                // Look up agent ID using the ACP session ID (from the client connection),
-                // NOT permReq.sessionId which is the agent's internal session ID.
-                // The session mapper maps ACP session IDs → agent IDs, so using the
-                // internal session ID would fail silently and drop the permission request.
-                const agentId = this.sessionMapper.getAgentId(acpSessionId);
-                if (!agentId) {
-                    console.warn(`[MacroAgent] No agent found for ACP session ${acpSessionId}, cannot forward permission request`);
-                    return;
+            catch { /* best effort */ }
+            // Update upstream sidecar state (so OpenHive sees activity)
+            try {
+                const sidecarConn = system.mapSidecar;
+                if (sidecarConn?.connected) {
+                    // The sidecar's underlying AgentConnection has updateState
+                    // but it's not directly exposed. Emit via the eventBus instead.
                 }
-                // Forward via requestPermission RPC
-                // This will trigger the client's handler which will show the prompt
-                try {
-                    const response = await this.connection.requestPermission({
-                        sessionId: acpSessionId,
-                        toolCall: {
-                            toolCallId: permReq.toolCall.toolCallId,
-                            title: permReq.toolCall.title,
-                            status: permReq.toolCall.status,
-                            rawInput: permReq.toolCall.rawInput,
-                        },
-                        options: permReq.options,
-                    });
-                    // Forward the response back to the sub-agent via agentManager
-                    if (response.outcome) {
-                        if (response.outcome.outcome === "selected" &&
-                            response.outcome.optionId) {
-                            const success = this.agentManager.respondToPermission(agentId, permReq.requestId, response.outcome.optionId);
-                            if (!success) {
-                                console.warn(`[MacroAgent] Failed to forward permission response to agent ${agentId}`);
+            }
+            catch { /* best effort */ }
+            try {
+                // Stream updates from agentManager.prompt()
+                const updates = agentManager.prompt(agentId, message);
+                for await (const update of updates) {
+                    // Track tool calls, files, and token usage for trajectory checkpoint.
+                    // Also emit task bridge events for TaskCreate/TaskUpdate tool calls.
+                    if ("sessionUpdate" in update) {
+                        const su = update;
+                        if (su.sessionUpdate === "tool_call") {
+                            toolCallCount++;
+                            const input = su.rawInput;
+                            if (input?.file_path)
+                                filesTouched.add(input.file_path);
+                            if (input?.filePath)
+                                filesTouched.add(input.filePath);
+                            if (input?.path)
+                                filesTouched.add(input.path);
+                            if (input?.command)
+                                filesTouched.add(`[bash] ${input.command.slice(0, 50)}`);
+                        }
+                        // Track token usage from session info updates
+                        if (su.sessionUpdate === "session_info_update" && su.usage) {
+                            const u = su.usage;
+                            if (u.inputTokens)
+                                tokenUsage.input_tokens += u.inputTokens;
+                            if (u.outputTokens)
+                                tokenUsage.output_tokens += u.outputTokens;
+                            if (u.cacheReadTokens)
+                                tokenUsage.cache_read_tokens += u.cacheReadTokens;
+                            if (u.cacheCreationTokens)
+                                tokenUsage.cache_creation_tokens += u.cacheCreationTokens;
+                        }
+                        // Bridge tool call completions to MAP events
+                        if (su.sessionUpdate === "tool_call_update" && su.output !== undefined) {
+                            const toolName = su.title ?? "";
+                            const sidecar = system.mapSidecar;
+                            if (sidecar?.connected && toolName) {
+                                try {
+                                    // Native task lifecycle events
+                                    if (toolName === "TaskCreate" || toolName.includes("TaskCreate")) {
+                                        const taskData = typeof su.output === "string"
+                                            ? JSON.parse(su.output) : su.output;
+                                        sidecar.reportCheckpoint?.({
+                                            id: `task-created-${Date.now()}`,
+                                            session_id: params.sessionId,
+                                            agent: agentId,
+                                            branch: null,
+                                            files_touched: [],
+                                            checkpoints_count: checkpointCounter,
+                                            metadata: { phase: "active", event: "task.created", task: taskData },
+                                        }).catch(() => { });
+                                    }
+                                    else if (toolName === "TaskUpdate" || toolName.includes("TaskUpdate")) {
+                                        const taskData = typeof su.output === "string"
+                                            ? JSON.parse(su.output) : su.output;
+                                        sidecar.reportCheckpoint?.({
+                                            id: `task-updated-${Date.now()}`,
+                                            session_id: params.sessionId,
+                                            agent: agentId,
+                                            branch: null,
+                                            files_touched: [],
+                                            checkpoints_count: checkpointCounter,
+                                            metadata: { phase: "active", event: "task.status", task: taskData },
+                                        }).catch(() => { });
+                                    }
+                                    // Gap 3: Opentasks MCP bridge — bridge opentasks tool calls to MAP events
+                                    else if (toolName === "opentasks__create_task" || toolName.includes("create_task")) {
+                                        const taskData = typeof su.output === "string"
+                                            ? JSON.parse(su.output) : su.output;
+                                        sidecar.reportCheckpoint?.({
+                                            id: `opentasks-created-${Date.now()}`,
+                                            session_id: params.sessionId,
+                                            agent: agentId,
+                                            branch: null,
+                                            files_touched: [],
+                                            checkpoints_count: checkpointCounter,
+                                            metadata: { phase: "active", event: "task.created", source: "opentasks", task: taskData },
+                                        }).catch(() => { });
+                                    }
+                                    else if (toolName === "opentasks__update_task" || toolName.includes("update_task")) {
+                                        const taskData = typeof su.output === "string"
+                                            ? JSON.parse(su.output) : su.output;
+                                        sidecar.reportCheckpoint?.({
+                                            id: `opentasks-status-${Date.now()}`,
+                                            session_id: params.sessionId,
+                                            agent: agentId,
+                                            branch: null,
+                                            files_touched: [],
+                                            checkpoints_count: checkpointCounter,
+                                            metadata: { phase: "active", event: "task.status", source: "opentasks", task: taskData },
+                                        }).catch(() => { });
+                                    }
+                                    else if (toolName === "opentasks__link" || toolName.includes("opentasks") && toolName.includes("link")) {
+                                        const linkData = typeof su.output === "string"
+                                            ? JSON.parse(su.output) : su.output;
+                                        sidecar.reportCheckpoint?.({
+                                            id: `opentasks-linked-${Date.now()}`,
+                                            session_id: params.sessionId,
+                                            agent: agentId,
+                                            branch: null,
+                                            files_touched: [],
+                                            checkpoints_count: checkpointCounter,
+                                            metadata: { phase: "active", event: "task.linked", source: "opentasks", link: linkData },
+                                        }).catch(() => { });
+                                    }
+                                    else if (toolName === "opentasks__annotate" || toolName.includes("opentasks") && toolName.includes("annotate")) {
+                                        const annotateData = typeof su.output === "string"
+                                            ? JSON.parse(su.output) : su.output;
+                                        sidecar.reportCheckpoint?.({
+                                            id: `opentasks-sync-${Date.now()}`,
+                                            session_id: params.sessionId,
+                                            agent: agentId,
+                                            branch: null,
+                                            files_touched: [],
+                                            checkpoints_count: checkpointCounter,
+                                            metadata: { phase: "active", event: "task.sync", source: "opentasks", annotation: annotateData },
+                                        }).catch(() => { });
+                                    }
+                                    // Gap 2: Memory sync — detect minimem write tools
+                                    else if (toolName.includes("memory_append") || toolName.includes("memory_upsert")) {
+                                        sidecar.reportCheckpoint?.({
+                                            id: `memory-sync-${Date.now()}`,
+                                            session_id: params.sessionId,
+                                            agent: agentId,
+                                            branch: null,
+                                            files_touched: [],
+                                            checkpoints_count: checkpointCounter,
+                                            metadata: { phase: "active", event: "memory.sync" },
+                                        }).catch(() => { });
+                                    }
+                                }
+                                catch { /* ignore parse errors */ }
                             }
                         }
-                        else if (response.outcome.outcome === "cancelled") {
-                            const success = this.agentManager.cancelPermission(agentId, permReq.requestId);
-                            if (!success) {
-                                console.warn(`[MacroAgent] Failed to cancel permission for agent ${agentId}`);
+                    }
+                    // Handle permission requests from the underlying agent.
+                    // When the agent is in interactive mode, it yields
+                    // PermissionRequestUpdate objects instead of auto-approving.
+                    // We forward these to the client via AgentSideConnection's
+                    // requestPermission() method (JSON-RPC agent→client request).
+                    if (isPermissionRequestUpdate(update)) {
+                        try {
+                            const permResponse = await connection.requestPermission({
+                                sessionId: params.sessionId,
+                                toolCall: {
+                                    toolCallId: update.toolCall.toolCallId,
+                                    title: update.toolCall.title,
+                                    status: update.toolCall.status,
+                                    rawInput: update.toolCall.rawInput,
+                                },
+                                options: update.options,
+                            });
+                            // Relay the permission response back to the agent.
+                            // ACP response: { outcome: { outcome: "selected", optionId } | { outcome: "cancelled" } }
+                            const outcome = permResponse?.outcome;
+                            if (outcome) {
+                                if (outcome.outcome === "selected" && "optionId" in outcome) {
+                                    agentManager.respondToPermission(agentId, update.requestId, outcome.optionId);
+                                }
+                                else if (outcome.outcome === "cancelled") {
+                                    agentManager.cancelPermission(agentId, update.requestId);
+                                }
+                            }
+                        }
+                        catch {
+                            // If the permission request fails (e.g., client disconnected),
+                            // cancel it so the agent doesn't hang.
+                            try {
+                                agentManager.cancelPermission(agentId, update.requestId);
+                            }
+                            catch {
+                                // Best effort
                             }
                         }
+                        continue;
+                    }
+                    // Forward each update to the client as a session notification.
+                    // Only forward ACP-compatible SessionUpdate types; skip
+                    // acp-factory extended types like CompactionUpdate.
+                    if ("sessionUpdate" in update && isACPSessionUpdate(update)) {
+                        const notification = {
+                            sessionId: params.sessionId,
+                            update,
+                        };
+                        await connection.sessionUpdate(notification);
                     }
                 }
-                catch (err) {
-                    console.error(`[MacroAgent] Failed to forward permission_request:`, err instanceof Error ? err.message : err);
-                    // Cancel the permission request on error
+                // Emit enriched trajectory checkpoint after prompt completes.
+                // Matches cc-swarm's wire format so OpenHive UI can display session data.
+                const sidecar = system.mapSidecar;
+                if (sidecar) {
+                    checkpointCounter++;
+                    const agentRecord = system.agentStore?.getAgent?.(agentId);
+                    const agentCwd = agentRecord?.cwd ?? defaultCwd;
+                    const git = getGitInfo(agentCwd);
+                    // Determine sync level from sessionlog config (default: "full")
+                    const syncLevel = system._sessionlogSyncLevel ?? "full";
+                    // Build checkpoint with sync-level gating:
+                    // - lifecycle: phase, turnId, startedAt, label
+                    // - metrics: above + token_usage, files_touched, checkpoints_count, toolCallCount, duration_ms
+                    // - full: everything
+                    const isMetrics = syncLevel === "metrics" || syncLevel === "full";
+                    const isFull = syncLevel === "full";
+                    const checkpoint = {
+                        id: `${params.sessionId}-step${checkpointCounter}`,
+                        session_id: params.sessionId,
+                        agent: agentRecord?.name ?? agentId,
+                        branch: git.branch,
+                        files_touched: isMetrics ? Array.from(filesTouched) : [],
+                        checkpoints_count: isMetrics ? checkpointCounter : 0,
+                        // Token usage — only at metrics level or above
+                        ...(isMetrics && (tokenUsage.input_tokens > 0 || tokenUsage.output_tokens > 0)
+                            ? { token_usage: tokenUsage }
+                            : {}),
+                        metadata: {
+                            // lifecycle fields (always included)
+                            phase: "active",
+                            startedAt: sessionStartedAt,
+                            label: `Step ${checkpointCounter} (${toolCallCount} tool calls)`,
+                            // metrics fields
+                            ...(isMetrics ? {
+                                duration_ms: Date.now() - promptStartTime,
+                                toolCallCount,
+                            } : {}),
+                            // full fields
+                            ...(isFull ? {
+                                project: agentCwd.split("/").pop() ?? "",
+                                projectPath: agentCwd,
+                                firstPrompt: firstPrompt ?? undefined,
+                                gitCommitHash: git.commitHash ?? undefined,
+                                gitRemoteUrl: git.remoteUrl ?? undefined,
+                            } : {}),
+                        },
+                    };
+                    // Enrich with sessionlog state if available (adds turn IDs, better token usage)
+                    let enrichedCheckpoint = checkpoint;
                     try {
-                        this.agentManager.cancelPermission(agentId, permReq.requestId);
+                        const { findActiveSession, enrichCheckpoint } = await import("../integrations/sessionlog.js");
+                        const sessionState = findActiveSession(agentCwd);
+                        if (sessionState) {
+                            enrichedCheckpoint = enrichCheckpoint(sessionState, checkpoint);
+                        }
                     }
                     catch {
-                        // Ignore cancel errors
+                        // sessionlog not available — use base checkpoint
                     }
+                    sidecar.reportCheckpoint(enrichedCheckpoint).catch(() => { });
                 }
-                // Don't forward via sessionUpdate - we handled it via requestPermission
-                return;
+                return { stopReason: "end_turn" };
             }
-            default:
-                // Log other update types at debug level
-                console.log(`[MacroAgent] Forwarding ${updateType}`);
-        }
-        // Accumulate content for history persistence (preserving text/tool interleaving order)
-        const buffer = this.promptBuffers.get(acpSessionId);
-        if (buffer) {
-            if (updateType === "agent_message_chunk") {
-                const content = sessionUpdate.content;
-                if (content?.text) {
-                    const last = buffer.parts[buffer.parts.length - 1];
-                    if (last && last.type === "text") {
-                        last.text += content.text;
-                    }
-                    else {
-                        buffer.parts.push({ type: "text", text: content.text });
-                    }
-                }
+            catch (err) {
+                // If prompt fails, still return a valid response
+                return { stopReason: "cancelled" };
             }
-            else if (updateType === "tool_call" ||
-                updateType === "tool_call_update") {
-                const toolCallId = sessionUpdate.toolCallId;
-                const status = sessionUpdate.status;
-                const meta = sessionUpdate._meta;
-                const toolInfoCache = this.toolInfoCaches.get(acpSessionId);
-                // Cache tool info from initial tool_call events
-                if (updateType === "tool_call" && toolCallId && toolInfoCache) {
-                    toolInfoCache.set(toolCallId, {
-                        title: sessionUpdate.title,
-                        name: meta?.claudeCode?.toolName,
-                        input: sessionUpdate.rawInput,
-                    });
-                }
-                if (status === "completed" || status === "failed") {
-                    // Merge cached info for tool_call_update events that lack title/input
-                    const cached = toolCallId ? toolInfoCache?.get(toolCallId) : undefined;
-                    buffer.parts.push({
-                        type: "tool",
-                        toolCallId,
-                        title: sessionUpdate.title ?? cached?.title,
-                        name: meta?.claudeCode?.toolName ?? cached?.name,
-                        status: sessionUpdate.status,
-                        input: sessionUpdate.rawInput ?? cached?.input,
-                        output: extractToolOutput(sessionUpdate.rawOutput),
-                    });
+            finally {
+                sessionMapper.setProcessing(params.sessionId, false);
+                // Update agent state back to "idle" — local MAP server
+                try {
+                    const mapServer = system.mapServerInstance;
+                    if (mapServer) {
+                        const agents = mapServer.agents?.list?.() ?? [];
+                        const mapAgent = agents.find((a) => a.metadata?.localAgentId === agentId);
+                        if (mapAgent) {
+                            mapServer.agents.updateState(mapAgent.id, "idle");
+                        }
+                    }
                 }
+                catch { /* best effort */ }
             }
-        }
-        // Forward updates via sessionUpdate (except permission_request which is handled above)
-        try {
-            await this.connection.sessionUpdate({
-                sessionId: acpSessionId,
-                update: sessionUpdate,
-            });
-        }
-        catch (err) {
-            console.error(`[MacroAgent] Failed to forward ${updateType}:`, err instanceof Error ? err.message : err);
-        }
-    }
-    /**
-     * Emit a session_info_update with title and timestamps.
-     * Uses agent task as title and session mapping timestamps.
-     */
-    async emitSessionInfo(acpSessionId) {
-        const mapping = this.sessionMapper.getMapping(acpSessionId);
-        const agentId = mapping?.agentId;
-        const agent = agentId ? this.eventStore.getAgent(agentId) : null;
-        const title = agent?.task ?? null;
-        const updatedAt = new Date(mapping?.updatedAt ?? Date.now()).toISOString();
-        try {
-            await this.connection.sessionUpdate({
-                sessionId: acpSessionId,
-                update: {
-                    sessionUpdate: "session_info_update",
-                    title,
-                    updatedAt,
-                },
-            });
-        }
-        catch (err) {
-            console.warn(`[MacroAgent] Failed to send session_info_update:`, err instanceof Error ? err.message : err);
-        }
-    }
-    /**
-     * Build system prompt with configured prefix/suffix
-     */
-    buildSystemPrompt() {
-        const { systemPromptPrefix, systemPromptSuffix } = this.initConfig;
-        if (!systemPromptPrefix && !systemPromptSuffix) {
-            return undefined;
-        }
-        const parts = [];
-        if (systemPromptPrefix) {
-            parts.push(systemPromptPrefix);
-        }
-        if (systemPromptSuffix) {
-            parts.push(systemPromptSuffix);
-        }
-        return parts.join("\n\n");
-    }
-    /**
-     * Merge default sub-agent config with per-spawn override
-     *
-     * Override values take precedence over defaults.
-     * Arrays (like mcpServers) are concatenated, not replaced.
-     */
-    mergeSubAgentConfig(defaults, override) {
-        if (!defaults && !override) {
-            return undefined;
-        }
-        if (!defaults) {
-            return override;
-        }
-        if (!override) {
-            return defaults;
-        }
-        // Deep merge with override taking precedence
-        return {
-            model: override.model ?? defaults.model,
-            maxTokens: override.maxTokens ?? defaults.maxTokens,
-            temperature: override.temperature ?? defaults.temperature,
-            permissionMode: override.permissionMode ?? defaults.permissionMode,
-            agentType: override.agentType ?? defaults.agentType,
-            // Merge env variables (override takes precedence for same keys)
-            env: defaults.env || override.env
-                ? { ...defaults.env, ...override.env }
-                : undefined,
-            // Concatenate MCP servers (both default and override)
-            mcpServers: [...(defaults.mcpServers ?? []), ...(override.mcpServers ?? [])]
-                .length > 0
-                ? [...(defaults.mcpServers ?? []), ...(override.mcpServers ?? [])]
-                : undefined,
-        };
-    }
-    /**
-     * Convert SubAgentConfig to internal AgentConfig format
-     */
-    toAgentConfig(config) {
-        if (!config) {
-            return undefined;
-        }
-        return {
-            model: config.model,
-            maxTokens: config.maxTokens,
-            temperature: config.temperature,
-            env: config.env,
-            mcpServers: config.mcpServers?.map((server) => ({
-                name: server.name,
-                command: server.command,
-                args: server.args,
-                env: server.env,
-            })),
-        };
-    }
-    // ─────────────────────────────────────────────────────────────────
-    // History Persistence Helpers
-    // ─────────────────────────────────────────────────────────────────
-    /**
-     * Ensure a conversation exists in the EventStore for a session.
-     * Uses the ACP session ID as the conversation ID for direct lookup.
-     */
-    ensureConversation(acpSessionId, agentId) {
-        // Guard: EventStore may not support conversations (e.g., in tests with mocks)
-        if (typeof this.eventStore.getConversation !== "function")
-            return;
-        // Check if conversation already exists
-        const existing = this.eventStore.getConversation(acpSessionId);
-        if (existing)
-            return;
-        try {
-            this.eventStore.emit({
-                type: "conversation",
-                source: { agent_id: agentId },
-                payload: {
-                    action: "created",
-                    conversation_id: acpSessionId,
-                    conversation_type: "session",
-                    subject: `ACP session ${acpSessionId}`,
-                },
-            });
-        }
-        catch (error) {
-            console.warn(`[MacroAgent] Failed to create conversation for session ${acpSessionId}:`, error instanceof Error ? error.message : String(error));
-        }
-    }
-    /**
-     * Record user and assistant turns after a prompt completes.
-     */
-    recordPromptTurns(acpSessionId, agentId, userMessage) {
-        const buffer = this.promptBuffers.get(acpSessionId);
-        if (!buffer)
-            return;
-        const now = Date.now();
-        try {
-            // Record user turn
-            if (userMessage) {
-                this.eventStore.emit({
-                    type: "turn",
-                    source: { agent_id: agentId },
-                    payload: {
-                        action: "recorded",
-                        turn_id: `turn_user_${now}_${Math.random().toString(36).slice(2, 8)}`,
-                        conversation_id: acpSessionId,
-                        participant: "user",
-                        timestamp: now,
-                        content_type: "user_prompt",
-                        content: userMessage,
-                        source_type: "explicit",
-                    },
-                });
+        },
+        async cancel(params) {
+            const mapping = sessionMapper.getMapping(params.sessionId);
+            if (!mapping)
+                return;
+            try {
+                await agentManager.terminate(mapping.agentId, "cancelled");
             }
-            // Record assistant turn with accumulated content (parts already in order)
-            const parts = buffer.parts;
-            if (parts.length > 0) {
-                this.eventStore.emit({
-                    type: "turn",
-                    source: { agent_id: agentId },
-                    payload: {
-                        action: "recorded",
-                        turn_id: `turn_asst_${now}_${Math.random().toString(36).slice(2, 8)}`,
-                        conversation_id: acpSessionId,
-                        participant: agentId,
-                        timestamp: now + 1, // +1ms to ensure ordering after user turn
-                        content_type: "assistant_response",
-                        content: { parts },
-                        source_type: "explicit",
-                    },
-                });
+            catch {
+                // Best effort cancellation
             }
-        }
-        catch (error) {
-            console.warn(`[MacroAgent] Failed to record turns for session ${acpSessionId}:`, error instanceof Error ? error.message : String(error));
-        }
-        finally {
-            // Clean up the buffer and tool info cache
-            this.promptBuffers.delete(acpSessionId);
-            this.toolInfoCaches.delete(acpSessionId);
-        }
-    }
-    /**
-     * Handle _macro/getModels extension — returns the session's available models.
-     * Claude Code populates models asynchronously after session creation
-     * (via _model_state_update notification), so this allows the TUI to poll
-     * for the model list once it's available.
-     *
-     * Returns full model info (modelId + name) since Claude Code uses shorthand
-     * model IDs ("default", "sonnet") that don't match models.dev. The name
-     * field (e.g., "Claude Sonnet 4") enables better model registry matching.
-     */
-    handleGetModels(params) {
-        const { sessionId } = params;
-        const agentId = this.sessionMapper.getAgentId(sessionId);
-        if (!agentId) {
-            return { currentModelId: null, availableModels: [] };
-        }
-        const session = this.agentManager.getSession(agentId);
-        if (!session) {
-            return { currentModelId: null, availableModels: [] };
-        }
-        // Try clientHandler's model info store first (from _model_state_update notification)
-        const clientHandler = session.clientHandler;
-        const modelInfo = clientHandler?.getSessionModelInfo?.(session.id);
-        if (modelInfo && modelInfo.availableModels.length > 0) {
-            return modelInfo;
-        }
-        // Fall back to Session.models (from initial session response — just IDs)
-        if (session.models && session.models.length > 0) {
-            return {
-                currentModelId: session.models[0],
-                availableModels: session.models.map((id) => ({ modelId: id, name: id })),
-            };
-        }
-        return { currentModelId: null, availableModels: [] };
-    }
-    /**
-     * Handle _macro/getHistory extension — returns conversation turns for a session
-     */
-    handleGetHistory(params) {
-        const { sessionId, limit } = params;
-        // Query turns from EventStore (conversation ID = session ID)
-        const turns = this.eventStore.listTurns({
-            conversationId: sessionId,
-            order: "asc",
-            limit: limit ?? 200,
-        });
-        // Convert to HistoryTurn format
-        const historyTurns = turns.map((turn) => ({
-            role: turn.contentType === "user_prompt"
-                ? "user"
-                : "assistant",
-            timestamp: turn.timestamp,
-            content: turn.content,
-        }));
-        return { turns: historyTurns };
-    }
-    // ─────────────────────────────────────────────────────────────────
-    // Accessors
-    // ─────────────────────────────────────────────────────────────────
-    /**
-     * Get the session mapper for testing/debugging
-     */
-    getSessionMapper() {
-        return this.sessionMapper;
-    }
-    /**
-     * Get mapped agent ID for a session
-     */
-    getMappedAgentId(acpSessionId) {
-        return this.sessionMapper.getAgentId(acpSessionId);
-    }
-    /**
-     * Get the applied initialization config
-     */
-    getInitConfig() {
-        return this.initConfig;
-    }
+        },
+        async extMethod(method, params) {
+            return handleExtension(method, params);
+        },
+    };
+    return agent;
 }
+/**
+ * Get the SessionMapper instance from a macro-agent.
+ * Exposed for testing and for the WebSocket server.
+ */
+export { SessionMapper };
 //# sourceMappingURL=macro-agent.js.map