@teneo-protocol/sdk 2.2.2 → 3.0.0

package/src/constants.ts

@@ -15,7 +15,9 @@ export const TIMEOUTS = {
   /** Webhook delivery timeout */
   WEBHOOK_TIMEOUT: 10_000,
   /** Auth state polling interval */
-  AUTH_POLL_INTERVAL: 100
+  AUTH_POLL_INTERVAL: 100,
+  /** Time window for matching responses without client_request_id (fallback) */
+  RESPONSE_MATCH_WINDOW: 60_000
 } as const;
 
 /**
@@ -36,8 +38,8 @@ export const RETRY = {
  * Limits and constraints
  */
 export const LIMITS = {
-  /** Maximum message size (2MB) */
-  MAX_MESSAGE_SIZE: 2 * 1024 * 1024,
+  /** Maximum message size (10MB - sufficient for room history) */
+  MAX_MESSAGE_SIZE: 10 * 1024 * 1024,
   /** Random jitter for reconnection */
   MAX_JITTER: 1000
 } as const;

package/src/core/websocket-client.ts

@@ -338,16 +338,14 @@ export class WebSocketClient extends EventEmitter<SDKEvents> {
           if (parseResult.success) {
             this.handleMessage(parseResult.data as BaseMessage);
           } else {
-            // Use warn instead of error - allows SDK to be more resilient
-            this.logger.warn("Received message with unknown or invalid format", {
+            // Log validation errors at debug level only (hidden from end users)
+            this.logger.debug("Message validation warning", {
               type: rawMessage?.type,
               error: parseResult.error?.message
             });
-            this.emit(
-              "message:error",
-              new ValidationError("Invalid message format", parseResult.error),
-              rawMessage
-            );
+
+            // Still process the message for resilience - don't block on validation errors
+            this.handleMessage(rawMessage as BaseMessage);
           }
         } catch (error) {
           this.logger.error("Failed to parse message", error);
@@ -618,8 +616,11 @@ export class WebSocketClient extends EventEmitter<SDKEvents> {
     try {
       // Check for cached authentication first
       if (this.config.walletAddress) {
-        this.logger.debug("Checking cached authentication");
-        await this.sendMessage(createCheckCachedAuth(this.config.walletAddress));
+        const sessionToken = this.authState.sessionToken;
+        this.logger.debug("Checking cached authentication", {
+          hasSessionToken: !!sessionToken
+        });
+        await this.sendMessage(createCheckCachedAuth(this.config.walletAddress, sessionToken));
 
         // Wait briefly for cached auth response
         await new Promise((resolve) => setTimeout(resolve, TIMEOUTS.CACHED_AUTH_WAIT));

package/src/handlers/message-handlers/agent-details-response-handler.ts

@@ -36,7 +36,7 @@ export class AgentDetailsResponseHandler extends BaseMessageHandler<AgentDetails
       status: agent.status
     });
 
-    // Send webhook
-    this.sendWebhook(context, "agent_details_response", { agent });
+    // Note: This is a query response, not sent via webhook
+    // Users can listen to the 'agent:details' event if needed
   }
 }

package/src/handlers/message-handlers/agent-error-handler.ts

@@ -0,0 +1,47 @@
+/**
+ * Handler for agent_error messages
+ * Processes agent failure notifications from the server (no payment charged)
+ */
+
+import { AgentErrorMessage, AgentErrorMessageSchema } from "../../types";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+
+export class AgentErrorHandler extends BaseMessageHandler<AgentErrorMessage> {
+  readonly type = "agent_error" as const;
+  readonly schema = AgentErrorMessageSchema;
+
+  protected handleValidated(message: AgentErrorMessage, context: HandlerContext): void {
+    const { content, from, data, room } = message;
+
+    context.logger.debug("Handling agent_error", {
+      from,
+      taskId: data?.task_id,
+      content
+    });
+
+    context.logger.warn("Agent error received", {
+      agentName: from,
+      content,
+      taskId: data?.task_id
+    });
+
+    // Emit agent error event
+    this.emit(context, "agent:error", {
+      agentName: from,
+      content,
+      taskId: data?.task_id,
+      clientRequestId: data?.client_request_id,
+      room
+    });
+
+    // Send webhook
+    this.sendWebhook(context, "agent_error", {
+      agentName: from,
+      content,
+      taskId: data?.task_id,
+      clientRequestId: data?.client_request_id,
+      room
+    });
+  }
+}

package/src/handlers/message-handlers/agent-status-update-handler.ts

@@ -41,12 +41,7 @@ export class AgentStatusUpdateHandler extends BaseMessageHandler<AgentStatusUpda
       agent
     });
 
-    // Send webhook
-    this.sendWebhook(context, "agent_status_update", {
-      room_id,
-      agent_id,
-      status,
-      agent
-    });
+    // Note: Agent status updates fire constantly and would spam webhooks
+    // Users can listen to the 'agent_room:status_update' event if needed
   }
 }

package/src/handlers/message-handlers/all-agents-response-handler.ts

@@ -33,7 +33,7 @@ export class AllAgentsResponseHandler extends BaseMessageHandler<AllAgentsRespon
       filter
     });
 
-    // Send webhook
-    this.sendWebhook(context, "all_agents_response", message.data);
+    // Note: This is a query response, not sent via webhook
+    // Admins can listen to the 'admin:all_agents' event if needed
   }
 }

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

@@ -65,7 +65,13 @@ export class AuthMessageHandler extends BaseMessageHandler<AuthMessage> {
         // v2.0.0: New fields
         privateRoomIds, // Rooms user owns
         sharedRoomIds, // Rooms user is member of
-        maxPrivateRooms: message.data?.max_private_rooms // Max rooms user can create
+        maxPrivateRooms: message.data?.max_private_rooms, // Max rooms user can create
+
+        // Auth enhancement fields (audit #6, #7, #9)
+        jwtToken: message.data?.jwt_token, // JWT token for KeyVault API
+        sessionToken: message.data?.session_token, // Session token for fast re-auth
+        whitelistVerified: message.data?.whitelist_verified, // Whitelist verification status
+        userCount: message.data?.user_count // Total user count (admin only)
       });
 
       // Initialize room management manager with room data (v2.0.0)

package/src/handlers/message-handlers/auth-success-handler.ts

@@ -42,7 +42,13 @@ export class AuthSuccessHandler extends BaseMessageHandler<AuthSuccessMessage> {
       roomObjects: rooms, // Full room objects with is_owner field
       privateRoomIds, // Rooms user owns
       sharedRoomIds, // Rooms user is member of
-      maxPrivateRooms: message.data.max_private_rooms // Max rooms user can create
+      maxPrivateRooms: message.data.max_private_rooms, // Max rooms user can create
+
+      // Auth enhancement fields (audit #6, #7, #9)
+      jwtToken: message.data.jwt_token, // JWT token for KeyVault API
+      sessionToken: message.data.session_token, // Session token for fast re-auth
+      whitelistVerified: message.data.whitelist_verified, // Whitelist verification status
+      userCount: message.data.user_count // Total user count (admin only)
     });
 
     // Get updated auth state

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

@@ -34,10 +34,29 @@ export abstract class BaseMessageHandler<T extends BaseMessage = BaseMessage>
   public async handle(message: BaseMessage, context: HandlerContext): Promise<void> {
     try {
       // Validate message with Zod schema
-      const validated = this.validate(message);
+      const result = this.schema.safeParse(message);
+      if (!result.success) {
+        // Log validation errors at debug level only (hidden from end users)
+        context.logger.debug(`${this.type} message validation warning`, {
+          error: result.error.message
+        });
+      }
 
-      // Call subclass implementation
-      await this.handleValidated(validated, context);
+      // Process message even if validation failed (resilience)
+      // Use validated data if available, otherwise use raw message
+      const messageToProcess = result.success ? result.data : (message as T);
+
+      // Call subclass implementation with additional error protection
+      try {
+        await this.handleValidated(messageToProcess, context);
+      } catch (handlerError) {
+        // Catch errors from handlers accessing malformed data
+        context.logger.warn(`Handler ${this.type} failed to process message`, {
+          error: handlerError instanceof Error ? handlerError.message : String(handlerError),
+          messageType: message.type
+        });
+        // Don't re-throw - resilient processing continues
+      }
     } catch (error) {
       context.logger.error(`Error handling ${this.type} message`, error);
       this.onError(error, message, context);
@@ -45,7 +64,8 @@ export abstract class BaseMessageHandler<T extends BaseMessage = BaseMessage>
   }
 
   /**
-   * Validate message against schema
+   * Validate message against schema (deprecated - validation now inline in handle())
+   * @deprecated Validation is now done inline in handle() method
    */
   protected validate(message: BaseMessage): T {
     const result = this.schema.safeParse(message);

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

@@ -18,6 +18,7 @@ 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 { SuccessHandler } from "./success-handler";
 export { RegularMessageHandler } from "./regular-message-handler";
 export { PingHandler, PongHandler } from "./ping-pong-handler";
 export { SubscribeResponseHandler } from "./subscribe-response-handler";
@@ -39,6 +40,15 @@ export { RateLimitNotificationHandler } from "./rate-limit-notification-handler"
 export { AllAgentsResponseHandler } from "./all-agents-response-handler";
 export { UserCountHandler } from "./user-count-handler";
 
+// Agent Error handler
+export { AgentErrorHandler } from "./agent-error-handler";
+
+// Task Confirmed handler
+export { TaskConfirmedHandler } from "./task-confirmed-handler";
+
+// Wallet Transaction handler
+export { TriggerWalletTxHandler } from "./trigger-wallet-tx-handler";
+
 // Presence handler
 export { UserAuthenticatedHandler } from "./user-authenticated-handler";
 
@@ -53,6 +63,7 @@ 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 { SuccessHandler } from "./success-handler";
 import { RegularMessageHandler } from "./regular-message-handler";
 import { PingHandler, PongHandler } from "./ping-pong-handler";
 import { SubscribeResponseHandler } from "./subscribe-response-handler";
@@ -67,6 +78,9 @@ import { AgentDetailsResponseHandler } from "./agent-details-response-handler";
 import { RateLimitNotificationHandler } from "./rate-limit-notification-handler";
 import { AllAgentsResponseHandler } from "./all-agents-response-handler";
 import { UserCountHandler } from "./user-count-handler";
+import { AgentErrorHandler } from "./agent-error-handler";
+import { TaskConfirmedHandler } from "./task-confirmed-handler";
+import { TriggerWalletTxHandler } from "./trigger-wallet-tx-handler";
 import { UserAuthenticatedHandler } from "./user-authenticated-handler";
 import { MessageHandler } from "./types";
 
@@ -95,6 +109,7 @@ export function getDefaultHandlers(
     // Message handlers
     new RegularMessageHandler(),
     new ErrorMessageHandler(),
+    new SuccessHandler(),
 
     // Room handlers
     new SubscribeResponseHandler(),
@@ -120,6 +135,15 @@ export function getDefaultHandlers(
     new AllAgentsResponseHandler(),
     new UserCountHandler(),
 
+    // Agent Error handler
+    new AgentErrorHandler(),
+
+    // Task Confirmed handler
+    new TaskConfirmedHandler(),
+
+    // Wallet Transaction handler
+    new TriggerWalletTxHandler(),
+
     // Presence handler
     new UserAuthenticatedHandler(),
 

package/src/handlers/message-handlers/list-available-agents-handler.ts

@@ -13,29 +13,42 @@ export class ListAvailableAgentsHandler extends BaseMessageHandler<AvailableAgen
   readonly schema = AvailableAgentsResponseSchema;
 
   protected handleValidated(message: AvailableAgentsResponse, context: HandlerContext): void {
-    const { agents } = message.data;
+    const { agents, total, offset, limit, has_more } = message.data;
 
     context.logger.debug("Handling available_agents_response", {
-      agentCount: agents?.length || 0
+      agentCount: agents?.length || 0,
+      total,
+      offset,
+      limit,
+      has_more
     });
 
     // Parse agents array (handle undefined as empty array)
     const agentList: AgentRoomInfo[] = agents || [];
 
     context.logger.info("Available agents listed", {
-      count: agentList.length
+      count: agentList.length,
+      total
     });
 
     // Note: We don't cache this globally since it's room-specific
     // The AgentRoomManager will cache it with the room context
 
-    // Emit success event
-    this.emit(context, "agent_room:available_agents_listed", agentList);
-
-    // Send webhook
-    this.sendWebhook(context, "available_agents_listed", {
-      agents: agentList,
-      count: agentList.length
-    });
+    // Emit success event, with pagination metadata if present
+    const hasPagination =
+      total !== undefined || offset !== undefined || limit !== undefined || has_more !== undefined;
+    if (hasPagination) {
+      this.emit(context, "agent_room:available_agents_listed", agentList, {
+        total,
+        offset,
+        limit,
+        hasMore: has_more
+      });
+    } else {
+      this.emit(context, "agent_room:available_agents_listed", agentList);
+    }
+
+    // Note: This is a query response, not sent via webhook
+    // Users can listen to the 'agent_room:available_agents_listed' event if needed
   }
 }

package/src/handlers/message-handlers/list-room-agents-handler.ts

@@ -48,11 +48,7 @@ export class ListRoomAgentsHandler extends BaseMessageHandler<RoomAgentsResponse
     // Emit success event
     this.emit(context, "agent_room:agents_listed", room_id, agentList);
 
-    // Send webhook
-    this.sendWebhook(context, "room_agents_listed", {
-      room_id,
-      agents: agentList,
-      count: agentList.length
-    });
+    // Note: This is a query response, not sent via webhook
+    // Users can listen to the 'agent_room:agents_listed' event if needed
   }
 }

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

@@ -21,10 +21,7 @@ export class ListRoomsResponseHandler extends BaseMessageHandler<ListRoomsRespon
     // 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
-    });
+    // Note: This is a query response, not sent via webhook
+    // Users can listen to the 'room:list' event if needed
   }
 }

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

@@ -22,9 +22,34 @@ 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");
+  protected async handleValidated(message: PongMessage, context: HandlerContext): Promise<void> {
+    // Check if this is a room pong (has room data) or regular pong
+    if (message.data && typeof message.data === "object" && "room_id" in message.data) {
+      // Room pong - server responds to room_ping with live user count
+      const roomData = message.data as {
+        room_id: string;
+        live_count?: number;
+        timestamp: string;
+      };
+
+      context.logger.debug("Received room pong", {
+        roomId: roomData.room_id,
+        liveCount: roomData.live_count,
+        timestamp: roomData.timestamp
+      });
+
+      // Emit room pong event
+      this.emit(context, "room:pong", {
+        roomId: roomData.room_id,
+        liveCount: roomData.live_count ?? 0,
+        timestamp: roomData.timestamp
+      });
+
+      // Note: room_pong is an internal keepalive/user-count event, not sent via webhook
+      // Users can listen to the 'room:pong' event if needed
+    } else {
+      // Regular pong - handled at the WebSocket level (ws library)
+      context.logger.debug("Received pong");
+    }
   }
 }

package/src/handlers/message-handlers/rate-limit-notification-handler.ts

@@ -39,7 +39,8 @@ export class RateLimitNotificationHandler extends BaseMessageHandler<RateLimitNo
       resetAt: reset_at
     });
 
-    // Send webhook
-    this.sendWebhook(context, "rate_limit_notification", message.data);
+    // Note: Rate limits are already logged and handled internally
+    // Sending via webhook would be redundant
+    // Users can listen to the 'rate_limit' event if needed
   }
 }

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

@@ -0,0 +1,26 @@
+/**
+ * Handler for success messages
+ * Server sends generic success confirmations that can be displayed to users
+ */
+
+import { SuccessMessage, SuccessMessageSchema } from "../../types";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+
+export class SuccessHandler extends BaseMessageHandler<SuccessMessage> {
+  readonly type = "success" as const;
+  readonly schema = SuccessMessageSchema;
+
+  protected handleValidated(message: SuccessMessage, context: HandlerContext): void {
+    const content = message.content || message.data?.content;
+
+    context.logger.debug("Handling success message", { content });
+
+    // Emit success event
+    this.emit(context, "success", content || "Operation successful");
+
+    // Note: Generic success messages are too vague for webhooks
+    // Specific success events (room_operation, etc.) have their own handlers
+    // Users can listen to the 'success' event if needed
+  }
+}

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

@@ -0,0 +1,49 @@
+/**
+ * Handler for task_confirmed messages
+ * Server sends this as acknowledgment after confirm_task in the Quote-Confirm flow.
+ * Indicates that task execution has begun.
+ */
+
+import { TaskConfirmedMessage, TaskConfirmedMessageSchema } from "../../types";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+
+export class TaskConfirmedHandler extends BaseMessageHandler<TaskConfirmedMessage> {
+  readonly type = "task_confirmed" as const;
+  readonly schema = TaskConfirmedMessageSchema;
+
+  protected handleValidated(message: TaskConfirmedMessage, context: HandlerContext): void {
+    const taskId = message.data?.task_id ?? message.task_id ?? "";
+    const agentId = message.data?.agent_id;
+    const agentName = message.data?.agent_name;
+    const clientRequestId = message.data?.client_request_id;
+
+    context.logger.debug("Handling task_confirmed", {
+      taskId,
+      agentId,
+      agentName
+    });
+
+    context.logger.info("Task confirmed and execution started", {
+      taskId,
+      agentId,
+      agentName
+    });
+
+    // Emit task confirmed event
+    this.emit(context, "task:confirmed", {
+      taskId,
+      agentId,
+      agentName,
+      clientRequestId
+    });
+
+    // Send webhook
+    this.sendWebhook(context, "task_confirmed", {
+      taskId,
+      agentId,
+      agentName,
+      clientRequestId
+    });
+  }
+}

package/src/handlers/message-handlers/trigger-wallet-tx-handler.ts

@@ -0,0 +1,62 @@
+/**
+ * Handler for trigger_wallet_tx messages
+ * Server sends this when an agent requires an on-chain transaction
+ */
+
+import { TriggerWalletTxMessage, TriggerWalletTxMessageSchema } from "../../types";
+import { BaseMessageHandler } from "./base-handler";
+import { HandlerContext } from "./types";
+
+export class TriggerWalletTxHandler extends BaseMessageHandler<TriggerWalletTxMessage> {
+  readonly type = "trigger_wallet_tx" as const;
+  readonly schema = TriggerWalletTxMessageSchema;
+
+  protected handleValidated(message: TriggerWalletTxMessage, context: HandlerContext): void {
+    const { from, data, room } = message;
+
+    // Defensive: Check for required fields
+    if (!data?.task_id || !data?.tx) {
+      context.logger.warn("Invalid trigger_wallet_tx message: missing required fields", {
+        from,
+        hasData: !!data,
+        hasTaskId: !!data?.task_id,
+        hasTx: !!data?.tx
+      });
+      return;
+    }
+
+    context.logger.debug("Handling trigger_wallet_tx", {
+      from,
+      taskId: data.task_id,
+      tx: data.tx
+    });
+
+    context.logger.info("Wallet transaction requested", {
+      agentName: from,
+      taskId: data.task_id,
+      to: data.tx.to,
+      value: data.tx.value,
+      chainId: data.tx.chainId
+    });
+
+    // Emit wallet tx requested event
+    this.emit(context, "wallet:tx_requested", {
+      taskId: data.task_id,
+      agentName: from,
+      tx: data.tx,
+      description: data.description,
+      optional: data.optional ?? false,
+      room
+    });
+
+    // Send webhook
+    this.sendWebhook(context, "wallet_tx_requested", {
+      taskId: data.task_id,
+      agentName: from,
+      tx: data.tx,
+      description: data.description,
+      optional: data.optional,
+      room
+    });
+  }
+}

package/src/handlers/message-handlers/user-authenticated-handler.ts

@@ -25,7 +25,7 @@ export class UserAuthenticatedHandler extends BaseMessageHandler<UserAuthenticat
     // Emit presence event
     this.emit(context, "user:authenticated", { wallet });
 
-    // Send webhook
-    this.sendWebhook(context, "user_authenticated", message.data);
+    // Note: user_authenticated is not in the WebhookEventType enum, so no webhook is sent
+    // This is a broadcast event for presence tracking, not typically needed in webhooks
   }
 }

package/src/handlers/message-handlers/user-count-handler.ts

@@ -28,7 +28,7 @@ export class UserCountHandler extends BaseMessageHandler<UserCountMessage> {
     // Emit admin event
     this.emit(context, "admin:user_count", { count, timestamp });
 
-    // Send webhook
-    this.sendWebhook(context, "user_count", message.data);
+    // Note: user_count is not in the WebhookEventType enum, so no webhook is sent
+    // This is an admin-only broadcast event, not typically needed in webhooks
   }
 }

package/src/index.ts

@@ -243,20 +243,28 @@ export {
   PEAQ_CHAIN_ID,
   USDC_CONTRACT,
   DEFAULT_PAY_TO_ADDRESS,
-  DEFAULT_RPC_URL,
   USDC_DECIMALS,
   X402_VERSION,
   DEFAULT_PAYMENT_TIMEOUT_SECONDS,
   buildX402ResourceUrl,
   usdcToUnits,
   unitsToUsdc,
-  type SupportedChain
+  // Multi-network support (v2.3.0)
+  type NetworkConfig,
+  NETWORKS,
+  CHAIN_ID_TO_NETWORK,
+  CAIP2_TO_NETWORK,
+  getNetwork,
+  getDefaultNetwork,
+  createChainDefinition,
+  isNetworkSupported,
+  getSupportedNetworks
 } from "./payments";
 
 /**
  * SDK version string
  */
-export const VERSION = "2.2.2";
+export const VERSION = "3.0.0";
 
 /**
  * Convenience type re-exports for message operations
@@ -275,7 +283,7 @@ export type { SendMessageOptions, AgentCommand } from "./teneo-sdk";
  * const sdk = await createTeneoSDK({
  *   wsUrl: 'ws://localhost:8080/ws',
  *   privateKey: 'your-private-key',
- *   autoJoinRooms: ['general']
+ *   autoJoinPublicRooms: ['room-id-1']
  * });
  * ```
  */

package/src/managers/admin-manager.ts

@@ -30,6 +30,8 @@ export interface ListAllAgentsOptions {
   offset?: number;
   /** Number of agents to return (default: 50) */
   limit?: number;
+  /** Sort order: alphabetical or by request count */
+  sortBy?: "a-z" | "requests";
 }
 
 /**
@@ -124,9 +126,9 @@ export class AdminManager extends EventEmitter<AdminManagerEvents> {
       throw new SDKError("Admin privileges required", ErrorCode.AUTH_ERROR);
     }
 
-    const { filter, offset = 0, limit = 50 } = options;
+    const { filter, offset = 0, limit = 50, sortBy } = options;
 
-    this.logger.info("AdminManager: Listing all agents", { filter, offset, limit });
+    this.logger.info("AdminManager: Listing all agents", { filter, offset, limit, sortBy });
 
     // Generate request ID
     const requestId = `admin_list_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
@@ -137,6 +139,7 @@ export class AdminManager extends EventEmitter<AdminManagerEvents> {
       filter,
       offset,
       limit,
+      ...(sortBy && { sort_by: sortBy }),
       request_id: requestId
     };