@teneo-protocol/sdk 3.0.0 → 3.1.1

package/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to the Teneo Protocol SDK will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.1.1] - 2026-02-19
+
+### ✨ Pre-Flight Auto-Summon
+
+The SDK now automatically adds missing agents to your room before sending commands, eliminating coordinator reject→retry cycles.
+
+- **Pre-flight cache check**: Before sending a command, the SDK checks if the target agent is already in the room
+- **Automatic addition**: If the agent is missing, it's added to the room before the command is sent
+- **Lifecycle events**: `autosummon:start`, `autosummon:success`, `autosummon:failed` for full observability
+- **Fallback path**: If pre-flight fails or cache is empty, falls back to coordinator-triggered auto-summon
+- **Configuration**: Enable with `autoSummon: true` or `.withAutoSummon(true)` in the builder
+
+### 🔐 Private Key Validation
+
+- Constructor now validates private key format (64 hex characters / 32 bytes)
+- Catches empty strings, malformed keys, and too-short keys immediately
+- Prevents cryptic signing errors downstream
+
+
+---
+
 ## [3.0.0] - 2026-01-28
 
 *Built on top of v2.3.0 multi-network support*

package/README.md

@@ -2,7 +2,7 @@
 
 **Connect your app to the Teneo AI Agent Network**
 
-[![npm version](https://img.shields.io/badge/version-3.0.0-blue)](https://www.npmjs.com/package/@teneo-protocol/sdk)
+[![npm version](https://img.shields.io/badge/version-3.1.1-blue)](https://www.npmjs.com/package/@teneo-protocol/sdk)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green)](https://nodejs.org/)
 [![Tests](https://img.shields.io/badge/tests-671%20passing-success)](/)
@@ -15,6 +15,46 @@ The Teneo Protocol SDK lets you connect your application to a **decentralized ne
 
 ---
 
+## 🎉 What's New in v3.1.1
+
+### 🤖 Pre-Flight Auto-Summon
+
+The SDK now automatically detects when an agent is missing from your room and adds it **before** sending your command — no more failed requests or retry cycles:
+
+```typescript
+const sdk = new TeneoSDK({
+  wsUrl: process.env.WS_URL,
+  privateKey: process.env.PRIVATE_KEY,
+  autoSummon: true // Enable auto-summon
+});
+
+// Agent not in room? SDK handles it automatically:
+// 1. Checks local cache → agent missing
+// 2. Fires autosummon:start
+// 3. Adds agent to room
+// 4. Fires autosummon:success
+// 5. Sends your command
+await sdk.sendDirectCommand({
+  agent: "example-agent",
+  command: "latest 2h",
+  room: roomId
+}, true);
+```
+
+**Lifecycle events** for full visibility:
+
+- `autosummon:start` — agent addition initiated
+- `autosummon:success` — agent added, command proceeding
+- `autosummon:failed` — agent not found or addition failed, falls back to coordinator
+
+### 🔐 Private Key Validation
+
+Constructor now validates private key format immediately, catching empty or malformed keys before they cause cryptic signing errors downstream.
+
+[See Full CHANGELOG](CHANGELOG.md#311---2026-02-19)
+
+---
+
 ## 🎉 What's New in v3.0
 
 Version 3.0 introduces **API Naming Improvements** for better clarity and consistency:
@@ -623,6 +663,71 @@ sdk.on("agent_room:list_available_error", (error) => {
 });
 ```
 
+### Auto-Summon
+
+When you send a command to an agent that isn't in your room yet, the SDK can automatically add it for you. No manual `addAgentToRoom()` call needed — just send your command and the SDK handles the rest.
+
+#### Setup
+
+```typescript
+const sdk = new TeneoSDK(
+  TeneoSDK.builder()
+    .withWebSocketUrl(process.env.TENEO_WS_URL!)
+    .withAuthentication(process.env.PRIVATE_KEY!)
+    .withAutoSummon(true)  // Enable auto-summon
+    .withNetwork("base")
+    .build()
+);
+
+await sdk.connect();
+```
+
+#### How It Works
+
+```typescript
+// Just send a command — the agent doesn't need to be in your room
+const response = await sdk.sendDirectCommand({
+  agent: "example-agent",
+  command: "latest 2h",
+  room: roomId
+}, true);
+
+// Behind the scenes:
+// 1. SDK checks if agent is in the room (instant cache lookup)
+// 2. If not -> automatically adds the agent to your room
+// 3. Sends your command to the agent
+// 4. Returns the response
+console.log(response.humanized);
+```
+
+#### Auto-Summon Events
+
+Track the auto-summon lifecycle to show loading states in your UI:
+
+```typescript
+// Agent is being added to the room
+sdk.on("autosummon:start", (agentName, roomId) => {
+  showLoadingState(`Adding ${agentName} to your room...`);
+});
+
+// Agent was successfully added — command is now being processed
+sdk.on("autosummon:success", (agentName, agentId, roomId) => {
+  showNotification(`${agentName} joined your room`);
+});
+
+// Agent could not be added (doesn't exist, is offline, etc.)
+sdk.on("autosummon:failed", (agentName, roomId, reason) => {
+  showError(`Could not add ${agentName}: ${reason}`);
+});
+```
+
+#### Behavior Notes
+
+- **No duplicates**: If the agent is already in the room, the SDK skips the summon and sends your command directly.
+- **Works with any message method**: Auto-summon triggers from both `sendDirectCommand()` and `sendMessage()` when the message targets an `@agent`.
+- **Graceful fallback**: If the local cache is empty (e.g., first connection), the SDK falls back to server-side detection — your command still works, just with a small extra round trip.
+- **Room ownership required**: Auto-summon only works in rooms you own, since adding agents requires owner permissions.
+
 ### Complete Example: Room Setup
 
 ```typescript