macro-agent 0.2.4 → 0.2.6

package/src/map/task-bridge.ts

@@ -1,89 +0,0 @@
-/**
- * Task Bridge — emits task lifecycle events to the MAP hub for observability.
- *
- * Bridges internal opentasks state changes to MAP-visible events so that
- * OpenHive's UI can display task progress across swarms.
- *
- * @module map/task-bridge
- */
-
-import type { TaskBridge } from "./types.js";
-
-/** Minimal interface for the MAP connection methods we need */
-export interface TaskBridgeConnection {
-  send(
-    to: { scope: string } | string,
-    payload?: unknown,
-    meta?: Record<string, unknown>,
-  ): Promise<unknown>;
-  get isConnected(): boolean;
-}
-
-/**
- * Create a task bridge that emits task events to the MAP hub.
- * Wire format matches cc-swarm's bridge-task-* commands.
- */
-export function createTaskBridge(
-  connection: TaskBridgeConnection,
-  scope: string,
-): TaskBridge {
-  const send = async (payload: Record<string, unknown>): Promise<void> => {
-    if (!connection.isConnected) return;
-    try {
-      await connection.send({ scope }, payload);
-    } catch {
-      // Silent — MAP hub may be temporarily unavailable
-    }
-  };
-
-  return {
-    async taskCreated(task): Promise<void> {
-      await send({
-        type: "task.created",
-        task: {
-          id: task.id,
-          title: task.title,
-          status: task.status,
-          assignee: task.assignee,
-        },
-        _origin: "macro-agent",
-      });
-    },
-
-    async taskStatusChanged(
-      taskId,
-      previous,
-      current,
-      agentId,
-    ): Promise<void> {
-      await send({
-        type: "task.status",
-        taskId,
-        previous,
-        current,
-        agentId,
-        _origin: "macro-agent",
-      });
-
-      // Also emit task.completed if terminal status
-      if (current === "completed" || current === "closed") {
-        await send({
-          type: "task.completed",
-          taskId,
-          agentId,
-          timestamp: Date.now(),
-          _origin: "macro-agent",
-        });
-      }
-    },
-
-    async taskAssigned(taskId, assignee): Promise<void> {
-      await send({
-        type: "task.assigned",
-        taskId,
-        assignee,
-        _origin: "macro-agent",
-      });
-    },
-  };
-}

package/src/map/trajectory-reporter.ts

@@ -1,124 +0,0 @@
-/**
- * Trajectory Reporter — builds and reports trajectory checkpoints to the MAP hub.
- *
- * Sends checkpoints via the `trajectory/checkpoint` JSON-RPC extension.
- * Also handles inbound `trajectory/content.request` notifications by serving
- * session transcript data.
- *
- * @module map/trajectory-reporter
- */
-
-import type {
-  TrajectoryCheckpointPayload,
-  TrajectoryCheckpointResult,
-  TrajectoryContentRequest,
-  TrajectoryReporter,
-  MAPSidecarConfig,
-} from "./types.js";
-
-/** Minimal interface for the MAP connection methods we need */
-export interface TrajectoryConnection {
-  callExtension<TParams = unknown, TResult = unknown>(
-    method: string,
-    params?: TParams,
-  ): Promise<TResult>;
-  sendNotification(method: string, params: unknown): Promise<void>;
-  onNotification(
-    method: string,
-    handler: (params: unknown) => void | Promise<void>,
-  ): void;
-  offNotification(
-    method: string,
-    handler: (params: unknown) => void | Promise<void>,
-  ): void;
-  get isConnected(): boolean;
-}
-
-/**
- * Create a trajectory reporter that sends checkpoints to the MAP hub
- * and serves content on demand.
- */
-export function createTrajectoryReporter(
-  connection: TrajectoryConnection,
-  config: Pick<MAPSidecarConfig, "trajectorySyncLevel">,
-): TrajectoryReporter {
-  // Cache the resource_id from the first checkpoint response
-  // so subsequent calls reuse it (avoids creating duplicate session resources)
-  let cachedResourceId: string | undefined;
-
-  // Handler for inbound content requests
-  const contentHandler = async (params: unknown): Promise<void> => {
-    const req = params as TrajectoryContentRequest;
-    if (!req?.request_id) return;
-
-    try {
-      // Respond with what we have — macro-agent doesn't store full transcripts
-      // like sessionlog does, so we send a minimal response.
-      // Future: integrate with ACP session history for richer content.
-      await connection.sendNotification("trajectory/content.response", {
-        request_id: req.request_id,
-        transcript: null,
-        metadata: {
-          source: "macro-agent",
-          note: "Full transcript serving not yet implemented",
-        },
-      });
-    } catch {
-      // Best effort
-      try {
-        await connection.sendNotification("trajectory/content.response", {
-          request_id: req.request_id,
-          error: "Content serving failed",
-        });
-      } catch {
-        // Double failure — give up silently
-      }
-    }
-  };
-
-  // Register content request handler
-  connection.onNotification("trajectory/content.request", contentHandler);
-
-  return {
-    async reportCheckpoint(
-      checkpoint: TrajectoryCheckpointPayload,
-    ): Promise<TrajectoryCheckpointResult | null> {
-      if (!connection.isConnected) return null;
-      if (config.trajectorySyncLevel === "off") return null;
-
-      try {
-        const result = await connection.callExtension<
-          { checkpoint: TrajectoryCheckpointPayload; resource_id?: string },
-          TrajectoryCheckpointResult
-        >("trajectory/checkpoint", {
-          checkpoint,
-          resource_id: cachedResourceId,
-        });
-
-        // Cache the resource_id for subsequent calls
-        if (result?.resource_id) {
-          cachedResourceId = result.resource_id;
-        }
-
-        return result;
-      } catch (err) {
-        // Fallback: try broadcasting as a message instead
-        try {
-          await connection.sendNotification("trajectory.checkpoint", {
-            checkpoint,
-          });
-        } catch {
-          // Silent — hub may not support either method
-        }
-        return null;
-      }
-    },
-
-    stop(): void {
-      connection.offNotification(
-        "trajectory/content.request",
-        contentHandler,
-      );
-    },
-  };
-}

package/src/map/types.ts

@@ -1,304 +0,0 @@
-/**
- * MAP Sidecar Types
- *
- * Configuration, interfaces, and wire format types for the MAP hub sidecar.
- * The sidecar connects macro-agent to an OpenHive MAP hub for agent observability,
- * trajectory reporting, task bridging, and cross-swarm coordination.
- *
- * @module map/types
- */
-
-import type { AgentManager } from "../agent/agent-manager.js";
-import type { AgentStore } from "../agent/agent-store.js";
-import type { InboxAdapter, TasksAdapter } from "../adapters/types.js";
-
-// =============================================================================
-// Configuration
-// =============================================================================
-
-export interface MAPSidecarConfig {
-  /** MAP hub WebSocket URL (e.g., "ws://localhost:8080" or "wss://hub.openhive.dev") */
-  server: string;
-
-  /** Authentication token (appended as ?token= query param) */
-  token?: string;
-
-  /** MAP scope for broadcasting events (default: "swarm:macro-agent") */
-  scope?: string;
-
-  /** System ID for federation (default: "macro-agent") */
-  systemId?: string;
-
-  /** Opaque credential for server-driven auth (verified mode) */
-  credential?: string;
-
-  /** Agent name for MAP registration (default: "macro-agent-sidecar") */
-  agentName?: string;
-
-  /** Swarm ID for stable identity across reconnections */
-  swarmId?: string;
-
-  /** Trajectory sync level */
-  trajectorySyncLevel?: "off" | "lifecycle" | "metrics" | "full";
-
-  /** Mesh transport (agentic-mesh P2P) */
-  mesh?: {
-    enabled?: boolean;
-    peerId?: string;
-  };
-
-  /** Reconnection settings (SDK-level) */
-  reconnection?: {
-    enabled?: boolean;
-    maxRetries?: number;
-    baseDelayMs?: number;
-    maxDelayMs?: number;
-  };
-
-  /** Slow reconnect interval after SDK retries exhausted (ms, default: 60000) */
-  reconnectIntervalMs?: number;
-}
-
-// =============================================================================
-// Dependencies
-// =============================================================================
-
-export interface MAPSidecarDeps {
-  agentManager: AgentManager;
-  agentStore: AgentStore;
-  inboxAdapter: InboxAdapter;
-  tasksAdapter: TasksAdapter;
-  /**
-   * Optional lookup for the local MAP server's ULID for a given local agent ID.
-   * When provided, the lifecycle bridge includes this ID in hub registration
-   * metadata so clients (e.g., SwarmCraft) can target the agent correctly on
-   * the macro-agent's own MAP server.
-   */
-  getLocalMapId?: (localAgentId: string) => string | undefined;
-  /**
-   * Optional GitCascadeAdapter. When provided, the sidecar wires a cascade
-   * bridge that forwards the adapter's event stream to the hub as
-   * `x-cascade/*` MAP notifications. Leave undefined to disable cascade
-   * event forwarding (macro-agent will still use cascade internally, just
-   * 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;
-}
-
-// =============================================================================
-// Sidecar Interface
-// =============================================================================
-
-export interface MAPSidecar {
-  /** Start the sidecar (connect to hub, subscribe to events) */
-  start(): Promise<void>;
-
-  /** Stop the sidecar (disconnect, unsubscribe) */
-  stop(): Promise<void>;
-
-  /** Whether the sidecar is connected to the hub */
-  readonly connected: boolean;
-
-  /** Report a trajectory checkpoint manually */
-  reportCheckpoint(
-    checkpoint: TrajectoryCheckpointPayload,
-  ): Promise<TrajectoryCheckpointResult | null>;
-
-  /** 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;
-}
-
-// =============================================================================
-// Trajectory Wire Format
-// =============================================================================
-
-/**
- * Trajectory checkpoint payload — matches cc-swarm wire format.
- * Top-level fields are snake_case per the OpenHive trajectory protocol.
- */
-export interface TrajectoryCheckpointPayload {
-  /** Checkpoint ID (e.g., "<sessionId>-step<N>") */
-  id: string;
-  /** Session identifier */
-  session_id: string;
-  /** Agent name (e.g., "macro-agent-sidecar") */
-  agent: string;
-  /** Git branch (nullable) */
-  branch: string | null;
-  /** Files touched in this checkpoint period */
-  files_touched: string[];
-  /** Total checkpoint count in session */
-  checkpoints_count: number;
-  /** Token usage metrics (when sync level >= "metrics") */
-  token_usage?: {
-    input_tokens?: number;
-    output_tokens?: number;
-    cache_creation_tokens?: number;
-    cache_read_tokens?: number;
-    api_call_count?: number;
-  };
-  /** Additional metadata */
-  metadata?: {
-    project?: string;
-    projectPath?: string;
-    template?: string;
-    firstPrompt?: string;
-    phase?: string;
-    [key: string]: unknown;
-  };
-}
-
-/** Response from trajectory/checkpoint extension call */
-export interface TrajectoryCheckpointResult {
-  ok: boolean;
-  resource_id?: string;
-  created?: boolean;
-  checkpoint_id?: string;
-}
-
-/** Inbound content request from the hub */
-export interface TrajectoryContentRequest {
-  request_id: string;
-  checkpoint_id: string;
-}
-
-// =============================================================================
-// Coordination Wire Format
-// =============================================================================
-
-/** Inbound task assignment from hub */
-export interface CoordinationTaskAssign {
-  title: string;
-  description?: string;
-  assigned_to?: string;
-  assigned_by: string;
-  priority?: string;
-  context?: Record<string, unknown>;
-  deadline?: string;
-}
-
-/** Inbound task status update from hub */
-export interface CoordinationTaskStatus {
-  task_id: string;
-  status: string;
-  progress?: number;
-  result?: unknown;
-  error?: string;
-}
-
-/** Inbound context share from hub */
-export interface CoordinationContextShare {
-  hive_id?: string;
-  source_swarm_id: string;
-  context_type: string;
-  data: unknown;
-  target_swarm_ids?: string[];
-  ttl_seconds?: number;
-}
-
-/** Inbound message from hub */
-export interface CoordinationMessage {
-  hive_id?: string;
-  from_swarm_id: string;
-  to_swarm_id: string;
-  content_type: string;
-  content: unknown;
-  reply_to?: string;
-  metadata?: Record<string, unknown>;
-}
-
-// =============================================================================
-// Internal Bridge Types
-// =============================================================================
-
-/** Task bridge interface for emitting task events to MAP */
-export interface TaskBridge {
-  taskCreated(task: {
-    id: string;
-    title: string;
-    status: string;
-    assignee?: string;
-  }): Promise<void>;
-  taskStatusChanged(
-    taskId: string,
-    previous: string,
-    current: string,
-    agentId?: string,
-  ): Promise<void>;
-  taskAssigned(taskId: string, assignee: string): Promise<void>;
-}
-
-/** Trajectory reporter interface */
-export interface TrajectoryReporter {
-  reportCheckpoint(
-    checkpoint: TrajectoryCheckpointPayload,
-  ): Promise<TrajectoryCheckpointResult | null>;
-  stop(): void;
-}
-
-// =============================================================================
-// MAP Server Types (inbound connections)
-// =============================================================================
-
-/** Configuration for the MAP server that accepts inbound connections */
-export interface MapServerConfig {
-  /** Port for MAP WebSocket server (default: 3002) */
-  port?: number;
-  /** Host to bind (default: "127.0.0.1") */
-  host?: string;
-  /** WebSocket path (default: "/map") */
-  path?: string;
-  /** Server name for MAP protocol (default: "macro-agent") */
-  name?: string;
-}
-
-/** MAP server instance for accepting inbound MAP connections */
-export interface MAPServerInstance {
-  /** Start the server */
-  start(): Promise<void>;
-  /** Stop the server */
-  stop(): Promise<void>;
-  /** Get the WebSocket URL */
-  getUrl(): string;
-  /** Get number of active connections */
-  getConnectionCount(): number;
-  /**
-   * Resolve a local agent ID (macro-agent internal) to its MAP server-assigned ULID.
-   * Returns undefined if the agent is not registered on the MAP server yet.
-   */
-  getLocalMapId(localAgentId: string): string | undefined;
-}