@teneo-protocol/sdk 2.0.0 → 2.2.0

package/src/managers/agent-registry.ts

@@ -4,26 +4,52 @@
  */
 
 import { EventEmitter } from "eventemitter3";
-import { Agent, Logger } from "../types";
-import { SDKEvents } from "../types/events";
+import { Agent, AgentCategory, Logger, AgentRoomInfo } from "../types";
+import { SDKEvents, SDKError } from "../types/events";
+import { ErrorCode } from "../types/error-codes";
 import { AgentIdSchema, SearchQuerySchema } from "../types/validation";
+import { WebSocketClient } from "../core/websocket-client";
+
+/**
+ * Pending request for agent details with promise sharing for concurrent requests
+ */
+interface PendingDetailsRequest {
+  promise: Promise<AgentRoomInfo>;
+  resolve: (agent: AgentRoomInfo) => void;
+  reject: (error: Error) => void;
+  timeout: ReturnType<typeof setTimeout>;
+}
 
 export class AgentRegistry extends EventEmitter<SDKEvents> {
   private readonly logger: Logger;
   private readonly agents = new Map<string, Agent>();
   private cachedAgents?: Readonly<Agent>[];
   private isAgentsCacheDirty = true;
+  private wsClient?: WebSocketClient;
 
   // PERF-3: Search indices for O(1) lookups
   private capabilityIndex = new Map<string, Set<string>>();
   private nameTokenIndex = new Map<string, Set<string>>();
   private statusIndex = new Map<string, Set<string>>();
+  private categoryIndex = new Map<AgentCategory, Set<string>>();
+
+  // Pending agent details requests
+  private readonly pendingDetailsRequests = new Map<string, PendingDetailsRequest>();
+  private readonly detailsTimeout = 30000; // 30 seconds
 
   constructor(logger: Logger) {
     super();
     this.logger = logger;
   }
 
+  /**
+   * Sets the WebSocket client for making requests.
+   * @internal
+   */
+  public setWebSocketClient(wsClient: WebSocketClient): void {
+    this.wsClient = wsClient;
+  }
+
   /**
    * Gets a cached list of all available agents in the network.
    * Uses lazy caching with dirty flag for optimal performance.
@@ -200,6 +226,39 @@ export class AgentRegistry extends EventEmitter<SDKEvents> {
       .map((agent) => ({ ...agent }));
   }
 
+  /**
+   * Finds all agents that have a specific category.
+   * Uses O(1) category index lookup instead of O(n) filtering.
+   *
+   * @param category - The category to search for
+   * @returns Read-only array of agents with the specified category
+   *
+   * @example
+   * ```typescript
+   * const tradingAgents = agentRegistry.findByCategory('Trading');
+   * console.log(`Found ${tradingAgents.length} trading agents`);
+   * ```
+   */
+  public findByCategory(category: AgentCategory): ReadonlyArray<Agent> {
+    // Ensure cache is up to date
+    if (this.isAgentsCacheDirty || !this.cachedAgents) {
+      this.rebuildCache();
+    }
+
+    // O(1) index lookup
+    const agentIds = this.categoryIndex.get(category);
+
+    if (!agentIds || agentIds.size === 0) {
+      return [];
+    }
+
+    // Map agent IDs to agent objects with defensive copies
+    return Array.from(agentIds)
+      .map((id) => this.agents.get(id))
+      .filter((agent): agent is Agent => agent !== undefined)
+      .map((agent) => ({ ...agent }));
+  }
+
   /**
    * Updates the registry with a new list of agents.
    * Merges with existing agents and marks cache as dirty.
@@ -244,6 +303,97 @@ export class AgentRegistry extends EventEmitter<SDKEvents> {
     this.isAgentsCacheDirty = true;
   }
 
+  /**
+   * 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.
+   *
+   * Multiple concurrent calls for the same agent will share the same request,
+   * avoiding redundant server calls and preventing race conditions.
+   *
+   * @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 agentRegistry.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> {
+    if (!this.wsClient || !this.wsClient.isConnected) {
+      throw new SDKError("Not connected to Teneo Protocol", ErrorCode.NOT_CONNECTED);
+    }
+
+    // Validate agent ID
+    const validatedAgentId = AgentIdSchema.parse(agentId);
+
+    // Check if there's already a pending request for this agent - reuse it
+    const existingRequest = this.pendingDetailsRequests.get(validatedAgentId);
+    if (existingRequest) {
+      this.logger.debug("AgentRegistry: Reusing pending request for agent details", {
+        agentId: validatedAgentId
+      });
+      return existingRequest.promise;
+    }
+
+    this.logger.info("AgentRegistry: Requesting agent details", { agentId: validatedAgentId });
+
+    // Send get_agent_details message
+    const message = {
+      type: "get_agent_details" as const,
+      agent_id: validatedAgentId
+    };
+
+    await this.wsClient.sendMessage(message);
+
+    // Create promise with stored resolve/reject for later resolution
+    let resolvePromise: (agent: AgentRoomInfo) => void;
+    let rejectPromise: (error: Error) => void;
+
+    const promise = new Promise<AgentRoomInfo>((resolve, reject) => {
+      resolvePromise = resolve;
+      rejectPromise = reject;
+    });
+
+    const timeout = setTimeout(() => {
+      this.pendingDetailsRequests.delete(validatedAgentId);
+      rejectPromise!(new SDKError("Agent details request timed out", ErrorCode.TIMEOUT_ERROR));
+    }, this.detailsTimeout);
+
+    this.pendingDetailsRequests.set(validatedAgentId, {
+      promise,
+      resolve: resolvePromise!,
+      reject: rejectPromise!,
+      timeout
+    });
+
+    return promise;
+  }
+
+  /**
+   * Handles incoming agent_details_response from server.
+   * @internal
+   */
+  public handleAgentDetails(agent: AgentRoomInfo): void {
+    this.logger.debug("AgentRegistry: Received agent details", {
+      agentId: agent.agent_id,
+      agentName: agent.agent_name
+    });
+
+    // Resolve pending request
+    const pending = this.pendingDetailsRequests.get(agent.agent_id);
+    if (pending) {
+      clearTimeout(pending.timeout);
+      this.pendingDetailsRequests.delete(agent.agent_id);
+      pending.resolve(agent);
+    }
+  }
+
   /**
    * Clears all agents from the registry.
    * Removes all cached agents and marks cache as dirty.
@@ -257,6 +407,13 @@ export class AgentRegistry extends EventEmitter<SDKEvents> {
   public clear(): void {
     this.agents.clear();
     this.isAgentsCacheDirty = true;
+
+    // Clear pending requests
+    for (const [, pending] of this.pendingDetailsRequests) {
+      clearTimeout(pending.timeout);
+      pending.reject(new SDKError("Agent registry cleared", ErrorCode.SDK_DESTROYED));
+    }
+    this.pendingDetailsRequests.clear();
   }
 
   /**
@@ -291,6 +448,7 @@ export class AgentRegistry extends EventEmitter<SDKEvents> {
     this.capabilityIndex.clear();
     this.nameTokenIndex.clear();
     this.statusIndex.clear();
+    this.categoryIndex.clear();
 
     // Populate indices
     for (const agent of this.agents.values()) {
@@ -320,6 +478,16 @@ export class AgentRegistry extends EventEmitter<SDKEvents> {
         this.statusIndex.set(status, new Set());
       }
       this.statusIndex.get(status)!.add(agent.id);
+
+      // Index categories
+      if (agent.categories) {
+        for (const category of agent.categories) {
+          if (!this.categoryIndex.has(category)) {
+            this.categoryIndex.set(category, new Set());
+          }
+          this.categoryIndex.get(category)!.add(agent.id);
+        }
+      }
     }
 
     this.isAgentsCacheDirty = false;

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

@@ -1,7 +1,7 @@
 /**
  * AgentRoomManager - Manages agent-room associations (v2.0.0)
  * Allows room owners to control which agents are available in their rooms
- * Implements caching with 5-minute TTL for performance
+ * Implements caching with 5-minute TTL and LRU eviction for performance
  */
 
 import { EventEmitter } from "eventemitter3";
@@ -27,16 +27,96 @@ export interface AgentRoomInfo {
 // Cache TTL: 5 minutes
 const CACHE_TTL_MS = 5 * 60 * 1000;
 
+// Maximum number of rooms to cache (LRU eviction beyond this)
+const MAX_CACHED_ROOMS = 1000;
+
+/**
+ * Simple LRU cache with TTL support
+ * Uses Map's insertion order for LRU tracking
+ */
+class LRUCache<T> {
+  private readonly cache = new Map<string, T>();
+  private readonly timestamps = new Map<string, number>();
+  private readonly maxSize: number;
+  private readonly ttlMs: number;
+
+  constructor(maxSize: number, ttlMs: number) {
+    this.maxSize = maxSize;
+    this.ttlMs = ttlMs;
+  }
+
+  get(key: string): T | undefined {
+    const value = this.cache.get(key);
+    if (value === undefined) return undefined;
+
+    // Check TTL
+    const timestamp = this.timestamps.get(key);
+    if (timestamp && Date.now() - timestamp >= this.ttlMs) {
+      this.delete(key);
+      return undefined;
+    }
+
+    // Move to end (most recently used) by re-inserting
+    this.cache.delete(key);
+    this.cache.set(key, value);
+
+    return value;
+  }
+
+  set(key: string, value: T): void {
+    // Delete first to update insertion order
+    this.cache.delete(key);
+    this.timestamps.delete(key);
+
+    // Evict oldest entries if at capacity
+    while (this.cache.size >= this.maxSize) {
+      const oldestKey = this.cache.keys().next().value;
+      if (oldestKey !== undefined) {
+        this.cache.delete(oldestKey);
+        this.timestamps.delete(oldestKey);
+      }
+    }
+
+    this.cache.set(key, value);
+    this.timestamps.set(key, Date.now());
+  }
+
+  delete(key: string): void {
+    this.cache.delete(key);
+    this.timestamps.delete(key);
+  }
+
+  has(key: string): boolean {
+    return this.get(key) !== undefined;
+  }
+
+  isValid(key: string): boolean {
+    const timestamp = this.timestamps.get(key);
+    if (!timestamp) return false;
+    return Date.now() - timestamp < this.ttlMs;
+  }
+
+  clear(): void {
+    this.cache.clear();
+    this.timestamps.clear();
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+}
+
 export class AgentRoomManager extends EventEmitter<SDKEvents> {
   private readonly wsClient: WebSocketClient;
   private readonly logger: Logger;
   private readonly roomManagementManager: RoomManagementManager; // Reference to check ownership
 
-  // Caches with TTL
-  private readonly roomAgentsCache = new Map<string, AgentRoomInfo[]>();
-  private readonly availableAgentsCache = new Map<string, AgentRoomInfo[]>();
-  private readonly roomAgentsCacheTime = new Map<string, number>();
-  private readonly availableAgentsCacheTime = new Map<string, number>();
+  // LRU caches with TTL (max 1000 rooms each)
+  private readonly roomAgentsCache = new LRUCache<AgentRoomInfo[]>(MAX_CACHED_ROOMS, CACHE_TTL_MS);
+  private readonly availableAgentsCache = new LRUCache<AgentRoomInfo[]>(
+    MAX_CACHED_ROOMS,
+    CACHE_TTL_MS
+  );
 
   constructor(
     wsClient: WebSocketClient,
@@ -70,7 +150,7 @@ export class AgentRoomManager extends EventEmitter<SDKEvents> {
    */
   public async addAgentToRoom(roomId: string, agentId: string): Promise<void> {
     if (!this.wsClient.isConnected) {
-      throw new SDKError("Not connected to Teneo network", ErrorCode.NOT_CONNECTED);
+      throw new SDKError("Not connected to Teneo Protocol", ErrorCode.NOT_CONNECTED);
     }
 
     // Validate inputs
@@ -152,7 +232,7 @@ export class AgentRoomManager extends EventEmitter<SDKEvents> {
    */
   public async removeAgentFromRoom(roomId: string, agentId: string): Promise<void> {
     if (!this.wsClient.isConnected) {
-      throw new SDKError("Not connected to Teneo network", ErrorCode.NOT_CONNECTED);
+      throw new SDKError("Not connected to Teneo Protocol", ErrorCode.NOT_CONNECTED);
     }
 
     // Validate inputs
@@ -230,19 +310,16 @@ export class AgentRoomManager extends EventEmitter<SDKEvents> {
    * const freshAgents = await sdk.listRoomAgents('room-123', false);
    * ```
    */
-  public async listRoomAgents(
-    roomId: string,
-    useCache: boolean = true
-  ): Promise<AgentRoomInfo[]> {
+  public async listRoomAgents(roomId: string, useCache: boolean = true): Promise<AgentRoomInfo[]> {
     if (!this.wsClient.isConnected) {
-      throw new SDKError("Not connected to Teneo network", ErrorCode.NOT_CONNECTED);
+      throw new SDKError("Not connected to Teneo Protocol", ErrorCode.NOT_CONNECTED);
     }
 
     // Validate input
     this.validateRoomId(roomId);
 
     // Check cache if enabled
-    if (useCache && this.isCacheValid(this.roomAgentsCacheTime, roomId)) {
+    if (useCache) {
       const cached = this.roomAgentsCache.get(roomId);
       if (cached) {
         this.logger.debug("AgentRoomManager: Returning cached room agents", {
@@ -315,14 +392,14 @@ export class AgentRoomManager extends EventEmitter<SDKEvents> {
     useCache: boolean = true
   ): Promise<AgentRoomInfo[]> {
     if (!this.wsClient.isConnected) {
-      throw new SDKError("Not connected to Teneo network", ErrorCode.NOT_CONNECTED);
+      throw new SDKError("Not connected to Teneo Protocol", ErrorCode.NOT_CONNECTED);
     }
 
     // Validate input
     this.validateRoomId(roomId);
 
     // Check cache if enabled
-    if (useCache && this.isCacheValid(this.availableAgentsCacheTime, roomId)) {
+    if (useCache) {
       const cached = this.availableAgentsCache.get(roomId);
       if (cached) {
         this.logger.debug("AgentRoomManager: Returning cached available agents", {
@@ -391,9 +468,6 @@ export class AgentRoomManager extends EventEmitter<SDKEvents> {
    * ```
    */
   public getRoomAgents(roomId: string): AgentRoomInfo[] | undefined {
-    if (!this.isCacheValid(this.roomAgentsCacheTime, roomId)) {
-      return undefined;
-    }
     const cached = this.roomAgentsCache.get(roomId);
     return cached ? cached.map((agent) => ({ ...agent })) : undefined;
   }
@@ -414,9 +488,6 @@ export class AgentRoomManager extends EventEmitter<SDKEvents> {
    * ```
    */
   public getAvailableAgents(roomId: string): AgentRoomInfo[] | undefined {
-    if (!this.isCacheValid(this.availableAgentsCacheTime, roomId)) {
-      return undefined;
-    }
     const cached = this.availableAgentsCache.get(roomId);
     return cached ? cached.map((agent) => ({ ...agent })) : undefined;
   }
@@ -493,8 +564,6 @@ export class AgentRoomManager extends EventEmitter<SDKEvents> {
   public clearAllCaches(): void {
     this.roomAgentsCache.clear();
     this.availableAgentsCache.clear();
-    this.roomAgentsCacheTime.clear();
-    this.availableAgentsCacheTime.clear();
     this.logger.debug("AgentRoomManager: All caches cleared");
   }
 
@@ -524,10 +593,10 @@ export class AgentRoomManager extends EventEmitter<SDKEvents> {
    */
   public cacheRoomAgents(roomId: string, agents: AgentRoomInfo[]): void {
     this.roomAgentsCache.set(roomId, agents);
-    this.roomAgentsCacheTime.set(roomId, Date.now());
     this.logger.debug("AgentRoomManager: Cached room agents", {
       roomId,
-      count: agents.length
+      count: agents.length,
+      cacheSize: this.roomAgentsCache.size
     });
   }
 
@@ -537,10 +606,10 @@ export class AgentRoomManager extends EventEmitter<SDKEvents> {
    */
   public cacheAvailableAgents(roomId: string, agents: AgentRoomInfo[]): void {
     this.availableAgentsCache.set(roomId, agents);
-    this.availableAgentsCacheTime.set(roomId, Date.now());
     this.logger.debug("AgentRoomManager: Cached available agents", {
       roomId,
-      count: agents.length
+      count: agents.length,
+      cacheSize: this.availableAgentsCache.size
     });
   }
 
@@ -548,25 +617,12 @@ export class AgentRoomManager extends EventEmitter<SDKEvents> {
   // PRIVATE HELPERS
   // ============================================================================
 
-  /**
-   * Checks if cache is still valid (within TTL)
-   */
-  private isCacheValid(cacheTimeMap: Map<string, number>, roomId: string): boolean {
-    const cacheTime = cacheTimeMap.get(roomId);
-    if (!cacheTime) return false;
-
-    const age = Date.now() - cacheTime;
-    return age < CACHE_TTL_MS;
-  }
-
   /**
    * Invalidates all caches for a specific room
    */
   private invalidateRoomCaches(roomId: string): void {
     this.roomAgentsCache.delete(roomId);
     this.availableAgentsCache.delete(roomId);
-    this.roomAgentsCacheTime.delete(roomId);
-    this.availableAgentsCacheTime.delete(roomId);
   }
 
   /**
@@ -604,6 +660,6 @@ export class AgentRoomManager extends EventEmitter<SDKEvents> {
     const ownedRooms = this.roomManagementManager.getOwnedRooms?.();
     if (!ownedRooms) return true; // Skip check if method not available
 
-    return ownedRooms.some((room: any) => room.id === roomId);
+    return ownedRooms.some((room) => room.id === roomId);
   }
 }

package/src/managers/index.ts

@@ -8,4 +8,16 @@ export { RoomManager } from "./room-manager";
 export { RoomManagementManager } from "./room-management-manager";
 export { AgentRoomManager, type AgentRoomInfo } from "./agent-room-manager";
 export { AgentRegistry } from "./agent-registry";
-export { MessageRouter, type SendMessageOptions, type AgentCommand } from "./message-router";
+export {
+  MessageRouter,
+  type SendMessageOptions,
+  type AgentCommand,
+  type QuoteResult,
+  type MessageRouterConfig
+} from "./message-router";
+export {
+  AdminManager,
+  type AdminManagerEvents,
+  type ListAllAgentsOptions,
+  type AllAgentsResult
+} from "./admin-manager";