@teneo-protocol/sdk 2.2.2 → 3.0.1

package/src/managers/agent-room-manager.ts

@@ -24,6 +24,40 @@ export interface AgentRoomInfo {
   added_at?: string;
 }
 
+/**
+ * Options for listing available agents with pagination
+ */
+export interface ListAvailableAgentsOptions {
+  /** Number of agents to return (default: server decides) */
+  limit?: number;
+  /** Pagination offset */
+  offset?: number;
+  /** Include full agent details */
+  includeDetails?: boolean;
+  /** Return minimal agent info only */
+  minimal?: boolean;
+  /** Sort order: alphabetical or by other criteria */
+  sortBy?: "a-z" | "requests";
+  /** Include agents already in the room */
+  includeInRoom?: boolean;
+}
+
+/**
+ * Paginated result from listAvailableAgents with options
+ */
+export interface PaginatedAgentsResult {
+  /** List of agents */
+  agents: AgentRoomInfo[];
+  /** Total number of matching agents */
+  total: number;
+  /** Current offset */
+  offset: number;
+  /** Page size */
+  limit: number;
+  /** Whether there are more agents to load */
+  hasMore: boolean;
+}
+
 // Cache TTL: 5 minutes
 const CACHE_TTL_MS = 5 * 60 * 1000;
 
@@ -380,17 +414,25 @@ export class AgentRoomManager extends EventEmitter<SDKEvents> {
    * @param useCache - Whether to use cached data (default: true)
    * @returns Promise that resolves with array of available agents
    * @throws {SDKError} If not connected or operation fails
+   */
+  public async listAvailableAgents(roomId: string, useCache?: boolean): Promise<AgentRoomInfo[]>;
+  /**
+   * Lists agents available to add to a room with pagination and filtering options.
+   * Does not use cache when called with options.
    *
-   * @example
-   * ```typescript
-   * const availableAgents = await sdk.listAvailableAgents('room-123');
-   * console.log(`${availableAgents.length} agents can be added`);
-   * ```
+   * @param roomId - ID of the room to check available agents for
+   * @param options - Pagination and filter options
+   * @returns Promise that resolves with paginated agents result
+   * @throws {SDKError} If not connected or operation fails
    */
   public async listAvailableAgents(
     roomId: string,
-    useCache: boolean = true
-  ): Promise<AgentRoomInfo[]> {
+    options: ListAvailableAgentsOptions
+  ): Promise<PaginatedAgentsResult>;
+  public async listAvailableAgents(
+    roomId: string,
+    useCacheOrOptions?: boolean | ListAvailableAgentsOptions
+  ): Promise<AgentRoomInfo[] | PaginatedAgentsResult> {
     if (!this.wsClient.isConnected) {
       throw new SDKError("Not connected to Teneo Protocol", ErrorCode.NOT_CONNECTED);
     }
@@ -398,8 +440,12 @@ export class AgentRoomManager extends EventEmitter<SDKEvents> {
     // Validate input
     this.validateRoomId(roomId);
 
-    // Check cache if enabled
-    if (useCache) {
+    // Determine if using pagination options or legacy boolean
+    const isPaginated = typeof useCacheOrOptions === "object" && useCacheOrOptions !== null;
+    const useCache = isPaginated ? false : ((useCacheOrOptions as boolean) ?? true);
+
+    // Check cache if enabled (only for legacy non-paginated calls)
+    if (!isPaginated && useCache) {
       const cached = this.availableAgentsCache.get(roomId);
       if (cached) {
         this.logger.debug("AgentRoomManager: Returning cached available agents", {
@@ -410,13 +456,24 @@ export class AgentRoomManager extends EventEmitter<SDKEvents> {
       }
     }
 
-    this.logger.debug("AgentRoomManager: Listing available agents", { roomId });
+    this.logger.debug("AgentRoomManager: Listing available agents", { roomId, isPaginated });
+
+    // Build message data with optional pagination params
+    const data: Record<string, unknown> = { room_id: roomId };
+
+    if (isPaginated) {
+      const options = useCacheOrOptions as ListAvailableAgentsOptions;
+      if (options.limit !== undefined) data.limit = options.limit;
+      if (options.offset !== undefined) data.offset = options.offset;
+      if (options.includeDetails !== undefined) data.include_details = options.includeDetails;
+      if (options.minimal !== undefined) data.minimal = options.minimal;
+      if (options.sortBy !== undefined) data.sort_by = options.sortBy;
+      if (options.includeInRoom !== undefined) data.include_in_room = options.includeInRoom;
+    }
 
     const message = {
       type: "list_available_agents" as const,
-      data: {
-        room_id: roomId
-      }
+      data
     };
 
     return new Promise((resolve, reject) => {
@@ -425,9 +482,27 @@ export class AgentRoomManager extends EventEmitter<SDKEvents> {
         reject(new SDKError("List available agents timeout", ErrorCode.TIMEOUT));
       }, 30000);
 
-      const onSuccess = (agents: AgentRoomInfo[]) => {
+      const onSuccess = (
+        agents: AgentRoomInfo[],
+        paginationMeta?: {
+          total?: number;
+          offset?: number;
+          limit?: number;
+          hasMore?: boolean;
+        }
+      ) => {
         cleanup();
-        resolve(agents);
+        if (isPaginated) {
+          resolve({
+            agents,
+            total: paginationMeta?.total ?? agents.length,
+            offset: paginationMeta?.offset ?? 0,
+            limit: paginationMeta?.limit ?? agents.length,
+            hasMore: paginationMeta?.hasMore ?? false
+          });
+        } else {
+          resolve(agents);
+        }
       };
 
       const onError = (error: Error) => {
@@ -461,17 +536,29 @@ export class AgentRoomManager extends EventEmitter<SDKEvents> {
    *
    * @example
    * ```typescript
-   * const agents = sdk.getRoomAgents('room-123');
+   * const agents = sdk.getCachedRoomAgents('room-123');
    * if (agents) {
    *   console.log(`Found ${agents.length} agents in cache`);
    * }
    * ```
    */
-  public getRoomAgents(roomId: string): AgentRoomInfo[] | undefined {
+  public getCachedRoomAgents(roomId: string): AgentRoomInfo[] | undefined {
     const cached = this.roomAgentsCache.get(roomId);
     return cached ? cached.map((agent) => ({ ...agent })) : undefined;
   }
 
+  /**
+   * @deprecated Use getCachedRoomAgents() instead. This method returns cached data only.
+   *
+   * Gets agents currently in a room from cache (synchronous).
+   *
+   * @param roomId - Room ID to query
+   * @returns Array of agents or undefined if not cached
+   */
+  public getRoomAgents(roomId: string): AgentRoomInfo[] | undefined {
+    return this.getCachedRoomAgents(roomId);
+  }
+
   /**
    * Gets available agents for a room from cache (synchronous).
    * Returns undefined if not cached or cache expired.
@@ -481,17 +568,29 @@ export class AgentRoomManager extends EventEmitter<SDKEvents> {
    *
    * @example
    * ```typescript
-   * const available = sdk.getAvailableAgents('room-123');
+   * const available = sdk.getCachedAvailableAgents('room-123');
    * if (available) {
    *   console.log(`${available.length} agents can be added`);
    * }
    * ```
    */
-  public getAvailableAgents(roomId: string): AgentRoomInfo[] | undefined {
+  public getCachedAvailableAgents(roomId: string): AgentRoomInfo[] | undefined {
     const cached = this.availableAgentsCache.get(roomId);
     return cached ? cached.map((agent) => ({ ...agent })) : undefined;
   }
 
+  /**
+   * @deprecated Use getCachedAvailableAgents() instead. This method returns cached data only.
+   *
+   * Gets available agents for a room from cache (synchronous).
+   *
+   * @param roomId - Room ID to query
+   * @returns Array of available agents or undefined if not cached
+   */
+  public getAvailableAgents(roomId: string): AgentRoomInfo[] | undefined {
+    return this.getCachedAvailableAgents(roomId);
+  }
+
   /**
    * Checks if an agent is currently in a room (from cache).
    * Returns undefined if cache is invalid.
@@ -502,18 +601,36 @@ export class AgentRoomManager extends EventEmitter<SDKEvents> {
    *
    * @example
    * ```typescript
-   * const isInRoom = sdk.isAgentInRoom('room-123', 'agent-456');
-   * if (isInRoom === true) {
+   * const inRoom = sdk.checkAgentInRoom('room-123', 'agent-456');
+   * if (inRoom === true) {
    *   console.log('Agent is in this room');
+   * } else if (inRoom === false) {
+   *   console.log('Agent is not in this room');
+   * } else {
+   *   console.log('Cache unavailable - need to fetch');
    * }
    * ```
    */
-  public isAgentInRoom(roomId: string, agentId: string): boolean | undefined {
-    const agents = this.getRoomAgents(roomId);
+  public checkAgentInRoom(roomId: string, agentId: string): boolean | undefined {
+    const agents = this.getCachedRoomAgents(roomId);
     if (!agents) return undefined;
     return agents.some((agent) => agent.agent_id === agentId);
   }
 
+  /**
+   * @deprecated Use checkAgentInRoom() instead. The 'is*' naming convention implies boolean-only,
+   * but this method returns boolean | undefined to indicate cache validity.
+   *
+   * Checks if an agent is currently in a room (from cache).
+   *
+   * @param roomId - Room ID to check
+   * @param agentId - Agent ID to check
+   * @returns True if agent in room, false if not, undefined if cache invalid
+   */
+  public isAgentInRoom(roomId: string, agentId: string): boolean | undefined {
+    return this.checkAgentInRoom(roomId, agentId);
+  }
+
   /**
    * Gets the count of agents in a room (from cache).
    * Returns undefined if cache is invalid.
@@ -523,17 +640,29 @@ export class AgentRoomManager extends EventEmitter<SDKEvents> {
    *
    * @example
    * ```typescript
-   * const count = sdk.getRoomAgentCount('room-123');
+   * const count = sdk.getCachedRoomAgentCount('room-123');
    * if (count !== undefined) {
    *   console.log(`Room has ${count} agents`);
    * }
    * ```
    */
-  public getRoomAgentCount(roomId: string): number | undefined {
-    const agents = this.getRoomAgents(roomId);
+  public getCachedRoomAgentCount(roomId: string): number | undefined {
+    const agents = this.getCachedRoomAgents(roomId);
     return agents ? agents.length : undefined;
   }
 
+  /**
+   * @deprecated Use getCachedRoomAgentCount() instead. This method returns cached data only.
+   *
+   * Gets the count of agents in a room (from cache).
+   *
+   * @param roomId - Room ID to count agents for
+   * @returns Number of agents or undefined if cache invalid
+   */
+  public getRoomAgentCount(roomId: string): number | undefined {
+    return this.getCachedRoomAgentCount(roomId);
+  }
+
   // ============================================================================
   // CACHE MANAGEMENT (Public methods)
   // ============================================================================

package/src/managers/index.ts

@@ -6,7 +6,12 @@
 export { ConnectionManager } from "./connection-manager";
 export { RoomManager } from "./room-manager";
 export { RoomManagementManager } from "./room-management-manager";
-export { AgentRoomManager, type AgentRoomInfo } from "./agent-room-manager";
+export {
+  AgentRoomManager,
+  type AgentRoomInfo,
+  type ListAvailableAgentsOptions,
+  type PaginatedAgentsResult
+} from "./agent-room-manager";
 export { AgentRegistry } from "./agent-registry";
 export {
   MessageRouter,

package/src/managers/message-router.ts

@@ -29,7 +29,8 @@ import {
   AgentCommandContentSchema
 } from "../types/validation";
 import { waitForEvent } from "../utils/event-waiter";
-import { PaymentClient, buildX402ResourceUrl } from "../payments/payment-client";
+import { PaymentClient, buildX402ResourceUrl, usdcToUnits } from "../payments/payment-client";
+import { getDefaultNetwork, getNetwork } from "../payments/networks";
 import type { SecurePrivateKey } from "../utils/secure-private-key";
 
 export interface SendMessageOptions {
@@ -38,12 +39,26 @@ export interface SendMessageOptions {
   waitForResponse?: boolean;
   timeout?: number;
   format?: ResponseFormat | "raw" | "humanized";
+  network?: string; // Network name override (peaq, base, avalanche) (v2.3.0)
+  networkChainId?: number; // Chain ID override (v2.3.0)
 }
 
 export interface AgentCommand {
   agent: string;
   command: string;
   room: string;
+  network?: string | number; // Per-request network override (v2.3.0)
+}
+
+/**
+ * Settlement data from backend for x402x-router-settlement extension
+ */
+export interface SettlementData {
+  settlementRouter: string;
+  salt: string;
+  facilitatorFee: string;
+  hook: string;
+  hookData: string;
 }
 
 /**
@@ -57,6 +72,10 @@ export interface QuoteResult {
   command: string;
   pricing: PricingInfo;
   expiresAt: Date;
+  /** Backend-provided settlement data for x402x-router-settlement */
+  settlement: SettlementData;
+  /** Per-request network override, carried from requestQuote to confirmQuote (v2.3.0) */
+  networkOverride?: string | number;
 }
 
 export interface MessageRouterConfig {
@@ -66,8 +85,9 @@ export interface MessageRouterConfig {
   maxPricePerRequest?: number;
   quoteTimeout?: number;
   wsUrl?: string;
-  paymentNetwork?: string;
+  paymentNetwork?: string; // CAIP-2 format (e.g., "eip155:3338")
   paymentAsset?: string;
+  network?: string; // Network name (e.g., "peaq", "base", "avalanche")
 }
 
 export class MessageRouter extends EventEmitter<SDKEvents> {
@@ -85,8 +105,9 @@ export class MessageRouter extends EventEmitter<SDKEvents> {
   private readonly maxPricePerRequest?: number;
   private readonly quoteTimeout: number;
   private readonly wsUrl: string;
-  private readonly paymentNetwork: string;
+  private readonly paymentNetwork: string; // CAIP-2 format if set
   private readonly paymentAsset: string;
+  private readonly networkName: string; // Network name (peaq, base, avalanche)
 
   constructor(
     wsClient: WebSocketClient,
@@ -108,21 +129,61 @@ export class MessageRouter extends EventEmitter<SDKEvents> {
     this.maxPricePerRequest = config.maxPricePerRequest;
     this.quoteTimeout = config.quoteTimeout ?? 30000;
     this.wsUrl = config.wsUrl ?? "";
-    this.paymentNetwork = config.paymentNetwork ?? "eip155:3338";
-    // USDC contract address on PEAQ network
-    this.paymentAsset = config.paymentAsset ?? "0xbbA60da06c2c5424f03f7434542280FCAd453d10";
+
+    // Store config values - dynamic network resolution happens lazily in getPaymentNetwork/Asset()
+    // because networks are only initialized after connect() is called
+    this.paymentNetwork = config.paymentNetwork ?? "";
+    this.paymentAsset = config.paymentAsset ?? "";
+    this.networkName = config.network ?? "";
 
     this.setupEventForwarding();
   }
 
+  /**
+   * Gets the payment network CAIP-2 identifier, resolving from network name or default.
+   * Only call this after connect() has been called (networks initialized).
+   */
+  private getResolvedPaymentNetwork(networkOverride?: string | number): string {
+    // Priority: per-request override > paymentNetwork (CAIP-2) > networkName > default
+    if (networkOverride) {
+      const network = getNetwork(networkOverride);
+      return network.caip2;
+    }
+    if (this.paymentNetwork) {
+      return this.paymentNetwork;
+    }
+    if (this.networkName) {
+      const network = getNetwork(this.networkName);
+      return network.caip2;
+    }
+    const defaultNetwork = getDefaultNetwork();
+    return defaultNetwork.caip2;
+  }
+
+  /**
+   * Gets the payment asset, resolving from network name or default.
+   * Only call this after connect() has been called (networks initialized).
+   */
+  private getResolvedPaymentAsset(): string {
+    if (this.paymentAsset) {
+      return this.paymentAsset;
+    }
+    if (this.networkName) {
+      const network = getNetwork(this.networkName);
+      return network.usdcContract;
+    }
+    const defaultNetwork = getDefaultNetwork();
+    return defaultNetwork.usdcContract;
+  }
+
   /**
    * Sets up the payment client for quote-approve flow.
    * Must be called before using requestQuote/confirmQuote with paid tasks.
    */
   public setPaymentClient(secureKey: SecurePrivateKey, walletAddress: string): void {
     this.paymentClient = new PaymentClient(secureKey, walletAddress, {
-      network: this.paymentNetwork,
-      asset: this.paymentAsset
+      network: this.getResolvedPaymentNetwork(),
+      asset: this.getResolvedPaymentAsset()
     });
   }
 
@@ -146,11 +207,11 @@ export class MessageRouter extends EventEmitter<SDKEvents> {
    * @example
    * ```typescript
    * // Fire and forget
-   * await messageRouter.sendMessage('What is the weather?', { room: 'general' });
+   * await messageRouter.sendMessage('What is the weather?', { room: 'room-id' });
    *
    * // Wait for response
    * const response = await messageRouter.sendMessage('Calculate 2+2', {
-   *   room: 'general',
+   *   room: 'room-id',
    *   waitForResponse: true,
    *   timeout: 30000
    * });
@@ -173,11 +234,13 @@ export class MessageRouter extends EventEmitter<SDKEvents> {
 
     // Use quote-approve flow with auto-approval (v2.2.0)
     if (this.autoApproveQuotes) {
+      const networkOverride = options.network || options.networkChainId;
       this.logger.debug("MessageRouter: Using quote-approve flow", {
         content: validatedContent,
-        room
+        room,
+        network: networkOverride
       });
-      const quote = await this.requestQuote(validatedContent, room);
+      const quote = await this.requestQuote(validatedContent, room, networkOverride);
       return await this.confirmQuote(quote.taskId, {
         waitForResponse: options.waitForResponse,
         timeout: options.timeout ?? this.messageTimeout
@@ -211,17 +274,28 @@ export class MessageRouter extends EventEmitter<SDKEvents> {
    * @param command.agent - Agent ID or name to send command to
    * @param command.command - Command text to send
    * @param command.room - Room to send in (required)
-   * @returns Promise that resolves when command is sent
+   * @param command.network - Optional per-request network override (name like "base" or chain ID like 8453)
+   * @param waitForResponse - Whether to wait for agent response (default: false)
+   * @returns Promise resolving to FormattedResponse if waiting, void otherwise
    * @throws {SDKError} If not connected
    * @throws {ValidationError} If agent/command empty or room not specified
    *
    * @example
    * ```typescript
+   * // Basic usage
    * await messageRouter.sendDirectCommand({
    *   agent: 'weather-agent',
    *   command: 'Get forecast for Tokyo',
-   *   room: 'general'
+   *   room: 'room-id'
    * });
+   *
+   * // With per-request network override
+   * await messageRouter.sendDirectCommand({
+   *   agent: 'x-agent-enterprise-v2',
+   *   command: 'user @elonmusk',
+   *   room: 'room-id',
+   *   network: 'base'
+   * }, true);
    * ```
    */
   public async sendDirectCommand(
@@ -244,8 +318,8 @@ export class MessageRouter extends EventEmitter<SDKEvents> {
 
     // Use quote-approve flow with auto-approval (v2.2.0)
     if (this.autoApproveQuotes) {
-      this.logger.debug("MessageRouter: Using quote-approve flow", { content, room });
-      const quote = await this.requestQuote(content, room);
+      this.logger.debug("MessageRouter: Using quote-approve flow", { content, room, network: command.network });
+      const quote = await this.requestQuote(content, room, command.network);
       return await this.confirmQuote(quote.taskId, {
         waitForResponse,
         timeout: this.messageTimeout
@@ -284,13 +358,15 @@ export class MessageRouter extends EventEmitter<SDKEvents> {
    * Requests a quote for a task without auto-approval.
    * Returns the quote data for manual confirmation.
    */
-  public async requestQuote(content: string, room: string): Promise<QuoteResult> {
+  public async requestQuote(content: string, room: string, networkOverride?: string | number): Promise<QuoteResult> {
     if (!this.wsClient.isConnected) {
       throw new SDKError("Not connected to Teneo network", ErrorCode.NOT_CONNECTED);
     }
 
-    const message = createRequestTask(content, room);
-    this.logger.debug("MessageRouter: Requesting quote", { content, room });
+    // Include payment network in request so backend returns correct contract addresses
+    const resolvedNetwork = this.getResolvedPaymentNetwork(networkOverride);
+    const message = createRequestTask(content, room, resolvedNetwork);
+    this.logger.debug("MessageRouter: Requesting quote", { content, room, network: resolvedNetwork });
 
     await this.wsClient.sendMessage(message);
 
@@ -306,9 +382,25 @@ export class MessageRouter extends EventEmitter<SDKEvents> {
       agentWallet: quote.data.agent_wallet,
       command: quote.data.command,
       pricing: quote.data.pricing,
-      expiresAt: new Date(quote.data.expires_at)
+      expiresAt: new Date(quote.data.expires_at),
+      // Backend-provided settlement data for x402x-router-settlement
+      settlement: {
+        settlementRouter: quote.data.settlement_router,
+        salt: quote.data.salt,
+        facilitatorFee: quote.data.facilitator_fee,
+        hook: quote.data.hook,
+        hookData: quote.data.hook_data ?? "0x"
+      },
+      networkOverride
     };
 
+    this.logger.debug("MessageRouter: Quote received with settlement data", {
+      taskId: result.taskId,
+      settlementRouter: result.settlement.settlementRouter,
+      salt: result.settlement.salt?.substring(0, 20) + "...",
+      hook: result.settlement.hook
+    });
+
     this.pendingQuotes.set(result.taskId, result);
     return result;
   }
@@ -335,9 +427,9 @@ export class MessageRouter extends EventEmitter<SDKEvents> {
       throw new SDKError("Quote has expired", ErrorCode.QUOTE_EXPIRED);
     }
 
-    // Check price limit
+    // Check price limit (pricePerUnit is in USDC, convert to micro-units)
+    const priceInUnits = usdcToUnits(quote.pricing.pricePerUnit);
     if (this.maxPricePerRequest !== undefined) {
-      const priceInUnits = quote.pricing.pricePerUnit * 1_000_000;
       if (priceInUnits > this.maxPricePerRequest) {
         this.emit("payment:blocked", {
           agentId: quote.agentId,
@@ -357,14 +449,17 @@ export class MessageRouter extends EventEmitter<SDKEvents> {
     // Create payment header if payment client is configured and price > 0
     if (this.paymentClient && quote.pricing.pricePerUnit > 0) {
       try {
+        // Pass backend-provided settlement data to payment header creation
         paymentHeader = await this.paymentClient.createPaymentHeader(
-          quote.pricing.pricePerUnit * 1_000_000,
+          priceInUnits,
           quote.agentWallet,
-          buildX402ResourceUrl(this.wsUrl)
+          buildX402ResourceUrl(this.wsUrl),
+          quote.networkOverride, // Per-request network override (v2.3.0)
+          quote.settlement // Backend-provided settlement data
         );
         this.emit("payment:attached", {
           agentId: quote.agentId,
-          amount: quote.pricing.pricePerUnit * 1_000_000,
+          amount: priceInUnits,
           command: quote.command
         });
       } catch (error) {
@@ -452,12 +547,12 @@ export class MessageRouter extends EventEmitter<SDKEvents> {
         }
 
         // Fallback: If server doesn't support client_request_id,
-        // match the first response from the expected room within 60 seconds
+        // match the first response from the expected room within the time window
         // This handles servers that don't echo back client_request_id
         const timeSinceRequest = Date.now() - requestTimestamp;
         const responseRoom = r.raw?.room;
         const isFromExpectedRoom = responseRoom === message.room;
-        const isWithinTimeWindow = timeSinceRequest < 60000; // 60 second window
+        const isWithinTimeWindow = timeSinceRequest < TIMEOUTS.RESPONSE_MATCH_WINDOW;
 
         if (isFromExpectedRoom && isWithinTimeWindow && !responseRequestId) {
           this.logger.debug("Matching response without client_request_id (server fallback)", {