@teneo-protocol/sdk 1.0.0

package/src/handlers/message-handlers/index.ts

@@ -0,0 +1,77 @@
+/**
+ * Message handlers index
+ * Exports all message handlers and provides convenience functions
+ */
+
+// Export types
+export * from "./types";
+export * from "./base-handler";
+
+// Export all handlers
+export { TaskResponseHandler } from "./task-response-handler";
+export { AgentSelectedHandler } from "./agent-selected-handler";
+export { ChallengeHandler } from "./challenge-handler";
+export { AuthMessageHandler } from "./auth-message-handler";
+export { AuthSuccessHandler } from "./auth-success-handler";
+export { AuthErrorHandler } from "./auth-error-handler";
+export { AuthRequiredHandler } from "./auth-required-handler";
+export { AgentsListHandler } from "./agents-list-handler";
+export { ErrorMessageHandler } from "./error-message-handler";
+export { RegularMessageHandler } from "./regular-message-handler";
+export { PingHandler, PongHandler } from "./ping-pong-handler";
+export { SubscribeResponseHandler } from "./subscribe-response-handler";
+export { UnsubscribeResponseHandler } from "./unsubscribe-response-handler";
+export { ListRoomsResponseHandler } from "./list-rooms-response-handler";
+
+// Import for convenience function
+import { TaskResponseHandler } from "./task-response-handler";
+import { AgentSelectedHandler } from "./agent-selected-handler";
+import { ChallengeHandler } from "./challenge-handler";
+import { AuthMessageHandler } from "./auth-message-handler";
+import { AuthSuccessHandler } from "./auth-success-handler";
+import { AuthErrorHandler } from "./auth-error-handler";
+import { AuthRequiredHandler } from "./auth-required-handler";
+import { AgentsListHandler } from "./agents-list-handler";
+import { ErrorMessageHandler } from "./error-message-handler";
+import { RegularMessageHandler } from "./regular-message-handler";
+import { PingHandler, PongHandler } from "./ping-pong-handler";
+import { SubscribeResponseHandler } from "./subscribe-response-handler";
+import { UnsubscribeResponseHandler } from "./unsubscribe-response-handler";
+import { ListRoomsResponseHandler } from "./list-rooms-response-handler";
+import { MessageHandler } from "./types";
+
+/**
+ * Get all default message handlers
+ * @param clientType - The client type for authentication (default: "user")
+ * @returns Array of all default handlers
+ */
+export function getDefaultHandlers(
+  clientType: "user" | "agent" | "coordinator" = "user"
+): MessageHandler[] {
+  return [
+    // Authentication handlers
+    new ChallengeHandler(clientType),
+    new AuthMessageHandler(),
+    new AuthSuccessHandler(),
+    new AuthErrorHandler(),
+    new AuthRequiredHandler(),
+
+    // Agent/coordinator handlers
+    new TaskResponseHandler(),
+    new AgentSelectedHandler(),
+    new AgentsListHandler(),
+
+    // Message handlers
+    new RegularMessageHandler(),
+    new ErrorMessageHandler(),
+
+    // Room handlers
+    new SubscribeResponseHandler(),
+    new UnsubscribeResponseHandler(),
+    new ListRoomsResponseHandler(),
+
+    // Keepalive handlers
+    new PingHandler(),
+    new PongHandler()
+  ];
+}

package/src/handlers/message-handlers/list-rooms-response-handler.ts

@@ -0,0 +1,28 @@
+/**
+ * Handler for list_rooms response messages
+ * Processes room list from server
+ */
+
+import { ListRoomsResponse, ListRoomsResponseSchema } from "../../types";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+
+export class ListRoomsResponseHandler extends BaseMessageHandler<ListRoomsResponse> {
+  readonly type = "list_rooms" as const;
+  readonly schema = ListRoomsResponseSchema;
+
+  protected handleValidated(message: ListRoomsResponse, context: HandlerContext): void {
+    context.logger.debug("Handling list_rooms response", {
+      roomCount: message.data.rooms.length
+    });
+
+    // Emit room:list event with room info array
+    this.emit(context, "room:list", message.data.rooms);
+
+    // Send webhook (fire-and-forget)
+    this.sendWebhook(context, "room_list", {
+      rooms: message.data.rooms,
+      count: message.data.rooms.length
+    });
+  }
+}

package/src/handlers/message-handlers/ping-pong-handler.ts

@@ -0,0 +1,30 @@
+/**
+ * Handler for ping and pong messages
+ * These are keepalive messages that don't require special handling
+ */
+
+import { PingMessage, PongMessage, PingMessageSchema, PongMessageSchema } from "../../types";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+
+export class PingHandler extends BaseMessageHandler<PingMessage> {
+  readonly type = "ping" as const;
+  readonly schema = PingMessageSchema;
+
+  protected async handleValidated(_message: PingMessage, context: HandlerContext): Promise<void> {
+    // Ping messages are handled at the WebSocket level (ws library)
+    // No special processing needed here
+    context.logger.debug("Received ping");
+  }
+}
+
+export class PongHandler extends BaseMessageHandler<PongMessage> {
+  readonly type = "pong" as const;
+  readonly schema = PongMessageSchema;
+
+  protected async handleValidated(_message: PongMessage, context: HandlerContext): Promise<void> {
+    // Pong messages are handled at the WebSocket level (ws library)
+    // No special processing needed here
+    context.logger.debug("Received pong");
+  }
+}

package/src/handlers/message-handlers/regular-message-handler.ts

@@ -0,0 +1,65 @@
+/**
+ * Handler for regular 'message' type messages
+ * Processes messages from agents (when they send 'message' instead of 'task_response')
+ */
+
+import { UserMessage, UserMessageSchema } from "../../types";
+import { AgentResponse } from "../../types/events";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+
+export class RegularMessageHandler extends BaseMessageHandler<UserMessage> {
+  readonly type = "message" as const;
+  readonly schema = UserMessageSchema;
+
+  protected async handleValidated(message: UserMessage, context: HandlerContext): Promise<void> {
+    // Check if this message has a 'from' field and content
+    if (!message.from || !message.content) {
+      return;
+    }
+
+    if (!message.room) {
+      context.logger.warn("Inbound 'message' lacks room; proceeding without room context", {
+        from: message.from
+      });
+    }
+
+    const authState = context.getAuthState();
+    const fromLower = message.from.toLowerCase();
+    const walletLower = authState.walletAddress?.toLowerCase();
+
+    context.logger.debug('Received message type "message"', {
+      from: message.from,
+      fromLower,
+      walletLower
+    });
+
+    // If message is NOT from the user's wallet, it's likely from an agent
+    // Treat it as an agent response
+    if (fromLower !== walletLower) {
+      context.logger.info("Treating message as agent response", {
+        from: message.from,
+        contentPreview:
+          typeof message.content === "string" ? message.content.substring(0, 100) : "non-string",
+        room: message.room
+      });
+
+      // Build agent response
+      const response: AgentResponse = {
+        taskId: message.data?.task_id || `msg-${Date.now()}`,
+        agentId: message.from,
+        agentName: message.data?.agent_name || "Agent",
+        content:
+          typeof message.content === "string" ? message.content : JSON.stringify(message.content),
+        contentType: message.content_type || "text/plain",
+        success: true,
+        timestamp: new Date(),
+        humanized:
+          typeof message.content === "string" ? message.content : JSON.stringify(message.content)
+      };
+
+      // Emit agent:response event
+      this.emit(context, "agent:response", response);
+    }
+  }
+}

package/src/handlers/message-handlers/subscribe-response-handler.ts

@@ -0,0 +1,47 @@
+/**
+ * Handler for subscribe response messages
+ * Processes room subscription confirmations
+ */
+
+import { SubscribeResponse, SubscribeResponseSchema } from "../../types";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+
+export class SubscribeResponseHandler extends BaseMessageHandler<SubscribeResponse> {
+  readonly type = "subscribe" as const;
+  readonly schema = SubscribeResponseSchema;
+
+  protected handleValidated(message: SubscribeResponse, context: HandlerContext): void {
+    context.logger.debug("Handling subscribe response", {
+      roomId: message.data.room_id,
+      success: message.data.success
+    });
+
+    if (message.data.success) {
+      // Update subscription state from server's authoritative list
+      if (context.roomManager && message.data.subscriptions) {
+        context.roomManager.updateSubscriptions(message.data.subscriptions);
+      }
+
+      // Emit room:subscribed event
+      this.emit(context, "room:subscribed", {
+        roomId: message.data.room_id,
+        subscriptions: message.data.subscriptions || []
+      });
+
+      // Send webhook (fire-and-forget)
+      this.sendWebhook(context, "room_subscribed", {
+        roomId: message.data.room_id,
+        subscriptions: message.data.subscriptions
+      });
+    } else {
+      context.logger.warn("Room subscription failed", {
+        roomId: message.data.room_id,
+        message: message.data.message
+      });
+
+      // Emit error event
+      this.emit(context, "error", new Error(`Subscription failed: ${message.data.message}`));
+    }
+  }
+}

package/src/handlers/message-handlers/task-response-handler.ts

@@ -0,0 +1,45 @@
+/**
+ * Handler for task_response messages
+ * Processes agent responses to tasks
+ */
+
+import { z } from "zod";
+import { TaskResponseMessage, TaskResponseMessageSchema } from "../../types";
+import { AgentResponse } from "../../types/events";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+
+export class TaskResponseHandler extends BaseMessageHandler<TaskResponseMessage> {
+  readonly type = "task_response" as const;
+  readonly schema = TaskResponseMessageSchema as z.ZodSchema<TaskResponseMessage>;
+
+  protected handleValidated(message: TaskResponseMessage, context: HandlerContext): void {
+    context.logger.debug("Handling task_response message", {
+      taskId: message.data.task_id,
+      from: message.from
+    });
+
+    // Build agent response
+    const response: AgentResponse = {
+      taskId: message.data.task_id,
+      agentId: message.from || "",
+      agentName: message.data.agent_name,
+      content: message.content,
+      contentType: message.content_type,
+      success: message.data.success !== false,
+      error: message.data.error,
+      timestamp: new Date(),
+      raw: message,
+      humanized: message.content
+    };
+
+    // Emit agent:response event
+    this.emit(context, "agent:response", response);
+
+    // Send webhook (fire-and-forget)
+    this.sendWebhook(context, "task_response", response, {
+      agentId: response.agentId,
+      taskId: response.taskId
+    });
+  }
+}

package/src/handlers/message-handlers/types.ts

@@ -0,0 +1,77 @@
+/**
+ * Types and interfaces for the Message Handler Registry pattern
+ * Defines the contract for message handlers and their context
+ */
+
+import { z } from "zod";
+import { BaseMessage, MessageType, Logger, WebhookEventType } from "../../types";
+import { FormattedResponse } from "../../formatters/response-formatter";
+import { PrivateKeyAccount } from "viem/accounts";
+
+/**
+ * Context provided to message handlers
+ * Contains all dependencies needed to handle messages
+ */
+export interface HandlerContext {
+  // Event emission
+  emit: (event: string, ...args: any[]) => void;
+
+  // Webhook delivery
+  sendWebhook: (type: WebhookEventType, data: any, metadata?: any) => Promise<void>;
+
+  // Response formatting (optional)
+  formatResponse?: (message: BaseMessage) => FormattedResponse;
+
+  // Logging
+  logger: Logger;
+
+  // State access
+  getConnectionState: () => any;
+  getAuthState: () => any;
+  updateConnectionState: (update: any) => void;
+  updateAuthState: (update: any) => void;
+
+  // Room manager for subscription updates (optional)
+  roomManager?: any;
+
+  // Account for signing (optional, for auth handlers)
+  account?: PrivateKeyAccount;
+
+  // Send message back to server
+  sendMessage: (message: BaseMessage) => Promise<void>;
+}
+
+/**
+ * Message handler interface
+ * Each message type has a handler implementing this interface
+ */
+export interface MessageHandler<T extends BaseMessage = BaseMessage> {
+  // Message type this handler processes
+  readonly type: MessageType;
+
+  // Zod schema for validation
+  readonly schema: z.ZodSchema<T>;
+
+  // Handle the message
+  handle(message: BaseMessage, context: HandlerContext): Promise<void> | void;
+
+  // Validate if this handler can handle a message
+  canHandle(message: BaseMessage): boolean;
+}
+
+/**
+ * Handler metadata for registration
+ */
+export interface HandlerMetadata {
+  type: MessageType;
+  description?: string;
+  priority?: number; // For handler ordering (lower = higher priority)
+}
+
+/**
+ * Handler registration options
+ */
+export interface HandlerRegistrationOptions {
+  replace?: boolean; // Replace existing handler for this type
+  priority?: number; // Handler priority
+}

package/src/handlers/message-handlers/unsubscribe-response-handler.ts

@@ -0,0 +1,47 @@
+/**
+ * Handler for unsubscribe response messages
+ * Processes room unsubscription confirmations
+ */
+
+import { UnsubscribeResponse, UnsubscribeResponseSchema } from "../../types";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+
+export class UnsubscribeResponseHandler extends BaseMessageHandler<UnsubscribeResponse> {
+  readonly type = "unsubscribe" as const;
+  readonly schema = UnsubscribeResponseSchema;
+
+  protected handleValidated(message: UnsubscribeResponse, context: HandlerContext): void {
+    context.logger.debug("Handling unsubscribe response", {
+      roomId: message.data.room_id,
+      success: message.data.success
+    });
+
+    if (message.data.success) {
+      // Update subscription state from server's authoritative list
+      if (context.roomManager && message.data.subscriptions) {
+        context.roomManager.updateSubscriptions(message.data.subscriptions);
+      }
+
+      // Emit room:unsubscribed event
+      this.emit(context, "room:unsubscribed", {
+        roomId: message.data.room_id,
+        subscriptions: message.data.subscriptions || []
+      });
+
+      // Send webhook (fire-and-forget)
+      this.sendWebhook(context, "room_unsubscribed", {
+        roomId: message.data.room_id,
+        subscriptions: message.data.subscriptions
+      });
+    } else {
+      context.logger.warn("Room unsubscription failed", {
+        roomId: message.data.room_id,
+        message: message.data.message
+      });
+
+      // Emit error event
+      this.emit(context, "error", new Error(`Unsubscription failed: ${message.data.message}`));
+    }
+  }
+}