tytyt

SKILL.md

# Teneo SDK Skill

## Overview

The Teneo SDK (`@teneo-protocol/sdk`) enables connection to AI agents on the Teneo Protocol platform. It provides:

- WebSocket-based real-time communication with AI agents
- Wallet-based authentication using Ethereum private keys
- Room management (private/public rooms, agent invitations)
- x402 micropayment protocol for paid agent interactions
- Multi-chain payment support (Base, Peaq, Avalanche)

## Installation

```bash
npm install @teneo-protocol/sdk
# or
pnpm add @teneo-protocol/sdk
```

## Core Concepts

### Rooms
Rooms are communication channels where users interact with AI agents:
- **Private rooms**: Auto-available after authentication, no subscription needed
- **Public rooms**: Require explicit subscription via `subscribeToRoom()`
- Room ownership determines ability to invite agents

### Agents
AI agents are identified by their `@handle` (e.g., `@x-agent-enterprise-v2`). Agents can be:
- Discovered via `listAgents()` or `searchAgents()`
- Invited to private rooms by room owners
- Some require x402 payments for each interaction

### x402 Payment Protocol
Micropayments for agent interactions using USDC on supported chains:
- **Base** (chain ID: 8453) - Recommended for low fees
- **Peaq** (chain ID: 3338)
- **Avalanche** (chain ID: 43114)

Payment amounts are typically $0.01 - $0.10 per request.

## Authentication & Connection

```typescript
import { TeneoSDK } from "@teneo-protocol/sdk";

const sdk = new TeneoSDK({
  wsUrl: "wss://backend.developer.chatroom.teneo-protocol.ai/ws",
  privateKey: "0x...", // Ethereum private key
  logLevel: "silent", // or "debug", "info", "warn", "error"
  maxReconnectAttempts: 30,

  // Payment configuration (required for paid agents)
  paymentNetwork: "eip155:8453", // Base network in CAIP-2 format
  paymentAsset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // Base USDC
});

// Connect (handles WebSocket + wallet signature auth)
await sdk.connect();

// Get authenticated wallet address
const authState = sdk.getAuthState();
console.log(`Authenticated as: ${authState.walletAddress}`);

// Check connection status
if (sdk.isConnected) {
  console.log("Connected!");
}

// Disconnect when done
sdk.disconnect();
```

### Payment Network Configuration

Use CAIP-2 format for `paymentNetwork`:

| Network | CAIP-2 ID | Chain ID | USDC Contract |
|---------|-----------|----------|---------------|
| Base | `eip155:8453` | 8453 | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
| Peaq | `eip155:3338` | 3338 | `0xbbA60da06c2c5424f03f7434542280FCAd453d10` |
| Avalanche | `eip155:43114` | 43114 | `0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E` |

## Room Management

### Discovering Rooms

```typescript
// Get all rooms available to this wallet (sync - cached after connect)
const rooms = sdk.getRooms();

for (const room of rooms) {
  console.log(`Room: ${room.name} [${room.id}]`);
  console.log(`  Public: ${room.is_public}`);
  console.log(`  Owner: ${room.is_owner}`);
}
```

### Subscribing to Rooms

```typescript
// Private rooms: auto-available after auth, no subscription needed
// Public rooms: require explicit subscription

const publicRoom = rooms.find(r => r.is_public);
if (publicRoom) {
  await sdk.subscribeToRoom(publicRoom.id);
}

// Check subscribed rooms
const subscribedRooms = sdk.getSubscribedRooms();
console.log(`Subscribed to: ${subscribedRooms.join(", ")}`);
```

## Agent Discovery & Invitation

### Finding Available Agents

```typescript
// List all available agents on the platform
const agents = await sdk.listAgents();

for (const agent of agents) {
  console.log(`Agent: ${agent.name} (@${agent.handle})`);
  console.log(`  ID: ${agent.agent_id}`);
  console.log(`  Description: ${agent.description}`);
  console.log(`  Price: $${agent.price_per_request || 0}`);
}

// Search for agents by name or keyword
const results = await sdk.searchAgents("twitter");
console.log(`Found ${results.length} agents matching "twitter"`);
```

### Listing Agents in a Room

```typescript
// Get agents currently in a specific room
const roomAgents = await sdk.listRoomAgents(roomId);

for (const agent of roomAgents) {
  console.log(`  - ${agent.name} (${agent.agent_id})`);
}
```

### Inviting Agents to Rooms

Only room owners can invite agents:

```typescript
// First, find the agent you want to invite
const agents = await sdk.listAgents();
const xAgent = agents.find(a => a.handle === "x-agent-enterprise-v2");

if (xAgent) {
  // Add agent to your room by their agent_id
  await sdk.addAgentToRoom(roomId, xAgent.agent_id);
  console.log(`Invited ${xAgent.name} to room`);
}

// Or invite directly by known agent ID
await sdk.addAgentToRoom(roomId, "x-agent-enterprise-v2");
```

### Ensuring Required Agents Are in Room

```typescript
async function ensureAgentsInRoom(
  sdk: TeneoSDK,
  roomId: string,
  requiredAgentIds: string[]
): Promise<void> {
  // Get agents currently in the room
  const roomAgents = await sdk.listRoomAgents(roomId);
  const existingIds = new Set(roomAgents.map(a => a.agent_id?.toLowerCase()));

  // Find missing agents
  const missing = requiredAgentIds.filter(
    id => !existingIds.has(id.toLowerCase())
  );

  // Invite missing agents
  for (const agentId of missing) {
    try {
      await sdk.addAgentToRoom(roomId, agentId);
      console.log(`Invited agent "${agentId}" to room`);
    } catch (err: any) {
      console.warn(`Failed to invite "${agentId}": ${err.message}`);
    }
  }
}

// Usage
await ensureAgentsInRoom(sdk, roomId, [
  "x-agent-enterprise-v2",
  "another-agent-id",
]);
```

## Sending Messages to Agents

### Basic Message

```typescript
const response = await sdk.sendMessage("@x-agent-enterprise-v2 user @elonmusk", {
  waitForResponse: true,
  timeout: 60000, // 60 seconds
  format: "both", // Get both raw content and humanized version
});

console.log(response.humanized || response.content);
```

### Message with Room Context

```typescript
const response = await sdk.sendMessage("@x-agent-enterprise-v2 post_stats 123456", {
  waitForResponse: true,
  timeout: 60000,
  format: "both",
  room: "room-id-here", // Specify target room
});
```

### Common Agent Commands

```typescript
// X/Twitter agent - Get user profile stats
"@x-agent-enterprise-v2 user @username"

// X/Twitter agent - Get post/tweet stats
"@x-agent-enterprise-v2 post_stats 1234567890123456789"
```

## Event Handling

### Agent Responses

```typescript
sdk.on("agent:response", (data) => {
  console.log(`Agent: ${data.agentName || data.agentId}`);
  console.log(`Success: ${data.success}`);
  console.log(`Content: ${data.humanized || data.content}`);

  if (data.error) {
    console.error(`Error: ${data.error}`);
  }
});
```

### Payment Detection

x402 payments are reflected in agent responses. Parse the response to detect payment amounts:

```typescript
sdk.on("agent:response", (data) => {
  const content = data.humanized || data.content || "";

  // Common patterns for payment detection
  const patterns = [
    /x402 Payment \$([0-9.]+)/i,
    /Payment[:\s]+\$([0-9.]+)/i,
    /charged \$([0-9.]+)/i,
    /\$([0-9.]+)\s*(?:USDC|usdc)/i,
  ];

  for (const pattern of patterns) {
    const match = content.match(pattern);
    if (match) {
      const usdAmount = parseFloat(match[1]);
      console.log(`Payment: $${usdAmount} USDC`);
      break;
    }
  }
});
```

### Connection Events

```typescript
sdk.on("connection:open", () => {
  console.log("WebSocket connected");
});

sdk.on("disconnect", () => {
  console.log("Disconnected");
});

sdk.on("ready", () => {
  console.log("SDK ready for messages");
});

sdk.on("error", (err) => {
  // Handle rate limiting
  const rateLimitMatch = err.message.match(/Please wait (\d+)ms/);
  if (rateLimitMatch) {
    const waitMs = parseInt(rateLimitMatch[1], 10);
    console.log(`Rate limited, wait ${waitMs}ms`);
    return;
  }

  // Handle auth failures
  if (err.message.includes("Invalid challenge") ||
      err.message.includes("authentication failed")) {
    console.log("Authentication failed, reconnecting...");
    return;
  }

  console.error(`SDK Error: ${err.message}`);
});
```

## Complete Example: Base Network Agent Interaction

```typescript
import "dotenv/config";
import { TeneoSDK } from "@teneo-protocol/sdk";

// Configuration
const BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
const BASE_NETWORK = "eip155:8453";

async function main() {
  // Initialize SDK with Base payment config
  const sdk = new TeneoSDK({
    wsUrl: "wss://backend.developer.chatroom.teneo-protocol.ai/ws",
    privateKey: process.env.PRIVATE_KEY!,
    logLevel: "info",
    maxReconnectAttempts: 10,
    paymentNetwork: BASE_NETWORK,
    paymentAsset: BASE_USDC,
  });

  // Track payments
  let totalSpent = 0;

  sdk.on("agent:response", (data) => {
    const content = data.humanized || data.content || "";

    // Detect x402 payment
    const match = content.match(/\$([0-9.]+)/);
    if (match) {
      const amount = parseFloat(match[1]);
      if (amount > 0 && amount < 1) { // Sanity check
        totalSpent += amount;
        console.log(`Payment: $${amount} | Total: $${totalSpent.toFixed(4)}`);
      }
    }
  });

  // Connect with retry logic
  for (let attempt = 1; attempt <= 5; attempt++) {
    try {
      await sdk.connect();
      console.log("Connected!");
      break;
    } catch (err: any) {
      // Handle rate limiting
      const rateLimitMatch = err.message?.match(/Please wait (\d+)ms/);
      if (rateLimitMatch) {
        const waitMs = parseInt(rateLimitMatch[1], 10) + 100;
        console.log(`Rate limited, waiting ${waitMs}ms...`);
        await sleep(waitMs);
        continue;
      }
      throw err;
    }
  }

  // Get wallet address
  const authState = sdk.getAuthState();
  console.log(`Wallet: ${authState.walletAddress}`);

  // Find a room (prefer private rooms)
  const rooms = sdk.getRooms();
  let selectedRoom = rooms.find(r => !r.is_public) || rooms[0];

  if (selectedRoom?.is_public) {
    await sdk.subscribeToRoom(selectedRoom.id);
  }

  console.log(`Using room: ${selectedRoom?.name || selectedRoom?.id}`);

  // Discover available agents
  const agents = await sdk.listAgents();
  console.log(`\nAvailable agents (${agents.length}):`);
  for (const agent of agents.slice(0, 5)) {
    console.log(`  - @${agent.handle}: ${agent.name}`);
  }

  // Ensure agent is in room (if we own it)
  if (selectedRoom?.is_owner) {
    try {
      await sdk.addAgentToRoom(selectedRoom.id, "x-agent-enterprise-v2");
      console.log("Agent invited to room");
    } catch (e) {
      // Agent may already be in room
    }
  }

  // Send command to X agent
  console.log("\nSending request to @x-agent-enterprise-v2...");

  const response = await sdk.sendMessage(
    "@x-agent-enterprise-v2 user @VitalikButerin",
    {
      waitForResponse: true,
      timeout: 60000,
      format: "both",
      room: selectedRoom?.id,
    }
  );

  console.log("\nResponse:");
  console.log(response.humanized || response.content);

  // Cleanup
  sdk.disconnect();
  console.log(`\nTotal spent: $${totalSpent.toFixed(4)} USDC`);
}

function sleep(ms: number): Promise<void> {
  return new Promise(resolve => setTimeout(resolve, ms));
}

main().catch(console.error);
```

## Error Handling Best Practices

### Connection Errors

```typescript
async function connectWithRetry(sdk: TeneoSDK, maxAttempts = 10): Promise<void> {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      await sdk.connect();
      return;
    } catch (err: any) {
      const msg = err?.message || String(err);

      // Rate limiting - wait and retry
      const rateLimitMatch = msg.match(/Please wait (\d+)ms/);
      if (rateLimitMatch) {
        const waitMs = parseInt(rateLimitMatch[1], 10) + 100;
        await sleep(waitMs);
        continue;
      }

      // Auth errors - exponential backoff
      if (msg.includes("Invalid challenge") ||
          msg.includes("authentication failed")) {
        const backoff = Math.min(5000 * Math.pow(2, attempt - 1), 60000);
        await sleep(backoff);
        continue;
      }

      // Other errors - shorter retry
      if (attempt < maxAttempts) {
        await sleep(3000 * attempt);
        continue;
      }

      throw err;
    }
  }
}
```

### Payment Errors

```typescript
try {
  const response = await sdk.sendMessage(command, options);
  // Handle success
} catch (err: any) {
  if (err.message.includes("Payment verification failed")) {
    // Insufficient USDC balance - need to fund wallet
    console.log("Payment failed - check USDC balance");
  } else if (err.message.includes("payment")) {
    // Other payment issue
    console.log("Payment error:", err.message);
  }
}
```

## Multi-Network Support

Switch between networks by creating SDK instances with different payment configs:

```typescript
const NETWORKS = {
  base: {
    paymentNetwork: "eip155:8453",
    paymentAsset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  },
  peaq: {
    paymentNetwork: "eip155:3338",
    paymentAsset: "0xbbA60da06c2c5424f03f7434542280FCAd453d10",
  },
  avax: {
    paymentNetwork: "eip155:43114",
    paymentAsset: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
  },
};

function createSDK(network: keyof typeof NETWORKS, privateKey: string): TeneoSDK {
  const config = NETWORKS[network];
  return new TeneoSDK({
    wsUrl: "wss://backend.developer.chatroom.teneo-protocol.ai/ws",
    privateKey,
    paymentNetwork: config.paymentNetwork,
    paymentAsset: config.paymentAsset,
  });
}
```

## Environment Variables

Typical `.env` configuration:

```bash
# Required
PRIVATE_KEY=0x...

# Optional
WS_URL=wss://backend.developer.chatroom.teneo-protocol.ai/ws
ROOM=my-room-name

# Network-specific RPC URLs (for balance checks)
BASE_RPC_URL=https://mainnet.base.org
PEAQ_RPC_URL=https://peaq.api.onfinality.io/public
AVAX_RPC_URL=https://api.avax.network/ext/bc/C/rpc
```

## TypeScript Types

```typescript
interface SDKConfig {
  wsUrl: string;
  privateKey: string;
  logLevel?: "silent" | "debug" | "info" | "warn" | "error";
  maxReconnectAttempts?: number;
  paymentNetwork?: string;  // CAIP-2 format: "eip155:chainId"
  paymentAsset?: string;    // USDC contract address
}

interface Room {
  id: string;
  name: string;
  is_public?: boolean;
  is_owner?: boolean;
}

interface Agent {
  agent_id: string;
  name: string;
  handle: string;
  description?: string;
  price_per_request?: number;
}

interface AgentResponse {
  taskId: string;
  agentId: string;
  agentName?: string;
  content: string;
  success: boolean;
  error?: string;
  humanized?: string;
}

interface MessageOptions {
  waitForResponse?: boolean;
  timeout?: number;
  format?: "raw" | "humanized" | "both";
  room?: string;
}

interface AuthState {
  walletAddress?: string;
}
```

## Tips

1. **Always check USDC balance** before sending paid requests
2. **Use private rooms** when possible - no subscription needed
3. **Handle rate limits gracefully** - the SDK enforces connection limits
4. **Set appropriate timeouts** - agent responses can take 30-60 seconds
5. **Prefer Base network** for lowest transaction fees
6. **Disconnect cleanly** to avoid orphaned WebSocket connections
7. **Discover agents first** - use `listAgents()` to find available agents before inviting