macro-agent 0.1.12 → 0.2.0

package/src/map/lifecycle-bridge.ts

@@ -37,7 +37,28 @@ export function createLifecycleBridge(
   scope: string,
   taskBridge?: TaskBridge,
   getLocalMapId?: (localAgentId: string) => string | undefined,
-): { callback: AgentLifecycleCallback; cleanup: () => Promise<void> } {
+): {
+  callback: AgentLifecycleCallback;
+  cleanup: () => Promise<void>;
+  /**
+   * Resolve true once the named agent has completed `map/agents/register`
+   * with the hub (its entry.mapId is populated). Used by the dispatch
+   * spawn-agent handler to barrier-wait for hub-side registration before
+   * returning, so the orchestrator's subsequent `findAcpAgentInfo` lookup
+   * doesn't race the registration.
+   *
+   * Returns false if the timeout elapses before registration completes.
+   */
+  awaitRegistration: (agentId: string, timeoutMs?: number) => Promise<boolean>;
+  /**
+   * Reverse-lookup: hub-assigned MAP ULID → local agent id. Used by the
+   * `map/dispatch/message` handler in the sidecar to translate envelope
+   * recipients (which the hub addresses by MAP ULID) into local agent ids
+   * (which the inbox addresses messages by). Returns undefined when no
+   * registered agent matches.
+   */
+  findLocalAgentByMapId: (mapId: string) => string | undefined;
+} {
   const registered = new Map<string, RegisteredAgent>();
 
   /**
@@ -186,5 +207,30 @@ export function createLifecycleBridge(
     registered.clear();
   };
 
-  return { callback, cleanup };
+  /**
+   * Block until the named agent's hub-side registration completes (entry
+   * has been assigned a mapId by the `map/agents/register` response) or
+   * the timeout elapses. Polls the local `registered` map.
+   */
+  const awaitRegistration = async (
+    agentId: string,
+    timeoutMs = 5000,
+  ): Promise<boolean> => {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const entry = registered.get(agentId);
+      if (entry?.mapId) return true;
+      await new Promise((r) => setTimeout(r, 50));
+    }
+    return Boolean(registered.get(agentId)?.mapId);
+  };
+
+  const findLocalAgentByMapId = (mapId: string): string | undefined => {
+    for (const [localId, entry] of registered) {
+      if (entry.mapId === mapId) return localId;
+    }
+    return undefined;
+  };
+
+  return { callback, cleanup, awaitRegistration, findLocalAgentByMapId };
 }

package/src/map/mail-bridge.ts

@@ -0,0 +1,203 @@
+/**
+ * Mail Bridge — connects OpenHive's hub-side mail to macro-agent's local inbox.
+ *
+ * OpenHive's mail module (src/mail/index.ts) calls forwardTurnToSwarms() when
+ * a new mail turn lands in a conversation a swarm participates in. The hub
+ * sends a `mail/turn.received` JSON-RPC notification to the connected swarm
+ * sidecar via MAP. macro-agent's sidecar (this module) receives the
+ * notification, parses the turn content, and forwards it into the local
+ * agent-inbox so:
+ *
+ *   1. swarm-dispatch's MessagePort (boot-v2 wires `createAgentInboxPort`)
+ *      sees the inbox delivery event and runs its classifier on the message.
+ *   2. The classifier recognizes `x-dispatch/work` schema and routes the
+ *      prompt to a worker agent (existing or freshly spawned).
+ *
+ * Without this bridge, hub-side mail turns never reach macro-agent's
+ * dispatcher. The MessagePort is wired to local inbox events only.
+ */
+import type { InboxAdapter } from "../adapters/types.js";
+
+/**
+ * Subset of MAPClient surface this module needs. Mirrors the shape used by
+ * trajectory-reporter / coordination-handler — keeps the bridge testable
+ * without dragging in the full SDK type.
+ */
+export interface MailBridgeConnection {
+  onNotification(
+    method: string,
+    handler: (params: unknown) => void | Promise<void>,
+  ): void;
+  offNotification(
+    method: string,
+    handler: (params: unknown) => void | Promise<void>,
+  ): void;
+}
+
+/**
+ * Synthetic recipient registered on the local inbox to receive bridged
+ * turns. Choosing a stable name lets the macro-agent dispatcher (or any
+ * other inbox observer) filter on `to: BRIDGE_RECIPIENT_ID` if it cares
+ * about the source — but normally it doesn't, since the dispatcher's
+ * MessagePort matches on the `x-dispatch/work` schema in the payload, not
+ * on the recipient id.
+ */
+const BRIDGE_RECIPIENT_ID = "openhive-mail-bridge";
+
+interface MailTurnReceivedParams {
+  conversation_id?: string;
+  turn_id?: string;
+  participant_id?: string;
+  content_type?: string;
+  content?: unknown;
+  thread_id?: string;
+  created_at?: string;
+}
+
+/**
+ * Parse the turn content into a JS object suitable for inbox routing.
+ * Returns null when the content is not parseable as JSON or doesn't look
+ * like an object payload (e.g., plain text mail turns).
+ */
+function parseTurnContent(
+  content: unknown,
+  contentType: string | undefined,
+): Record<string, unknown> | null {
+  if (typeof content === "object" && content !== null) {
+    return content as Record<string, unknown>;
+  }
+  if (typeof content !== "string") return null;
+  // The hub serializes envelope objects via JSON.stringify and tags them
+  // application/json. We accept either explicit content type or a leading
+  // `{` to handle clients that omit the header.
+  if (
+    contentType === "application/json" ||
+    content.startsWith("{") ||
+    content.startsWith("[")
+  ) {
+    try {
+      const parsed = JSON.parse(content);
+      return typeof parsed === "object" && parsed !== null
+        ? (parsed as Record<string, unknown>)
+        : null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+export interface MailBridgeOptions {
+  connection: MailBridgeConnection;
+  inboxAdapter: InboxAdapter;
+  /**
+   * The dispatcher agent ID used by swarm-dispatch's createAgentInboxPort.
+   * Messages must be delivered TO this ID so the MessagePort's onIncoming
+   * filter (event.agentId === dispatcherAgentId) fires correctly.
+   * When omitted the bridge falls back to BRIDGE_RECIPIENT_ID (inert —
+   * the MessagePort will never see the message).
+   */
+  dispatcherAgentId?: string;
+  /**
+   * Optional logger for diagnostic output. The sidecar currently logs via
+   * console; swap if you want structured output.
+   */
+  log?: (msg: string) => void;
+}
+
+/**
+ * Wire the mail bridge. Returns a cleanup function that detaches the
+ * notification handler.
+ *
+ * Idempotent registration: register is called exactly once; the handler
+ * itself is best-effort (errors are caught and logged so a malformed turn
+ * doesn't break subsequent ones).
+ */
+export async function setupMailBridge(
+  opts: MailBridgeOptions,
+): Promise<() => void> {
+  const { connection, inboxAdapter, dispatcherAgentId, log = () => {} } = opts;
+
+  // Determine the inbox recipient. When a dispatcherAgentId is provided we
+  // deliver directly to the dispatcher so createAgentInboxPort.onIncoming
+  // (which filters event.agentId === dispatcherAgentId) picks it up.
+  const recipientId = dispatcherAgentId ?? BRIDGE_RECIPIENT_ID;
+
+  // Register the recipient on the local inbox so routeMessage accepts the
+  // forwarded turn. Idempotent — registerAgent putAgent is an upsert.
+  await inboxAdapter.registerAgent(recipientId, {
+    name: dispatcherAgentId ? "OpenHive Dispatcher (bridged)" : "OpenHive Mail Bridge",
+    role: dispatcherAgentId ? "dispatcher" : "mail-bridge",
+    scope: "default",
+    metadata: { source: "openhive-mail-forward" },
+  });
+
+  const handler = async (params: unknown): Promise<void> => {
+    const turn = (params ?? {}) as MailTurnReceivedParams;
+    const raw = parseTurnContent(turn.content, turn.content_type);
+    if (!raw) {
+      log(
+        `[mail-bridge] Dropping non-JSON turn (conv=${turn.conversation_id ?? "?"} ` +
+          `participant=${turn.participant_id ?? "?"})`,
+      );
+      return;
+    }
+
+    // Translate hub envelope shape { type, body } → canonical inbox shape
+    // { schema, data } that classifyMessage in boot-v2 expects.
+    // Hub sends: { type: "x-dispatch/work", body: { prompt, taskId, role } }
+    // Classifier expects: { schema: "x-dispatch/work", data: { prompt, taskId, role } }
+    const hubType = (raw as { type?: string }).type;
+    const hubBody = (raw as { body?: Record<string, unknown> }).body;
+    const content: Record<string, unknown> =
+      hubType && hubBody
+        ? { schema: hubType, data: hubBody }
+        : raw;
+
+    // Attach conversation_id as a top-level field in the payload so
+    // the mail-inbound consumer can thread it into the worker spawn.
+    // This lets the reply bridge look up which hub conversation to post
+    // the worker's output back to.
+    //
+    // IMPORTANT: include `type: "data"` so agent-inbox's normalizeContent()
+    // passes the object through unchanged. Without it, an object lacking
+    // a `type` string is re-wrapped as `{ type:"data", data: original }`,
+    // burying `schema` one level deeper and breaking the consumer's filter.
+    const contentWithConvId: Record<string, unknown> = {
+      type: "data",
+      ...content,
+      ...(turn.conversation_id ? { _conversationId: turn.conversation_id } : {}),
+    };
+
+    try {
+      await inboxAdapter.send(
+        turn.participant_id ?? "openhive-hub",
+        recipientId,
+        contentWithConvId as never,
+        {
+          threadTag: turn.thread_id,
+          importance: "normal",
+        },
+      );
+      log(
+        `[mail-bridge] Forwarded turn ${turn.turn_id ?? "?"} into local inbox ` +
+          `(schema=${(content as { schema?: string }).schema ?? "n/a"})`,
+      );
+    } catch (err) {
+      log(
+        `[mail-bridge] Forward failed for turn ${turn.turn_id ?? "?"}: ` +
+          `${(err as Error).message}`,
+      );
+    }
+  };
+
+  connection.onNotification("mail/turn.received", handler);
+
+  return () => {
+    try {
+      connection.offNotification("mail/turn.received", handler);
+    } catch {
+      // best effort
+    }
+  };
+}

package/src/map/sidecar.ts

@@ -35,7 +35,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,6 +51,10 @@ 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 reconnectTimer: ReturnType<typeof setTimeout> | null = null;
 
   /**
@@ -83,10 +87,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;
@@ -278,6 +298,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 +316,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");
@@ -363,5 +679,34 @@ 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)}`,
+        );
+      }
+    },
   };
 }

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,18 @@ 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>;
 }
 
 // =============================================================================

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

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