macro-agent 0.1.8 → 0.1.11

package/src/map/server.ts

@@ -74,6 +74,14 @@ export function createMAPServerInstance(
   const clientWebSockets = new Map<string, WebSocket>(); // participant/agent ID → WebSocket
   // Track subscription IDs by client agent ID for ACP response delivery
   const clientSubscriptions = new Map<string, string[]>(); // agent ID → subscription IDs
+  /**
+   * Per-subscription monotonic event counter. The MAP SDK's Subscription
+   * checks `sequenceNumber !== lastSequenceNumber + 1` and warns on gaps —
+   * using `Date.now()` (millisecond timestamp) breaks that assumption since
+   * each event becomes a "gap". Track a per-subscription counter starting
+   * at 1 and increment per event.
+   */
+  const subscriptionSequence = new Map<string, number>(); // subscription ID → next sequence number
   // Track original ws.send for each WebSocket (before interception)
   const originalSends = new Map<WebSocket, Function>();
 
@@ -90,11 +98,21 @@ export function createMAPServerInstance(
 
     // ── Agent extensions ──────────────────────────────────────────
     handlers["_macro/spawnAgent"] = async (params, ctx) => {
+      // Forward the full SpawnAgentOptions surface so callers can set
+      // permission mode, agent type, custom prompt, model config, etc.
+      // Previously this handler dropped everything except role/cwd/task,
+      // making _macro/spawnAgent useless for any non-default agent.
       const spawned = await agentManager.spawn({
         task: params.task ?? "Spawned via MAP",
         parent: params.parent ?? null,
         cwd: params.cwd,
         role: params.role ?? "worker",
+        permissionMode: params.permissionMode,
+        agentType: params.agentType,
+        customPrompt: params.customPrompt,
+        topics: params.topics,
+        config: params.config,
+        taskRef: params.taskRef,
       });
 
       // Ensure agent is registered in MAPServer's registry.
@@ -107,7 +125,7 @@ export function createMAPServerInstance(
             role: params.role ?? "worker",
             state: "idle",
             sessionId: ctx?.session?.id,
-            metadata: { localAgentId: spawned.id, task: params.task },
+            metadata: { peerAgentId: spawned.id, task: params.task },
           });
           if (registered?.id) {
             mapIdToLocalId.set(registered.id, spawned.id);
@@ -145,6 +163,160 @@ export function createMAPServerInstance(
       return { agent: { id: spawned.id } };
     };
 
+    /**
+     * Resume an agent session with full routing + session info returned.
+     *
+     * Session-first resolution: given a Claude Code `providerSessionId` (the
+     * session UUID persisted on the session record), reverse-look-up the
+     * owning agent. Falls back to `agentId` (either the MAP ULID or the
+     * local store id) when no providerSessionId is given or the reverse
+     * lookup misses.
+     *
+     * Behavior:
+     *   1. Resolve the local agent id.
+     *   2. Call `agentManager.resume(localId)` — idempotent; the manager
+     *      re-spawns the coordinator/head-manager if its process isn't live,
+     *      otherwise returns the existing handle.
+     *   3. Ensure the agent is registered in the MAPServer's registry so
+     *      ACP streams can target it via the returned peerMapId.
+     *   4. Return `{ agent: { id: peerMapId, localId, name }, acpSessionId,
+     *      providerSessionId }` — the caller needs peerMapId to open the
+     *      ACP stream and providerSessionId to pass into `session/load` so
+     *      Claude Code replays its on-disk transcript.
+     *
+     * Used by OpenHive's POST /sessions/:id/resume to revive a session whose
+     * swarm has been offline for longer than the hub's stale-grace window.
+     */
+    handlers["_macro/resumeAgent"] = async (params, ctx) => {
+      const providerSessionIdParam = params.providerSessionId as string | undefined;
+      const agentIdParam = params.agentId as string | undefined;
+
+      let localId: string | undefined;
+      let providerSessionId: string | undefined;
+
+      if (providerSessionIdParam) {
+        const session = agentStore.findSessionByProviderSessionId(providerSessionIdParam);
+        if (session) {
+          localId = session.agent_id;
+          providerSessionId = session.provider_session_id;
+        }
+      }
+
+      if (!localId && agentIdParam) {
+        localId = mapIdToLocalId.get(agentIdParam) ?? agentIdParam;
+        const session = agentStore.getSession(localId);
+        providerSessionId = session?.provider_session_id;
+      }
+
+      if (!localId) {
+        return {
+          success: false,
+          error: "providerSessionId or agentId required",
+        };
+      }
+
+      const agentRec = agentStore.getAgent(localId);
+      if (!agentRec) {
+        return { success: false, error: `Agent not found: ${localId}` };
+      }
+
+      // Already-running case: skip resume() (which rejects with ALREADY_RUNNING)
+      // and return the live agent's session info straight from the store.
+      // This makes the call idempotent — callers don't need to pre-check.
+      let resumedId: string;
+      let resumedSessionId: string;
+      let resumedName: string | undefined;
+      if (agentManager.hasActiveSession(localId as any)) {
+        resumedId = localId;
+        resumedName = agentRec.name;
+        const liveSession = agentStore.getSession(localId);
+        if (!liveSession) {
+          return {
+            success: false,
+            error: `Agent ${localId} is active but has no session record`,
+          };
+        }
+        resumedSessionId = liveSession.session_id;
+      } else {
+        try {
+          const resumed = await agentManager.resume(localId as any);
+          resumedId = resumed.id;
+          resumedSessionId = resumed.session_id;
+          resumedName = (resumed as any).name;
+        } catch (err) {
+          return { success: false, error: (err as Error).message };
+        }
+      }
+
+      // Ensure agent is registered in MAPServer's registry. resume() fires
+      // the spawned lifecycle event, which the lifecycle bridge handles —
+      // but we also register here for subscription routing context on the
+      // current MAP session (mirrors _macro/spawnAgent).
+      if (mapServer && !localIdToMapId.has(resumedId)) {
+        try {
+          const registered = mapServer.agents.register({
+            name: resumedName ?? resumedId,
+            role: agentRec.role,
+            state: "idle",
+            sessionId: ctx?.session?.id,
+            metadata: { peerAgentId: resumedId },
+          });
+          if (registered?.id) {
+            mapIdToLocalId.set(registered.id, resumedId);
+            localIdToMapId.set(resumedId, registered.id);
+          }
+        } catch {
+          // Best effort; lifecycle bridge will register on spawned event
+        }
+      }
+
+      const peerMapId = localIdToMapId.get(resumedId) ?? resumedId;
+
+      return {
+        success: true,
+        agent: {
+          id: peerMapId,
+          localId: resumedId,
+          name: resumedName,
+          role: agentRec.role,
+        },
+        acpSessionId: resumedSessionId,
+        providerSessionId,
+      };
+    };
+
+    /**
+     * Terminate a running agent. Accepts either the agent's local ID or the
+     * MAP-assigned ULID (we resolve back to local via mapIdToLocalId).
+     * Reason defaults to "stopped"; use "cancelled" for user-initiated stops.
+     */
+    handlers["_macro/terminateAgent"] = async (params) => {
+      const agentIdParam = params.agentId as string | undefined;
+      const reason = (params.reason as string) ?? "cancelled";
+      if (!agentIdParam) {
+        return { success: false, error: "agentId is required" };
+      }
+      // Resolve either a MAP ULID or a local agent ID to our internal ID.
+      const localId = mapIdToLocalId.get(agentIdParam) ?? agentIdParam;
+      try {
+        await agentManager.terminate(localId as any, reason as any);
+        return { success: true };
+      } catch (err) {
+        return { success: false, error: (err as Error).message };
+      }
+    };
+
+    /**
+     * Inspect ACP stream → peer agent bindings on this MAP server.
+     * Each stream carries the peer agent id (macro-agent's internal store id)
+     * it was opened against, set by the bridge from MAP routing. Useful for
+     * routing tests and debugging multi-coordinator scenarios.
+     */
+    handlers["_macro/getAcpStreamBindings"] = async () => {
+      if (!acpBridge) return { bindings: [] };
+      return { bindings: acpBridge.getStreamBindings() };
+    };
+
     // ── Task extensions ───────────────────────────────────────────
     handlers["_macro/task/list"] = async () => {
       if (!tasksAdapter.connected) return { tasks: [] };
@@ -256,15 +428,21 @@ export function createMAPServerInstance(
 
             // Send as subscription event notification (what ACPStreamConnection expects).
             // The _pushEvent method expects: { subscriptionId, sequenceNumber, eventId, timestamp, event }
+            //
+            // sequenceNumber must be a per-subscription monotonic counter that
+            // increments by exactly 1 — the SDK warns on any gap. Don't use
+            // Date.now() here (breaks the contract on every event).
             for (const subId of subIds) {
               const event = rawEvent.params?.event ?? rawEvent;
               const eventId = event.id ?? `acp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+              const nextSeq = (subscriptionSequence.get(subId) ?? 0) + 1;
+              subscriptionSequence.set(subId, nextSeq);
               const notification = JSON.stringify({
                 jsonrpc: "2.0",
                 method: "map/event",
                 params: {
                   subscriptionId: subId,
-                  sequenceNumber: Date.now(),
+                  sequenceNumber: nextSeq,
                   eventId,
                   timestamp: Date.now(),
                   event,
@@ -381,6 +559,32 @@ export function createMAPServerInstance(
           return originalSend(data, ...args);
         } as any;
 
+        // Observe incoming messages so we drop subscription IDs from our
+        // routing array when the client unsubscribes. Without this, closed
+        // ACP streams keep receiving events ("MAP: Event for unknown
+        // subscription" warnings on the client). We don't intercept the
+        // SDK's processing — this listener runs alongside it.
+        ws.on("message", (data: any) => {
+          try {
+            const text = typeof data === "string"
+              ? data
+              : Buffer.isBuffer(data)
+                ? data.toString("utf-8")
+                : String(data);
+            const msg = JSON.parse(text);
+            if (msg?.method === "map/unsubscribe") {
+              const subId = msg?.params?.subscriptionId;
+              if (typeof subId === "string") {
+                const idx = subscriptionIds.indexOf(subId);
+                if (idx >= 0) subscriptionIds.splice(idx, 1);
+                subscriptionSequence.delete(subId);
+              }
+            }
+          } catch {
+            // Non-JSON or parse failure — ignore
+          }
+        });
+
         const stream = websocketStream(ws as unknown as globalThis.WebSocket);
         const router = mapServer.accept(stream, {
           role: "client",
@@ -390,6 +594,11 @@ export function createMAPServerInstance(
 
         ws.on("close", () => {
           connectionCount--;
+          // Clear sequence counters for any subscriptions belonging to this
+          // connection. Use a copy of subscriptionIds since we don't mutate it.
+          for (const subId of subscriptionIds) {
+            subscriptionSequence.delete(subId);
+          }
           if (clientAgentId) {
             clientWebSockets.delete(clientAgentId);
             clientSubscriptions.delete(clientAgentId);
@@ -404,16 +613,21 @@ export function createMAPServerInstance(
         try {
           if (event.type === "spawned" || event.type === "started") {
             const agent = event.agent;
-            // Register agent in MAPServer's registry so it's visible to clients.
-            // We wrap in try/catch because the registry's event bus may throw
-            // if subscription filters encounter unexpected state.
+            // Register agent ONCE. spawn() fires "spawned" immediately followed
+            // by "started", so without this guard the listener re-registers
+            // on the second event — generating a fresh MAP ULID and overwriting
+            // localIdToMapId. Consumers racing against that overwrite (like the
+            // sidecar's lifecycle bridge, which snapshots peerMapId into hub
+            // metadata) end up disagreeing with _macro/spawnAgent's return
+            // value on which ULID refers to this agent.
+            if (localIdToMapId.has(agent.id)) return;
             try {
               const registered = mapServer.agents.register({
                 name: agent.name ?? agent.id,
                 role: agent.role ?? "worker",
                 state: "idle",
                 metadata: {
-                  localAgentId: agent.id, // Store local ID in metadata
+                  peerAgentId: agent.id, // macro-agent's internal store id
                   parent: (agent as any).parent ?? null,
                   task: (agent as any).task ?? null,
                   cwd: (agent as any).cwd ?? null,
@@ -454,7 +668,7 @@ export function createMAPServerInstance(
             role: agent.role ?? "worker",
             state: agent.state === "running" ? "busy" : "idle",
             metadata: {
-              localAgentId: agent.id,
+              peerAgentId: agent.id,
               parent: agent.parent ?? null,
               task: agent.task ?? null,
             },
@@ -535,5 +749,9 @@ export function createMAPServerInstance(
     getConnectionCount(): number {
       return connectionCount;
     },
+
+    getLocalMapId(localAgentId: string): string | undefined {
+      return localIdToMapId.get(localAgentId);
+    },
   };
 }

package/src/map/sidecar.ts

@@ -35,7 +35,7 @@ export function createMAPSidecar(
   deps: MAPSidecarDeps,
   config: MAPSidecarConfig,
 ): MAPSidecar {
-  const { agentManager, agentStore, inboxAdapter, tasksAdapter } = deps;
+  const { agentManager, agentStore, inboxAdapter, tasksAdapter, getLocalMapId, gitCascadeAdapter } = deps;
   const scope = config.scope ?? "swarm:macro-agent";
   const agentName = config.agentName ?? "macro-agent-sidecar";
 
@@ -50,6 +50,7 @@ export function createMAPSidecar(
   let trajectoryReporter: TrajectoryReporter | null = null;
   let taskBridge: TaskBridge | null = null;
   let coordinationCleanup: (() => void) | null = null;
+  let cascadeBridgeCleanup: (() => void) | null = null;
   let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
 
   /**
@@ -82,6 +83,10 @@ export function createMAPSidecar(
       coordinationCleanup();
       coordinationCleanup = null;
     }
+    if (cascadeBridgeCleanup) {
+      try { cascadeBridgeCleanup(); } catch { /* non-critical */ }
+      cascadeBridgeCleanup = null;
+    }
     if (trajectoryReporter) {
       trajectoryReporter.stop();
       trajectoryReporter = null;
@@ -126,6 +131,10 @@ export function createMAPSidecar(
         metadata: {
           systemId: config.systemId ?? "macro-agent",
           type: "macro-agent-sidecar",
+          // Signals that this swarm can spawn ACP-capable coordinators on demand,
+          // even before any coordinator has registered. The hub's /sessions/create-acp
+          // endpoint handles the spawn via _macro/spawnAgent when no ACP agent exists.
+          canHostAcp: true,
         },
         reconnection: {
           enabled: config.reconnection?.enabled ?? true,
@@ -175,6 +184,19 @@ export function createMAPSidecar(
       isConnected = true;
       } // end if (!isConnected)
 
+      // Publish sidecar metadata to the hub. The MAP SDK's connect()/register()
+      // does not propagate the `metadata` field from connect options — it only
+      // forwards name/role/capabilities/scopes. Call updateMetadata explicitly
+      // so the hub sees canHostAcp (and any other metadata the UI relies on).
+      try {
+        const metadata = (connectOpts.metadata as Record<string, unknown>) ?? {};
+        if (typeof connection.updateMetadata === "function") {
+          await connection.updateMetadata(metadata);
+        }
+      } catch {
+        // Non-fatal — metadata is advisory
+      }
+
       // Monitor connection state
       connection.onStateChange(
         (newState: string, _oldState: string) => {
@@ -252,6 +274,7 @@ export function createMAPSidecar(
       agentStore,
       scope,
       taskBridge,
+      getLocalMapId,
     );
     lifecycleCallback = bridge.callback;
     lifecycleCleanup = bridge.cleanup;
@@ -270,6 +293,21 @@ export function createMAPSidecar(
       tasksAdapter,
       trajectoryReporter,
     });
+
+    // 5. Cascade Bridge + Action Handler (optional — only when a GitCascadeAdapter is available)
+    if (gitCascadeAdapter) {
+      const { createCascadeBridge } = await import("./cascade-bridge.js");
+      const cascadeBridge = createCascadeBridge(connection, gitCascadeAdapter);
+
+      // 5b. Inbound action handler — receives x-cascade/request.* from hub
+      const { setupCascadeActionHandlers } = await import("./cascade-action-handler.js");
+      const actionCleanup = setupCascadeActionHandlers(connection, gitCascadeAdapter);
+
+      cascadeBridgeCleanup = () => {
+        cascadeBridge.dispose();
+        actionCleanup();
+      };
+    }
   }
 
   return {
@@ -316,5 +354,14 @@ export function createMAPSidecar(
       if (!trajectoryReporter) return null;
       return trajectoryReporter.reportCheckpoint(checkpoint);
     },
+
+    async emitEvent(event: Record<string, unknown>): Promise<void> {
+      if (!connection || !isConnected) return;
+      try {
+        await connection.send({ scope }, { ...event, _origin: "macro-agent" });
+      } catch {
+        // Best effort — MAP hub may be temporarily unavailable
+      }
+    },
   };
 }

package/src/map/types.ts

@@ -68,6 +68,21 @@ export interface MAPSidecarDeps {
   agentStore: AgentStore;
   inboxAdapter: InboxAdapter;
   tasksAdapter: TasksAdapter;
+  /**
+   * Optional lookup for the local MAP server's ULID for a given local agent ID.
+   * When provided, the lifecycle bridge includes this ID in hub registration
+   * metadata so clients (e.g., SwarmCraft) can target the agent correctly on
+   * the macro-agent's own MAP server.
+   */
+  getLocalMapId?: (localAgentId: string) => string | undefined;
+  /**
+   * Optional GitCascadeAdapter. When provided, the sidecar wires a cascade
+   * bridge that forwards the adapter's event stream to the hub as
+   * `x-cascade/*` MAP notifications. Leave undefined to disable cascade
+   * event forwarding (macro-agent will still use cascade internally, just
+   * without hub observability).
+   */
+  gitCascadeAdapter?: import("../workspace/git-cascade-adapter.js").GitCascadeAdapter;
 }
 
 // =============================================================================
@@ -88,6 +103,9 @@ export interface MAPSidecar {
   reportCheckpoint(
     checkpoint: TrajectoryCheckpointPayload,
   ): Promise<TrajectoryCheckpointResult | null>;
+
+  /** Emit a custom event to the MAP hub scope (best-effort, no-op if disconnected) */
+  emitEvent?(event: Record<string, unknown>): Promise<void>;
 }
 
 // =============================================================================
@@ -244,4 +262,9 @@ export interface MAPServerInstance {
   getUrl(): string;
   /** Get number of active connections */
   getConnectionCount(): number;
+  /**
+   * Resolve a local agent ID (macro-agent internal) to its MAP server-assigned ULID.
+   * Returns undefined if the agent is not registered on the MAP server yet.
+   */
+  getLocalMapId(localAgentId: string): string | undefined;
 }

package/src/mcp/tools/done-v2.ts

@@ -106,6 +106,15 @@ function buildLifecycleContext(
     streamId: record?.workspace_stream_id ?? process.env.MACRO_STREAM_ID,
   };
 
+  // Pull task_ref out of agent metadata if it was stashed there at spawn
+  // time. Validates the shape — bad data is silently dropped rather than
+  // pushed downstream into cascade payloads.
+  const meta = record?.metadata as Record<string, unknown> | undefined;
+  const tr = meta?.task_ref as { resource_id?: unknown; node_id?: unknown } | undefined;
+  if (tr && typeof tr.resource_id === "string" && typeof tr.node_id === "string") {
+    ctx.taskRef = { resource_id: tr.resource_id, node_id: tr.node_id };
+  }
+
   // Resolve capabilities for dispatch
   if (roleRegistry) {
     try {

package/src/teams/team-manager-v2.ts

@@ -142,6 +142,43 @@ export class TeamManagerV2 {
       basePath ?? process.cwd()
     );
 
+    // V3: auto-wire TopologyPolicy when the team declares
+    // `macro_agent.workspace`. Requires a WorkspaceManager to be present.
+    if (workspaceManager) {
+      try {
+        const { extractWorkspaceConfig } = await import(
+          "../workspace/yaml-schema.js"
+        );
+        const workspaceConfig = extractWorkspaceConfig(
+          manifest as unknown as { macro_agent?: Record<string, unknown> }
+        );
+        if (workspaceConfig) {
+          const { YamlDrivenTopology } = await import(
+            "../workspace/topology/yaml-driven.js"
+          );
+          const policy = new YamlDrivenTopology(workspaceConfig);
+          agentManager.setTopologyPolicy(policy);
+
+          // Kick the topology's onTeamStart so team-root streams get
+          // created before any agents spawn.
+          await policy.onTeamStart({
+            teamName: name,
+            teamInstanceId: `${name}-${this.instanceCounter + 1}`,
+            workspaceConfig,
+            workspaceManager,
+          });
+        }
+      } catch (err) {
+        // Non-fatal: topology wiring is a progressive enhancement. Log and
+        // fall through to legacy capability-based dispatch.
+        console.warn(
+          `[TeamManagerV2] topology auto-wire skipped for team "${name}": ${
+            err instanceof Error ? err.message : String(err)
+          }`
+        );
+      }
+    }
+
     // Create runtime
     const runtimeServices: TeamServicesV2 = {
       agentManager,

package/src/teams/team-runtime-v2.ts

@@ -506,12 +506,12 @@ export class TeamRuntimeV2 {
       const capabilities = resolved.capabilities;
       let streamId = options.streamId;
       let streamConfig = options.streamConfig;
-      let dataplaneTaskId = options.dataplaneTaskId;
+      let gitCascadeTaskId = options.gitCascadeTaskId;
 
       if (this.teamStreamId && capabilities) {
         if (capabilities.includes(WORKSPACE_CAPABILITIES.WORKTREE)) {
           streamId = streamId ?? this.teamStreamId;
-          dataplaneTaskId = dataplaneTaskId ?? `worker-${Date.now()}`;
+          gitCascadeTaskId = gitCascadeTaskId ?? `worker-${Date.now()}`;
         } else if (capabilities.includes(WORKSPACE_CAPABILITIES.INTEGRATE)) {
           streamId = streamId ?? this.teamStreamId;
         }
@@ -521,7 +521,7 @@ export class TeamRuntimeV2 {
         ...options,
         streamId,
         streamConfig,
-        dataplaneTaskId,
+        gitCascadeTaskId,
         capabilities: capabilities ?? options.capabilities,
         // Set team scope on all team agents
         team_instance: options.team_instance ?? this.manifest.name,
@@ -846,6 +846,26 @@ Focus on correctness — your changes go live immediately.`);
     const { workspaceManager } = this.services;
     if (!workspaceManager || !this.integrationStrategy) return;
 
+    // V3 coexistence: if TeamManagerV2 has already wired a YamlDrivenTopology
+    // from `macro_agent.workspace`, that policy owns the team root stream.
+    // Don't create a second one via the legacy createIntegrationStream.
+    const hasV3Topology =
+      typeof (
+        this.services.agentManager as {
+          getTopologyPolicy?: () => unknown;
+        }
+      ).getTopologyPolicy === 'function';
+    // AgentManager doesn't expose a getter today, so detect indirectly: a
+    // V3-wired team has already created a stream owned by `team:<name>`.
+    const existingTeamRoot = workspaceManager
+      .listStreams({ ownerId: `team:${this.manifest.name}` } as never)
+      .find((s: { name: string }) => s.name === this.manifest.name);
+
+    if (existingTeamRoot) {
+      this.teamStreamId = existingTeamRoot.id;
+      return;
+    }
+
     try {
       this.teamStreamId = workspaceManager.createIntegrationStream(
         rootAgentId,