macro-agent 0.0.11 → 0.0.13

package/src/acp/__tests__/session-persistence.test.ts

@@ -0,0 +1,276 @@
+/**
+ * Session persistence and recovery tests
+ *
+ * Tests that session lifecycle events are persisted to the EventStore
+ * and that SessionMapper can recover its state from persisted sessions.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { SessionMapper } from "../session-mapper.js";
+import { createEventStore, type EventStore } from "../../store/event-store.js";
+
+describe("Session Persistence", () => {
+  let eventStore: EventStore;
+  let mapper: SessionMapper;
+
+  beforeEach(async () => {
+    eventStore = await createEventStore({ inMemory: true });
+    mapper = new SessionMapper(eventStore);
+  });
+
+  afterEach(async () => {
+    await eventStore.close();
+  });
+
+  describe("session lifecycle events", () => {
+    it("should emit session created event on createMapping", () => {
+      mapper.createMapping("session-1", "agent-head");
+
+      const session = eventStore.getSession("session-1");
+      expect(session).not.toBeNull();
+      expect(session!.id).toBe("session-1");
+      expect(session!.head_manager_id).toBe("agent-head");
+      expect(session!.current_agent_id).toBe("agent-head");
+      expect(session!.state).toBe("active");
+      expect(session!.created_at).toBeGreaterThan(0);
+    });
+
+    it("should emit session mounted event on mount", () => {
+      mapper.createMapping("session-1", "agent-head");
+      mapper.mount("session-1", "agent-child");
+
+      const session = eventStore.getSession("session-1");
+      expect(session!.state).toBe("mounted");
+      expect(session!.current_agent_id).toBe("agent-child");
+      expect(session!.head_manager_id).toBe("agent-head");
+    });
+
+    it("should emit session unmounted event on unmount", () => {
+      mapper.createMapping("session-1", "agent-head");
+      mapper.mount("session-1", "agent-child");
+      mapper.unmount("session-1");
+
+      const session = eventStore.getSession("session-1");
+      expect(session!.state).toBe("active");
+      expect(session!.current_agent_id).toBe("agent-head");
+    });
+
+    it("should emit unmounted when mounting back to head manager", () => {
+      mapper.createMapping("session-1", "agent-head");
+      mapper.mount("session-1", "agent-child");
+      mapper.mount("session-1", "agent-head");
+
+      const session = eventStore.getSession("session-1");
+      expect(session!.state).toBe("active");
+      expect(session!.current_agent_id).toBe("agent-head");
+    });
+
+    it("should emit session closed event on removeMapping", () => {
+      mapper.createMapping("session-1", "agent-head");
+      mapper.removeMapping("session-1");
+
+      const session = eventStore.getSession("session-1");
+      expect(session!.state).toBe("closed");
+      expect(session!.closed_at).toBeGreaterThan(0);
+    });
+
+    it("should not emit close for non-existent session", () => {
+      mapper.removeMapping("non-existent");
+
+      const session = eventStore.getSession("non-existent");
+      expect(session).toBeNull();
+    });
+
+    it("should track multiple sessions independently", () => {
+      mapper.createMapping("session-1", "agent-1");
+      mapper.createMapping("session-2", "agent-2");
+      mapper.mount("session-1", "agent-child");
+
+      const s1 = eventStore.getSession("session-1");
+      const s2 = eventStore.getSession("session-2");
+
+      expect(s1!.state).toBe("mounted");
+      expect(s2!.state).toBe("active");
+    });
+  });
+
+  describe("listSessions", () => {
+    it("should list sessions by state", () => {
+      mapper.createMapping("session-1", "agent-1");
+      mapper.createMapping("session-2", "agent-2");
+      mapper.mount("session-1", "agent-child");
+
+      const active = eventStore.listSessions({ state: "active" });
+      const mounted = eventStore.listSessions({ state: "mounted" });
+
+      expect(active).toHaveLength(1);
+      expect(active[0].id).toBe("session-2");
+      expect(mounted).toHaveLength(1);
+      expect(mounted[0].id).toBe("session-1");
+    });
+
+    it("should list sessions by agent", () => {
+      mapper.createMapping("session-1", "agent-1");
+      mapper.createMapping("session-2", "agent-2");
+
+      const sessions = eventStore.listSessions({ agent_id: "agent-1" });
+      expect(sessions).toHaveLength(1);
+      expect(sessions[0].id).toBe("session-1");
+    });
+
+    it("should filter closed sessions", () => {
+      mapper.createMapping("session-1", "agent-1");
+      mapper.createMapping("session-2", "agent-2");
+      mapper.removeMapping("session-1");
+
+      const active = eventStore.listSessions({ state: "active" });
+      const closed = eventStore.listSessions({ state: "closed" });
+
+      expect(active).toHaveLength(1);
+      expect(active[0].id).toBe("session-2");
+      expect(closed).toHaveLength(1);
+      expect(closed[0].id).toBe("session-1");
+    });
+  });
+
+  describe("session events in event log", () => {
+    it("should persist session events that can be queried", () => {
+      mapper.createMapping("session-1", "agent-head");
+      mapper.mount("session-1", "agent-child");
+      mapper.unmount("session-1");
+      mapper.removeMapping("session-1");
+
+      const events = eventStore.query({ type: "session" });
+      expect(events).toHaveLength(4);
+      expect(events[0].payload.action).toBe("created");
+      expect(events[1].payload.action).toBe("mounted");
+      expect(events[2].payload.action).toBe("unmounted");
+      expect(events[3].payload.action).toBe("closed");
+    });
+  });
+});
+
+describe("Session Recovery", () => {
+  let eventStore: EventStore;
+
+  beforeEach(async () => {
+    eventStore = await createEventStore({ inMemory: true });
+  });
+
+  afterEach(async () => {
+    await eventStore.close();
+  });
+
+  it("should recover active sessions from EventStore", () => {
+    // Create sessions with original mapper
+    const original = new SessionMapper(eventStore);
+    original.createMapping("session-1", "agent-1");
+    original.createMapping("session-2", "agent-2");
+
+    // Create new mapper and recover
+    const recovered = new SessionMapper(eventStore);
+    const count = recovered.recoverFromStore();
+
+    expect(count).toBe(2);
+    expect(recovered.size).toBe(2);
+    expect(recovered.getAgentId("session-1")).toBe("agent-1");
+    expect(recovered.getAgentId("session-2")).toBe("agent-2");
+  });
+
+  it("should recover mounted sessions with correct state", () => {
+    const original = new SessionMapper(eventStore);
+    original.createMapping("session-1", "agent-head");
+    original.mount("session-1", "agent-child");
+
+    const recovered = new SessionMapper(eventStore);
+    const count = recovered.recoverFromStore();
+
+    expect(count).toBe(1);
+    expect(recovered.getAgentId("session-1")).toBe("agent-child");
+    expect(recovered.getHeadManagerId("session-1")).toBe("agent-head");
+    expect(recovered.isMounted("session-1")).toBe(true);
+  });
+
+  it("should not recover closed sessions", () => {
+    const original = new SessionMapper(eventStore);
+    original.createMapping("session-1", "agent-1");
+    original.createMapping("session-2", "agent-2");
+    original.removeMapping("session-1");
+
+    const recovered = new SessionMapper(eventStore);
+    const count = recovered.recoverFromStore();
+
+    expect(count).toBe(1);
+    expect(recovered.getAgentId("session-1")).toBeUndefined();
+    expect(recovered.getAgentId("session-2")).toBe("agent-2");
+  });
+
+  it("should recover after unmount returns to active state", () => {
+    const original = new SessionMapper(eventStore);
+    original.createMapping("session-1", "agent-head");
+    original.mount("session-1", "agent-child");
+    original.unmount("session-1");
+
+    const recovered = new SessionMapper(eventStore);
+    const count = recovered.recoverFromStore();
+
+    expect(count).toBe(1);
+    expect(recovered.getAgentId("session-1")).toBe("agent-head");
+    expect(recovered.isMounted("session-1")).toBe(false);
+  });
+
+  it("should reset isProcessing to false on recovery", () => {
+    const original = new SessionMapper(eventStore);
+    original.createMapping("session-1", "agent-1");
+    original.setProcessing("session-1", true);
+
+    const recovered = new SessionMapper(eventStore);
+    recovered.recoverFromStore();
+
+    const status = recovered.getSessionStatus("agent-1");
+    expect(status).toBeDefined();
+    expect(status!.isProcessing).toBe(false);
+  });
+
+  it("should return 0 when no EventStore is configured", () => {
+    const mapper = new SessionMapper();
+    const count = mapper.recoverFromStore();
+    expect(count).toBe(0);
+  });
+
+  it("should survive view rebuild", () => {
+    const original = new SessionMapper(eventStore);
+    original.createMapping("session-1", "agent-1");
+    original.createMapping("session-2", "agent-2");
+    original.mount("session-1", "agent-child");
+    original.removeMapping("session-2");
+
+    // Simulate reload (which rebuilds views from events)
+    // We don't need to call reload() since in-memory; just verify
+    // the view state matches after rebuilding
+    const session1 = eventStore.getSession("session-1");
+    const session2 = eventStore.getSession("session-2");
+
+    expect(session1!.state).toBe("mounted");
+    expect(session1!.current_agent_id).toBe("agent-child");
+    expect(session2!.state).toBe("closed");
+  });
+});
+
+describe("SessionMapper backward compatibility", () => {
+  it("should work without EventStore (original behavior)", () => {
+    const mapper = new SessionMapper();
+
+    const mapping = mapper.createMapping("session-1", "agent-head");
+    expect(mapping.agentId).toBe("agent-head");
+
+    mapper.mount("session-1", "agent-child");
+    expect(mapper.getAgentId("session-1")).toBe("agent-child");
+
+    mapper.unmount("session-1");
+    expect(mapper.getAgentId("session-1")).toBe("agent-head");
+
+    mapper.removeMapping("session-1");
+    expect(mapper.getMapping("session-1")).toBeUndefined();
+  });
+});

package/src/acp/macro-agent.ts

@@ -61,6 +61,8 @@ import type {
   RespondToPermissionResponse,
   CancelPermissionRequest,
   CancelPermissionResponse,
+  ResumeAgentRequest,
+  ResumeAgentResponse,
 } from "./types.js";
 import { ACPError } from "./types.js";
 import type { PeerManager } from "../peer/peer-manager.js";
@@ -92,6 +94,7 @@ const SUPPORTED_EXTENSIONS: ACPExtensionMethod[] = [
   "_macro/checkCapability",
   "_macro/respondToPermission",
   "_macro/cancelPermission",
+  "_macro/resume",
 ];
 
 // ─────────────────────────────────────────────────────────────────
@@ -155,8 +158,16 @@ export class MacroAgent implements Agent {
     this.peerManager = config.peerManager;
     this.capabilityManager = config.capabilityManager;
     this.roleRegistry = config.roleRegistry ?? new DefaultRoleRegistry();
-    this.sessionMapper = new SessionMapper();
+    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`
+      );
+    }
   }
 
   // ─────────────────────────────────────────────────────────────────
@@ -229,9 +240,25 @@ export class MacroAgent implements Agent {
    * Load an existing session from EventStore
    */
   async loadSession(params: LoadSessionRequest): Promise<LoadSessionResponse> {
-    const acpSessionId = params.sessionId;
+    let acpSessionId = params.sessionId;
     const cwd = params.cwd ?? this.defaultCwd;
 
+    // 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 as { _meta?: Record<string, unknown> })._meta
+      ?.agentId as string | undefined;
+    if (metaAgentId) {
+      const agent = this.eventStore.getAgent(metaAgentId as AgentId);
+      if (!agent) {
+        throw new Error(`Agent not found: ${metaAgentId}`);
+      }
+      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);
@@ -340,8 +367,8 @@ export class MacroAgent implements Agent {
       await this.connection.sessionUpdate({
         sessionId: acpSessionId,
         update: {
-          type: "agent_message_chunk",
-          textChunk: `Error: ${errorMessage}`,
+          sessionUpdate: "agent_message_chunk",
+          content: { type: "text", text: `Error: ${errorMessage}` },
         },
       });
 
@@ -481,6 +508,11 @@ export class MacroAgent implements Agent {
           params as unknown as CancelPermissionRequest
         ) as unknown as Record<string, unknown>;
 
+      case "_macro/resume":
+        return this.handleResumeAgent(
+          params as unknown as ResumeAgentRequest
+        ) as unknown as Record<string, unknown>;
+
       default:
         throw new ACPError(
           `Unknown extension method: ${method}`,
@@ -1089,6 +1121,42 @@ export class MacroAgent implements Agent {
     }
   }
 
+  /**
+   * Resume a stopped/failed agent
+   */
+  private async handleResumeAgent(
+    params: ResumeAgentRequest
+  ): Promise<ResumeAgentResponse> {
+    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
   // ─────────────────────────────────────────────────────────────────
@@ -1221,10 +1289,14 @@ export class MacroAgent implements Agent {
             toolCall: {
               toolCallId: permReq.toolCall.toolCallId,
               title: permReq.toolCall.title,
-              status: permReq.toolCall.status,
+              status: permReq.toolCall.status as "pending" | "in_progress" | "completed" | "failed" | undefined,
               rawInput: permReq.toolCall.rawInput,
             },
-            options: permReq.options,
+            options: permReq.options as Array<{
+              kind: "allow_once" | "allow_always" | "reject_once" | "reject_always";
+              name: string;
+              optionId: string;
+            }>,
           });
 
           // Forward the response back to the sub-agent via agentManager
@@ -1280,7 +1352,7 @@ export class MacroAgent implements Agent {
     try {
       await this.connection.sessionUpdate({
         sessionId: acpSessionId,
-        update: sessionUpdate,
+        update: sessionUpdate as Parameters<AgentSideConnection["sessionUpdate"]>[0]["update"],
       });
     } catch (err) {
       console.error(

package/src/acp/session-mapper.ts

@@ -6,9 +6,12 @@
  * - Default mapping to head manager on session creation
  * - Remapping via mount to control different agents
  * - Multiple concurrent sessions with independent mappings
+ * - Persistent session lifecycle events via EventStore
+ * - Recovery of session state from EventStore after restart
  */
 
 import type { AgentId } from "../store/types/index.js";
+import type { EventStore } from "../store/event-store.js";
 import type { ACPSessionId, SessionMapping } from "./types.js";
 import { ACPError } from "./types.js";
 
@@ -16,6 +19,13 @@ export class SessionMapper {
   /** Map of ACP session ID to mapping info */
   private mappings: Map<ACPSessionId, SessionMapping> = new Map();
 
+  /** Optional EventStore for persisting session lifecycle events */
+  private eventStore: EventStore | null;
+
+  constructor(eventStore?: EventStore) {
+    this.eventStore = eventStore ?? null;
+  }
+
   /**
    * Register a new ACP session with its head manager
    *
@@ -40,6 +50,12 @@ export class SessionMapper {
     };
 
     this.mappings.set(acpSessionId, mapping);
+
+    // Persist session creation event
+    this.emitSessionEvent("created", acpSessionId, {
+      head_manager_id: headManagerId,
+    });
+
     return mapping;
   }
 
@@ -123,6 +139,19 @@ export class SessionMapper {
     mapping.isMounted = agentId !== mapping.headManagerId;
     mapping.updatedAt = Date.now();
 
+    // Persist mount event
+    if (mapping.isMounted) {
+      this.emitSessionEvent("mounted", acpSessionId, {
+        target_agent_id: agentId,
+        previous_agent_id: previousAgentId,
+      });
+    } else {
+      // Mounting back to head manager is effectively an unmount
+      this.emitSessionEvent("unmounted", acpSessionId, {
+        previous_agent_id: previousAgentId,
+      });
+    }
+
     return previousAgentId;
   }
 
@@ -141,6 +170,11 @@ export class SessionMapper {
     mapping.isMounted = false;
     mapping.updatedAt = Date.now();
 
+    // Persist unmount event
+    this.emitSessionEvent("unmounted", acpSessionId, {
+      previous_agent_id: previousAgentId,
+    });
+
     return previousAgentId;
   }
 
@@ -155,12 +189,17 @@ export class SessionMapper {
   }
 
   /**
-   * Remove a session mapping
+   * Remove a session mapping and emit a close event
    *
    * @param acpSessionId - The ACP session ID
    * @returns True if removed, false if not found
    */
   removeMapping(acpSessionId: ACPSessionId): boolean {
+    const existed = this.mappings.has(acpSessionId);
+    if (existed) {
+      // Persist close event before removing
+      this.emitSessionEvent("closed", acpSessionId, {});
+    }
     return this.mappings.delete(acpSessionId);
   }
 
@@ -226,6 +265,43 @@ export class SessionMapper {
     return undefined;
   }
 
+  /**
+   * Recover session mappings from the EventStore.
+   *
+   * Loads all non-closed sessions and rebuilds the in-memory mapping state.
+   * Called during initialization to restore sessions after a restart.
+   *
+   * @returns Number of sessions recovered
+   */
+  recoverFromStore(): number {
+    if (!this.eventStore || typeof this.eventStore.listSessions !== "function") {
+      return 0;
+    }
+
+    const activeSessions = this.eventStore.listSessions({ state: "active" });
+    const mountedSessions = this.eventStore.listSessions({ state: "mounted" });
+    const allSessions = [...activeSessions, ...mountedSessions];
+
+    let recovered = 0;
+    for (const session of allSessions) {
+      const now = Date.now();
+      const mapping: SessionMapping = {
+        acpSessionId: session.id,
+        agentId: session.current_agent_id,
+        headManagerId: session.head_manager_id,
+        isMounted: session.state === "mounted",
+        createdAt: session.created_at,
+        updatedAt: now,
+        isProcessing: false,
+        lastProcessingChangeAt: now,
+      };
+      this.mappings.set(session.id, mapping);
+      recovered++;
+    }
+
+    return recovered;
+  }
+
   /**
    * Get the number of active session mappings
    */
@@ -239,4 +315,35 @@ export class SessionMapper {
   clear(): void {
     this.mappings.clear();
   }
+
+  /**
+   * Emit a session lifecycle event to the EventStore
+   */
+  private emitSessionEvent(
+    action: string,
+    sessionId: ACPSessionId,
+    details: Record<string, unknown>
+  ): void {
+    if (!this.eventStore || typeof this.eventStore.emit !== "function") {
+      return;
+    }
+
+    try {
+      this.eventStore.emit({
+        type: "session",
+        source: {},
+        payload: {
+          action,
+          session_id: sessionId,
+          ...details,
+        },
+      });
+    } catch (error) {
+      // Log but don't fail — session events are supplementary
+      console.warn(
+        `[SessionMapper] Failed to emit session ${action} event:`,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
 }

package/src/acp/types.ts

@@ -605,6 +605,35 @@ export interface CancelPermissionResponse {
   error?: string;
 }
 
+// ─────────────────────────────────────────────────────────────────
+// ACP Extension: _macro/resume
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Request for _macro/resume extension
+ *
+ * Resumes a stopped/failed agent by spawning a new process and
+ * loading the existing session. Called on the head manager's ACP stream.
+ */
+export interface ResumeAgentRequest {
+  /** Agent ID to resume */
+  agentId: AgentId;
+}
+
+/**
+ * Response for _macro/resume extension
+ */
+export interface ResumeAgentResponse {
+  /** Whether the resume was successful */
+  success: boolean;
+
+  /** The resumed agent's ID */
+  agentId: AgentId;
+
+  /** The agent's session ID */
+  sessionId: string;
+}
+
 // ─────────────────────────────────────────────────────────────────
 // Extension Method Types (Union)
 // ─────────────────────────────────────────────────────────────────
@@ -627,7 +656,8 @@ export type ACPExtensionMethod =
   | "_macro/getCapabilities"
   | "_macro/checkCapability"
   | "_macro/respondToPermission"
-  | "_macro/cancelPermission";
+  | "_macro/cancelPermission"
+  | "_macro/resume";
 
 /**
  * Map of extension methods to their request types
@@ -648,6 +678,7 @@ export interface ACPExtensionRequests {
   "_macro/checkCapability": CheckCapabilityRequest;
   "_macro/respondToPermission": RespondToPermissionRequest;
   "_macro/cancelPermission": CancelPermissionRequest;
+  "_macro/resume": ResumeAgentRequest;
 }
 
 /**
@@ -669,6 +700,7 @@ export interface ACPExtensionResponses {
   "_macro/checkCapability": CheckCapabilityResponse;
   "_macro/respondToPermission": RespondToPermissionResponse;
   "_macro/cancelPermission": CancelPermissionResponse;
+  "_macro/resume": ResumeAgentResponse;
 }
 
 // ─────────────────────────────────────────────────────────────────