@teneo-protocol/sdk 1.0.1 → 2.2.0

package/src/teneo-sdk.ts

@@ -6,18 +6,19 @@
 
 import { EventEmitter } from "eventemitter3";
 import { z } from "zod";
+import { privateKeyToAccount } from "viem/accounts";
 import {
   SDKConfig,
   PartialSDKConfig,
   PartialSDKConfigSchema,
   SDKConfigBuilder,
   Agent,
-  Room,
   RoomInfo,
   Logger,
   validateConfig,
   DEFAULT_CONFIG,
   ResponseFormatSchema,
+  AgentRoomInfo,
   type HealthStatus
 } from "./types";
 import { SDKEvents, SDKError } from "./types/events";
@@ -32,16 +33,29 @@ import {
 import {
   ConnectionManager,
   RoomManager,
+  RoomManagementManager,
+  AgentRoomManager,
   AgentRegistry,
   MessageRouter,
   SendMessageOptions,
-  AgentCommand
+  AgentCommand,
+  QuoteResult,
+  AdminManager,
+  ListAllAgentsOptions,
+  AllAgentsResult
 } from "./managers";
 import { createPinoLogger } from "./utils/logger";
 import { RoomIdSchema, AgentIdSchema, AgentCommandContentSchema } from "./types/validation";
+import { SecurePrivateKey } from "./utils/secure-private-key";
 
 // Re-export types for external use
-export type { SendMessageOptions, AgentCommand };
+export type {
+  SendMessageOptions,
+  AgentCommand,
+  QuoteResult,
+  ListAllAgentsOptions,
+  AllAgentsResult
+};
 
 // Zod schemas for SDK-specific interfaces
 export const SendMessageOptionsSchema = z.object({
@@ -62,6 +76,7 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
   private config: SDKConfig;
   private readonly logger: Logger;
   private isDestroyed = false;
+  private secureKey?: SecurePrivateKey;
 
   // Core components
   private readonly wsClient: WebSocketClient;
@@ -71,8 +86,11 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
   // Managers
   private readonly connection: ConnectionManager;
   private readonly rooms: RoomManager;
+  private readonly roomManagement: RoomManagementManager;
+  private readonly agentRoom: AgentRoomManager;
   private readonly agents: AgentRegistry;
   private readonly messages: MessageRouter;
+  private readonly _admin: AdminManager;
 
   /**
    * Creates a new instance of the Teneo Protocol SDK.
@@ -138,6 +156,15 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
       // Initialize logger
       this.logger = this.config.logger ?? this.createDefaultLogger();
 
+      // Store secure key for payment client
+      if (config.privateKey) {
+        if (typeof config.privateKey === "object" && "use" in config.privateKey) {
+          this.secureKey = config.privateKey;
+        } else {
+          this.secureKey = new SecurePrivateKey(config.privateKey as string);
+        }
+      }
+
       // Initialize core components
       this.wsClient = new WebSocketClient(this.config);
       this.webhookHandler = new WebhookHandler(this.config, this.logger);
@@ -149,8 +176,16 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
       // Initialize managers
       this.connection = new ConnectionManager(this.wsClient, this.logger);
       this.rooms = new RoomManager(this.wsClient, this.logger);
+      this.roomManagement = new RoomManagementManager(this.wsClient, this.logger);
+      this.agentRoom = new AgentRoomManager(this.wsClient, this.logger, this.roomManagement);
       this.wsClient.setRoomManager(this.rooms); // Enable subscription tracking in handlers
+      this.wsClient.setRoomManagementManager(this.roomManagement); // Enable room CRUD in handlers (v2.0.0)
+      this.wsClient.setAgentRoomManager(this.agentRoom); // Enable agent-room operations in handlers (v2.0.0)
       this.agents = new AgentRegistry(this.logger);
+      this.agents.setWebSocketClient(this.wsClient); // Enable getAgentDetails requests
+      this._admin = new AdminManager(this.wsClient, this.logger);
+      this.wsClient.setAdminManager(this._admin); // Enable admin handlers
+      this.wsClient.setAgentRegistry(this.agents); // Enable agent details handler
       this.messages = new MessageRouter(
         this.wsClient,
         this.webhookHandler,
@@ -158,10 +193,27 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
         this.logger,
         {
           messageTimeout: this.config.messageTimeout,
-          responseFormat: this.config.responseFormat
+          responseFormat: this.config.responseFormat,
+          autoApproveQuotes: this.config.autoApproveQuotes,
+          maxPricePerRequest: this.config.maxPricePerRequest,
+          quoteTimeout: this.config.quoteTimeout,
+          wsUrl: this.config.wsUrl,
+          paymentNetwork: this.config.paymentNetwork,
+          paymentAsset: this.config.paymentAsset
         }
       );
 
+      // Set up payment client if private key is configured (v2.2.0)
+      if (this.config.privateKey) {
+        const secureKey =
+          this.config.privateKey instanceof SecurePrivateKey
+            ? this.config.privateKey
+            : new SecurePrivateKey(this.config.privateKey);
+        const walletAddress =
+          this.config.walletAddress || this.deriveWalletAddress(this.config.privateKey);
+        this.messages.setPaymentClient(secureKey, walletAddress);
+      }
+
       // Set up event forwarding
       this.setupEventForwarding();
 
@@ -175,7 +227,7 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
   }
 
   /**
-   * Establishes a connection to the Teneo network via WebSocket.
+   * Establishes a connection to the Teneo Protocol via WebSocket.
    * Handles authentication automatically and joins any configured auto-join rooms.
    * Emits 'connection:open', 'auth:success', and 'ready' events on successful connection.
    *
@@ -188,7 +240,7 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
    * ```typescript
    * const sdk = new TeneoSDK({ wsUrl: 'wss://example.com', privateKey: '0x...' });
    * await sdk.connect();
-   * console.log('Connected to Teneo network');
+   * console.log('Connected to Teneo Protocol');
    * ```
    */
   public async connect(): Promise<void> {
@@ -197,7 +249,7 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
     }
 
     try {
-      this.logger.info("Connecting to Teneo network");
+      this.logger.info("Connecting to Teneo Protocol");
       await this.connection.connect();
 
       // Auto-join rooms if configured
@@ -207,26 +259,26 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
         }
       }
 
-      this.logger.info("Successfully connected to Teneo network");
+      this.logger.info("Successfully connected to Teneo Protocol");
     } catch (error) {
-      this.logger.error("Failed to connect to Teneo network", error);
+      this.logger.error("Failed to connect to Teneo Protocol", error);
       throw error;
     }
   }
 
   /**
-   * Disconnects from the Teneo network and cleans up all active connections.
+   * Disconnects from the Teneo Protocol and cleans up all active connections.
    * Clears all timers, pending messages, and stops automatic reconnection attempts.
    * Emits 'disconnect' event after disconnection is complete.
    *
    * @example
    * ```typescript
    * sdk.disconnect();
-   * console.log('Disconnected from Teneo network');
+   * console.log('Disconnected from Teneo Protocol');
    * ```
    */
   public disconnect(): void {
-    this.logger.info("Disconnecting from Teneo network");
+    this.logger.info("Disconnecting from Teneo Protocol");
     this.connection.disconnect();
   }
 
@@ -298,19 +350,49 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
   }
 
   /**
-   * Subscribes to a specified room in the Teneo network.
-   * Agents in the room will be able to see and respond to your messages.
+   * Requests a quote for a task from the coordinator.
+   * The quote includes agent selection, pricing, and expiration.
+   * Does NOT auto-approve - use confirmQuote() to execute.
+   */
+  public async requestQuote(content: string, room: string): Promise<QuoteResult> {
+    return this.messages.requestQuote(content, room);
+  }
+
+  /**
+   * Confirms a pending quote and executes the task with payment.
+   * Attaches x402 payment header if payment client is configured.
+   */
+  public async confirmQuote(
+    taskId: string,
+    options?: { waitForResponse?: boolean; timeout?: number }
+  ): Promise<FormattedResponse | void> {
+    return this.messages.confirmQuote(taskId, options);
+  }
+
+  /**
+   * Gets a pending quote by task ID.
+   */
+  public getPendingQuote(taskId: string): QuoteResult | undefined {
+    return this.messages.getPendingQuote(taskId);
+  }
+
+  /**
+   * Subscribes to a public room in the Teneo Protocol.
+   * This is only needed for public rooms - private rooms are automatically subscribed.
    * Emits 'room:subscribed' event when successfully subscribed.
    *
-   * @param roomId - The ID of the room to subscribe to
+   * @param roomId - The ID of the public room to subscribe to
    * @returns Promise that resolves when the room has been subscribed
    * @throws {SDKError} If not connected to the network (ErrorCode.NOT_CONNECTED)
    * @throws {ValidationError} If roomId is empty or invalid
    *
    * @example
    * ```typescript
-   * await sdk.subscribeToRoom('general');
-   * console.log('Subscribed to general room');
+   * // Subscribe to a public room
+   * await sdk.subscribeToRoom('public-announcements');
+   * console.log('Subscribed to public room');
+   *
+   * // Note: Private rooms don't need subscription - you're always subscribed
    * ```
    */
   public async subscribeToRoom(roomId: string): Promise<void> {
@@ -318,19 +400,21 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
   }
 
   /**
-   * Unsubscribes from a specified room in the Teneo network.
-   * You will no longer receive messages from agents in this room.
+   * Unsubscribes from a public room in the Teneo Protocol.
+   * You will no longer receive messages from this public room.
    * Emits 'room:unsubscribed' event when successfully unsubscribed.
    *
-   * @param roomId - The ID of the room to unsubscribe from
+   * Note: This only applies to public rooms. Private rooms cannot be unsubscribed from.
+   *
+   * @param roomId - The ID of the public room to unsubscribe from
    * @returns Promise that resolves when the room has been unsubscribed
    * @throws {SDKError} If not connected to the network (ErrorCode.NOT_CONNECTED)
    * @throws {ValidationError} If roomId is empty or invalid
    *
    * @example
    * ```typescript
-   * await sdk.unsubscribeFromRoom('general');
-   * console.log('Unsubscribed from general room');
+   * await sdk.unsubscribeFromRoom('public-announcements');
+   * console.log('Unsubscribed from public room');
    * ```
    */
   public async unsubscribeFromRoom(roomId: string): Promise<void> {
@@ -376,7 +460,7 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
   }
 
   /**
-   * Gets a list of all available agents in the Teneo network.
+   * Gets a list of all available agents in the Teneo Protocol.
    * The list is automatically updated when new agents join or leave.
    * Returns a read-only array to prevent external modification.
    *
@@ -486,7 +570,84 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
   }
 
   /**
-   * Gets a list of all available rooms in the Teneo network.
+   * Fetches detailed information about a specific agent from the server.
+   * Makes a request to the server for full agent details including capabilities,
+   * commands, pricing, and more.
+   *
+   * @param agentId - The unique identifier of the agent
+   * @returns Promise that resolves with full agent details
+   * @throws {SDKError} If not connected or request times out
+   * @throws {ValidationError} If agentId is invalid
+   *
+   * @example
+   * ```typescript
+   * const details = await sdk.getAgentDetails('weather-agent-001');
+   * console.log(`Agent: ${details.agent_name}`);
+   * console.log(`Capabilities: ${details.capabilities?.length}`);
+   * console.log(`Status: ${details.status}`);
+   * ```
+   */
+  public async getAgentDetails(agentId: string): Promise<AgentRoomInfo> {
+    return this.agents.getAgentDetails(agentId);
+  }
+
+  // ============================================================================
+  // ADMIN API (Admin-Only Features)
+  // ============================================================================
+
+  /**
+   * Gets the admin manager for admin-only features.
+   * Returns undefined if the current user is not an admin.
+   * Use this to access admin APIs like listing all agents, user counts, etc.
+   *
+   * @returns The AdminManager instance if user is admin, undefined otherwise
+   *
+   * @example
+   * ```typescript
+   * if (sdk.admin?.isAdmin) {
+   *   // List all agents in the network
+   *   const result = await sdk.admin.listAllAgents({ limit: 20 });
+   *   console.log(`Found ${result.total} agents`);
+   *
+   *   result.agents.forEach(agent => {
+   *     console.log(`${agent.agent_name}: verified=${agent.is_verified}, banned=${agent.is_banned}`);
+   *   });
+   *
+   *   // Get user count
+   *   const userCount = sdk.admin.getLastUserCount();
+   *   console.log(`Online users: ${userCount?.count}`);
+   *
+   *   // Listen for user count updates
+   *   sdk.admin.on('user_count', (data) => {
+   *     console.log(`User count updated: ${data.count}`);
+   *   });
+   * }
+   * ```
+   */
+  public get admin(): AdminManager | undefined {
+    return this._admin.isAdmin ? this._admin : undefined;
+  }
+
+  /**
+   * Lists all agents in the network (admin only, convenience method).
+   * Returns paginated list of agents with full admin information.
+   *
+   * @param options - Pagination and filter options
+   * @returns Promise that resolves with agents list
+   * @throws {SDKError} If not connected or not an admin
+   *
+   * @example
+   * ```typescript
+   * const result = await sdk.listAllAgents({ limit: 50, filter: 'weather' });
+   * console.log(`Found ${result.total} agents matching 'weather'`);
+   * ```
+   */
+  public async listAllAgents(options: ListAllAgentsOptions = {}): Promise<AllAgentsResult> {
+    return this._admin.listAllAgents(options);
+  }
+
+  /**
+   * Gets a list of all available rooms in the Teneo Protocol.
    * Includes rooms you have access to based on your authentication.
    * Returns a read-only array to prevent external modification.
    *
@@ -501,7 +662,7 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
    * });
    * ```
    */
-  public getRooms(): ReadonlyArray<Room> {
+  public getRooms(): ReadonlyArray<RoomInfo> {
     return this.rooms.getRooms();
   }
 
@@ -523,10 +684,464 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
    * }
    * ```
    */
-  public getRoom(roomId: string): Room | undefined {
+  public getRoom(roomId: string): RoomInfo | undefined {
     return this.rooms.getRoom(roomId);
   }
 
+  // ============================================================================
+  // ROOM MANAGEMENT API (v2.0.0)
+  // ============================================================================
+
+  /**
+   * Creates a new private or public room.
+   * Checks room limit before creating (for private rooms).
+   * Emits 'room:created' event on success, 'room:create_error' on failure.
+   *
+   * @param options - Room creation options
+   * @param options.name - Room name (1-100 characters)
+   * @param options.description - Optional room description (max 500 characters)
+   * @param options.isPublic - Whether room is public (default: false)
+   * @returns Promise that resolves with created room info
+   * @throws {SDKError} If not connected, over limit, or validation fails
+   *
+   * @example
+   * ```typescript
+   * const room = await sdk.createRoom({
+   *   name: 'My Project Room',
+   *   description: 'Collaboration space for my project',
+   *   isPublic: false
+   * });
+   * console.log(`Created room: ${room.id}`);
+   * ```
+   */
+  public async createRoom(options: {
+    name: string;
+    description?: string;
+    isPublic?: boolean;
+  }): Promise<RoomInfo> {
+    return this.roomManagement.createRoom(options);
+  }
+
+  /**
+   * Updates an existing room's name and/or description.
+   * User must own the room to update it.
+   * Emits 'room:updated' event on success, 'room:update_error' on failure.
+   *
+   * @param roomId - ID of room to update
+   * @param updates - Fields to update
+   * @param updates.name - New room name (1-100 characters)
+   * @param updates.description - New room description (max 500 characters)
+   * @returns Promise that resolves with updated room info
+   * @throws {SDKError} If not connected, not owner, or validation fails
+   *
+   * @example
+   * ```typescript
+   * const room = await sdk.updateRoom('room-123', {
+   *   name: 'Updated Room Name',
+   *   description: 'New description'
+   * });
+   * ```
+   */
+  public async updateRoom(
+    roomId: string,
+    updates: { name?: string; description?: string }
+  ): Promise<RoomInfo> {
+    return this.roomManagement.updateRoom(roomId, updates);
+  }
+
+  /**
+   * Deletes a room permanently.
+   * User must own the room to delete it.
+   * Emits 'room:deleted' event on success, 'room:delete_error' on failure.
+   *
+   * @param roomId - ID of room to delete
+   * @returns Promise that resolves when room is deleted
+   * @throws {SDKError} If not connected or not owner
+   *
+   * @example
+   * ```typescript
+   * await sdk.deleteRoom('room-123');
+   * console.log('Room deleted successfully');
+   * ```
+   */
+  public async deleteRoom(roomId: string): Promise<void> {
+    return this.roomManagement.deleteRoom(roomId);
+  }
+
+  /**
+   * Gets all rooms owned by the current user.
+   * Synchronous method that returns cached data from authentication.
+   *
+   * @returns Array of owned room info
+   *
+   * @example
+   * ```typescript
+   * const myRooms = sdk.getOwnedRooms();
+   * console.log(`I own ${myRooms.length} rooms`);
+   * myRooms.forEach(room => {
+   *   console.log(`- ${room.name} (${room.id})`);
+   * });
+   * ```
+   */
+  public getOwnedRooms(): ReadonlyArray<Readonly<RoomInfo>> {
+    return this.roomManagement.getOwnedRooms();
+  }
+
+  /**
+   * Gets all rooms the user is a member of (but doesn't own).
+   * Synchronous method that returns cached data from authentication.
+   *
+   * @returns Array of shared room info
+   *
+   * @example
+   * ```typescript
+   * const sharedRooms = sdk.getSharedRooms();
+   * console.log(`I'm a member of ${sharedRooms.length} shared rooms`);
+   * ```
+   */
+  public getSharedRooms(): ReadonlyArray<Readonly<RoomInfo>> {
+    return this.roomManagement.getSharedRooms();
+  }
+
+  /**
+   * Gets all rooms the user has access to (both owned and shared).
+   * Convenience method that combines getOwnedRooms() and getSharedRooms().
+   * Synchronous method that returns cached data from authentication.
+   *
+   * @returns Array of all room info (owned + shared)
+   *
+   * @example
+   * ```typescript
+   * const allRooms = sdk.getAllRooms();
+   * console.log(`I have access to ${allRooms.length} total rooms`);
+   *
+   * // You can filter by ownership if needed
+   * const myRooms = allRooms.filter(r => r.is_owner);
+   * const sharedWithMe = allRooms.filter(r => !r.is_owner);
+   * ```
+   */
+  public getAllRooms(): ReadonlyArray<Readonly<RoomInfo>> {
+    return this.roomManagement.getAllRooms();
+  }
+
+  /**
+   * Gets the maximum number of private rooms the user can create.
+   * Based on user's subscription/plan.
+   *
+   * @returns Maximum private room limit
+   *
+   * @example
+   * ```typescript
+   * const limit = sdk.getRoomLimit();
+   * const current = sdk.getOwnedRoomCount();
+   * console.log(`Using ${current}/${limit} room slots`);
+   * ```
+   */
+  public getRoomLimit(): number {
+    return this.roomManagement.getRoomLimit();
+  }
+
+  /**
+   * Gets the current count of owned private rooms.
+   *
+   * @returns Number of rooms user owns
+   *
+   * @example
+   * ```typescript
+   * const count = sdk.getOwnedRoomCount();
+   * if (sdk.canCreateRoom()) {
+   *   console.log(`Can create ${sdk.getRoomLimit() - count} more rooms`);
+   * }
+   * ```
+   */
+  public getOwnedRoomCount(): number {
+    return this.roomManagement.getOwnedRoomCount();
+  }
+
+  /**
+   * Checks if user can create another private room.
+   * Compares current owned room count against limit.
+   *
+   * @returns True if under limit, false otherwise
+   *
+   * @example
+   * ```typescript
+   * if (sdk.canCreateRoom()) {
+   *   await sdk.createRoom({ name: 'New Room' });
+   * } else {
+   *   console.log('Room limit reached! Upgrade your plan.');
+   * }
+   * ```
+   */
+  public canCreateRoom(): boolean {
+    return this.roomManagement.canCreateRoom();
+  }
+
+  // ============================================================================
+  // AGENT ROOM MANAGEMENT API (v2.0.0)
+  // ============================================================================
+
+  /**
+   * Adds an agent to a room. Only room owners can add agents.
+   * Emits 'agent_room:agent_added' on success, 'agent_room:add_error' on failure.
+   *
+   * @param roomId - ID of the room to add the agent to
+   * @param agentId - ID of the agent to add
+   * @returns Promise that resolves when agent is added
+   * @throws {SDKError} If not connected, not owner, or agent already in room
+   *
+   * @example
+   * ```typescript
+   * await sdk.addAgentToRoom('room-123', 'weather-agent');
+   * console.log('Agent added to room');
+   * ```
+   */
+  public async addAgentToRoom(roomId: string, agentId: string): Promise<void> {
+    return this.agentRoom.addAgentToRoom(roomId, agentId);
+  }
+
+  /**
+   * Removes an agent from a room. Only room owners can remove agents.
+   * Emits 'agent_room:agent_removed' on success, 'agent_room:remove_error' on failure.
+   *
+   * @param roomId - ID of the room to remove the agent from
+   * @param agentId - ID of the agent to remove
+   * @returns Promise that resolves when agent is removed
+   * @throws {SDKError} If not connected, not owner, or agent not in room
+   *
+   * @example
+   * ```typescript
+   * await sdk.removeAgentFromRoom('room-123', 'weather-agent');
+   * console.log('Agent removed from room');
+   * ```
+   */
+  public async removeAgentFromRoom(roomId: string, agentId: string): Promise<void> {
+    return this.agentRoom.removeAgentFromRoom(roomId, agentId);
+  }
+
+  /**
+   * Lists all agents in a room.
+   * Results are cached for 5 minutes for performance.
+   * Emits 'agent_room:agents_listed' when list is received.
+   *
+   * @param roomId - ID of the room to list agents for
+   * @param useCache - Whether to use cached data if available (default: true)
+   * @returns Promise that resolves to array of agents in the room
+   * @throws {SDKError} If not connected
+   *
+   * @example
+   * ```typescript
+   * const agents = await sdk.listRoomAgents('room-123');
+   * console.log(`Room has ${agents.length} agents`);
+   * agents.forEach(agent => {
+   *   console.log(`- ${agent.agent_name} (${agent.status})`);
+   * });
+   * ```
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  public async listRoomAgents(roomId: string, useCache: boolean = true): Promise<any[]> {
+    return this.agentRoom.listRoomAgents(roomId, useCache);
+  }
+
+  /**
+   * Lists all agents available to be added to a room.
+   * Shows agents not currently in the room.
+   * Results are cached for 5 minutes for performance.
+   * Emits 'agent_room:available_agents_listed' when list is received.
+   *
+   * @param roomId - ID of the room to check available agents for
+   * @param useCache - Whether to use cached data if available (default: true)
+   * @returns Promise that resolves to array of available agents
+   * @throws {SDKError} If not connected
+   *
+   * @example
+   * ```typescript
+   * const available = await sdk.listAvailableAgents('room-123');
+   * console.log(`${available.length} agents available to add`);
+   * ```
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  public async listAvailableAgents(roomId: string, useCache: boolean = true): Promise<any[]> {
+    return this.agentRoom.listAvailableAgents(roomId, useCache);
+  }
+
+  /**
+   * Gets agents in a room from cache (synchronous).
+   * Returns undefined if not cached. Use listRoomAgents() to fetch.
+   *
+   * @param roomId - ID of the room
+   * @returns Array of agents if cached, undefined otherwise
+   *
+   * @example
+   * ```typescript
+   * const agents = sdk.getRoomAgents('room-123');
+   * if (agents) {
+   *   console.log(`${agents.length} agents (cached)`);
+   * } else {
+   *   await sdk.listRoomAgents('room-123'); // Fetch from server
+   * }
+   * ```
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  public getRoomAgents(roomId: string): any[] | undefined {
+    return this.agentRoom.getRoomAgents(roomId);
+  }
+
+  /**
+   * Gets available agents for a room from cache (synchronous).
+   * Returns undefined if not cached. Use listAvailableAgents() to fetch.
+   *
+   * @param roomId - ID of the room
+   * @returns Array of available agents if cached, undefined otherwise
+   *
+   * @example
+   * ```typescript
+   * const available = sdk.getAvailableAgents('room-123');
+   * if (available) {
+   *   console.log(`${available.length} agents available (cached)`);
+   * }
+   * ```
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  public getAvailableAgents(roomId: string): any[] | undefined {
+    return this.agentRoom.getAvailableAgents(roomId);
+  }
+
+  /**
+   * Checks if an agent is in a room (synchronous, from cache).
+   * Returns undefined if room data not cached.
+   *
+   * @param roomId - ID of the room
+   * @param agentId - ID of the agent
+   * @returns True if agent is in room, false if not, undefined if not cached
+   *
+   * @example
+   * ```typescript
+   * const inRoom = sdk.isAgentInRoom('room-123', 'weather-agent');
+   * if (inRoom === true) {
+   *   console.log('Agent is in room');
+   * } else if (inRoom === false) {
+   *   console.log('Agent is not in room');
+   * } else {
+   *   console.log('Room data not cached');
+   * }
+   * ```
+   */
+  public isAgentInRoom(roomId: string, agentId: string): boolean | undefined {
+    return this.agentRoom.isAgentInRoom(roomId, agentId);
+  }
+
+  /**
+   * Gets the count of agents in a room (synchronous, from cache).
+   * Returns undefined if room data not cached.
+   *
+   * @param roomId - ID of the room
+   * @returns Number of agents in room, or undefined if not cached
+   *
+   * @example
+   * ```typescript
+   * const count = sdk.getRoomAgentCount('room-123');
+   * if (count !== undefined) {
+   *   console.log(`Room has ${count} agents`);
+   * }
+   * ```
+   */
+  public getRoomAgentCount(roomId: string): number | undefined {
+    return this.agentRoom.getRoomAgentCount(roomId);
+  }
+
+  /**
+   * Invalidates the agent-room cache for a specific room.
+   * Forces the next listRoomAgents() or listAvailableAgents() call to fetch fresh data.
+   * Useful after bulk operations or when you know the cache is stale.
+   *
+   * @param roomId - ID of the room to invalidate cache for
+   *
+   * @example
+   * ```typescript
+   * // After adding/removing agents
+   * await sdk.addAgentToRoom('room-123', 'agent-456');
+   * sdk.invalidateAgentRoomCache('room-123');
+   * const freshAgents = await sdk.listRoomAgents('room-123');
+   * ```
+   */
+  public invalidateAgentRoomCache(roomId: string): void {
+    this.agentRoom.invalidateCache(roomId);
+  }
+
+  /**
+   * Updates user preferences on the server.
+   * Server-side enforcement of max price per request - prevents quotes/payments exceeding the limit.
+   *
+   * @param preferences - User preferences to update
+   * @param preferences.maxPricePerRequest - Max price per request in USDC (e.g., 0.01 = $0.01), or null to remove limit
+   * @returns Promise that resolves when preferences are updated
+   * @throws {SDKError} If update fails or times out
+   *
+   * @example
+   * ```typescript
+   * // Set a spending limit of $0.05 per request
+   * await sdk.setUserPreferences({ maxPricePerRequest: 0.05 });
+   *
+   * // Remove the spending limit
+   * await sdk.setUserPreferences({ maxPricePerRequest: null });
+   * ```
+   */
+  public async setUserPreferences(preferences: {
+    maxPricePerRequest?: number | null;
+  }): Promise<void> {
+    if (this.isDestroyed) {
+      throw new SDKError("SDK has been destroyed", ErrorCode.SDK_DESTROYED, null, false);
+    }
+
+    const message = {
+      type: "set_user_preferences" as const,
+      data: {
+        max_price_per_request: preferences.maxPricePerRequest
+      }
+    };
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        cleanup();
+        reject(new SDKError("Set user preferences request timed out", ErrorCode.TIMEOUT_ERROR));
+      }, 30000);
+
+      const handleResponse = (msg: {
+        type: string;
+        data?: { success?: boolean; message?: string; max_price_per_request?: number | null };
+      }) => {
+        if (msg.type === "user_preferences_updated") {
+          cleanup();
+          if (msg.data?.success) {
+            this.emit("preferences:updated", {
+              maxPricePerRequest: msg.data.max_price_per_request
+            });
+            resolve();
+          } else {
+            reject(
+              new SDKError(
+                msg.data?.message || "Failed to update preferences",
+                ErrorCode.MESSAGE_ERROR
+              )
+            );
+          }
+        }
+      };
+
+      const cleanup = () => {
+        clearTimeout(timeout);
+        this.wsClient.off("message:received", handleResponse);
+      };
+
+      this.wsClient.on("message:received", handleResponse);
+      this.wsClient.sendMessage(message).catch((error) => {
+        cleanup();
+        reject(error);
+      });
+    });
+  }
+
   /**
    * Configures webhook URL and headers for receiving real-time event notifications.
    * Webhooks allow you to receive events at your server endpoint via HTTP POST requests.
@@ -616,7 +1231,7 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
    * This is a convenience getter that returns only the connection status.
    * For detailed state information, use getConnectionState().
    *
-   * @returns True if connected to the Teneo network, false otherwise
+   * @returns True if connected to the Teneo Protocol, false otherwise
    *
    * @example
    * ```typescript
@@ -637,7 +1252,7 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
    * This is a convenience getter that returns only the authentication status.
    * For detailed auth information, use getAuthState().
    *
-   * @returns True if authenticated with the Teneo network, false otherwise
+   * @returns True if authenticated with the Teneo Protocol, false otherwise
    *
    * @example
    * ```typescript
@@ -922,6 +1537,7 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
     this.rooms.destroy();
     this.agents.destroy();
     this.messages.destroy();
+    this._admin.destroy();
 
     // Destroy other components
     this.webhookHandler.destroy();
@@ -951,7 +1567,9 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
     this.connection.on("auth:success", (state) => {
       this.logger.debug("Received auth:success event in SDK", {
         authenticated: state?.authenticated,
-        hasRooms: !!state?.roomObjects
+        hasRooms: !!state?.roomObjects,
+        ownedRooms: state?.privateRoomIds?.length || 0,
+        sharedRooms: state?.sharedRoomIds?.length || 0
       });
 
       // Update rooms from auth state
@@ -959,6 +1577,23 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
         this.rooms.updateRoomsFromAuth(state.roomObjects);
       }
 
+      // Ensure RoomManagementManager is synced with auth state
+      if (state.roomObjects && state.roomObjects.length > 0) {
+        const ownedRooms = state.roomObjects.filter((r) => r.is_owner);
+        const sharedRooms = state.roomObjects.filter((r) => !r.is_owner);
+        this.roomManagement.setOwnedRooms(ownedRooms);
+        this.roomManagement.setSharedRooms(sharedRooms);
+
+        if (state.maxPrivateRooms) {
+          this.roomManagement.setRoomLimit(state.maxPrivateRooms);
+        }
+      }
+
+      // Set up payment client for x402 payments
+      if (this.secureKey && state.walletAddress) {
+        this.messages.setPaymentClient(this.secureKey, state.walletAddress);
+      }
+
       this.emit("auth:success", state);
     });
     this.connection.on("auth:error", (error) => this.emit("auth:error", error));
@@ -975,6 +1610,12 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
     this.messages.on("agent:selected", (data) => this.emit("agent:selected", data));
     this.messages.on("agent:response", (response) => this.emit("agent:response", response));
 
+    // Forward quote and payment events from MessageRouter (v2.2.0)
+    this.messages.on("quote:received", (quote) => this.emit("quote:received", quote));
+    this.messages.on("payment:blocked", (data) => this.emit("payment:blocked", data));
+    this.messages.on("payment:attached", (data) => this.emit("payment:attached", data));
+    this.messages.on("payment:error", (error) => this.emit("payment:error", error));
+
     // Forward coordinator events from MessageRouter
     this.messages.on("coordinator:processing", (request) =>
       this.emit("coordinator:processing", request)
@@ -993,6 +1634,126 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
     this.wsClient.on("room:subscribed", (data) => this.emit("room:subscribed", data));
     this.wsClient.on("room:unsubscribed", (data) => this.emit("room:unsubscribed", data));
 
+    // Forward room management events from WebSocketClient (emitted by handlers) (v2.0.0)
+    // These events are emitted by message handlers, so we listen on wsClient
+    // We forward to RoomManagementManager first (for promise resolution), then emit on SDK
+    this.wsClient.on("room:created", (room) => {
+      // Update RoomManagementManager cache
+      this.roomManagement.upsertRoom(room);
+      // Emit on RoomManagementManager for promise resolution (see createRoom method)
+      this.roomManagement.emit("room:created", room);
+      // Emit on SDK for external listeners
+      this.emit("room:created", room);
+    });
+    this.wsClient.on("room:updated", (room) => {
+      // Update RoomManagementManager cache
+      this.roomManagement.upsertRoom(room);
+      // Emit on RoomManagementManager for promise resolution (see updateRoom method)
+      this.roomManagement.emit("room:updated", room);
+      // Emit on SDK for external listeners
+      this.emit("room:updated", room);
+    });
+    this.wsClient.on("room:deleted", (roomId) => {
+      // Remove from RoomManagementManager cache
+      this.roomManagement.removeRoom(roomId);
+      // Emit on RoomManagementManager for promise resolution (see deleteRoom method)
+      this.roomManagement.emit("room:deleted", roomId);
+      // Emit on SDK for external listeners
+      this.emit("room:deleted", roomId);
+    });
+    this.wsClient.on("room:create_error", (error) => {
+      // Emit on RoomManagementManager for promise rejection
+      this.roomManagement.emit("room:create_error", error);
+      // Emit on SDK for external listeners
+      this.emit("room:create_error", error);
+    });
+    this.wsClient.on("room:update_error", (error, roomId) => {
+      // Emit on RoomManagementManager for promise rejection
+      this.roomManagement.emit("room:update_error", error, roomId);
+      // Emit on SDK for external listeners
+      this.emit("room:update_error", error, roomId);
+    });
+    this.wsClient.on("room:delete_error", (error, roomId) => {
+      // Emit on RoomManagementManager for promise rejection
+      this.roomManagement.emit("room:delete_error", error, roomId);
+      // Emit on SDK for external listeners
+      this.emit("room:delete_error", error, roomId);
+    });
+
+    // Forward agent room management events from WebSocketClient (emitted by handlers) (v2.0.0)
+    // These events are emitted by message handlers, so we listen on wsClient
+    // We forward to AgentRoomManager first (for promise resolution), then emit on SDK
+    this.wsClient.on("agent_room:agent_added", (roomId, agentId) => {
+      // Emit on AgentRoomManager for promise resolution (see addAgentToRoom method)
+      this.agentRoom.emit("agent_room:agent_added", roomId, agentId);
+      // Emit on SDK for external listeners
+      this.emit("agent_room:agent_added", roomId, agentId);
+    });
+    this.wsClient.on("agent_room:agent_removed", (roomId, agentId) => {
+      // Emit on AgentRoomManager for promise resolution (see removeAgentFromRoom method)
+      this.agentRoom.emit("agent_room:agent_removed", roomId, agentId);
+      // Emit on SDK for external listeners
+      this.emit("agent_room:agent_removed", roomId, agentId);
+    });
+    this.wsClient.on("agent_room:agents_listed", (roomId, agents) => {
+      // Emit on AgentRoomManager for promise resolution
+      this.agentRoom.emit("agent_room:agents_listed", roomId, agents);
+      // Emit on SDK for external listeners
+      this.emit("agent_room:agents_listed", roomId, agents);
+    });
+    this.wsClient.on("agent_room:available_agents_listed", (agents) => {
+      // Emit on AgentRoomManager for promise resolution
+      this.agentRoom.emit("agent_room:available_agents_listed", agents);
+      // Emit on SDK for external listeners
+      this.emit("agent_room:available_agents_listed", agents);
+    });
+    this.wsClient.on("agent_room:status_update", (data) => {
+      // Emit on SDK for external listeners
+      this.emit("agent_room:status_update", data);
+    });
+    this.wsClient.on("agent_room:add_error", (error, roomId) => {
+      // Emit on AgentRoomManager for promise rejection
+      this.agentRoom.emit("agent_room:add_error", error, roomId);
+      // Emit on SDK for external listeners
+      this.emit("agent_room:add_error", error, roomId);
+    });
+    this.wsClient.on("agent_room:remove_error", (error, roomId) => {
+      // Emit on AgentRoomManager for promise rejection
+      this.agentRoom.emit("agent_room:remove_error", error, roomId);
+      // Emit on SDK for external listeners
+      this.emit("agent_room:remove_error", error, roomId);
+    });
+    this.wsClient.on("agent_room:list_error", (error, roomId) => {
+      // Emit on AgentRoomManager for promise rejection
+      this.agentRoom.emit("agent_room:list_error", error, roomId);
+      // Emit on SDK for external listeners
+      this.emit("agent_room:list_error", error, roomId);
+    });
+    this.wsClient.on("agent_room:list_available_error", (error) => {
+      // Emit on AgentRoomManager for promise rejection
+      this.agentRoom.emit("agent_room:list_available_error", error);
+      // Emit on SDK for external listeners
+      this.emit("agent_room:list_available_error", error);
+    });
+
+    // Forward admin events from AdminManager
+    this._admin.on("user_count", (data) => {
+      this.emit("admin:user_count", data);
+    });
+    this._admin.on("status_changed", (isAdmin) => {
+      this.emit("admin:status_changed", isAdmin);
+    });
+
+    // Forward rate limit notifications from WebSocketClient (emitted by handlers)
+    this.wsClient.on("rate_limit", (notification) => {
+      this.emit("rate_limit", notification);
+    });
+
+    // Forward user authenticated events from WebSocketClient (emitted by handlers)
+    this.wsClient.on("user:authenticated", (data) => {
+      this.emit("user:authenticated", data);
+    });
+
     // Forward webhook events from WebhookHandler
     this.webhookHandler.on("webhook:sent", (payload, url) =>
       this.emit("webhook:sent", payload, url)
@@ -1009,8 +1770,13 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
     this.connection.on("error", (error) => {
       this.emit("error", error);
       // Fire and forget - don't block event emission
+      // Defensive check: ensure error has toJSON method (SDKError instances do)
+      const errorPayload =
+        typeof error.toJSON === "function"
+          ? error.toJSON()
+          : { message: error.message, name: error.name, code: error.code };
       this.webhookHandler
-        .sendWebhook("error", error, { code: error.code })
+        .sendWebhook("error", errorPayload, { code: error.code })
         .catch((webhookError) => {
           this.logger.error("Failed to send webhook for error event", webhookError);
         });
@@ -1028,6 +1794,16 @@ export class TeneoSDK extends EventEmitter<SDKEvents> {
     return createPinoLogger(this.config.logLevel ?? "info", "TeneoSDK");
   }
 
+  /**
+   * Derive wallet address from private key
+   */
+  private deriveWalletAddress(privateKey: string | SecurePrivateKey): string {
+    if (privateKey instanceof SecurePrivateKey) {
+      return privateKey.use((key) => privateKeyToAccount(key as `0x${string}`).address);
+    }
+    return privateKeyToAccount(privateKey as `0x${string}`).address;
+  }
+
   /**
    * Creates a new SDK configuration builder for fluent configuration.
    * The builder pattern provides a more intuitive way to configure the SDK