macro-agent 0.1.12 → 0.2.1

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/repo-workspace.ts

@@ -0,0 +1,82 @@
+export const REPO_PROTOCOL_VERSION = "0.1.0";
+
+export interface WorkspaceCapability {
+  protocolVersion: string;
+  declare: {
+    enabled: boolean;
+    defaultVisibility: "private" | "hub_local" | "federated";
+  };
+  list: {
+    enabled: boolean;
+  };
+}
+
+export interface RepoClientTransport {
+  notify(method: string, params: unknown): Promise<void>;
+  request(method: string, params: unknown): Promise<unknown>;
+}
+
+export interface RepoAttachConfig {
+  remoteUrl: string;
+  localPath: string;
+  currentBranch?: string;
+}
+
+export interface RepoHandle {
+  identity: {
+    canonicalUrl: string;
+  };
+  localPath: string;
+  currentBranch?: string;
+}
+
+export interface RepoDeclaration {
+  bindings: Array<{
+    canonical_url: string;
+    local_path: string;
+    current_branch?: string;
+  }>;
+}
+
+export class RepoManager {
+  private readonly repos: RepoHandle[] = [];
+
+  async attach(config: RepoAttachConfig): Promise<RepoHandle> {
+    const existing = this.repos.find(
+      (repo) =>
+        repo.identity.canonicalUrl === config.remoteUrl ||
+        repo.localPath === config.localPath,
+    );
+    if (existing) return existing;
+
+    const handle: RepoHandle = {
+      identity: { canonicalUrl: config.remoteUrl },
+      localPath: config.localPath,
+      ...(config.currentBranch ? { currentBranch: config.currentBranch } : {}),
+    };
+    this.repos.push(handle);
+    return handle;
+  }
+
+  list(): RepoHandle[] {
+    return [...this.repos];
+  }
+}
+
+export class RepoClient {
+  constructor(private readonly transport: RepoClientTransport) {}
+
+  static snapshot(manager: RepoManager): RepoDeclaration {
+    return {
+      bindings: manager.list().map((repo) => ({
+        canonical_url: repo.identity.canonicalUrl,
+        local_path: repo.localPath,
+        ...(repo.currentBranch ? { current_branch: repo.currentBranch } : {}),
+      })),
+    };
+  }
+
+  async declare(declaration: RepoDeclaration): Promise<void> {
+    await this.transport.notify("x-workspace/repo.declare", declaration);
+  }
+}

package/src/map/server.ts

@@ -108,6 +108,7 @@ export function createMAPServerInstance(
         cwd: params.cwd,
         role: params.role ?? "worker",
         permissionMode: params.permissionMode,
+        askForAllTools: params.askForAllTools,
         agentType: params.agentType,
         customPrompt: params.customPrompt,
         topics: params.topics,