macro-agent 0.2.4 → 0.2.6

package/dist/map/adapter/rpc-handler.js

@@ -0,0 +1,365 @@
+/**
+ * JSON-RPC Handler for MAP Protocol
+ *
+ * Handles JSON-RPC 2.0 message parsing, method dispatch, request/response
+ * correlation, and error formatting for the MAP adapter.
+ *
+ * Adapted from MAP SDK patterns (RouterConnectionImpl) but simplified
+ * for macro-agent's needs.
+ *
+ * @see specs/s-5qir_map_integration_for_macro_agent.md
+ */
+// =============================================================================
+// Standard JSON-RPC Error Codes
+// =============================================================================
+export const JSON_RPC_ERRORS = {
+    /** Invalid JSON was received. */
+    PARSE_ERROR: -32700,
+    /** The JSON sent is not a valid Request object. */
+    INVALID_REQUEST: -32600,
+    /** The method does not exist / is not available. */
+    METHOD_NOT_FOUND: -32601,
+    /** Invalid method parameter(s). */
+    INVALID_PARAMS: -32602,
+    /** Internal JSON-RPC error. */
+    INTERNAL_ERROR: -32603,
+};
+// =============================================================================
+// MAP-specific Error Codes (custom range: -32000 to -32099)
+// =============================================================================
+export const MAP_ERRORS = {
+    /** Participant not found. */
+    PARTICIPANT_NOT_FOUND: -32001,
+    /** Agent not found. */
+    AGENT_NOT_FOUND: -32002,
+    /** Scope not found. */
+    SCOPE_NOT_FOUND: -32003,
+    /** Subscription not found. */
+    SUBSCRIPTION_NOT_FOUND: -32004,
+    /** Permission denied. */
+    PERMISSION_DENIED: -32010,
+    /** Rate limit exceeded. */
+    RATE_LIMIT_EXCEEDED: -32011,
+    /** Resource limit exceeded. */
+    RESOURCE_LIMIT_EXCEEDED: -32012,
+    /** Authentication failed. */
+    AUTHENTICATION_FAILED: -32013,
+    /** Invalid address. */
+    INVALID_ADDRESS: -32020,
+    /** Routing failed. */
+    ROUTING_FAILED: -32021,
+    /** Connection not established. */
+    NOT_CONNECTED: -32030,
+    /** Already connected. */
+    ALREADY_CONNECTED: -32031,
+};
+// =============================================================================
+// Message Helpers
+// =============================================================================
+/**
+ * Check if a message is a JSON-RPC request.
+ */
+export function isRequest(message) {
+    return (typeof message === "object" &&
+        message !== null &&
+        "jsonrpc" in message &&
+        message.jsonrpc === "2.0" &&
+        "id" in message &&
+        "method" in message);
+}
+/**
+ * Check if a message is a JSON-RPC notification.
+ */
+export function isNotification(message) {
+    return (typeof message === "object" &&
+        message !== null &&
+        "jsonrpc" in message &&
+        message.jsonrpc === "2.0" &&
+        "method" in message &&
+        !("id" in message));
+}
+/**
+ * Check if a message is a JSON-RPC response.
+ */
+export function isResponse(message) {
+    return (typeof message === "object" &&
+        message !== null &&
+        "jsonrpc" in message &&
+        message.jsonrpc === "2.0" &&
+        "id" in message &&
+        ("result" in message || "error" in message));
+}
+/**
+ * Check if a response is an error response.
+ */
+export function isErrorResponse(response) {
+    return "error" in response;
+}
+/**
+ * Create a success response.
+ */
+export function createSuccessResponse(id, result) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        result,
+    };
+}
+/**
+ * Create an error response.
+ */
+export function createErrorResponse(id, code, message, data) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: { code, message, data },
+    };
+}
+/**
+ * Create a notification.
+ */
+export function createNotification(method, params) {
+    return {
+        jsonrpc: "2.0",
+        method,
+        params,
+    };
+}
+// =============================================================================
+// RPC Error Class
+// =============================================================================
+/**
+ * Error that can be converted to JSON-RPC error response.
+ */
+export class RPCError extends Error {
+    errorCode;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.name = "RPCError";
+        this.errorCode = code;
+        this.data = data;
+    }
+    toJsonRpcError() {
+        return {
+            code: this.errorCode,
+            message: this.message,
+            data: this.data,
+        };
+    }
+    static methodNotFound(method) {
+        return new RPCError(JSON_RPC_ERRORS.METHOD_NOT_FOUND, `Method not found: ${method}`);
+    }
+    static invalidParams(message) {
+        return new RPCError(JSON_RPC_ERRORS.INVALID_PARAMS, message);
+    }
+    static internalError(message) {
+        return new RPCError(JSON_RPC_ERRORS.INTERNAL_ERROR, message);
+    }
+    static permissionDenied(message) {
+        return new RPCError(MAP_ERRORS.PERMISSION_DENIED, message);
+    }
+    static notFound(type, id) {
+        const codes = {
+            agent: MAP_ERRORS.AGENT_NOT_FOUND,
+            scope: MAP_ERRORS.SCOPE_NOT_FOUND,
+            subscription: MAP_ERRORS.SUBSCRIPTION_NOT_FOUND,
+            participant: MAP_ERRORS.PARTICIPANT_NOT_FOUND,
+            peer: MAP_ERRORS.NOT_CONNECTED, // Use NOT_CONNECTED for peer not found
+            conversation: JSON_RPC_ERRORS.INTERNAL_ERROR,
+        };
+        return new RPCError(codes[type], `${type} not found: ${id}`);
+    }
+    static resourceLimitExceeded(message) {
+        return new RPCError(MAP_ERRORS.RESOURCE_LIMIT_EXCEEDED, message);
+    }
+    static invalidAddress(message) {
+        return new RPCError(MAP_ERRORS.INVALID_ADDRESS, message);
+    }
+    static routingFailed(message) {
+        return new RPCError(MAP_ERRORS.ROUTING_FAILED, message);
+    }
+    static authenticationFailed(message) {
+        return new RPCError(MAP_ERRORS.AUTHENTICATION_FAILED, message);
+    }
+}
+/**
+ * RPC Handler class.
+ *
+ * Processes JSON-RPC messages, dispatches to handlers, and formats responses.
+ */
+export class RPCHandler {
+    handlers;
+    middleware;
+    notificationHandler;
+    constructor(config) {
+        this.handlers = config.handlers;
+        this.middleware = config.middleware ?? [];
+        this.notificationHandler = config.notificationHandler;
+    }
+    /**
+     * Process an incoming JSON-RPC message.
+     *
+     * @param message - The parsed JSON-RPC message
+     * @param context - Handler context
+     * @returns Processing result
+     */
+    async process(message, context) {
+        // Handle requests
+        if (isRequest(message)) {
+            const response = await this.handleRequest(message, {
+                ...context,
+                requestId: message.id,
+            });
+            return { type: "response", response };
+        }
+        // Handle notifications
+        if (isNotification(message)) {
+            const handled = await this.handleNotification(message);
+            return { type: "notification", handled };
+        }
+        // Ignore responses (we don't make outgoing requests from handler)
+        if (isResponse(message)) {
+            return { type: "ignored" };
+        }
+        // Unknown message type - could be malformed
+        return { type: "ignored" };
+    }
+    /**
+     * Handle a JSON-RPC request.
+     */
+    async handleRequest(request, context) {
+        const { id, method, params } = request;
+        console.error(`[RPCHandler.handleRequest] method=${method} id=${id}`);
+        try {
+            // Find handler
+            const handler = this.handlers[method];
+            if (!handler) {
+                throw RPCError.methodNotFound(method);
+            }
+            // Execute through middleware chain
+            console.error(`[RPCHandler.handleRequest] Executing handler for ${method}`);
+            const result = await this.executeWithMiddleware(method, params, context, handler);
+            console.error(`[RPCHandler.handleRequest] Handler success for ${method}`);
+            return createSuccessResponse(id, result ?? null);
+        }
+        catch (error) {
+            console.error(`[RPCHandler.handleRequest] Error in ${method}:`, error);
+            return this.errorToResponse(id, error);
+        }
+    }
+    /**
+     * Handle a JSON-RPC notification.
+     */
+    async handleNotification(notification) {
+        if (!this.notificationHandler) {
+            return false;
+        }
+        try {
+            await this.notificationHandler(notification.method, notification.params);
+            return true;
+        }
+        catch (error) {
+            console.error("[RPCHandler] Notification handler error:", error);
+            return false;
+        }
+    }
+    /**
+     * Execute handler with middleware chain.
+     */
+    async executeWithMiddleware(method, params, context, handler) {
+        let index = 0;
+        const next = async () => {
+            if (index < this.middleware.length) {
+                const middleware = this.middleware[index++];
+                return middleware(method, params, context, next);
+            }
+            else {
+                return handler(params, context);
+            }
+        };
+        return next();
+    }
+    /**
+     * Convert an error to a JSON-RPC error response.
+     */
+    errorToResponse(id, error) {
+        if (error instanceof RPCError) {
+            return createErrorResponse(id, error.errorCode, error.message, error.data);
+        }
+        if (error instanceof Error) {
+            return createErrorResponse(id, JSON_RPC_ERRORS.INTERNAL_ERROR, error.message);
+        }
+        return createErrorResponse(id, JSON_RPC_ERRORS.INTERNAL_ERROR, "Unknown error");
+    }
+    /**
+     * Check if a method is registered.
+     */
+    hasMethod(method) {
+        return method in this.handlers;
+    }
+    /**
+     * Get list of registered methods.
+     */
+    getMethods() {
+        return Object.keys(this.handlers);
+    }
+    /**
+     * Add a handler for a method.
+     */
+    addHandler(method, handler) {
+        this.handlers[method] = handler;
+    }
+    /**
+     * Remove a handler for a method.
+     */
+    removeHandler(method) {
+        delete this.handlers[method];
+    }
+}
+// =============================================================================
+// Factory
+// =============================================================================
+/**
+ * Create an RPCHandler instance.
+ */
+export function createRPCHandler(config) {
+    return new RPCHandler(config);
+}
+// =============================================================================
+// Common Middleware
+// =============================================================================
+/**
+ * Create a logging middleware.
+ */
+export function createLoggingMiddleware(prefix = "[RPC]") {
+    return async (method, params, context, next) => {
+        const start = Date.now();
+        try {
+            const result = await next();
+            const duration = Date.now() - start;
+            console.log(`${prefix} ${method} - ${duration}ms`);
+            return result;
+        }
+        catch (error) {
+            const duration = Date.now() - start;
+            console.error(`${prefix} ${method} FAILED - ${duration}ms`, error);
+            throw error;
+        }
+    };
+}
+/**
+ * Create a capability check middleware.
+ *
+ * @param requirements - Map of method to required capability
+ */
+export function createCapabilityMiddleware(requirements) {
+    return async (method, params, context, next) => {
+        const requiredCapability = requirements[method];
+        if (requiredCapability && !context.capabilities[requiredCapability]) {
+            throw RPCError.permissionDenied(`Requires capability: ${requiredCapability}`);
+        }
+        return next();
+    };
+}
+//# sourceMappingURL=rpc-handler.js.map

package/dist/map/adapter/rpc-handler.js.map

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

package/dist/map/adapter/subscription-manager.d.ts

@@ -0,0 +1,174 @@
+/**
+ * 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 type { ParticipantId, SubscriptionId, SubscriptionFilter, Subscription, EventNotification } from "./types.js";
+import type { AdapterLimits } from "./interface.js";
+import type { AgentId } from "../../store/types/index.js";
+/**
+ * Error codes for subscription manager operations.
+ */
+export type SubscriptionErrorCode = "MAX_SUBSCRIPTIONS_EXCEEDED" | "SUBSCRIPTION_NOT_FOUND" | "PARTICIPANT_NOT_FOUND" | "INVALID_FILTER";
+/**
+ * Error thrown by subscription manager operations.
+ */
+export declare class SubscriptionError extends Error {
+    readonly code: SubscriptionErrorCode;
+    constructor(message: string, code: SubscriptionErrorCode);
+}
+/**
+ * Configuration for SubscriptionManager.
+ */
+export interface SubscriptionManagerConfig {
+    /** Resource limits */
+    limits?: AdapterLimits;
+    /**
+     * Function to get agent's ancestors (for lineage filter matching).
+     * Returns agent IDs from immediate parent to root.
+     */
+    getAncestors?: (agentId: AgentId) => AgentId[];
+    /**
+     * Function to get agent's descendants (for subtree filter matching).
+     * Returns all descendant agent IDs.
+     */
+    getDescendants?: (agentId: AgentId) => AgentId[];
+}
+/**
+ * Event types emitted by SubscriptionManager.
+ */
+export type SubscriptionManagerEventType = "subscription.created" | "subscription.removed" | "subscription.paused" | "subscription.resumed";
+/**
+ * Event payload for subscription manager events.
+ */
+export type SubscriptionManagerEvent = {
+    type: "subscription.created";
+    subscription: Subscription;
+} | {
+    type: "subscription.removed";
+    subscriptionId: SubscriptionId;
+} | {
+    type: "subscription.paused";
+    subscriptionId: SubscriptionId;
+} | {
+    type: "subscription.resumed";
+    subscriptionId: SubscriptionId;
+};
+/**
+ * Handler for subscription manager events.
+ */
+export type SubscriptionManagerEventHandler = (event: SubscriptionManagerEvent) => void;
+/**
+ * Result of matching an event against subscriptions.
+ */
+export interface MatchResult {
+    /** Subscriptions that match the event */
+    subscriptions: Subscription[];
+    /** Participant IDs to deliver to */
+    participantIds: ParticipantId[];
+}
+/**
+ * SubscriptionManager interface.
+ */
+export interface SubscriptionManager {
+    /**
+     * Create a subscription for a participant.
+     *
+     * @param participantId - Subscribing participant
+     * @param filter - Event filter criteria (empty = all events)
+     * @returns Subscription ID
+     * @throws SubscriptionError if limits exceeded
+     */
+    subscribe(participantId: ParticipantId, filter?: SubscriptionFilter): SubscriptionId;
+    /**
+     * Remove a subscription.
+     *
+     * @param subscriptionId - Subscription to remove
+     */
+    unsubscribe(subscriptionId: SubscriptionId): void;
+    /**
+     * Get all subscriptions for a participant.
+     */
+    getSubscriptions(participantId: ParticipantId): Subscription[];
+    /**
+     * Get all subscription IDs for a participant.
+     */
+    getSubscriptionIds(participantId: ParticipantId): SubscriptionId[];
+    /**
+     * Get a specific subscription.
+     */
+    getSubscription(subscriptionId: SubscriptionId): Subscription | undefined;
+    /**
+     * Pause a subscription (stop receiving events).
+     */
+    pause(subscriptionId: SubscriptionId): void;
+    /**
+     * Resume a paused subscription.
+     */
+    resume(subscriptionId: SubscriptionId): void;
+    /**
+     * Check if a subscription is paused.
+     */
+    isPaused(subscriptionId: SubscriptionId): boolean;
+    /**
+     * Match an event against all active subscriptions.
+     *
+     * @param event - Event to match
+     * @returns Matching subscriptions and participant IDs
+     */
+    match(event: EventNotification): MatchResult;
+    /**
+     * Remove all subscriptions for a participant.
+     * Called when participant disconnects.
+     */
+    removeAllForParticipant(participantId: ParticipantId): void;
+    /**
+     * Get total subscription count.
+     */
+    getSubscriptionCount(): number;
+    /**
+     * Register an event handler.
+     */
+    onEvent(handler: SubscriptionManagerEventHandler): () => void;
+}
+/**
+ * SubscriptionManager implementation.
+ */
+export declare class SubscriptionManagerImpl implements SubscriptionManager {
+    private readonly subscriptions;
+    private readonly participantSubscriptions;
+    private readonly eventHandlers;
+    private readonly config;
+    constructor(config?: SubscriptionManagerConfig);
+    subscribe(participantId: ParticipantId, filter?: SubscriptionFilter): SubscriptionId;
+    unsubscribe(subscriptionId: SubscriptionId): void;
+    getSubscriptions(participantId: ParticipantId): Subscription[];
+    getSubscriptionIds(participantId: ParticipantId): SubscriptionId[];
+    getSubscription(subscriptionId: SubscriptionId): Subscription | undefined;
+    pause(subscriptionId: SubscriptionId): void;
+    resume(subscriptionId: SubscriptionId): void;
+    isPaused(subscriptionId: SubscriptionId): boolean;
+    match(event: EventNotification): MatchResult;
+    removeAllForParticipant(participantId: ParticipantId): void;
+    getSubscriptionCount(): number;
+    onEvent(handler: SubscriptionManagerEventHandler): () => void;
+    /**
+     * Check if an event matches a subscription filter.
+     * All filters are ANDed together.
+     */
+    private matchesFilter;
+    private emit;
+}
+/**
+ * Create a SubscriptionManager instance.
+ */
+export declare function createSubscriptionManager(config?: SubscriptionManagerConfig): SubscriptionManager;
+//# sourceMappingURL=subscription-manager.d.ts.map

package/dist/map/adapter/subscription-manager.d.ts.map

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