@teneo-protocol/sdk 1.0.1 → 2.2.0

package/examples/openai-teneo/index.ts

@@ -5,31 +5,38 @@
  * Uses the OpenAI Codex SDK for thread-based conversations.
  */
 
-import 'dotenv/config';
-import express, { Request, Response } from 'express';
-import { Codex } from '@openai/codex-sdk';
-import { SDKConfigBuilder, TeneoSDK } from '../../dist/index.js';
+import "dotenv/config";
+import express, { Request, Response } from "express";
+import { Codex } from "@openai/codex-sdk";
+import { SDKConfigBuilder, TeneoSDK } from "../../dist/index.js";
 
 // Load environment variables
-const WS_URL = process.env.WS_URL || '';
-const PRIVATE_KEY = process.env.PRIVATE_KEY || '';
-const WALLET_ADDRESS = process.env.WALLET_ADDRESS || '';
-const DEFAULT_ROOM = process.env.DEFAULT_ROOM || 'general';
-const LOG_LEVEL = (process.env.LOG_LEVEL || 'info') as 'debug' | 'info' | 'warn' | 'error' | 'silent';
-const ENABLE_SIG_VERIFICATION = process.env.ENABLE_SIGNATURE_VERIFICATION === 'true';
-const TRUSTED_ADDRESSES = process.env.TRUSTED_ADDRESSES?.split(',').filter(Boolean) || [];
-const ENABLE_CACHE = process.env.ENABLE_CACHE !== 'false';
-const CACHE_TIMEOUT = parseInt(process.env.CACHE_TIMEOUT || '300000');
-const MAX_CACHE_SIZE = parseInt(process.env.MAX_CACHE_SIZE || '100');
-const ENABLE_RECONNECTION = process.env.ENABLE_RECONNECTION !== 'false';
-const RECONNECT_DELAY = parseInt(process.env.RECONNECT_DELAY || '5000');
-const MAX_RECONNECT_ATTEMPTS = parseInt(process.env.MAX_RECONNECT_ATTEMPTS || '10');
-const OPENAI_API_KEY = process.env.OPENAI_API_KEY || '';
+const WS_URL = process.env.WS_URL || "";
+const PRIVATE_KEY = process.env.PRIVATE_KEY || "";
+const WALLET_ADDRESS = process.env.WALLET_ADDRESS || "";
+const DEFAULT_ROOM = process.env.DEFAULT_ROOM || "general";
+const LOG_LEVEL = (process.env.LOG_LEVEL || "info") as
+  | "debug"
+  | "info"
+  | "warn"
+  | "error"
+  | "silent";
+const ENABLE_SIG_VERIFICATION = process.env.ENABLE_SIGNATURE_VERIFICATION === "true";
+const TRUSTED_ADDRESSES = process.env.TRUSTED_ADDRESSES?.split(",").filter(Boolean) || [];
+const ENABLE_CACHE = process.env.ENABLE_CACHE !== "false";
+const CACHE_TIMEOUT = parseInt(process.env.CACHE_TIMEOUT || "300000");
+const MAX_CACHE_SIZE = parseInt(process.env.MAX_CACHE_SIZE || "100");
+const ENABLE_RECONNECTION = process.env.ENABLE_RECONNECTION !== "false";
+const RECONNECT_DELAY = parseInt(process.env.RECONNECT_DELAY || "5000");
+const MAX_RECONNECT_ATTEMPTS = parseInt(process.env.MAX_RECONNECT_ATTEMPTS || "10");
+const OPENAI_API_KEY = process.env.OPENAI_API_KEY || "";
 
 // Validate required environment variables
 if (!WS_URL || !PRIVATE_KEY) {
-  console.error('Missing required environment variables: WS_URL, PRIVATE_KEY');
-  console.error('Note: OPENAI_API_KEY is optional - Codex SDK will use default auth if not provided');
+  console.error("Missing required environment variables: WS_URL, PRIVATE_KEY");
+  console.error(
+    "Note: OPENAI_API_KEY is optional - Codex SDK will use default auth if not provided"
+  );
   process.exit(1);
 }
 
@@ -39,20 +46,20 @@ app.use(express.json());
 // Initialize Teneo SDK using SDKConfigBuilder pattern
 const config = new SDKConfigBuilder()
   .withWebSocketUrl(WS_URL)
-  .withAuthentication(PRIVATE_KEY, WALLET_ADDRESS)  // Wallet auto-derived if not provided
+  .withAuthentication(PRIVATE_KEY, WALLET_ADDRESS) // Wallet auto-derived if not provided
   .withAutoJoinRooms([DEFAULT_ROOM])
   .withReconnection({
     enabled: ENABLE_RECONNECTION,
     delay: RECONNECT_DELAY,
     maxAttempts: MAX_RECONNECT_ATTEMPTS
   })
-  .withResponseFormat({ format: 'both', includeMetadata: true })
+  .withResponseFormat({ format: "both", includeMetadata: true })
   .withLogging(LOG_LEVEL)
   .withCache(ENABLE_CACHE, CACHE_TIMEOUT, MAX_CACHE_SIZE)
   .withSignatureVerification({
     enabled: ENABLE_SIG_VERIFICATION,
     trustedAddresses: TRUSTED_ADDRESSES,
-    requireFor: ['task_response', 'agent_selected'],
+    requireFor: ["task_response", "agent_selected"],
     strictMode: false
   })
   .build();
@@ -66,17 +73,17 @@ const codex = new Codex({
 });
 
 // Connect to Teneo
-console.log('📡 Connecting to Teneo network...');
+console.log("📡 Connecting to Teneo Protocol...");
 await teneoSDK.connect();
-console.log('✅ Connected to Teneo\n');
+console.log("✅ Connected to Teneo\n");
 
 // Health endpoint
-app.get('/health', (_req: Request, res: Response) => {
+app.get("/health", (_req: Request, res: Response) => {
   const teneoHealth = teneoSDK.getHealth();
   res.json({
-    status: 'ok',
+    status: "ok",
     teneo: {
-      connected: teneoHealth.connection.status === 'connected',
+      connected: teneoHealth.connection.status === "connected",
       authenticated: teneoHealth.connection.authenticated
     },
     codex: {
@@ -87,14 +94,14 @@ app.get('/health', (_req: Request, res: Response) => {
 });
 
 // Query endpoint - Codex analyzes, then routes to Teneo agent
-app.post('/query', async (req: Request, res: Response) => {
+app.post("/query", async (req: Request, res: Response) => {
   try {
     const { message } = req.body;
 
     if (!message) {
       return res.status(400).json({
         success: false,
-        error: 'Message is required'
+        error: "Message is required"
       });
     }
 
@@ -104,11 +111,11 @@ app.post('/query', async (req: Request, res: Response) => {
     const agents = teneoSDK.getAgents();
 
     // Step 2: Ask Codex to select the best agent
-    console.log('🤖 Asking Codex to select best agent...');
+    console.log("🤖 Asking Codex to select best agent...");
 
-    const agentList = agents.map(a =>
-      `- ${a.name}: ${a.description || 'No description'}`
-    ).join('\n');
+    const agentList = agents
+      .map((a) => `- ${a.name}: ${a.description || "No description"}`)
+      .join("\n");
 
     const thread = codex.startThread();
     const codexResponse = await thread.run(
@@ -125,50 +132,55 @@ Respond with ONLY the agent name, nothing else.`
     // Extract text from Codex response
     // Codex SDK returns an object with finalResponse property
     let selectedAgentName: string;
-    if (typeof codexResponse === 'string') {
+    if (typeof codexResponse === "string") {
       selectedAgentName = codexResponse.trim();
-    } else if (codexResponse && typeof codexResponse === 'object') {
+    } else if (codexResponse && typeof codexResponse === "object") {
       // Extract from finalResponse property
-      selectedAgentName = (codexResponse as any).finalResponse
-        || (codexResponse as any).text
-        || (codexResponse as any).content
-        || String(codexResponse);
-      if (typeof selectedAgentName === 'object') {
+      selectedAgentName =
+        (codexResponse as any).finalResponse ||
+        (codexResponse as any).text ||
+        (codexResponse as any).content ||
+        String(codexResponse);
+      if (typeof selectedAgentName === "object") {
         selectedAgentName = JSON.stringify(selectedAgentName);
       }
       selectedAgentName = selectedAgentName.trim();
     } else {
-      selectedAgentName = agents[0]?.name || '';
+      selectedAgentName = agents[0]?.name || "";
     }
 
     console.log(`✅ Selected agent: ${selectedAgentName}`);
 
     // Find the agent by name or ID
-    const selectedAgent = agents.find(a =>
-      a.name?.toLowerCase() === selectedAgentName.toLowerCase() ||
-      a.id?.toLowerCase() === selectedAgentName.toLowerCase()
+    const selectedAgent = agents.find(
+      (a) =>
+        a.name?.toLowerCase() === selectedAgentName.toLowerCase() ||
+        a.id?.toLowerCase() === selectedAgentName.toLowerCase()
     );
 
     if (!selectedAgent) {
       return res.status(404).json({
         success: false,
-        error: `Agent '${selectedAgentName}' not found. Available agents: ${agents.map(a => a.name || a.id).join(', ')}`
+        error: `Agent '${selectedAgentName}' not found. Available agents: ${agents.map((a) => a.name || a.id).join(", ")}`
       });
     }
 
     // Step 3: Send direct command to selected Teneo agent (bypasses coordinator)
     // Use the SDK's built-in waitForResponse feature with the improved fallback matching
     console.log(`📤 Sending to Teneo agent: ${selectedAgent.name || selectedAgent.id}...`);
-    const teneoResponse = await teneoSDK.sendDirectCommand({
-      agent: selectedAgent.id,
-      command: message,
-      room: DEFAULT_ROOM
-    }, true);  // waitForResponse = true
+    const teneoResponse = await teneoSDK.sendDirectCommand(
+      {
+        agent: selectedAgent.id,
+        command: message,
+        room: DEFAULT_ROOM
+      },
+      true
+    ); // waitForResponse = true
 
     if (!teneoResponse || !teneoResponse.humanized) {
       return res.json({
         success: false,
-        error: 'No response from Teneo agent'
+        error: "No response from Teneo agent"
       });
     }
 
@@ -186,25 +198,24 @@ Respond with ONLY the agent name, nothing else.`
         metadata: teneoResponse.metadata
       }
     });
-
   } catch (error) {
-    console.error('❌ Query error:', error);
+    console.error("❌ Query error:", error);
     res.status(500).json({
       success: false,
-      error: error instanceof Error ? error.message : 'Unknown error'
+      error: error instanceof Error ? error.message : "Unknown error"
     });
   }
 });
 
 // Direct Codex query (bypass Teneo)
-app.post('/codex', async (req: Request, res: Response) => {
+app.post("/codex", async (req: Request, res: Response) => {
   try {
     const { message, threadId } = req.body;
 
     if (!message) {
       return res.status(400).json({
         success: false,
-        error: 'Message is required'
+        error: "Message is required"
       });
     }
 
@@ -217,13 +228,14 @@ app.post('/codex', async (req: Request, res: Response) => {
     // Extract text from Codex response
     // Codex SDK returns an object with finalResponse property
     let responseText: string;
-    if (typeof codexResult === 'string') {
+    if (typeof codexResult === "string") {
       responseText = codexResult;
-    } else if (codexResult && typeof codexResult === 'object') {
-      responseText = (codexResult as any).finalResponse
-        || (codexResult as any).text
-        || (codexResult as any).content
-        || JSON.stringify(codexResult);
+    } else if (codexResult && typeof codexResult === "object") {
+      responseText =
+        (codexResult as any).finalResponse ||
+        (codexResult as any).text ||
+        (codexResult as any).content ||
+        JSON.stringify(codexResult);
     } else {
       responseText = String(codexResult);
     }
@@ -232,26 +244,25 @@ app.post('/codex', async (req: Request, res: Response) => {
       success: true,
       data: {
         response: responseText,
-        threadId: thread.id || 'new',
+        threadId: thread.id || "new",
         usage: (codexResult as any).usage // Include token usage if available
       }
     });
-
   } catch (error) {
-    console.error('❌ Codex error:', error);
+    console.error("❌ Codex error:", error);
     res.status(500).json({
       success: false,
-      error: error instanceof Error ? error.message : 'Unknown error'
+      error: error instanceof Error ? error.message : "Unknown error"
     });
   }
 });
 
 // List Teneo agents
-app.get('/agents', (_req: Request, res: Response) => {
+app.get("/agents", (_req: Request, res: Response) => {
   const agents = teneoSDK.getAgents();
   res.json({
     success: true,
-    agents: agents.map(a => ({
+    agents: agents.map((a) => ({
       id: a.id,
       name: a.name,
       description: a.description,
@@ -272,8 +283,8 @@ app.listen(PORT, () => {
 });
 
 // Graceful shutdown
-process.on('SIGINT', () => {
-  console.log('\n👋 Shutting down...');
+process.on("SIGINT", () => {
+  console.log("\n👋 Shutting down...");
   teneoSDK.disconnect();
   teneoSDK.destroy();
   process.exit(0);

package/examples/production-dashboard/.env.example

@@ -2,13 +2,13 @@
 # Copy this file to .env and fill in your values
 
 # ============================================================================
-# REQUIRED: Teneo Network Connection
+# REQUIRED: Teneo Protocol Connection
 # ============================================================================
 
 # WebSocket URL for Teneo AI Network
 # Production: wss://your-production-server.com/ws
-# Development: wss://dev-rooms-websocket-ai-core-o9fmb.ondigitalocean.app/ws
-WS_URL=wss://dev-rooms-websocket-ai-core-o9fmb.ondigitalocean.app/ws
+# Development: wss://your-teneo-server.com/ws
+WS_URL=wss://your-teneo-server.com/ws
 
 # Ethereum Private Key (with 0x prefix)
 # IMPORTANT: Never commit your actual private key to version control!

package/examples/production-dashboard/README.md

@@ -11,7 +11,9 @@ This is the **ultimate reference implementation** showcasing every SDK capabilit
 ✅ **WebSocket Connection** - Auto-reconnection with exponential backoff
 ✅ **Ethereum Authentication** - Wallet-based authentication
 ✅ **Message Sending** - Coordinator-based and direct agent commands
-✅ **Room Management** - Subscribe, unsubscribe, and list rooms
+✅ **Room Management (v1)** - Subscribe, unsubscribe, and list rooms
+✅ **Room Management (v2.0)** - Create, update, delete rooms with ownership tracking
+✅ **Agent-Room Management (v2.0)** - Add/remove agents per room, list room agents
 ✅ **Agent Discovery** - List agents with capabilities
 ✅ **Response Formatting** - Raw JSON, humanized text, or both
 
@@ -29,6 +31,17 @@ This is the **ultimate reference implementation** showcasing every SDK capabilit
 ✅ **Error Handling** - Custom error classes with recovery strategies
 ✅ **Event System** - Complete event-driven architecture
 
+### v2.0 Features (New!)
+
+✅ **Multi-Room Management** - Create, update, and delete your own rooms
+✅ **Room Ownership Tracking** - Distinguish between owned and shared rooms
+✅ **Room Limits** - Track and display room creation quotas
+✅ **Agent-Room Customization** - Add/remove agents per room (owner only)
+✅ **Room Agent Listing** - List agents in specific rooms with caching
+✅ **Available Agents** - See which agents can be added to a room
+✅ **Real-time Room Events** - Live updates for room creation/updates/deletions
+✅ **Real-time Agent-Room Events** - Live updates when agents are added/removed
+
 ### Production Features
 
 ✅ **Health Check Endpoint** - `/health` for Kubernetes/Docker monitoring
@@ -205,15 +218,46 @@ const config = new SDKConfigBuilder()
 - `GET /api/agents/search/capability/:capability` - **PERF-3**: Search by capability (O(1))
 - `GET /api/agents/search/name/:name` - **PERF-3**: Search by name (O(k))
 - `GET /api/agents/search/status/:status` - **PERF-3**: Search by status (O(1))
-- `GET /api/rooms` - List all available rooms
+- `GET /api/rooms` - List all available rooms (v1)
 - `GET /api/deduplication` - **CB-4**: Get message deduplication status
-- `POST /api/room/subscribe` - Subscribe to a room
+- `POST /api/room/subscribe` - Subscribe to a room (v1)
   ```json
   {
     "roomId": "tech-support"
   }
   ```
-- `POST /api/room/unsubscribe` - Unsubscribe from a room
+- `POST /api/room/unsubscribe` - Unsubscribe from a room (v1)
+
+### Room Management v2.0 API
+
+- `GET /api/v2/rooms/owned` - Get all rooms you own
+- `GET /api/v2/rooms/shared` - Get all rooms you're a member of
+- `GET /api/v2/rooms/limit` - Get your room creation limit
+- `POST /api/v2/rooms` - Create a new room
+  ```json
+  {
+    "name": "My Room",
+    "description": "Optional description"
+  }
+  ```
+- `PUT /api/v2/rooms/:id` - Update room (owner only)
+  ```json
+  {
+    "name": "Updated Name",
+    "description": "New description"
+  }
+  ```
+- `DELETE /api/v2/rooms/:id` - Delete room (owner only)
+
+### Agent-Room Management v2.0 API
+
+- `GET /api/v2/rooms/:id/agents` - List agents in room (with 5-min cache)
+- `GET /api/v2/rooms/:id/available-agents` - List agents available to add
+- `GET /api/v2/rooms/:id/agents/count` - Get agent count (instant, from cache)
+- `GET /api/v2/rooms/:roomId/agents/:agentId/check` - Check if agent is in room
+- `POST /api/v2/rooms/:roomId/agents/:agentId` - Add agent to room (owner only)
+- `DELETE /api/v2/rooms/:roomId/agents/:agentId` - Remove agent from room (owner only)
+- `POST /api/v2/rooms/:id/cache/invalidate` - Manually invalidate agent-room cache
 
 ### Real-time Data
 
@@ -240,10 +284,12 @@ const config = new SDKConfigBuilder()
 ### Tabs
 
 1. **Agents Tab**: List all agents with capabilities and status
-2. **Rooms Tab**: Manage room subscriptions (subscribe/unsubscribe)
-3. **Messages Tab**: View message history with responses
-4. **Webhooks Tab**: Monitor received webhooks
-5. **Events Tab**: Real-time event stream
+2. **Rooms Tab**: Manage room subscriptions (subscribe/unsubscribe) - v1
+3. **Room Mgmt Tab** 🆕: Create, update, delete rooms - View owned/shared rooms with room limits (v2.0)
+4. **Agent-Room Tab** 🆕: Add/remove agents to rooms - List room agents and available agents (v2.0)
+5. **Messages Tab**: View message history with responses
+6. **Webhooks Tab**: Monitor received webhooks
+7. **Events Tab**: Real-time event stream (includes v2.0 room and agent-room events)
 
 ### Health Monitor
 
@@ -265,18 +311,18 @@ import { SecurePrivateKey } from "@teneo-protocol/sdk";
 const secureKey = new SecurePrivateKey(process.env.PRIVATE_KEY);
 
 // Use with SDK - automatically decrypted when needed
-const config = new SDKConfigBuilder()
-  .withAuthentication(secureKey, WALLET_ADDRESS)
-  .build();
+const config = new SDKConfigBuilder().withAuthentication(secureKey, WALLET_ADDRESS).build();
 ```
 
 **Security Benefits:**
+
 - Private key is encrypted in memory using AES-256-GCM
 - Protected from memory dumps and debugging tools
 - Automatic secure cleanup when no longer needed
 - Minimal performance overhead
 
 **Example Test:**
+
 ```bash
 # Without encryption: private key visible in memory dump
 # With encryption: only encrypted bytes visible
@@ -298,17 +344,20 @@ Prevent duplicate message processing using a TTL-based cache:
 ```
 
 **How It Works:**
+
 - Maintains an in-memory cache of processed message IDs
 - Automatically expires entries after TTL (Time To Live)
 - Bounded size prevents unbounded memory growth
 - Messages without IDs are allowed through (graceful degradation)
 
 **Configuration Options:**
+
 - `enabled`: Enable/disable deduplication (default: true)
 - `ttl`: How long to remember message IDs in milliseconds (default: 60000ms = 1 minute)
 - `maxSize`: Maximum number of message IDs to cache (default: 10000)
 
 **Monitoring:**
+
 ```bash
 # Check deduplication status
 curl http://localhost:3000/api/deduplication
@@ -324,15 +373,18 @@ curl http://localhost:3000/api/deduplication
 ```
 
 **Events:**
+
 - `message:duplicate` - Emitted when a duplicate message is detected and skipped
 
 **Testing:**
+
 1. Send the same message multiple times rapidly
 2. Watch Events tab for `message:duplicate` events
 3. Verify duplicates are not processed
 4. Monitor `/api/deduplication` to see cache size increase
 
 **Production Benefits:**
+
 - Prevents duplicate task execution if messages are retransmitted
 - Protects against network-level duplicates during reconnections
 - Configurable TTL balances memory usage vs duplicate window
@@ -354,11 +406,13 @@ curl http://localhost:3000/api/agents/search/status/online
 ```
 
 **Performance Comparison:**
+
 - Traditional: O(n) - iterate through all agents
 - Indexed: O(1) - direct map lookup for capability/status
 - Indexed: O(k) - token-based search for names (k = tokens)
 
 **SDK Usage:**
+
 ```typescript
 // Fast capability search
 const weatherAgents = sdk.findAgentsByCapability("weather-forecast");
@@ -524,7 +578,7 @@ Monitor rate limit status via `/metrics` endpoint.
 - Watch Webhooks tab for incoming webhook events
 - See event types: `task`, `agent_selected`, `task_response`
 
-### 5. Test Room Management
+### 5. Test Room Management (v1)
 
 - Go to Rooms tab
 - Enter a room ID
@@ -532,6 +586,29 @@ Monitor rate limit status via `/metrics` endpoint.
 - See room appear in subscribed list
 - Click "Unsubscribe" to unsubscribe from room
 
+### 5b. Test Room Management v2.0
+
+- Go to **Room Mgmt** tab
+- See your owned and shared rooms
+- Check your room limit (e.g., "2/50 rooms")
+- **Create a room**: Enter name and description, click "Create Room"
+- See room appear in "Private Rooms" list with owner badge
+- **Update room**: Click "Update" on an owned room, modify name/description
+- **Delete room**: Click "Delete" on an owned room
+- Watch Events tab for `room:created`, `room:updated`, `room:deleted` events
+
+### 5c. Test Agent-Room Management v2.0
+
+- Go to **Agent-Room** tab
+- Select a room you own from the dropdown
+- See "Agents in Room" list (may be empty for new rooms)
+- See "Available Agents" list (agents you can add)
+- **Add an agent**: Click "Add" next to an available agent
+- Watch agent move from "Available" to "Agents in Room"
+- See agent count update in real-time
+- **Remove an agent**: Click "Remove" next to an agent in room
+- Watch Events tab for `agent_room:agent_added`, `agent_room:agent_removed` events
+
 ### 6. Test Signature Verification
 
 - Enable in `.env`: `ENABLE_SIGNATURE_VERIFICATION=true`
@@ -637,7 +714,7 @@ Monitor rate limit status via `/metrics` endpoint.
 
 - **Problem**: "Authentication Pending" never completes
 - **Solution**: Verify `PRIVATE_KEY` and `WALLET_ADDRESS` are correct
-- **Check**: Ensure wallet has access to the Teneo network
+- **Check**: Ensure wallet has access to the Teneo Protocol
 
 ### Webhook Not Receiving