macro-agent 0.2.0 → 0.2.2

package/src/dispatch/mail-inbound-consumer.ts

@@ -61,6 +61,38 @@ export interface MailInboundSidecar {
   ): Promise<void>;
 }
 
+/** Repo metadata surfaced by the hub's enrichWithRepo → mail port injection. */
+export interface DispatchRepoMetadata {
+  repo_id?: string;
+  canonical_url?: string;
+  branch?: string;
+  commit_sha?: string;
+  clone_policy?: string;
+  clone_path?: string;
+}
+
+/**
+ * Narrow interface for the sidecar's RepoManager — keeps the consumer
+ * testable without importing the full agent-workspace concrete type.
+ */
+export interface RepoManagerLike {
+  list(): Array<{ identity: { canonicalUrl: string }; localPath: string }>;
+  attach(config: {
+    remoteUrl: string;
+    localPath: string;
+    currentBranch?: string;
+  }): Promise<{ localPath: string }>;
+}
+
+/**
+ * Narrow interface for the sidecar's RepoClient transport — used to
+ * declare newly-attached repos to the hub after clone.
+ */
+export interface RepoClientTransportLike {
+  notify(method: string, params: unknown): Promise<void>;
+  request(method: string, params: unknown): Promise<unknown>;
+}
+
 export interface MailInboundConsumerOptions {
   /**
    * The inbox agent ID that mail-bridge delivers envelopes to.
@@ -85,6 +117,19 @@ export interface MailInboundConsumerOptions {
    */
   getSidecar: () => MailInboundSidecar | null | undefined;
 
+  /**
+   * Optional repo manager for pre-spawn mount. When provided, the consumer
+   * can clone/attach repos before spawning workers and set the worker's cwd
+   * to the repo path. Populated lazily from the sidecar's workspace manager.
+   */
+  getRepoManager?: () => RepoManagerLike | null | undefined;
+
+  /**
+   * Optional repo client transport for declaring newly-cloned repos to the
+   * hub after a pre-spawn clone. Uses the sidecar's MAP connection transport.
+   */
+  getRepoTransport?: () => RepoClientTransportLike | null | undefined;
+
   /** Optional logger (default: console.log). */
   log?: (msg: string) => void;
 }
@@ -121,6 +166,8 @@ export function createMailInboundConsumer(
     agentManager,
     agentStore,
     getSidecar,
+    getRepoManager,
+    getRepoTransport,
     log = (msg: string) => console.log(msg),
   } = opts;
 
@@ -158,6 +205,102 @@ export function createMailInboundConsumer(
       `(recipient=${dispatcherAgentId})`,
   );
 
+  // ── Pre-spawn repo mount ─────────────────────────────────────
+  // Resolves the worker's cwd from the dispatch envelope's repo metadata.
+  // When clone_policy is 'allowed' and the repo isn't already attached,
+  // clones to clone_path (or a default under cwd) then attaches+declares.
+  // Best-effort: failures log a warning and return undefined (worker
+  // spawns without a repo-specific cwd).
+  async function resolveRepoCwd(
+    repoMeta: DispatchRepoMetadata,
+    taskId: string,
+  ): Promise<string | undefined> {
+    const manager = getRepoManager?.();
+    if (!manager) return undefined;
+
+    const canonicalUrl = repoMeta.canonical_url;
+    if (!canonicalUrl) return undefined;
+
+    // Check if the repo is already attached (by canonical URL match).
+    const existing = manager.list().find(
+      (h) => h.identity.canonicalUrl === canonicalUrl,
+    );
+    if (existing) {
+      log(`[mail-inbound] Repo already attached at ${existing.localPath} for taskId=${taskId}`);
+      return existing.localPath;
+    }
+
+    // Not attached — clone only if explicitly allowed.
+    if (repoMeta.clone_policy !== 'allowed') {
+      log(
+        `[mail-inbound] Repo ${canonicalUrl} not attached and clone_policy=${repoMeta.clone_policy ?? 'none'} — ` +
+          `skipping mount for taskId=${taskId}`,
+      );
+      return undefined;
+    }
+
+    const clonePath = repoMeta.clone_path ?? `/tmp/openhive-repos/${repoMeta.repo_id}`;
+    try {
+      const { execSync } = await import("node:child_process");
+
+      // Clone if the directory doesn't exist yet.
+      const fs = await import("node:fs");
+      if (!fs.existsSync(clonePath)) {
+        log(`[mail-inbound] Cloning ${canonicalUrl} → ${clonePath} for taskId=${taskId}`);
+        execSync(`git clone --depth 1 ${canonicalUrl} ${clonePath}`, {
+          stdio: "pipe",
+          timeout: 120_000,
+        });
+      }
+
+      // Checkout target branch if specified.
+      if (repoMeta.branch) {
+        try {
+          execSync(`git -C ${clonePath} fetch origin ${repoMeta.branch} --depth 1`, {
+            stdio: "pipe",
+            timeout: 60_000,
+          });
+          execSync(`git -C ${clonePath} checkout ${repoMeta.branch}`, {
+            stdio: "pipe",
+            timeout: 30_000,
+          });
+        } catch {
+          log(`[mail-inbound] Branch checkout failed for ${repoMeta.branch} — continuing on default branch`);
+        }
+      }
+
+      // Attach to the repo manager so future dispatches find it.
+      const handle = await manager.attach({
+        remoteUrl: canonicalUrl,
+        localPath: clonePath,
+        currentBranch: repoMeta.branch,
+      });
+
+      // Declare the new workspace to the hub (best-effort).
+      const transport = getRepoTransport?.();
+      if (transport) {
+        try {
+          const bindings = manager.list().map((h) => ({
+            canonical_url: h.identity.canonicalUrl,
+            local_path: h.localPath,
+          }));
+          await transport.notify("x-workspace/repo.declare", { bindings });
+        } catch {
+          // Non-fatal — the hub may not support workspace declarations.
+        }
+      }
+
+      log(`[mail-inbound] Mounted repo at ${handle.localPath} for taskId=${taskId}`);
+      return handle.localPath;
+    } catch (err) {
+      log(
+        `[mail-inbound] Pre-spawn repo mount failed for taskId=${taskId}: ` +
+          `${(err as Error).message ?? String(err)}`,
+      );
+      return undefined;
+    }
+  }
+
   // ── Inbox message listener ───────────────────────────────────
   const onMessage = (event: InboxMessageEvent): void => {
     // Only handle messages delivered to our dispatcher recipient.
@@ -258,17 +401,36 @@ export function createMailInboundConsumer(
       fullAutonomous: true,
     });
 
+    // Extract repo metadata from the envelope for pre-spawn mount.
+    const repoMeta: DispatchRepoMetadata = {
+      repo_id: data.metadata?.repo_id as string | undefined,
+      canonical_url: data.metadata?.canonical_url as string | undefined,
+      branch: data.metadata?.branch as string | undefined,
+      commit_sha: data.metadata?.commit_sha as string | undefined,
+      clone_policy: data.metadata?.clone_policy as string | undefined,
+      clone_path: data.metadata?.clone_path as string | undefined,
+    };
+
     log(
       `[mail-inbound] Received x-dispatch/work taskId=${taskId} ` +
         `conv=${conversationId ?? "(none)"} role=${role}` +
+        (repoMeta.repo_id ? ` repo=${repoMeta.repo_id}` : "") +
         (spawnLoadoutOpts.permissions
           ? ` permissions=${JSON.stringify(spawnLoadoutOpts.permissions)}`
           : ""),
     );
 
     // Spawn is async — fire and forget. Errors are logged, not thrown.
-    agentManager
-      .spawn({
+    // Pre-spawn mount resolves the worker's cwd from the repo metadata
+    // before spawning. Best-effort: mount failures proceed without a
+    // repo-specific cwd.
+    (async () => {
+      let repoCwd: string | undefined;
+      if (repoMeta.repo_id) {
+        repoCwd = await resolveRepoCwd(repoMeta, taskId);
+      }
+
+      const spawned = await agentManager.spawn({
         task: prompt,
         task_id: taskId,
         role,
@@ -278,40 +440,41 @@ export function createMailInboundConsumer(
         // (claude-code-swarm, oh-my-claudecode, …) don't auto-load and hang
         // session/new on environments where the host services aren't reachable.
         isolatedSettings: true,
+        ...(repoCwd ? { cwd: repoCwd } : {}),
         ...spawnLoadoutOpts,
-      })
-      .then(async (spawned) => {
-        log(
-          `[mail-inbound] Spawned worker agentId=${spawned.id} for taskId=${taskId}`,
-        );
-        if (conversationId) {
-          agentConversationMap.set(spawned.id, conversationId);
-        }
+      });
 
-        // Spawn only creates an idle ACP session — the task lives in the
-        // system prompt as instructions. To get the model to actually do
-        // the work, send the prompt as a user message via promptUntilDone.
-        // This drives the worker to completion (done() called) so the
-        // lifecycle stopped listener below fires and posts the reply
-        // back to the hub. Fire-and-forget; errors are logged.
-        try {
-          await agentManager.promptUntilDone(spawned.id, prompt, {
-            maxFollowUps: 0,
-          });
-        } catch (err) {
-          log(
-            `[mail-inbound] promptUntilDone failed for agentId=${spawned.id}: ` +
-              `${(err as Error).message ?? String(err)}`,
-          );
-        }
-      })
-      .catch((err: unknown) => {
+      log(
+        `[mail-inbound] Spawned worker agentId=${spawned.id} for taskId=${taskId}` +
+          (repoCwd ? ` cwd=${repoCwd}` : ""),
+      );
+      if (conversationId) {
+        agentConversationMap.set(spawned.id, conversationId);
+      }
+
+      // Spawn only creates an idle ACP session — the task lives in the
+      // system prompt as instructions. To get the model to actually do
+      // the work, send the prompt as a user message via promptUntilDone.
+      // This drives the worker to completion (done() called) so the
+      // lifecycle stopped listener below fires and posts the reply
+      // back to the hub. Fire-and-forget; errors are logged.
+      try {
+        await agentManager.promptUntilDone(spawned.id, prompt, {
+          maxFollowUps: 0,
+        });
+      } catch (err) {
         log(
-          `[mail-inbound] Spawn failed for taskId=${taskId}: ${
-            (err as Error).message ?? String(err)
-          }`,
+          `[mail-inbound] promptUntilDone failed for agentId=${spawned.id}: ` +
+            `${(err as Error).message ?? String(err)}`,
         );
-      });
+      }
+    })().catch((err: unknown) => {
+      log(
+        `[mail-inbound] Spawn failed for taskId=${taskId}: ${
+          (err as Error).message ?? String(err)
+        }`,
+      );
+    });
   };
 
   inboxEvents.on("inbox.message", onMessage);

package/src/map/__tests__/mail-bridge.test.ts

@@ -173,6 +173,94 @@ describe("setupMailBridge", () => {
     });
   });
 
+  describe("importance derivation", () => {
+    const DISPATCHER_ID = "dispatcher:host:1234:abc";
+
+    it("passes through importance from hub notification params", async () => {
+      await setupMailBridge({
+        connection: conn,
+        inboxAdapter: inbox as any,
+        dispatcherAgentId: DISPATCHER_ID,
+      });
+
+      await conn._fire({
+        conversation_id: "conv-imp-1",
+        turn_id: "turn-imp-1",
+        participant_id: "user:admin",
+        content_type: "application/json",
+        content: JSON.stringify({ schema: "x-dispatch/work", data: { taskId: "t-1" } }),
+        importance: "high",
+      });
+
+      expect(inbox.send).toHaveBeenCalledOnce();
+      const [, , , opts] = inbox.send.mock.calls[0];
+      expect(opts?.importance).toBe("high");
+    });
+
+    it("passes through 'urgent' importance for orchestrator recall", async () => {
+      await setupMailBridge({
+        connection: conn,
+        inboxAdapter: inbox as any,
+        dispatcherAgentId: DISPATCHER_ID,
+      });
+
+      await conn._fire({
+        conversation_id: "conv-imp-2",
+        turn_id: "turn-imp-2",
+        participant_id: "system:dispatch-orchestrator",
+        content_type: "application/json",
+        content: JSON.stringify({ schema: "x-dispatch/work", data: { taskId: "t-2" } }),
+        importance: "urgent",
+      });
+
+      expect(inbox.send).toHaveBeenCalledOnce();
+      const [, , , opts] = inbox.send.mock.calls[0];
+      expect(opts?.importance).toBe("urgent");
+    });
+
+    it("defaults to 'normal' when importance is missing", async () => {
+      await setupMailBridge({
+        connection: conn,
+        inboxAdapter: inbox as any,
+        dispatcherAgentId: DISPATCHER_ID,
+      });
+
+      await conn._fire({
+        conversation_id: "conv-imp-3",
+        turn_id: "turn-imp-3",
+        participant_id: "user:admin",
+        content_type: "application/json",
+        content: JSON.stringify({ schema: "x-dispatch/work", data: { taskId: "t-3" } }),
+        // no importance field
+      });
+
+      expect(inbox.send).toHaveBeenCalledOnce();
+      const [, , , opts] = inbox.send.mock.calls[0];
+      expect(opts?.importance).toBe("normal");
+    });
+
+    it("ignores invalid importance values and falls back to 'normal'", async () => {
+      await setupMailBridge({
+        connection: conn,
+        inboxAdapter: inbox as any,
+        dispatcherAgentId: DISPATCHER_ID,
+      });
+
+      await conn._fire({
+        conversation_id: "conv-imp-4",
+        turn_id: "turn-imp-4",
+        participant_id: "user:admin",
+        content_type: "application/json",
+        content: JSON.stringify({ schema: "x-dispatch/work", data: { taskId: "t-4" } }),
+        importance: "critical", // invalid value
+      });
+
+      expect(inbox.send).toHaveBeenCalledOnce();
+      const [, , , opts] = inbox.send.mock.calls[0];
+      expect(opts?.importance).toBe("normal");
+    });
+  });
+
   describe("without dispatcherAgentId (fallback mode)", () => {
     it("delivers to BRIDGE_RECIPIENT_ID", async () => {
       await setupMailBridge({

package/src/map/mail-bridge.ts

@@ -52,6 +52,9 @@ interface MailTurnReceivedParams {
   content?: unknown;
   thread_id?: string;
   created_at?: string;
+  /** Importance hint from the hub. When present, drives wake/interrupt
+   *  decisions via TriggerSystemV2's mapImportanceToWakeAction. */
+  importance?: string;
 }
 
 /**
@@ -169,6 +172,15 @@ export async function setupMailBridge(
       ...(turn.conversation_id ? { _conversationId: turn.conversation_id } : {}),
     };
 
+    // Derive importance from the hub's wire params. Default to "normal"
+    // when the hub doesn't tag the turn (backward compat).
+    const VALID_IMPORTANCE = ["low", "normal", "high", "urgent"];
+    const wireImportance =
+      typeof turn.importance === "string" &&
+      VALID_IMPORTANCE.includes(turn.importance)
+        ? (turn.importance as "low" | "normal" | "high" | "urgent")
+        : "normal";
+
     try {
       await inboxAdapter.send(
         turn.participant_id ?? "openhive-hub",
@@ -176,7 +188,7 @@ export async function setupMailBridge(
         contentWithConvId as never,
         {
           threadTag: turn.thread_id,
-          importance: "normal",
+          importance: wireImportance,
         },
       );
       log(

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,

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.
@@ -55,8 +62,25 @@ export function createMAPSidecar(
   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.
    */
@@ -121,6 +145,8 @@ export function createMAPSidecar(
     }
     lifecycleCallback = null;
     taskBridge = null;
+    workspaceManager = null;
+    workspaceTransport = null;
   }
 
   /**
@@ -147,6 +173,7 @@ export function createMAPSidecar(
             canUpdate: true,
             canList: true,
           },
+          workspace: workspaceCapability,
         },
         metadata: {
           systemId: config.systemId ?? "macro-agent",
@@ -624,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 {
@@ -708,5 +785,13 @@ export function createMAPSidecar(
         );
       }
     },
+
+    getWorkspaceManager() {
+      return workspaceManager;
+    },
+
+    getRepoTransport() {
+      return workspaceTransport;
+    },
   };
 }

package/src/map/types.ts

@@ -127,6 +127,19 @@ export interface MAPSidecar {
     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;
 }
 
 // =============================================================================