macro-agent 0.1.8 → 0.1.11

package/src/map/cascade-action-handler.ts

@@ -0,0 +1,205 @@
+/**
+ * Cascade Action Handler — receives hub→runtime commands.
+ *
+ * Listens for `x-cascade/request.*` notifications from the OpenHive hub
+ * and dispatches to the GitCascadeAdapter. This is the inbound counterpart
+ * to the CascadeBridge (which handles outbound events).
+ *
+ * Actions are fire-and-forget from the hub's perspective: the hub sends
+ * the notification and the UI updates reactively when the resulting
+ * `x-cascade/stream.*` event flows back through the bridge.
+ *
+ * @module map/cascade-action-handler
+ */
+
+import type { GitCascadeAdapter } from '../workspace/git-cascade-adapter.js';
+
+export interface CascadeActionConnection {
+  onNotification(
+    method: string,
+    handler: (params: unknown) => void | Promise<void>,
+  ): void;
+  offNotification(
+    method: string,
+    handler: (params: unknown) => void | Promise<void>,
+  ): void;
+}
+
+const REQUEST_METHODS = {
+  MERGE: 'x-cascade/request.merge',
+  ABANDON: 'x-cascade/request.abandon',
+  PAUSE: 'x-cascade/request.pause',
+  RESUME: 'x-cascade/request.resume',
+  RESOLVE: 'x-cascade/request.resolve',
+  PUSH: 'x-cascade/request.push',
+  COMMIT: 'x-cascade/request.commit',
+} as const;
+
+/**
+ * Register cascade action handlers on the MAP connection.
+ * Returns a cleanup function that removes all handlers.
+ */
+export function setupCascadeActionHandlers(
+  connection: CascadeActionConnection,
+  adapter: GitCascadeAdapter,
+): () => void {
+  const handlers: Array<{
+    method: string;
+    handler: (params: unknown) => void | Promise<void>;
+  }> = [];
+
+  const register = (
+    method: string,
+    handler: (params: unknown) => void | Promise<void>,
+  ): void => {
+    connection.onNotification(method, handler);
+    handlers.push({ method, handler });
+  };
+
+  /** Find the first worktree checked out on a given stream. */
+  function findWorktreeForStream(streamId: string): string | null {
+    const wts = adapter.listWorktrees();
+    const match = wts.find((wt) => wt.currentStream === streamId);
+    return match?.path ?? null;
+  }
+
+  // ── Merge ─────────────────────────────────────────────────────────
+  register(REQUEST_METHODS.MERGE, (params: unknown) => {
+    const p = params as { stream_id?: string; target_stream_id?: string };
+    if (!p?.stream_id) return;
+
+    const stream = adapter.getStream(p.stream_id);
+    const targetStreamId = p.target_stream_id ?? stream?.parentStream;
+    if (!targetStreamId) return;
+
+    const worktreePath = findWorktreeForStream(p.stream_id);
+    if (!worktreePath) return;
+
+    try {
+      adapter.mergeStream({
+        sourceStream: p.stream_id,
+        targetStream: targetStreamId,
+        agentId: 'hub-request',
+        worktree: worktreePath,
+      });
+    } catch {
+      // Non-fatal — the resulting event (or conflict) will surface via the bridge
+    }
+  });
+
+  // ── Abandon ───────────────────────────────────────────────────────
+  register(REQUEST_METHODS.ABANDON, (params: unknown) => {
+    const p = params as { stream_id?: string; reason?: string };
+    if (!p?.stream_id) return;
+    try {
+      adapter.abandonStream(p.stream_id, { reason: p.reason ?? 'hub-request' });
+    } catch { /* non-fatal */ }
+  });
+
+  // ── Pause ─────────────────────────────────────────────────────────
+  register(REQUEST_METHODS.PAUSE, (params: unknown) => {
+    const p = params as { stream_id?: string; reason?: string };
+    if (!p?.stream_id) return;
+    try {
+      adapter.pauseStream(p.stream_id, p.reason);
+    } catch { /* non-fatal */ }
+  });
+
+  // ── Resume ────────────────────────────────────────────────────────
+  register(REQUEST_METHODS.RESUME, (params: unknown) => {
+    const p = params as { stream_id?: string };
+    if (!p?.stream_id) return;
+    try {
+      adapter.resumeStream(p.stream_id);
+    } catch { /* non-fatal */ }
+  });
+
+  // ── Resolve conflict ──────────────────────────────────────────────
+  register(REQUEST_METHODS.RESOLVE, (params: unknown) => {
+    const p = params as {
+      stream_id?: string;
+      conflict_id?: string;
+      strategy?: string;
+    };
+    if (!p?.stream_id || !p?.conflict_id) return;
+    try {
+      adapter.resolveConflict({
+        conflictId: p.conflict_id,
+        resolution: {
+          method: (p.strategy as 'ours' | 'theirs') ?? 'ours',
+          resolvedBy: 'hub-request',
+        },
+      });
+    } catch { /* non-fatal */ }
+  });
+
+  // ── Push ───────────────────────────────────────────────────────────
+  register(REQUEST_METHODS.PUSH, (params: unknown) => {
+    const p = params as {
+      stream_id?: string;
+      remote?: string;
+      target_ref?: string;
+    };
+    if (!p?.stream_id) return;
+
+    const worktreePath = findWorktreeForStream(p.stream_id);
+    if (!worktreePath) return;
+
+    const remote = p.remote ?? 'origin';
+    const streamBranch = `stream/${p.stream_id}`;
+    const targetRef = p.target_ref ?? streamBranch;
+
+    try {
+      const { execSync } = require('child_process');
+      execSync(`git push ${remote} ${streamBranch}:refs/heads/${targetRef}`, {
+        cwd: worktreePath,
+        stdio: 'pipe',
+        encoding: 'utf-8',
+      });
+      // Emit pushed event so the hub records it
+      adapter.notifyStreamPushed?.({
+        streamId: p.stream_id,
+        agentId: 'hub-request',
+        pushedCommit: execSync('git rev-parse HEAD', {
+          cwd: worktreePath,
+          encoding: 'utf-8',
+        }).trim(),
+        remote,
+        remoteRef: targetRef,
+        strategy: 'hub-push',
+      });
+    } catch { /* non-fatal — push failure is reported via absence of pushed event */ }
+  });
+
+  // ── Commit ────────────────────────────────────────────────────────
+  register(REQUEST_METHODS.COMMIT, (params: unknown) => {
+    const p = params as {
+      stream_id?: string;
+      message?: string;
+      metadata?: Record<string, unknown>;
+    };
+    if (!p?.stream_id) return;
+
+    const worktreePath = findWorktreeForStream(p.stream_id);
+    if (!worktreePath) return;
+
+    const message = p.message ?? 'checkpoint (hub-requested)';
+    try {
+      adapter.commitChanges({
+        streamId: p.stream_id,
+        agentId: 'hub-request',
+        worktree: worktreePath,
+        message,
+        metadata: p.metadata,
+      });
+    } catch { /* non-fatal — nothing to commit, or stream conflicted */ }
+  });
+
+  // ── Cleanup ───────────────────────────────────────────────────────
+  return () => {
+    for (const { method, handler } of handlers) {
+      connection.offNotification(method, handler);
+    }
+    handlers.length = 0;
+  };
+}

package/src/map/cascade-bridge.ts

@@ -0,0 +1,339 @@
+/**
+ * Cascade Bridge — forwards GitCascadeAdapter events to the MAP hub as
+ * `x-cascade/*` notifications.
+ *
+ * macro-agent's GitCascadeAdapter maintains a structured `GitCascadeEvent`
+ * stream (translated from git-cascade's native `x-cascade/*` emissions + local
+ * adapter events). This bridge subscribes to that stream and translates
+ * **back** to `x-cascade/*` MAP method calls so the OpenHive hub receives the
+ * canonical event schema.
+ *
+ * The round-trip (git-cascade → adapter translation → bridge re-translation)
+ * is deliberate: it preserves the adapter's internal abstraction (other
+ * macro-agent code consumes `GitCascadeEvent`, not raw MAP params) while
+ * guaranteeing the hub sees the same schema git-cascade defines. The bridge
+ * is the only place that knows about both shapes.
+ *
+ * Standalone-safe: when `connection.isConnected` is false, events are
+ * dropped. macro-agent continues to work without an OpenHive hub.
+ *
+ * @module map/cascade-bridge
+ */
+
+import { CASCADE_METHODS } from 'git-cascade/events';
+
+// Fallback method names for events not yet present in the installed
+// git-cascade version (`STREAM_PAUSED`, `STREAM_RESUMED`,
+// `STREAM_ROLLED_BACK` were added after 0.0.7). When the dep is upgraded,
+// collapse these back into `CASCADE_METHODS.*` for a single source of truth.
+const X_CASCADE_STREAM_PAUSED = 'x-cascade/stream.paused' as const;
+const X_CASCADE_STREAM_RESUMED = 'x-cascade/stream.resumed' as const;
+const X_CASCADE_STREAM_ROLLED_BACK = 'x-cascade/stream.rolled_back' as const;
+import type { LifecycleBridgeConnection } from './lifecycle-bridge.js';
+import type {
+  GitCascadeAdapter,
+  GitCascadeEvent,
+} from '../workspace/git-cascade-adapter.js';
+
+export interface CascadeBridgeDisposable {
+  /** Unsubscribe from the adapter event stream. Safe to call multiple times. */
+  dispose: () => void;
+}
+
+export interface CascadeBridgeOptions {
+  /** Enable debug logging when events fail to forward. Defaults to false. */
+  verbose?: boolean;
+}
+
+/**
+ * Create a cascade bridge.
+ *
+ * Subscribes to `adapter.onEvent()` and forwards a fixed subset of events
+ * (the ones that have a canonical `x-cascade/*` method name) as MAP
+ * notifications via `connection.callExtension()`. Events with no MAP
+ * counterpart (`stream:forked`, `worktree:*`, `task:*`, `mergeQueue:*`, etc.)
+ * are silently ignored.
+ *
+ * @returns A disposable that unsubscribes from the adapter stream.
+ */
+export function createCascadeBridge(
+  connection: LifecycleBridgeConnection,
+  adapter: GitCascadeAdapter,
+  options: CascadeBridgeOptions = {}
+): CascadeBridgeDisposable {
+  const verbose = options.verbose ?? false;
+
+  const unsubscribe = adapter.onEvent((event: GitCascadeEvent) => {
+    if (!connection.isConnected) return;
+
+    const mapped = translate(event);
+    if (!mapped) return;
+
+    // Fire-and-forget: never block the adapter's event loop on a MAP RPC.
+    // Errors are swallowed to preserve standalone-safety; they indicate the
+    // hub is unreachable or the method isn't registered, neither of which
+    // should break local cascade operations.
+    void connection
+      .callExtension(mapped.method, mapped.params)
+      .catch((err) => {
+        if (verbose) {
+          // eslint-disable-next-line no-console
+          console.warn(
+            `[cascade-bridge] failed to forward ${event.type} as ${mapped.method}:`,
+            err instanceof Error ? err.message : err
+          );
+        }
+      });
+  });
+
+  return { dispose: unsubscribe };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// GitCascadeEvent → x-cascade/* translation
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface TranslatedCall {
+  method: string;
+  params: Record<string, unknown>;
+}
+
+/**
+ * Translate a `GitCascadeEvent` into a MAP method call.
+ *
+ * Covers the 7 event types that have canonical MAP method names. Returns
+ * `null` for events that are macro-agent-internal (worktree/task/mergeQueue
+ * lifecycle, local-only forks, etc.).
+ *
+ * Field names flip from camelCase (macro-agent internal) back to snake_case
+ * (MAP wire format). The bridge is intentionally conservative — it only
+ * emits fields present on the event, letting the hub back-fill/ignore as
+ * needed.
+ */
+function translate(event: GitCascadeEvent): TranslatedCall | null {
+  const d = event.data;
+
+  switch (event.type) {
+    case 'stream:created':
+      return {
+        method: CASCADE_METHODS.STREAM_OPENED,
+        params: {
+          stream_id: d.streamId,
+          name: d.name,
+          agent_id: d.agentId,
+          base_commit: d.baseCommit,
+          parent_stream: d.parentStream,
+          branch_name: d.branchName,
+          metadata: d.metadata,
+        },
+      };
+
+    case 'stream:committed':
+      return {
+        method: CASCADE_METHODS.STREAM_COMMITTED,
+        params: {
+          stream_id: d.streamId,
+          commit_hash: d.commit,
+          change_id: d.changeId,
+          agent_id: d.agentId,
+          message_summary: d.messageSummary,
+          files_touched: d.filesTouched,
+          parent_commit: d.parentCommit,
+          metadata: d.metadata,
+        },
+      };
+
+    case 'stream:merged':
+      return {
+        method: CASCADE_METHODS.STREAM_MERGED,
+        params: {
+          source_stream_id: d.sourceStreamId,
+          target_stream_id: d.targetStreamId,
+          merge_commit: d.mergeCommit,
+          agent_id: d.agentId,
+          strategy: d.strategy,
+          source_commit: d.sourceCommit,
+          metadata: d.metadata,
+        },
+      };
+
+    case 'stream:conflicted':
+      return {
+        method: CASCADE_METHODS.STREAM_CONFLICTED,
+        params: {
+          stream_id: d.streamId,
+          conflict_id: d.conflictId,
+          conflicted_files: d.conflictedFiles,
+          agent_id: d.agentId,
+          conflicting_commit: d.conflictingCommit,
+          target_commit: d.targetCommit,
+          source: d.source,
+          metadata: d.metadata,
+        },
+      };
+
+    case 'conflict:resolved':
+      // The adapter emits this from two sources: workspace-manager's local
+      // resolveConflict path (carries resolvedBy + resolutionCommit) AND the
+      // forwarded git-cascade stream.conflict_resolved (carries the explicit
+      // resolution_method). Bridge only forwards events with conflict_id +
+      // stream_id present (the cascade-driven shape).
+      if (!d.streamId || !d.conflictId) return null;
+      return {
+        method: CASCADE_METHODS.STREAM_CONFLICT_RESOLVED,
+        params: {
+          stream_id: d.streamId,
+          conflict_id: d.conflictId,
+          resolution_method:
+            (d.resolutionMethod as string | undefined) ??
+            (d.resolvedBy ? 'agent' : 'manual'),
+          resolved_by: d.resolvedBy,
+          resolution_summary: d.resolutionSummary,
+          metadata: d.metadata,
+        },
+      };
+
+    case 'stream:abandoned':
+      return {
+        method: CASCADE_METHODS.STREAM_ABANDONED,
+        params: {
+          stream_id: d.streamId,
+          reason: d.reason,
+          cascade: d.cascade,
+          metadata: d.metadata,
+        },
+      };
+
+    case 'stream:pushed':
+      // Trunk-style push to a remote (direct-push / optimistic-push). Hub
+      // sees this as the "merged" equivalent for non-stream targets.
+      if (!d.streamId || !d.pushedCommit || !d.remoteRef) return null;
+      return {
+        method: CASCADE_METHODS.STREAM_PUSHED,
+        params: {
+          stream_id: d.streamId,
+          agent_id: d.agentId,
+          pushed_commit: d.pushedCommit,
+          remote: d.remote ?? 'origin',
+          remote_ref: d.remoteRef,
+          strategy: d.strategy,
+          metadata: d.metadata,
+        },
+      };
+
+    case 'cascade:rebased':
+      return {
+        method: CASCADE_METHODS.CASCADE_REBASED,
+        params: {
+          stream_id: d.streamId,
+          agent_id: d.agentId,
+          triggered_by_stream_id: d.triggeredByStreamId,
+          triggered_by_agent_id: d.triggeredByAgentId,
+          new_base_commit: d.newBaseCommit,
+          new_head: d.newHead,
+          new_commits: d.newCommits,
+          metadata: d.metadata,
+        },
+      };
+
+    case 'cascade:completed':
+      return {
+        method: CASCADE_METHODS.CASCADE_COMPLETED,
+        params: {
+          root_stream_id: d.rootStreamId,
+          agent_id: d.agentId,
+          strategy: d.strategy,
+          updated_streams: d.updatedStreams,
+          failed_streams: d.failedStreams,
+          skipped_streams: d.skippedStreams,
+          deferred_streams: d.deferredStreams,
+          metadata: d.metadata,
+        },
+      };
+
+    case 'mergeQueue:added':
+      if (!d.entryId || !d.streamId) return null;
+      return {
+        method: CASCADE_METHODS.QUEUE_ADDED,
+        params: {
+          entry_id: d.entryId,
+          stream_id: d.streamId,
+          target_branch: (d.targetBranch as string | undefined) ?? 'main',
+          metadata: d.metadata,
+        },
+      };
+
+    case 'mergeQueue:ready':
+      if (!d.entryId || !d.streamId) return null;
+      return {
+        method: CASCADE_METHODS.QUEUE_READY,
+        params: {
+          entry_id: d.entryId,
+          stream_id: d.streamId,
+          target_branch: (d.targetBranch as string | undefined) ?? 'main',
+        },
+      };
+
+    case 'mergeQueue:cancelled':
+      if (!d.entryId || !d.streamId) return null;
+      return {
+        method: CASCADE_METHODS.QUEUE_CANCELLED,
+        params: {
+          entry_id: d.entryId,
+          stream_id: d.streamId,
+          target_branch: (d.targetBranch as string | undefined) ?? 'main',
+          reason: d.reason,
+        },
+      };
+
+    case 'mergeQueue:removed':
+      if (!d.entryId || !d.streamId) return null;
+      return {
+        method: CASCADE_METHODS.QUEUE_REMOVED,
+        params: {
+          entry_id: d.entryId,
+          stream_id: d.streamId,
+          target_branch: (d.targetBranch as string | undefined) ?? 'main',
+          outcome: d.outcome,
+        },
+      };
+
+    case 'stream:paused':
+      if (!d.streamId) return null;
+      return {
+        method: X_CASCADE_STREAM_PAUSED,
+        params: {
+          stream_id: d.streamId,
+          reason: d.reason,
+        },
+      };
+
+    case 'stream:resumed':
+      if (!d.streamId) return null;
+      return {
+        method: X_CASCADE_STREAM_RESUMED,
+        params: {
+          stream_id: d.streamId,
+        },
+      };
+
+    case 'stream:rolled_back':
+      if (!d.streamId) return null;
+      return {
+        method: X_CASCADE_STREAM_ROLLED_BACK,
+        params: {
+          stream_id: d.streamId,
+          strategy: d.strategy,
+          target: d.target,
+          new_head: d.newHead,
+        },
+      };
+
+    // Local-only events with no MAP counterpart.
+    // 'stream:updated', 'stream:forked', 'worktree:*', 'task:*',
+    // 'change:*', 'conflict:*' (legacy local-only variant — cascade-bridge
+    // handles the cascade-driven 'conflict:resolved' separately above)
+    default:
+      return null;
+  }
+}

package/src/map/coordination-handler.ts

@@ -75,12 +75,24 @@ export function setupCoordinationHandlers(
     if (!p?.title) return;
 
     try {
-      // Create task in opentasks
+      // Extract tags and metadata from OpenHive context
+      const context = p.context ?? {};
+      const tags = Array.isArray(context.tags) ? context.tags as string[] : undefined;
+      const metadata: Record<string, unknown> = {
+        ...context,
+        ...(p.assigned_by ? { assigned_by: p.assigned_by } : {}),
+        ...(p.deadline ? { deadline: p.deadline } : {}),
+      };
+      // Remove tags from metadata (already a top-level field)
+      delete metadata.tags;
+
       const taskId = await tasksAdapter.createTask({
         title: p.title,
         content: p.description,
         assignee: p.assigned_to,
+        tags,
         priority: p.priority === "critical" ? 1 : p.priority === "high" ? 2 : p.priority === "low" ? 4 : 3,
+        metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
       });
 
       // Optionally spawn an agent to work on the task

package/src/map/lifecycle-bridge.ts

@@ -36,9 +36,27 @@ export function createLifecycleBridge(
   agentStore: AgentStore,
   scope: string,
   taskBridge?: TaskBridge,
+  getLocalMapId?: (localAgentId: string) => string | undefined,
 ): { callback: AgentLifecycleCallback; cleanup: () => Promise<void> } {
   const registered = new Map<string, RegisteredAgent>();
 
+  /**
+   * Poll for the local MAP server's assigned ID for an agent.
+   * The local MAP server and the lifecycle bridge both listen to the same
+   * lifecycle callback, so they may fire in any order. Poll briefly to handle
+   * the race.
+   */
+  async function waitForLocalMapId(localAgentId: string, timeoutMs = 500): Promise<string | undefined> {
+    if (!getLocalMapId) return undefined;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const id = getLocalMapId(localAgentId);
+      if (id) return id;
+      await new Promise((r) => setTimeout(r, 20));
+    }
+    return getLocalMapId(localAgentId);
+  }
+
   const callback: AgentLifecycleCallback = (event) => {
     if (!connection.isConnected) return;
 
@@ -61,29 +79,46 @@ export function createLifecycleBridge(
         }
 
         // Register agent with MAP hub (use map/agents/register to preserve
-        // per-agent capabilities; map/agents/spawn drops them)
-        connection
-          .callExtension("map/agents/register", {
-            name,
-            role,
-            capabilities,
-            metadata: {
-              localAgentId: agent.id,
-              parent: (agent as any).parent_id ?? undefined,
-              team: (agent as any).team ?? undefined,
-              cwd: (agent as any).cwd ?? undefined,
-            },
-          })
-          .then((result: any) => {
+        // per-agent capabilities; map/agents/spawn drops them).
+        // Include the local MAP server's ID in metadata so clients can route
+        // ACP messages to the correct agent on the macro-agent's own MAP server.
+        // Also include provider_session_id so OpenHive can find the underlying
+        // Claude Code JSONL transcript on disk for history recovery.
+        const agentMetadata = (agent as any).metadata as Record<string, unknown> | undefined;
+        const providerSessionId =
+          typeof agentMetadata?.provider_session_id === "string"
+            ? agentMetadata.provider_session_id
+            : undefined;
+        (async () => {
+          const peerMapId = await waitForLocalMapId(agent.id);
+          try {
+            const result: any = await connection.callExtension("map/agents/register", {
+              name,
+              role,
+              capabilities,
+              metadata: {
+                // From the hub's perspective these IDs identify this agent on
+                // the macro-agent (peer) side. `peerAgentId` is macro-agent's
+                // internal store id; `peerMapId` is its local MAP server ULID.
+                // Hub callers use these to address the agent in routing
+                // (ACP streams target peerMapId, lifecycle ops use peerAgentId).
+                peerAgentId: agent.id,
+                peerMapId,
+                provider_session_id: providerSessionId,
+                parent: (agent as any).parent_id ?? undefined,
+                team: (agent as any).team ?? undefined,
+                cwd: (agent as any).cwd ?? undefined,
+              },
+            });
             // Track the MAP-assigned agent ID for unregistration
             const mapId = result?.agent?.id ?? result?.id;
             if (mapId) {
               entry.mapId = mapId;
             }
-          })
-          .catch(() => {
+          } catch {
             // Silent — MAP hub may be temporarily unavailable
-          });
+          }
+        })();
 
         // Bridge task creation if agent has a task
         if (taskBridge && (agent as any).task_id) {