macro-agent 0.1.12 → 0.2.1

package/src/map/sidecar.ts

@@ -23,6 +23,13 @@ import type {
   TaskBridge,
 } from "./types.js";
 import type { AgentLifecycleCallback } from "../agent/types.js";
+import {
+  REPO_PROTOCOL_VERSION,
+  RepoClient,
+  RepoManager,
+  type RepoClientTransport,
+  type WorkspaceCapability,
+} from "./repo-workspace.js";
 
 /**
  * Create a MAP sidecar that connects macro-agent to an OpenHive MAP hub.
@@ -35,7 +42,7 @@ export function createMAPSidecar(
   deps: MAPSidecarDeps,
   config: MAPSidecarConfig,
 ): MAPSidecar {
-  const { agentManager, agentStore, inboxAdapter, tasksAdapter, getLocalMapId, gitCascadeAdapter } = deps;
+  const { agentManager, agentStore, inboxAdapter, tasksAdapter, getLocalMapId, gitCascadeAdapter, dispatcherAgentId } = deps;
   const scope = config.scope ?? "swarm:macro-agent";
   const agentName = config.agentName ?? "macro-agent-sidecar";
 
@@ -51,8 +58,29 @@ export function createMAPSidecar(
   let taskBridge: TaskBridge | null = null;
   let coordinationCleanup: (() => void) | null = null;
   let cascadeBridgeCleanup: (() => void) | null = null;
+  let mailBridgeCleanup: (() => void) | null = null;
+  let dispatchSpawnHandlerCleanup: (() => void) | null = null;
+  let dispatchMessageHandlerCleanup: (() => void) | null = null;
+  let dispatchPermissionsHandlerCleanup: (() => void) | null = null;
+  let workspaceManager: RepoManager | null = null;
+  let workspaceTransport: RepoClientTransport | null = null;
   let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
 
+  // Resolve the workspace capability from env vars. Setting OPENHIVE_WORKSPACE_DECLARE=off
+  // disables both explicit declare AND trajectory-handler bootstrap on the hub side.
+  const workspaceCapability: WorkspaceCapability = {
+    protocolVersion: REPO_PROTOCOL_VERSION,
+    declare: {
+      enabled: process.env.OPENHIVE_WORKSPACE_DECLARE !== "off",
+      defaultVisibility:
+        (process.env.OPENHIVE_WORKSPACE_VISIBILITY as
+          | "private"
+          | "hub_local"
+          | "federated") ?? "hub_local",
+    },
+    list: { enabled: true },
+  };
+
   /**
    * Build the MAP connection URL with auth token.
    */
@@ -83,10 +111,26 @@ export function createMAPSidecar(
       coordinationCleanup();
       coordinationCleanup = null;
     }
+    if (mailBridgeCleanup) {
+      try { mailBridgeCleanup(); } catch { /* non-critical */ }
+      mailBridgeCleanup = null;
+    }
     if (cascadeBridgeCleanup) {
       try { cascadeBridgeCleanup(); } catch { /* non-critical */ }
       cascadeBridgeCleanup = null;
     }
+    if (dispatchMessageHandlerCleanup) {
+      try { dispatchMessageHandlerCleanup(); } catch { /* non-critical */ }
+      dispatchMessageHandlerCleanup = null;
+    }
+    if (dispatchSpawnHandlerCleanup) {
+      try { dispatchSpawnHandlerCleanup(); } catch { /* non-critical */ }
+      dispatchSpawnHandlerCleanup = null;
+    }
+    if (dispatchPermissionsHandlerCleanup) {
+      try { dispatchPermissionsHandlerCleanup(); } catch { /* non-critical */ }
+      dispatchPermissionsHandlerCleanup = null;
+    }
     if (trajectoryReporter) {
       trajectoryReporter.stop();
       trajectoryReporter = null;
@@ -101,6 +145,8 @@ export function createMAPSidecar(
     }
     lifecycleCallback = null;
     taskBridge = null;
+    workspaceManager = null;
+    workspaceTransport = null;
   }
 
   /**
@@ -127,6 +173,7 @@ export function createMAPSidecar(
             canUpdate: true,
             canList: true,
           },
+          workspace: workspaceCapability,
         },
         metadata: {
           systemId: config.systemId ?? "macro-agent",
@@ -278,6 +325,8 @@ export function createMAPSidecar(
     );
     lifecycleCallback = bridge.callback;
     lifecycleCleanup = bridge.cleanup;
+    const awaitAcpRegistration = bridge.awaitRegistration;
+    const findLocalAgentByMapId = bridge.findLocalAgentByMapId;
     lifecycleUnsubscribe = agentManager.onLifecycleEvent(lifecycleCallback);
 
     // 3. Trajectory Reporter
@@ -294,6 +343,300 @@ export function createMAPSidecar(
       trajectoryReporter,
     });
 
+    // 4b. Mail Bridge — forwards `mail/turn.received` notifications from the
+    // hub into the local agent-inbox so swarm-dispatch's MessagePort can
+    // pick them up via its `inbox.events` subscription. Without this,
+    // hub-side mail never reaches the dispatcher.
+    const { setupMailBridge } = await import("./mail-bridge.js");
+    mailBridgeCleanup = await setupMailBridge({
+      connection,
+      inboxAdapter,
+      dispatcherAgentId,
+      log: (msg) => console.log(msg),
+    });
+
+    // 4c. x-dispatch/spawn-agent handler — notification-pair pattern.
+    //
+    // The MAP SDK's AgentConnection doesn't expose setRequestHandler, so
+    // the hub→swarm spawn-agent "request" is sent as a notification
+    // with a correlation_id. We process and reply with a `.response`
+    // notification carrying the same correlation_id (or an error).
+    //
+    // Dual-listen: subscribe to BOTH the canonical
+    // `x-dispatch/spawn-agent.request` (Tier 2+, owned by swarm-dispatch)
+    // AND the legacy `dispatch/spawn-agent.request` for one release
+    // window. Reply on the matching channel — the hub's response
+    // dispatcher accepts both.
+    const { handleDispatchSpawnAgent } = await import(
+      "../dispatch/spawn-agent-handler.js"
+    );
+    const {
+      handleSpawnAgentRequest,
+      X_DISPATCH_METHODS: SPAWN_METHODS,
+      LEGACY_DISPATCH_SPAWN_AGENT_REQUEST,
+      LEGACY_DISPATCH_SPAWN_AGENT_RESPONSE,
+    } = await import("swarm-dispatch/client");
+
+    const makeSpawnHandler = (
+      responseMethod: string,
+    ): ((params: unknown) => Promise<void>) =>
+      async (params) => {
+        await handleSpawnAgentRequest({
+          params,
+          runtime: {
+            async spawn(req) {
+              return handleDispatchSpawnAgent(
+                req as unknown as Parameters<typeof handleDispatchSpawnAgent>[0],
+                {
+                  agentManager,
+                  // Wait barrier: lifecycle-bridge resolves once
+                  // `map/agents/register` completes, so the orchestrator's
+                  // subsequent `findAcpAgentInfo` lookup doesn't race.
+                  waitForAcpRegistration: awaitAcpRegistration,
+                  log: (msg) => console.log(msg),
+                },
+              );
+            },
+          },
+          sendResponse: async (responseParams) => {
+            await connection.sendNotification(responseMethod, responseParams);
+          },
+          log: (msg) => console.log(msg),
+        });
+      };
+
+    const canonicalSpawnHandler = makeSpawnHandler(
+      SPAWN_METHODS.SPAWN_AGENT_RESPONSE,
+    );
+    const legacySpawnHandler = makeSpawnHandler(
+      LEGACY_DISPATCH_SPAWN_AGENT_RESPONSE,
+    );
+
+    connection.onNotification(
+      SPAWN_METHODS.SPAWN_AGENT_REQUEST,
+      canonicalSpawnHandler,
+    );
+    connection.onNotification(
+      LEGACY_DISPATCH_SPAWN_AGENT_REQUEST,
+      legacySpawnHandler,
+    );
+    dispatchSpawnHandlerCleanup = () => {
+      try {
+        if (typeof connection.offNotification === "function") {
+          connection.offNotification(
+            SPAWN_METHODS.SPAWN_AGENT_REQUEST,
+            canonicalSpawnHandler,
+          );
+          connection.offNotification(
+            LEGACY_DISPATCH_SPAWN_AGENT_REQUEST,
+            legacySpawnHandler,
+          );
+        }
+      } catch {
+        /* connection already torn down */
+      }
+    };
+
+    // 4c'. x-dispatch/permissions.{set,clear} handlers — notification-pair
+    // pattern, mirrors spawn-agent's shape. Used by hubs (e.g. OpenHive's
+    // ACP+reuse dispatch path) to apply per-dispatch loadout deny/allow
+    // rules to a long-lived agent's session at runtime via the
+    // permission-overlay registry. The prompt iterator in
+    // `agent-manager-v2.ts` enforces the overlay against
+    // `permission_request` ACP session updates. Pairs with the mail+reuse
+    // path's overlay set/clear in `mail-inbound-reuse-consumer.ts` —
+    // same registry, different transport.
+    const {
+      handlePermissionsSet,
+      handlePermissionsClear,
+      X_DISPATCH_PERMISSIONS_METHODS,
+    } = await import("../dispatch/permissions-handler.js");
+
+    // Response shape per swarm-dispatch's notification-rpc registry:
+    //   { correlation_id, result }  → resolve(result)
+    //   { correlation_id, error: { code?, message? } } → reject
+    // The handler's `{ ok, error?: string }` is wrapped accordingly.
+    const sendPermissionsResponse = async (
+      method: string,
+      correlationId: string | undefined,
+      result: { ok: true } | { ok: false; error: string },
+    ): Promise<void> => {
+      const body: Record<string, unknown> = {};
+      if (correlationId) body.correlation_id = correlationId;
+      if (result.ok) {
+        body.result = result;
+      } else {
+        body.error = { message: result.error };
+      }
+      try {
+        await connection.sendNotification(method, body);
+      } catch (err) {
+        console.warn(
+          `[${method}] response send failed: ${(err as Error).message}`,
+        );
+      }
+    };
+
+    const permissionsSetHandler = async (params: unknown): Promise<void> => {
+      const correlationId =
+        (params as { correlation_id?: string })?.correlation_id;
+      const result = handlePermissionsSet(
+        params as Parameters<typeof handlePermissionsSet>[0],
+        (msg) => console.log(msg),
+      );
+      await sendPermissionsResponse(
+        X_DISPATCH_PERMISSIONS_METHODS.SET_RESPONSE,
+        correlationId,
+        result,
+      );
+    };
+
+    const permissionsClearHandler = async (params: unknown): Promise<void> => {
+      const correlationId =
+        (params as { correlation_id?: string })?.correlation_id;
+      const result = handlePermissionsClear(
+        params as Parameters<typeof handlePermissionsClear>[0],
+        (msg) => console.log(msg),
+      );
+      await sendPermissionsResponse(
+        X_DISPATCH_PERMISSIONS_METHODS.CLEAR_RESPONSE,
+        correlationId,
+        result,
+      );
+    };
+
+    connection.onNotification(
+      X_DISPATCH_PERMISSIONS_METHODS.SET_REQUEST,
+      permissionsSetHandler,
+    );
+    connection.onNotification(
+      X_DISPATCH_PERMISSIONS_METHODS.CLEAR_REQUEST,
+      permissionsClearHandler,
+    );
+    dispatchPermissionsHandlerCleanup = () => {
+      try {
+        if (typeof connection.offNotification === "function") {
+          connection.offNotification(
+            X_DISPATCH_PERMISSIONS_METHODS.SET_REQUEST,
+            permissionsSetHandler,
+          );
+          connection.offNotification(
+            X_DISPATCH_PERMISSIONS_METHODS.CLEAR_REQUEST,
+            permissionsClearHandler,
+          );
+        }
+      } catch {
+        /* connection already torn down */
+      }
+    };
+
+    // 4d. map/dispatch/message handler — receives hub-routed envelopes
+    // addressed to a specific agent on this swarm via MAP scope. The hub
+    // takes this path (not mail/turn) when the target agent declares
+    // `messaging.canReceive: true` per-agent but not `mail.canJoin`,
+    // which is the default for long-lived workers/coordinators registered
+    // by the lifecycle bridge. Without this handler, mail+reuse dispatches
+    // are silently dropped on the swarm side.
+    //
+    // Translate the hub-assigned MAP ULID (`to_agent_id`) → local agent
+    // id and forward the envelope into the local inbox so the new
+    // `mail-inbound-reuse-consumer` picks it up.
+    const dispatchMessageHandler = async (params: unknown): Promise<void> => {
+      const p = params as
+        | (Record<string, unknown> & {
+            to_agent_id?: string;
+            envelope?: unknown;
+            from_agent_id?: string;
+          })
+        | undefined;
+      const toAgentId = p?.to_agent_id;
+      const envelope = p?.envelope;
+      if (!toAgentId || !envelope) {
+        console.warn(
+          "[sidecar] map/dispatch/message missing to_agent_id or envelope; ignoring",
+        );
+        return;
+      }
+      const localAgentId = findLocalAgentByMapId(toAgentId);
+      if (!localAgentId) {
+        console.warn(
+          `[sidecar] map/dispatch/message recipient ${toAgentId} not registered locally; dropping`,
+        );
+        return;
+      }
+      // Translate envelope { type, body } → { schema, data } shape that the
+      // mail-inbound-reuse-consumer expects (mirrors mail-bridge's
+      // translation for `mail/turn.received`).
+      //
+      // Hub-side mail-transport injects `body._conversationId` when sending
+      // via MAP scope (sendViaMapScope) — extract it here and surface it
+      // on the top-level content (alongside `data`) so the
+      // mail-inbound-reuse-consumer's reply path can `postMailTurn` to
+      // the right conversation. Without this, the consumer drops the
+      // reply with "No conversationId".
+      const env = envelope as { type?: string; body?: Record<string, unknown> };
+      const conversationId =
+        env.body && typeof env.body._conversationId === "string"
+          ? (env.body._conversationId as string)
+          : undefined;
+      const content: Record<string, unknown> =
+        env.type && env.body
+          ? { schema: env.type, data: env.body }
+          : (envelope as Record<string, unknown>);
+      const contentWithMarker: Record<string, unknown> = {
+        type: "data",
+        ...content,
+        ...(conversationId ? { _conversationId: conversationId } : {}),
+      };
+      try {
+        await inboxAdapter.send(
+          (p?.from_agent_id as string | undefined) ?? "openhive-hub",
+          localAgentId,
+          contentWithMarker as never,
+          { importance: "normal" },
+        );
+      } catch (err) {
+        console.warn(
+          `[sidecar] map/dispatch/message inbox.send failed for ${localAgentId}: ` +
+            `${(err as Error).message}`,
+        );
+      }
+    };
+    // Dual-listen: subscribe to BOTH the canonical `x-dispatch/message`
+    // (the new method name owned by swarm-dispatch's protocol-constants
+    // module) AND the legacy `map/dispatch/message` alias for one
+    // release window. Older hub builds send under the legacy name; new
+    // builds send under the canonical name. Once the dual-listen window
+    // closes, drop the legacy registration.
+    const {
+      X_DISPATCH_METHODS,
+      LEGACY_MAP_DISPATCH_MESSAGE_METHOD,
+    } = await import("swarm-dispatch/client");
+    connection.onNotification(
+      X_DISPATCH_METHODS.MESSAGE,
+      dispatchMessageHandler,
+    );
+    connection.onNotification(
+      LEGACY_MAP_DISPATCH_MESSAGE_METHOD,
+      dispatchMessageHandler,
+    );
+    dispatchMessageHandlerCleanup = () => {
+      try {
+        if (typeof connection.offNotification === "function") {
+          connection.offNotification(
+            X_DISPATCH_METHODS.MESSAGE,
+            dispatchMessageHandler,
+          );
+          connection.offNotification(
+            LEGACY_MAP_DISPATCH_MESSAGE_METHOD,
+            dispatchMessageHandler,
+          );
+        }
+      } catch {
+        /* connection already torn down */
+      }
+    };
+
     // 5. Cascade Bridge + Action Handler (optional — only when a GitCascadeAdapter is available)
     if (gitCascadeAdapter) {
       const { createCascadeBridge } = await import("./cascade-bridge.js");
@@ -308,6 +651,56 @@ export function createMAPSidecar(
         actionCleanup();
       };
     }
+
+    // 6. Workspace (kinds/repo) — declare attached repos to the hub.
+    //    Discovers repos from WORKSPACE_* env vars (set by openhive's swarm-spawn
+    //    flow when spawning with a `repo_id`) plus OPENHIVE_WORKSPACE_REPOS for
+    //    multi-repo declarations. Skipped entirely when capability.declare is off.
+    if (workspaceCapability.declare.enabled) {
+      try {
+        // OpenHive's MAP server registers x-workspace/repo.* as request handlers
+        // (additionalHandlers), not notification handlers — so route notify
+        // through callExtension and ignore the (void) response.
+        const repoTransport: RepoClientTransport = {
+          notify: async (method: string, params: unknown) => {
+            await connection.callExtension(method, params);
+          },
+          request: (method: string, params: unknown) =>
+            connection.callExtension(method, params),
+        };
+        const manager = new RepoManager();
+        const single =
+          process.env.WORKSPACE_REPO_URL && process.env.WORKSPACE_LOCAL_PATH
+            ? [{
+                remoteUrl: process.env.WORKSPACE_REPO_URL,
+                localPath: process.env.WORKSPACE_LOCAL_PATH,
+              }]
+            : [];
+        const multi = process.env.OPENHIVE_WORKSPACE_REPOS
+          ? (JSON.parse(process.env.OPENHIVE_WORKSPACE_REPOS) as Array<{
+              remoteUrl: string;
+              localPath: string;
+            }>)
+          : [];
+        for (const cfg of [...single, ...multi]) {
+          await manager.attach(cfg);
+        }
+        if (manager.list().length > 0) {
+          const client = new RepoClient(repoTransport);
+          await client.declare(RepoClient.snapshot(manager));
+          workspaceManager = manager;
+          workspaceTransport = repoTransport;
+          console.log(
+            `[map-sidecar] Declared ${manager.list().length} workspace(s) to hub`,
+          );
+        }
+      } catch (err) {
+        // Non-fatal — sidecar continues without workspace declarations
+        console.warn(
+          `[map-sidecar] Workspace declare failed: ${(err as Error).message}`,
+        );
+      }
+    }
   }
 
   return {
@@ -363,5 +756,42 @@ export function createMAPSidecar(
         // Best effort — MAP hub may be temporarily unavailable
       }
     },
+
+    async postMailTurn(
+      conversationId: string,
+      participantId: string,
+      content: string,
+    ): Promise<void> {
+      if (!connection || !isConnected) {
+        console.warn(
+          `[map-sidecar] postMailTurn skipped (connection=${!!connection} ` +
+            `isConnected=${isConnected}) conv=${conversationId}`,
+        );
+        return;
+      }
+      try {
+        await connection.sendNotification("mail/turn", {
+          conversationId,
+          participantId,
+          contentType: "text/plain",
+          content,
+        });
+      } catch (err) {
+        // Best effort — hub may be temporarily unavailable. Log at warn
+        // so silent failures are visible during postmortem.
+        console.warn(
+          `[map-sidecar] postMailTurn failed for conv=${conversationId}: ` +
+            `${(err as Error).message ?? String(err)}`,
+        );
+      }
+    },
+
+    getWorkspaceManager() {
+      return workspaceManager;
+    },
+
+    getRepoTransport() {
+      return workspaceTransport;
+    },
   };
 }

package/src/map/types.ts

@@ -83,6 +83,15 @@ export interface MAPSidecarDeps {
    * without hub observability).
    */
   gitCascadeAdapter?: import("../workspace/git-cascade-adapter.js").GitCascadeAdapter;
+
+  /**
+   * The swarm-dispatch dispatcher agent ID (e.g. "dispatcher:<claimantId>").
+   * When provided, the mail bridge delivers hub-forwarded mail turns directly
+   * to this inbox recipient so createAgentInboxPort.onIncoming fires
+   * correctly. Without it, bridged turns land in BRIDGE_RECIPIENT_ID and the
+   * MessagePort never sees them.
+   */
+  dispatcherAgentId?: string;
 }
 
 // =============================================================================
@@ -106,6 +115,31 @@ export interface MAPSidecar {
 
   /** Emit a custom event to the MAP hub scope (best-effort, no-op if disconnected) */
   emitEvent?(event: Record<string, unknown>): Promise<void>;
+
+  /**
+   * Post a mail turn back to the hub via the `mail/turn` MAP notification.
+   * Used by the dispatch reply bridge to forward worker output into the hub's
+   * mail conversation after a mail-inbound task completes.
+   * No-op if disconnected.
+   */
+  postMailTurn?(
+    conversationId: string,
+    participantId: string,
+    content: string,
+  ): Promise<void>;
+
+  /**
+   * Access the sidecar's workspace RepoManager (if workspace declarations
+   * are enabled and the sidecar is connected). Used by mail-inbound-consumer
+   * for pre-spawn repo mount.
+   */
+  getWorkspaceManager?(): unknown;
+
+  /**
+   * Access the sidecar's repo client transport for declaring newly-attached
+   * repos to the hub. Used by mail-inbound-consumer after pre-spawn clone.
+   */
+  getRepoTransport?(): { notify(method: string, params: unknown): Promise<void>; request(method: string, params: unknown): Promise<unknown> } | null;
 }
 
 // =============================================================================

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

@@ -178,6 +178,7 @@ export function createDoneHandlerV2(
       inboxAdapter,
       tasksAdapter,
       agentManager,
+      agentStore,
       taskMode: deps.taskMode,
       mergeQueue: deps.mergeQueue,
     };

package/src/teams/team-loader.ts

@@ -84,7 +84,9 @@ export async function loadTeam(
 
   const manifest = template.manifest;
   const communication = (manifest.communication ?? {}) as CommunicationConfig;
-  const macroAgent = parseMacroAgentExtensions(manifest.macro_agent);
+  const macroAgent = parseMacroAgentExtensions(
+    manifest.macro_agent as Record<string, unknown> | undefined,
+  );
 
   // 2. Build enforcement-enriched roles
   const resolvedRoles = new Map<string, ResolvedTeamRole>();

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

@@ -63,6 +63,8 @@ function manifestToResolved(manifest: TeamManifest): MacroResolvedTemplate {
       roles: new Map(),
       prompts: new Map(),
       mcpServers: manifest._mcpServers,
+      mcpProviders: new Map(),
+      loadouts: new Map(),
       sourcePath: "",
     },
     resolvedRoles: manifest._resolvedRoles,