macro-agent 0.2.4 → 0.2.6

package/dist/map/adapter/subscription-manager.js

@@ -0,0 +1,248 @@
+/**
+ * SubscriptionManager - Manages external client subscriptions
+ *
+ * Tracks subscriptions for external MAP participants, handles filter matching,
+ * and provides event delivery to subscribers.
+ *
+ * Key design decisions:
+ * - Ephemeral subscriptions (no persistence across disconnect)
+ * - Filter matching: eventTypes, agents, scopes, subtree, lineage
+ * - Subscription limits enforced per participant
+ *
+ * @see specs/s-5qir_map_integration_for_macro_agent.md
+ */
+import { ulid } from "ulid";
+import { createSubscriptionId } from "./types.js";
+/**
+ * Error thrown by subscription manager operations.
+ */
+export class SubscriptionError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "SubscriptionError";
+        this.code = code;
+    }
+}
+// =============================================================================
+// Implementation
+// =============================================================================
+/**
+ * SubscriptionManager implementation.
+ */
+export class SubscriptionManagerImpl {
+    subscriptions = new Map();
+    participantSubscriptions = new Map();
+    eventHandlers = new Set();
+    config;
+    constructor(config = {}) {
+        this.config = config;
+    }
+    subscribe(participantId, filter) {
+        // Check subscription limit for this participant
+        const existing = this.participantSubscriptions.get(participantId);
+        const currentCount = existing?.size ?? 0;
+        const maxPerConnection = this.config.limits?.maxSubscriptionsPerConnection;
+        if (maxPerConnection !== undefined && currentCount >= maxPerConnection) {
+            throw new SubscriptionError(`Maximum subscriptions per connection exceeded (limit: ${maxPerConnection})`, "MAX_SUBSCRIPTIONS_EXCEEDED");
+        }
+        // Generate subscription ID
+        const subscriptionId = createSubscriptionId(`sub-${ulid()}`);
+        // Create subscription
+        const subscription = {
+            id: subscriptionId,
+            participantId,
+            filter: filter ?? {},
+            createdAt: Date.now(),
+            paused: false,
+        };
+        // Track subscription
+        this.subscriptions.set(subscriptionId, subscription);
+        // Track per-participant
+        if (!existing) {
+            this.participantSubscriptions.set(participantId, new Set([subscriptionId]));
+        }
+        else {
+            existing.add(subscriptionId);
+        }
+        // Emit event
+        this.emit({ type: "subscription.created", subscription });
+        return subscriptionId;
+    }
+    unsubscribe(subscriptionId) {
+        const subscription = this.subscriptions.get(subscriptionId);
+        if (!subscription) {
+            return; // Already removed or never existed
+        }
+        // Remove from main tracking
+        this.subscriptions.delete(subscriptionId);
+        // Remove from participant tracking
+        const participantSubs = this.participantSubscriptions.get(subscription.participantId);
+        if (participantSubs) {
+            participantSubs.delete(subscriptionId);
+            if (participantSubs.size === 0) {
+                this.participantSubscriptions.delete(subscription.participantId);
+            }
+        }
+        // Emit event
+        this.emit({ type: "subscription.removed", subscriptionId });
+    }
+    getSubscriptions(participantId) {
+        const subscriptionIds = this.participantSubscriptions.get(participantId);
+        if (!subscriptionIds) {
+            return [];
+        }
+        const result = [];
+        for (const id of subscriptionIds) {
+            const sub = this.subscriptions.get(id);
+            if (sub) {
+                result.push(sub);
+            }
+        }
+        return result;
+    }
+    getSubscriptionIds(participantId) {
+        const subscriptionIds = this.participantSubscriptions.get(participantId);
+        return subscriptionIds ? Array.from(subscriptionIds) : [];
+    }
+    getSubscription(subscriptionId) {
+        return this.subscriptions.get(subscriptionId);
+    }
+    pause(subscriptionId) {
+        const subscription = this.subscriptions.get(subscriptionId);
+        if (!subscription) {
+            throw new SubscriptionError(`Subscription not found: ${subscriptionId}`, "SUBSCRIPTION_NOT_FOUND");
+        }
+        if (!subscription.paused) {
+            subscription.paused = true;
+            this.emit({ type: "subscription.paused", subscriptionId });
+        }
+    }
+    resume(subscriptionId) {
+        const subscription = this.subscriptions.get(subscriptionId);
+        if (!subscription) {
+            throw new SubscriptionError(`Subscription not found: ${subscriptionId}`, "SUBSCRIPTION_NOT_FOUND");
+        }
+        if (subscription.paused) {
+            subscription.paused = false;
+            this.emit({ type: "subscription.resumed", subscriptionId });
+        }
+    }
+    isPaused(subscriptionId) {
+        const subscription = this.subscriptions.get(subscriptionId);
+        return subscription?.paused ?? false;
+    }
+    match(event) {
+        const matchingSubscriptions = [];
+        const participantIds = new Set();
+        for (const subscription of this.subscriptions.values()) {
+            // Skip paused subscriptions
+            if (subscription.paused) {
+                continue;
+            }
+            // Check if event matches filter
+            if (this.matchesFilter(event, subscription.filter)) {
+                matchingSubscriptions.push(subscription);
+                participantIds.add(subscription.participantId);
+            }
+        }
+        return {
+            subscriptions: matchingSubscriptions,
+            participantIds: Array.from(participantIds),
+        };
+    }
+    removeAllForParticipant(participantId) {
+        const subscriptionIds = this.participantSubscriptions.get(participantId);
+        if (!subscriptionIds) {
+            return;
+        }
+        // Copy to avoid modification during iteration
+        const idsToRemove = Array.from(subscriptionIds);
+        for (const id of idsToRemove) {
+            this.unsubscribe(id);
+        }
+    }
+    getSubscriptionCount() {
+        return this.subscriptions.size;
+    }
+    onEvent(handler) {
+        this.eventHandlers.add(handler);
+        return () => this.eventHandlers.delete(handler);
+    }
+    // ===========================================================================
+    // Private Methods
+    // ===========================================================================
+    /**
+     * Check if an event matches a subscription filter.
+     * All filters are ANDed together.
+     */
+    matchesFilter(event, filter) {
+        // Empty filter matches everything
+        if (!filter || Object.keys(filter).length === 0) {
+            return true;
+        }
+        // Event type filter (OR within array)
+        // Normalize between underscore format (SDK: "agent_registered") and
+        // dot format (internal: "agent.registered") so subscriptions match
+        // regardless of which convention the client uses.
+        if (filter.eventTypes && filter.eventTypes.length > 0) {
+            const normalizedEventType = event.type.replace(/\./g, "_");
+            if (!filter.eventTypes.some((ft) => ft.replace(/\./g, "_") === normalizedEventType)) {
+                return false;
+            }
+        }
+        // Agent filter (OR within array)
+        if (filter.agents && filter.agents.length > 0) {
+            if (!event.agentId || !filter.agents.includes(event.agentId)) {
+                return false;
+            }
+        }
+        // Scope filter (OR within array)
+        if (filter.scopes && filter.scopes.length > 0) {
+            if (!event.scopeId || !filter.scopes.includes(event.scopeId)) {
+                return false;
+            }
+        }
+        // Subtree filter - event must be from a descendant of the specified agent
+        if (filter.subtree) {
+            if (!event.agentId) {
+                return false;
+            }
+            const descendants = this.config.getDescendants?.(filter.subtree) ?? [];
+            if (!descendants.includes(event.agentId) && event.agentId !== filter.subtree) {
+                return false;
+            }
+        }
+        // Lineage filter - event must be from an ancestor of the specified agent
+        if (filter.lineage) {
+            if (!event.agentId) {
+                return false;
+            }
+            const ancestors = this.config.getAncestors?.(filter.lineage) ?? [];
+            if (!ancestors.includes(event.agentId) && event.agentId !== filter.lineage) {
+                return false;
+            }
+        }
+        return true;
+    }
+    emit(event) {
+        for (const handler of this.eventHandlers) {
+            try {
+                handler(event);
+            }
+            catch (error) {
+                console.error("[SubscriptionManager] Event handler error:", error);
+            }
+        }
+    }
+}
+// =============================================================================
+// Factory
+// =============================================================================
+/**
+ * Create a SubscriptionManager instance.
+ */
+export function createSubscriptionManager(config) {
+    return new SubscriptionManagerImpl(config);
+}
+//# sourceMappingURL=subscription-manager.js.map

package/dist/map/adapter/subscription-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription-manager.js","sourceRoot":"","sources":["../../../src/map/adapter/subscription-manager.ts"],"names":[],"mappings":"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"}

package/dist/map/adapter/types.d.ts

@@ -0,0 +1,194 @@
+/**
+ * MAPAdapter Connection and Participant Types
+ *
+ * This module defines the types for managing external connections,
+ * participants, and subscriptions in the MAP adapter layer.
+ *
+ * @see specs/s-5qir_map_integration_for_macro_agent.md
+ */
+import type { AgentId } from "../../store/types/index.js";
+import type { ScopeId } from "../types.js";
+/**
+ * Unique identifier for a connected participant.
+ * Generated when a participant connects to the MAP adapter.
+ */
+export type ParticipantId = string & {
+    readonly __brand: "ParticipantId";
+};
+/**
+ * Session identifier for connection persistence.
+ * Can be used for reconnection and subscription restoration.
+ */
+export type SessionId = string & {
+    readonly __brand: "SessionId";
+};
+/**
+ * Unique identifier for an active subscription.
+ */
+export type SubscriptionId = string & {
+    readonly __brand: "SubscriptionId";
+};
+/**
+ * Create a ParticipantId from a string.
+ */
+export declare function createParticipantId(id: string): ParticipantId;
+/**
+ * Create a SessionId from a string.
+ */
+export declare function createSessionId(id: string): SessionId;
+/**
+ * Create a SubscriptionId from a string.
+ */
+export declare function createSubscriptionId(id: string): SubscriptionId;
+/**
+ * Types of participants that can connect to the MAP adapter.
+ *
+ * - client: External observer/controller (e.g., CLI, web UI)
+ * - agent: Internal agent participant (for federation scenarios)
+ * - gateway: Federation bridge to another MAP system
+ */
+export type ParticipantType = "client" | "agent" | "gateway";
+/**
+ * Capabilities that can be granted to a participant.
+ * Controls what operations the participant can perform.
+ */
+export interface ParticipantCapabilities {
+    /** Can query agent list and details */
+    canQuery?: boolean;
+    /** Can subscribe to events */
+    canSubscribe?: boolean;
+    /** Can send messages to agents */
+    canMessage?: boolean;
+    /** Can spawn new agents */
+    canSpawn?: boolean;
+    /** Can stop/terminate agents */
+    canStop?: boolean;
+    /** Can create and manage scopes */
+    canManageScopes?: boolean;
+    /** Can update permissions */
+    canUpdatePermissions?: boolean;
+    /** Can create, assign, and complete tasks */
+    canManageTasks?: boolean;
+    /** Can manage federation connections (connect/disconnect peers) */
+    canManageFederation?: boolean;
+    /** Can manage agent lifecycle (resume, spawn, fork, permissions) */
+    canManageLifecycle?: boolean;
+}
+/**
+ * Information about a connected participant.
+ */
+export interface ConnectedParticipant {
+    /** Unique participant identifier */
+    id: ParticipantId;
+    /** Type of participant */
+    type: ParticipantType;
+    /** Human-readable name */
+    name?: string;
+    /** Granted capabilities */
+    capabilities: ParticipantCapabilities;
+    /** Session identifier for reconnection */
+    sessionId: SessionId;
+    /** Connection timestamp (ms since epoch) */
+    connectedAt: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Authentication credentials passed in map/connect request.
+ */
+export interface AuthCredentials {
+    /** Authentication method (e.g., "token", "api-key", "none") */
+    method: string;
+    /** Authentication token/key */
+    token?: string;
+    /** Additional auth parameters */
+    params?: Record<string, unknown>;
+}
+/**
+ * Result of authentication attempt.
+ */
+export interface AuthResult {
+    /** Whether authentication succeeded */
+    allowed: boolean;
+    /** Capabilities granted on success */
+    capabilities?: ParticipantCapabilities;
+    /** Assigned participant ID on success */
+    participantId?: ParticipantId;
+    /** Error message on failure */
+    error?: string;
+}
+/**
+ * Event types that can be subscribed to.
+ */
+export type MAPEventType = "agent.registered" | "agent.unregistered" | "agent.state.changed" | "scope.created" | "scope.deleted" | "scope.member.joined" | "scope.member.left" | "message.sent" | "message.delivered" | "permissions.updated" | "task.created" | "task.assigned" | "task.completed" | "task.failed" | "stream.updated" | "checkpoint.created" | "diffstack.created" | "diffstack.updated" | "merge_request.created" | "merge_request.updated" | "session.complete";
+/**
+ * Filter for event subscriptions.
+ * All filters are ANDed together.
+ */
+export interface SubscriptionFilter {
+    /** Filter by event types (OR within array) */
+    eventTypes?: MAPEventType[];
+    /** Filter by agent IDs (OR within array) */
+    agents?: AgentId[];
+    /** Filter by scope IDs (OR within array) */
+    scopes?: ScopeId[];
+    /** Subscribe to events from agent's descendants */
+    subtree?: AgentId;
+    /** Subscribe to events from agent's ancestors */
+    lineage?: AgentId;
+}
+/**
+ * Active subscription state.
+ */
+export interface Subscription {
+    /** Unique subscription identifier */
+    id: SubscriptionId;
+    /** Owning participant */
+    participantId: ParticipantId;
+    /** Subscription filter */
+    filter: SubscriptionFilter;
+    /** Creation timestamp (ms since epoch) */
+    createdAt: number;
+    /** Whether subscription is paused */
+    paused: boolean;
+    /** Last delivered event ID (for resumption) */
+    lastEventId?: string;
+    /** Last sequence number (for gap detection) */
+    lastSequence?: number;
+}
+/**
+ * Event notification sent to subscribers.
+ */
+export interface EventNotification {
+    /** Unique event identifier (ULID) */
+    eventId: string;
+    /** Event type */
+    type: MAPEventType;
+    /** Event timestamp (ms since epoch) */
+    timestamp: number;
+    /** Event-specific data */
+    data: unknown;
+    /** Parent event IDs for causal ordering */
+    causedBy?: string[];
+    /** Related agent ID (if applicable) */
+    agentId?: AgentId;
+    /** Related scope ID (if applicable) */
+    scopeId?: ScopeId;
+    /** Sequence number for ordering */
+    sequence?: number;
+}
+/**
+ * Events emitted by the connection lifecycle.
+ */
+export type ConnectionEventType = "connected" | "disconnected" | "reconnecting" | "reconnected" | "error";
+/**
+ * Connection event data.
+ */
+export interface ConnectionEvent {
+    type: ConnectionEventType;
+    participantId: ParticipantId;
+    timestamp: number;
+    reason?: string;
+    error?: Error;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/map/adapter/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/map/adapter/types.ts"],"names":[],"mappings":"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"}

package/dist/map/adapter/types.js

@@ -0,0 +1,27 @@
+/**
+ * MAPAdapter Connection and Participant Types
+ *
+ * This module defines the types for managing external connections,
+ * participants, and subscriptions in the MAP adapter layer.
+ *
+ * @see specs/s-5qir_map_integration_for_macro_agent.md
+ */
+/**
+ * Create a ParticipantId from a string.
+ */
+export function createParticipantId(id) {
+    return id;
+}
+/**
+ * Create a SessionId from a string.
+ */
+export function createSessionId(id) {
+    return id;
+}
+/**
+ * Create a SubscriptionId from a string.
+ */
+export function createSubscriptionId(id) {
+    return id;
+}
+//# sourceMappingURL=types.js.map

package/dist/map/adapter/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/map/adapter/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA0BH;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAAU;IAC5C,OAAO,EAAmB,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,EAAU;IACxC,OAAO,EAAe,CAAC;AACzB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,EAAU;IAC7C,OAAO,EAAoB,CAAC;AAC9B,CAAC"}

package/dist/map/adapter/websocket-integration.d.ts

@@ -0,0 +1,113 @@
+/**
+ * MAP WebSocket Integration
+ *
+ * Provides WebSocket integration for the MAP adapter, enabling external clients
+ * to connect via WebSocket and use the MAP protocol.
+ *
+ * Reuses the existing webSocketStream() adapter to keep MAPAdapter transport-agnostic.
+ *
+ * @see specs/s-5qir_map_integration_for_macro_agent.md
+ */
+import type { WebSocket } from "ws";
+import type { MAPAdapter } from "./interface.js";
+import type { ConnectedParticipant } from "./types.js";
+/**
+ * MAP WebSocket handler for managing connections
+ */
+export interface MAPWebSocketHandler {
+    /**
+     * Handle a new WebSocket connection.
+     * Called when a client connects to the /map path.
+     */
+    handleConnection(ws: WebSocket, req: {
+        socket: {
+            remoteAddress?: string;
+        };
+    }): Promise<void>;
+    /**
+     * Get the number of active MAP connections.
+     */
+    getConnectionCount(): number;
+    /**
+     * Close all MAP connections gracefully.
+     */
+    closeAll(): void;
+    /**
+     * Get participant by WebSocket instance.
+     */
+    getParticipant(ws: WebSocket): ConnectedParticipant | undefined;
+}
+/**
+ * Create a MAP WebSocket handler.
+ *
+ * This handler processes WebSocket connections for the MAP protocol.
+ * It creates a stream adapter from the WebSocket and passes it to the MAPAdapter.
+ *
+ * @param adapter - The MAPAdapter instance to use
+ * @returns Handler for managing MAP WebSocket connections
+ *
+ * @example
+ * ```typescript
+ * const mapHandler = createMAPWebSocketHandler(mapAdapter);
+ *
+ * wss.on("connection", (ws, req) => {
+ *   if (req.url?.startsWith("/map")) {
+ *     mapHandler.handleConnection(ws, req);
+ *   }
+ * });
+ * ```
+ */
+export declare function createMAPWebSocketHandler(adapter: MAPAdapter): MAPWebSocketHandler;
+/**
+ * Configuration for setting up MAP on a WebSocket server.
+ */
+export interface MAPWebSocketConfig {
+    /**
+     * The MAPAdapter instance.
+     */
+    adapter: MAPAdapter;
+    /**
+     * URL path for MAP connections (default: "/map").
+     */
+    path?: string;
+}
+/**
+ * Result of setting up MAP WebSocket handling.
+ */
+export interface MAPWebSocketSetup {
+    /**
+     * The MAP handler.
+     */
+    handler: MAPWebSocketHandler;
+    /**
+     * Check if a request URL matches the MAP path.
+     */
+    matchesPath: (url?: string) => boolean;
+}
+/**
+ * Set up MAP WebSocket handling configuration.
+ *
+ * Returns a handler and path matcher for use in a combined server setup.
+ *
+ * @param config - MAP WebSocket configuration
+ * @returns Setup result with handler and path matcher
+ *
+ * @example
+ * ```typescript
+ * const mapSetup = setupMAPWebSocket({ adapter: mapAdapter });
+ * const acpSetup = setupACPWebSocket(wss, services);
+ *
+ * // Route connections based on path
+ * httpServer.on("upgrade", (req, socket, head) => {
+ *   if (mapSetup.matchesPath(req.url)) {
+ *     wss.handleUpgrade(req, socket, head, (ws) => {
+ *       mapSetup.handler.handleConnection(ws, req);
+ *     });
+ *   } else {
+ *     // ACP or other handling
+ *   }
+ * });
+ * ```
+ */
+export declare function setupMAPWebSocket(config: MAPWebSocketConfig): MAPWebSocketSetup;
+//# sourceMappingURL=websocket-integration.d.ts.map

package/dist/map/adapter/websocket-integration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket-integration.d.ts","sourceRoot":"","sources":["../../../src/map/adapter/websocket-integration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAgBvD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE;QAAE,MAAM,EAAE;YAAE,aAAa,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5F;;OAEG;IACH,kBAAkB,IAAI,MAAM,CAAC;IAE7B;;OAEG;IACH,QAAQ,IAAI,IAAI,CAAC;IAEjB;;OAEG;IACH,cAAc,CAAC,EAAE,EAAE,SAAS,GAAG,oBAAoB,GAAG,SAAS,CAAC;CACjE;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,UAAU,GAAG,mBAAmB,CA0ElF;AAMD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,OAAO,EAAE,UAAU,CAAC;IAEpB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,OAAO,EAAE,mBAAmB,CAAC;IAE7B;;OAEG;IACH,WAAW,EAAE,CAAC,GAAG,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,kBAAkB,GAAG,iBAAiB,CAc/E"}