@teneo-protocol/sdk 2.2.2 → 3.0.1

package/examples/usage/README.md

@@ -32,7 +32,7 @@ PRIVATE_KEY=your_ethereum_private_key_here
 WS_URL=wss://your-teneo-server.com/ws
 
 # Optional
-DEFAULT_ROOM=general
+DEFAULT_ROOM=your-room-id
 WALLET_ADDRESS=0x...  # Auto-derived if not provided
 LOG_LEVEL=info
 ```
@@ -279,6 +279,20 @@ We recommend following this learning path:
 
 ## 🔧 Common Patterns
 
+### Understanding Message Routing
+
+The SDK supports two routing approaches depending on your environment:
+
+**Coordinator Environments:**
+- Natural language messages work: `"Get bitcoin info"`
+- Coordinator automatically selects the best agent
+- Direct commands also work for explicit agent selection
+
+**Non-Coordinator Environments:**
+- Must use direct command syntax: `"@Agent Name command params"`
+- Example: `"@X Platform Agent search bitcoin 5"`
+- Required for all messages in these environments
+
 ### Pattern 1: Basic Message Flow
 
 ```typescript
@@ -287,7 +301,7 @@ await sdk.connect();
 
 // Send and wait for response
 const response = await sdk.sendMessage('hello', {
-  room: 'general',
+  room: roomId,
   waitForResponse: true,
   timeout: 30000
 });
@@ -297,19 +311,31 @@ console.log(response.humanized);
 
 ### Pattern 2: Direct Agent Command
 
+Direct commands work in all environments and are **required** in non-coordinator environments.
+
 ```typescript
 // Find agent by capability
-const agents = sdk.findAgentsByCapability('weather');
+const agents = sdk.findAvailableAgentsByCapability('weather');
 const weatherAgent = agents[0];
 
-// Send direct command
+// Option 1: Use @mention syntax (recommended)
+const response = await sdk.sendMessage('@Weather Agent forecast for NYC', {
+  room: roomId,
+  waitForResponse: true
+});
+
+// Option 2: Use sendDirectCommand
 const response = await sdk.sendDirectCommand({
-  agent: weatherAgent.id,
+  agent: weatherAgent.name, // Use full agent name
   command: 'forecast for NYC',
-  room: 'general'
+  room: roomId
 }, true);
 ```
 
+**When to use:**
+- **Required** in non-coordinator environments
+- **Optional** in coordinator environments (explicit agent selection)
+
 ### Pattern 3: Event-Driven
 
 ```typescript
@@ -319,7 +345,7 @@ sdk.on('agent:response', (response) => {
 });
 
 // Fire and forget
-await sdk.sendMessage('hello', { room: 'general' });
+await sdk.sendMessage('hello', { room: roomId });
 ```
 
 ## 🐛 Troubleshooting

package/examples/webhook-integration.ts

@@ -66,7 +66,7 @@ async function main() {
   const sdk = new TeneoSDK({
     wsUrl: process.env.WS_URL || "ws://localhost:8080/ws",
     privateKey: process.env.PRIVATE_KEY,
-    autoJoinRooms: ["general"],
+    autoJoinPublicRooms: [process.env.ROOM_ID || "your-room-id"],
 
     // Webhook configuration
     webhookUrl: "http://localhost:3000/webhook",
@@ -106,20 +106,20 @@ async function main() {
     console.log("[SDK] Connecting to Teneo Protocol...");
     await sdk.connect();
 
-    // Wait for ready
-    await new Promise<void>((resolve) => {
-      sdk.once("ready", resolve);
-    });
-
     console.log("[SDK] Connected and ready!");
 
     // Send some test messages
     console.log("\n[SDK] Sending test messages...\n");
 
     // These will trigger webhooks
-    await sdk.sendMessage("What is blockchain technology?", { room: "general" });
-    await sdk.sendMessage("Explain quantum computing in simple terms", { room: "general" });
-    await sdk.sendMessage("How does machine learning work?", { room: "general" });
+    // WITH COORDINATOR: Natural language
+    await sdk.sendMessage("What is blockchain technology?", { room: process.env.ROOM_ID || "your-room-id" });
+    await sdk.sendMessage("Explain quantum computing in simple terms", { room: process.env.ROOM_ID || "your-room-id" });
+
+    // WITHOUT COORDINATOR: Direct command (use @Agent Name syntax)
+    // await sdk.sendMessage("@X Platform Agent search bitcoin 5", { room: process.env.ROOM_ID || "your-room-id" });
+    
+    await sdk.sendMessage("How does machine learning work?", { room: process.env.ROOM_ID || "your-room-id" });
 
     // Check webhook queue status
     const webhookStatus = sdk.getWebhookStatus();

package/examples/x-influencer-battle-server.ts

@@ -55,7 +55,7 @@ async function initSDK() {
   const config = new SDKConfigBuilder()
     .withWebSocketUrl(WS_URL)
     .withAuthentication(PRIVATE_KEY, WALLET_ADDRESS)
-    .withAutoJoinRooms([ROOM]) // Auto-join rooms on connect
+    .withAutoJoinPublicRooms([ROOM]) // Auto-join rooms on connect
     .withReconnection(true, 5000, 10) // Enable reconnection
     .withResponseFormat("both", true) // Get both raw and humanized responses with metadata
     .withLogging("debug") // Enable debug logging

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teneo-protocol/sdk",
-  "version": "2.2.2",
+  "version": "3.0.1",
   "description": "TypeScript SDK for external platforms to interact with Teneo agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/scripts/diagnose-connection.ts

@@ -0,0 +1,86 @@
+/**
+ * Diagnose connection and message flow
+ * Run with: npx tsx scripts/diagnose-connection.ts
+ */
+
+import { TeneoSDK, SDKConfigBuilder } from "../src";
+import { SecurePrivateKey } from "../src/utils/secure-private-key";
+
+const WS_URL = process.env.TENEO_WS_URL || "wss://backend.developer.chatroom.teneo-protocol.ai/ws";
+const TEST_PRIVATE_KEY = process.env.TENEO_PRIVATE_KEY || "0xYOUR_PRIVATE_KEY_HERE";
+
+async function diagnose() {
+  console.log("=".repeat(60));
+  console.log("CONNECTION DIAGNOSTIC");
+  console.log("=".repeat(60));
+
+  const secureKey = new SecurePrivateKey(TEST_PRIVATE_KEY);
+
+  const config = new SDKConfigBuilder()
+    .withWebSocketUrl(WS_URL)
+    .withAuthentication(secureKey)
+    .withLogging("debug")
+    .withPayments({ autoApprove: false })
+    .build();
+
+  const sdk = new TeneoSDK(config);
+
+  // Listen to all events
+  const events = [
+    "connected", "disconnected", "authenticated", "error",
+    "message:received", "message:sent", "message:error",
+    "agent:response", "agent:selected", "agents:list"
+  ];
+
+  for (const event of events) {
+    sdk.on(event as any, (data: any) => {
+      console.log(`\n[EVENT: ${event}]`);
+      if (typeof data === "object") {
+        console.log(JSON.stringify(data, null, 2).substring(0, 500));
+      } else {
+        console.log(data);
+      }
+    });
+  }
+
+  try {
+    console.log("\nConnecting...");
+    await sdk.connect();
+    console.log("\nConnected!");
+
+    // Get auth state
+    const authState = sdk.getAuthState();
+    console.log("\nAuth State:", JSON.stringify(authState, null, 2));
+
+    // Get connection state
+    const connState = sdk.getConnectionState();
+    console.log("\nConnection State:", JSON.stringify(connState, null, 2));
+
+    // Wait for agents list
+    console.log("\nWaiting for agents list (10s)...");
+    await new Promise(resolve => setTimeout(resolve, 10000));
+
+    // Try to send a simple message (fire and forget)
+    console.log("\nSending test message (fire and forget)...");
+    try {
+      await sdk.sendMessage("hello", { room: "public" });
+      console.log("Message sent successfully");
+    } catch (err) {
+      console.log("Send error:", err);
+    }
+
+    // Wait for any response
+    console.log("\nWaiting for response (15s)...");
+    await new Promise(resolve => setTimeout(resolve, 15000));
+
+    await sdk.disconnect();
+    console.log("\nDisconnected");
+
+  } catch (error) {
+    console.error("Error:", error);
+  }
+
+  process.exit(0);
+}
+
+diagnose().catch(console.error);

package/scripts/investigate-payload.ts

@@ -0,0 +1,163 @@
+/**
+ * Investigate WebSocket payload sizes from the Teneo server
+ * Run with: npx tsx scripts/investigate-payload.ts
+ */
+
+import WebSocket from "ws";
+import { privateKeyToAccount } from "viem/accounts";
+
+const WS_URL = process.env.TENEO_WS_URL || "wss://backend.developer.chatroom.teneo-protocol.ai/ws";
+
+// Set via environment variable
+const TEST_PRIVATE_KEY = process.env.TENEO_PRIVATE_KEY || "0xYOUR_PRIVATE_KEY_HERE";
+
+console.log("Connecting to:", WS_URL);
+console.log("Max payload set to 10MB\n");
+
+const account = privateKeyToAccount(TEST_PRIVATE_KEY);
+console.log("Wallet address:", account.address, "\n");
+
+const ws = new WebSocket(WS_URL, {
+  maxPayload: 10 * 1024 * 1024 // 10MB max
+});
+
+let messageCount = 0;
+let totalBytes = 0;
+const messageSizes: { type: string; size: number; preview: string }[] = [];
+let authStarted = false;
+
+ws.on("open", () => {
+  console.log("✅ Connected\n");
+});
+
+ws.on("message", async (data: Buffer) => {
+  messageCount++;
+  const size = data.length;
+  totalBytes += size;
+
+  let parsed: any;
+  let type = "unknown";
+  let preview = "";
+
+  try {
+    parsed = JSON.parse(data.toString());
+    type = parsed.type || parsed.action || "json";
+
+    if (parsed.type === "room_history") {
+      const historyLength = parsed.data?.history?.length || 0;
+      preview = `${historyLength} messages in history`;
+    } else if (parsed.type === "auth_success") {
+      preview = `wallet: ${parsed.data?.address?.substring(0, 10)}...`;
+    } else if (parsed.type === "challenge") {
+      preview = `challenge: ${parsed.data?.challenge?.substring(0, 20)}...`;
+    } else {
+      preview = JSON.stringify(parsed).substring(0, 100);
+    }
+  } catch {
+    preview = data.toString().substring(0, 100);
+  }
+
+  const sizeStr = formatBytes(size);
+  messageSizes.push({ type, size, preview });
+
+  console.log(`Message #${messageCount}: ${type}`);
+  console.log(`  Size: ${sizeStr}`);
+  console.log(`  Preview: ${preview}`);
+  console.log("");
+
+  // Handle auth flow using correct SDK message format
+  if (parsed?.type === "auth_required" && !authStarted) {
+    authStarted = true;
+    console.log("📤 Requesting challenge...\n");
+    ws.send(JSON.stringify({
+      type: "request_challenge",
+      data: {
+        userType: "user",
+        address: account.address
+      }
+    }));
+  } else if (parsed?.type === "challenge") {
+    const challenge = parsed.data?.challenge;
+    console.log("📤 Signing challenge and authenticating...\n");
+    const messageToSign = `Teneo authentication challenge: ${challenge}`;
+    const signature = await account.signMessage({ message: messageToSign });
+    ws.send(JSON.stringify({
+      type: "auth",
+      data: {
+        address: account.address,
+        signature,
+        message: messageToSign,
+        userType: "user"
+      }
+    }));
+  }
+
+  // After receiving enough messages post-auth, close and summarize
+  if (messageCount >= 15 || totalBytes > 100 * 1024 * 1024) {
+    summarize();
+    ws.close();
+  }
+});
+
+ws.on("error", (err) => {
+  console.error("❌ Error:", err.message);
+});
+
+ws.on("close", (code, reason) => {
+  console.log(`\nConnection closed: ${code} ${reason}`);
+  if (messageCount > 1) summarize();
+  process.exit(0);
+});
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
+
+function summarize() {
+  console.log("\n" + "=".repeat(60));
+  console.log("PAYLOAD SIZE INVESTIGATION SUMMARY");
+  console.log("=".repeat(60));
+  console.log(`Total messages received: ${messageCount}`);
+  console.log(`Total bytes received: ${formatBytes(totalBytes)}`);
+  console.log("\nBy message type:");
+
+  const byType: Record<string, { count: number; totalSize: number }> = {};
+  for (const msg of messageSizes) {
+    if (!byType[msg.type]) {
+      byType[msg.type] = { count: 0, totalSize: 0 };
+    }
+    byType[msg.type].count++;
+    byType[msg.type].totalSize += msg.size;
+  }
+
+  for (const [type, stats] of Object.entries(byType)) {
+    console.log(`  ${type}: ${stats.count} messages, ${formatBytes(stats.totalSize)}`);
+  }
+
+  console.log("\nLargest messages:");
+  const sorted = [...messageSizes].sort((a, b) => b.size - a.size).slice(0, 5);
+  for (const msg of sorted) {
+    console.log(`  ${msg.type}: ${formatBytes(msg.size)} - ${msg.preview.substring(0, 50)}`);
+  }
+
+  // Check if any message exceeded 2MB (original limit)
+  const over2mb = messageSizes.filter(m => m.size > 2 * 1024 * 1024);
+  if (over2mb.length > 0) {
+    console.log("\n⚠️  Messages exceeding original 2MB limit:");
+    for (const msg of over2mb) {
+      console.log(`  ${msg.type}: ${formatBytes(msg.size)}`);
+    }
+  } else {
+    console.log("\n✅ No messages exceeded the original 2MB limit");
+  }
+}
+
+// Timeout after 30 seconds
+setTimeout(() => {
+  console.log("\n⏰ Timeout - closing connection");
+  summarize();
+  ws.close();
+  process.exit(0);
+}, 30000);

package/scripts/list-agents.ts

@@ -0,0 +1,58 @@
+/**
+ * List available agents
+ * Run with: npx tsx scripts/list-agents.ts
+ */
+
+import { TeneoSDK, SDKConfigBuilder } from "../src";
+import { SecurePrivateKey } from "../src/utils/secure-private-key";
+
+const WS_URL = process.env.TENEO_WS_URL || "wss://backend.developer.chatroom.teneo-protocol.ai/ws";
+const TEST_PRIVATE_KEY = process.env.TENEO_PRIVATE_KEY || "0xYOUR_PRIVATE_KEY_HERE";
+
+async function listAgents() {
+  console.log("Listing available agents...\n");
+
+  const secureKey = new SecurePrivateKey(TEST_PRIVATE_KEY);
+
+  const config = new SDKConfigBuilder()
+    .withWebSocketUrl(WS_URL)
+    .withAuthentication(secureKey)
+    .withLogging("warn")
+    .build();
+
+  const sdk = new TeneoSDK(config);
+
+  try {
+    await sdk.connect();
+    console.log("Connected!\n");
+
+    // Wait for agents list
+    await new Promise(resolve => setTimeout(resolve, 3000));
+
+    // Get auth state for rooms
+    const authState = sdk.getAuthState();
+    console.log("User's rooms:", authState.rooms);
+    console.log("Private room:", authState.privateRoomIds?.[0] || "none");
+    console.log();
+
+    // Get available agents
+    const agents = sdk.agents.getAgents();
+    console.log(`Available agents (${agents.length}):\n`);
+
+    for (const agent of agents) {
+      console.log(`- ${agent.name} (${agent.id})`);
+      console.log(`  Description: ${agent.description?.substring(0, 100)}...`);
+      console.log(`  Online: ${agent.isOnline}`);
+      console.log(`  Rooms: ${agent.rooms?.join(", ") || "N/A"}`);
+      console.log();
+    }
+
+    await sdk.disconnect();
+  } catch (error) {
+    console.error("Error:", error);
+  }
+
+  process.exit(0);
+}
+
+listAgents().catch(console.error);

package/scripts/live-multi-network-test.ts

@@ -0,0 +1,230 @@
+/**
+ * Live Multi-Network Test
+ * Tests direct agent requests and coordinator requests across PEAQ, Base, and Avalanche
+ * Run with: npx tsx scripts/live-multi-network-test.ts
+ */
+
+import { TeneoSDK, SDKConfigBuilder } from "../src";
+import { SecurePrivateKey } from "../src/utils/secure-private-key";
+
+const WS_URL = process.env.TENEO_WS_URL || "wss://backend.developer.chatroom.teneo-protocol.ai/ws";
+const TEST_PRIVATE_KEY = process.env.TENEO_PRIVATE_KEY || "0xYOUR_PRIVATE_KEY_HERE";
+
+interface TestResult {
+  network: string;
+  type: "direct" | "coordinator";
+  success: boolean;
+  response?: string;
+  txHash?: string;
+  error?: string;
+  duration: number;
+}
+
+const results: TestResult[] = [];
+
+async function runTest() {
+  console.log("=".repeat(70));
+  console.log("LIVE MULTI-NETWORK TEST");
+  console.log("=".repeat(70));
+  console.log(`WebSocket: ${WS_URL}`);
+  console.log(`Networks: PEAQ (3338), Base (8453), Avalanche (43114)\n`);
+
+  const secureKey = new SecurePrivateKey(TEST_PRIVATE_KEY);
+
+  // Test each network
+  // Test all networks
+  const networks = ["peaq", "base", "avalanche"] as const;
+
+  for (const network of networks) {
+    console.log(`\n${"=".repeat(70)}`);
+    console.log(`TESTING NETWORK: ${network.toUpperCase()}`);
+    console.log("=".repeat(70));
+
+    let sdk: TeneoSDK | null = null;
+
+    try {
+      // Create SDK with network configuration
+      // Enable auto-approve for payments (wallet has USDC)
+      const config = new SDKConfigBuilder()
+        .withWebSocketUrl(WS_URL)
+        .withAuthentication(secureKey)
+        .withNetwork(network)
+        .withLogging("warn")
+        .withPayments({ autoApprove: true })
+        .build();
+
+      sdk = new TeneoSDK(config);
+
+      // Connect and authenticate
+      console.log(`\nConnecting to ${network}...`);
+      await sdk.connect();
+      console.log(`Connected and authenticated on ${network}`);
+
+      // Wait for agents list
+      await new Promise(resolve => setTimeout(resolve, 2000));
+
+      // Get the user's private room
+      const authState = sdk.getAuthState();
+      const privateRoom = authState.privateRoomIds?.[0] || authState.rooms?.[0] || "public";
+      console.log(`Using room: ${privateRoom}`);
+
+      // Test 1: Direct agent request
+      console.log(`\n--- Direct Request (@x-agent-enterprise-v2) ---`);
+      const directStart = Date.now();
+      try {
+        const directResponse = await sdk.sendMessage(
+          "@x-agent-enterprise-v2 user @elonmusk",
+          {
+            room: privateRoom,
+            waitForResponse: true,
+            timeout: 60000
+          }
+        );
+
+        const directDuration = Date.now() - directStart;
+        const directResult: TestResult = {
+          network,
+          type: "direct",
+          success: true,
+          response: typeof directResponse === "string"
+            ? directResponse.substring(0, 200) + "..."
+            : JSON.stringify(directResponse).substring(0, 200) + "...",
+          duration: directDuration
+        };
+
+        // Try to extract tx hash from response
+        if (typeof directResponse === "object" && directResponse !== null) {
+          const respObj = directResponse as Record<string, unknown>;
+          if (respObj.txHash) directResult.txHash = String(respObj.txHash);
+          if (respObj.payment_tx_hash) directResult.txHash = String(respObj.payment_tx_hash);
+          if (respObj.paymentTxHash) directResult.txHash = String(respObj.paymentTxHash);
+          // Check nested metadata
+          const metadata = respObj.metadata as Record<string, unknown> | undefined;
+          if (metadata?.txHash) directResult.txHash = String(metadata.txHash);
+          if (metadata?.payment_tx_hash) directResult.txHash = String(metadata.payment_tx_hash);
+        }
+        // Log full response for debugging
+        console.log("Full response:", JSON.stringify(directResponse, null, 2).substring(0, 1000));
+
+        results.push(directResult);
+        console.log(`Response (${directDuration}ms):`);
+        console.log(directResult.response);
+        if (directResult.txHash) console.log(`TX Hash: ${directResult.txHash}`);
+      } catch (error) {
+        const directDuration = Date.now() - directStart;
+        results.push({
+          network,
+          type: "direct",
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+          duration: directDuration
+        });
+        console.log(`Error (${directDuration}ms): ${error instanceof Error ? error.message : error}`);
+      }
+
+      // Wait between requests
+      await new Promise(resolve => setTimeout(resolve, 2000));
+
+      // Test 2: Coordinator request
+      console.log(`\n--- Coordinator Request ---`);
+      const coordStart = Date.now();
+      try {
+        const coordResponse = await sdk.sendMessage(
+          "give me 1 post from @elonmusk on x",
+          {
+            room: privateRoom,
+            waitForResponse: true,
+            timeout: 60000
+          }
+        );
+
+        const coordDuration = Date.now() - coordStart;
+        const coordResult: TestResult = {
+          network,
+          type: "coordinator",
+          success: true,
+          response: typeof coordResponse === "string"
+            ? coordResponse.substring(0, 200) + "..."
+            : JSON.stringify(coordResponse).substring(0, 200) + "...",
+          duration: coordDuration
+        };
+
+        // Try to extract tx hash from response
+        if (typeof coordResponse === "object" && coordResponse !== null) {
+          const respObj = coordResponse as Record<string, unknown>;
+          if (respObj.txHash) coordResult.txHash = String(respObj.txHash);
+          if (respObj.payment_tx_hash) coordResult.txHash = String(respObj.payment_tx_hash);
+          if (respObj.paymentTxHash) coordResult.txHash = String(respObj.paymentTxHash);
+          // Check nested metadata
+          const metadata = respObj.metadata as Record<string, unknown> | undefined;
+          if (metadata?.txHash) coordResult.txHash = String(metadata.txHash);
+          if (metadata?.payment_tx_hash) coordResult.txHash = String(metadata.payment_tx_hash);
+        }
+        // Log full response for debugging
+        console.log("Full response:", JSON.stringify(coordResponse, null, 2).substring(0, 1000));
+
+        results.push(coordResult);
+        console.log(`Response (${coordDuration}ms):`);
+        console.log(coordResult.response);
+        if (coordResult.txHash) console.log(`TX Hash: ${coordResult.txHash}`);
+      } catch (error) {
+        const coordDuration = Date.now() - coordStart;
+        results.push({
+          network,
+          type: "coordinator",
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+          duration: coordDuration
+        });
+        console.log(`Error (${coordDuration}ms): ${error instanceof Error ? error.message : error}`);
+      }
+
+    } catch (error) {
+      console.error(`Failed to test ${network}:`, error instanceof Error ? error.message : error);
+    } finally {
+      if (sdk) {
+        await sdk.disconnect();
+        console.log(`\nDisconnected from ${network}`);
+      }
+    }
+
+    // Wait between networks
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  }
+
+  // Print summary
+  console.log(`\n${"=".repeat(70)}`);
+  console.log("TEST RESULTS SUMMARY");
+  console.log("=".repeat(70));
+
+  console.log("\n| Network    | Type        | Success | Duration | TX Hash |");
+  console.log("|------------|-------------|---------|----------|---------|");
+
+  for (const result of results) {
+    const txHash = result.txHash ? result.txHash.substring(0, 10) + "..." : "N/A";
+    console.log(
+      `| ${result.network.padEnd(10)} | ${result.type.padEnd(11)} | ${result.success ? "YES    " : "NO     "} | ${(result.duration + "ms").padEnd(8)} | ${txHash} |`
+    );
+  }
+
+  // Print detailed results
+  console.log("\n--- Detailed Results ---\n");
+  for (const result of results) {
+    console.log(`${result.network.toUpperCase()} - ${result.type}:`);
+    if (result.success) {
+      console.log(`  Response: ${result.response}`);
+      if (result.txHash) console.log(`  TX Hash: ${result.txHash}`);
+    } else {
+      console.log(`  Error: ${result.error}`);
+    }
+    console.log();
+  }
+
+  // Exit
+  process.exit(results.every(r => r.success) ? 0 : 1);
+}
+
+runTest().catch(error => {
+  console.error("Test failed:", error);
+  process.exit(1);
+});