@teneo-protocol/sdk 3.0.1 → 3.1.2

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.2-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
@@ -726,8 +831,8 @@ console.log(NETWORKS); // {}
 await sdk.connect();
 
 // After connect: NETWORKS populated with backend configuration
-console.log(NETWORKS); // { peaq: {...}, base: {...}, avalanche: {...} }
-const networks = getSupportedNetworks(); // ["peaq", "base", "avalanche"]
+console.log(NETWORKS); // { peaq: {...}, base: {...}, avalanche: {...}, "x-layer": {...} }
+const networks = getSupportedNetworks(); // ["peaq", "base", "avalanche", "x-layer"]
 ```
 
 **Key Features:**
@@ -753,7 +858,7 @@ await sdk.connect();
 
 // Get all supported networks (dynamically loaded from backend)
 const networks = getSupportedNetworks();
-console.log(networks); // e.g., ["peaq", "base", "avalanche"]
+console.log(networks); // e.g., ["peaq", "base", "avalanche", "x-layer"]
 
 // Get network by name
 const baseNetwork = getNetwork("base");
@@ -803,6 +908,10 @@ These networks are currently supported (fetched dynamically from backend):
 - High-throughput blockchain
 - Sub-second finality
 
+**X Layer Mainnet (chainId: 196)**
+- OKX's Layer 2 network
+- Low gas fees (OKB native token)
+
 > **Note:** Network configurations are fetched from the backend and may change. Use `getSupportedNetworks()` to get the current list. The SDK automatically handles network selection based on agent requirements.
 
 #### Settlement Router Integration (x402 v2.5)
@@ -1142,6 +1251,117 @@ Your App                    Teneo Backend                 Agent
 
 ---
 
+## 🔗 Wallet Transaction Flow (On-Chain Actions)
+
+Some agents (e.g., Squid Router for cross-chain swaps) need your wallet to sign and submit on-chain transactions. The SDK handles this through a simple event-driven flow.
+
+### How It Works
+
+1. **Agent requests a transaction** — the SDK emits a `wallet:tx_requested` event with the transaction details
+2. **Your app signs and submits** — using your wallet/signer of choice (ethers, viem, web3.js, etc.)
+3. **Your app reports the result** — call `sendTxResult()` so the agent knows what happened
+4. **Agent may request more transactions** — for multi-step operations (e.g., approve + swap), the agent sends additional `trigger_wallet_tx` messages after each result
+
+```
+Your App                    Teneo Backend                 Agent
+   │                             │                          │
+   │                             │<── trigger_wallet_tx ────│  (e.g., "approve USDC")
+   │<── wallet:tx_requested ─────│                          │
+   │                             │                          │
+   │  [Sign & submit tx]         │                          │
+   │                             │                          │
+   │──── tx_result ─────────────>│──── tx_result ──────────>│
+   │    (confirmed + txHash)     │                          │
+   │                             │                          │
+   │                             │<── trigger_wallet_tx ────│  (e.g., "execute swap")
+   │<── wallet:tx_requested ─────│                          │
+   │                             │                          │
+   │  [Sign & submit tx]         │                          │
+   │                             │                          │
+   │──── tx_result ─────────────>│──── tx_result ──────────>│
+   │                             │                          │
+   │<───── task_response ────────│<────── response ─────────│
+   └                             └                          └
+```
+
+### Basic Usage
+
+```typescript
+sdk.on("wallet:tx_requested", async (data) => {
+  console.log(`Transaction requested by ${data.agentName}: ${data.description}`);
+  console.log(`Chain: ${data.tx.chainId}, To: ${data.tx.to}, Value: ${data.tx.value}`);
+
+  try {
+    // Sign and submit using your preferred library
+    const txHash = await wallet.sendTransaction({
+      to: data.tx.to,
+      value: data.tx.value,
+      data: data.tx.data,
+      chainId: data.tx.chainId,
+    });
+
+    // Wait for confirmation
+    const receipt = await provider.waitForTransaction(txHash);
+
+    // Report success — include data.room so the server can route it back to the agent
+    await sdk.sendTxResult(data.taskId, "confirmed", txHash, undefined, data.room);
+  } catch (err) {
+    // Report failure
+    await sdk.sendTxResult(data.taskId, "failed", undefined, err.message, data.room);
+  }
+});
+```
+
+### Rejecting a Transaction
+
+If the transaction is optional (`data.optional === true`) or you don't want to sign:
+
+```typescript
+await sdk.sendTxResult(data.taskId, "rejected", undefined, undefined, data.room);
+```
+
+### Event: `wallet:tx_requested`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `taskId` | `string` | Task identifier — pass this back in `sendTxResult()` |
+| `agentName` | `string?` | Name of the agent requesting the transaction |
+| `tx.to` | `string` | Target contract/address |
+| `tx.value` | `string` | Value in wei |
+| `tx.data` | `string?` | Encoded calldata (for contract interactions) |
+| `tx.chainId` | `number` | Target chain (e.g., `8453` for Base) |
+| `description` | `string?` | Human-readable description of the transaction |
+| `optional` | `boolean` | Whether the user can skip this transaction |
+| `room` | `string?` | Room ID — **must** be passed back in `sendTxResult()` for routing |
+
+### Method: `sendTxResult()`
+
+```typescript
+await sdk.sendTxResult(taskId, status, txHash?, error?, room?)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `taskId` | `string` | The `taskId` from the `wallet:tx_requested` event |
+| `status` | `"confirmed" \| "rejected" \| "failed"` | Transaction outcome |
+| `txHash` | `string?` | On-chain transaction hash (required for `"confirmed"`) |
+| `error` | `string?` | Error message (for `"failed"` status) |
+| `room` | `string?` | Room ID from the `wallet:tx_requested` event (required for routing) |
+
+> **Important:** Always pass `data.room` from the event back into `sendTxResult()`. The server uses this to route the result to the correct agent. Without it, the agent won't receive your response and multi-step transactions will stall.
+
+### Multi-Step Transactions
+
+Some operations require multiple sequential transactions (e.g., ERC-20 approve followed by a swap). The agent handles sequencing — your code just needs to keep listening:
+
+1. Agent sends `trigger_wallet_tx` #1 (approve) → you sign → you call `sendTxResult()`
+2. Agent receives the result, then sends `trigger_wallet_tx` #2 (swap) → you sign → you call `sendTxResult()`
+3. Agent sends `task_response` with the final outcome
+
+Your `wallet:tx_requested` listener stays active for the entire lifecycle. Each transaction arrives as a separate event with the **same `taskId`** but different `tx` data. The task is only resolved when the agent sends the final `task_response`.
+
+---
+
 ## 🎨 Event System
 
 The SDK is fully event-driven. Subscribe to what matters:
@@ -1196,6 +1416,16 @@ sdk.on("room:unsubscribed", (data) => {
 });
 ```
 
+### Wallet Transaction Events
+
+```typescript
+sdk.on("wallet:tx_requested", async (data) => {
+  console.log(`🔗 ${data.agentName} requests tx on chain ${data.tx.chainId}`);
+  console.log(`   ${data.description}`);
+  // See "Wallet Transaction Flow" section for full handling
+});
+```
+
 ---
 
 ## ⚙️ Configuration

package/dist/managers/message-router.d.ts

@@ -9,6 +9,7 @@ import { WebhookHandler } from "../handlers/webhook-handler";
 import { ResponseFormatter, FormattedResponse } from "../formatters/response-formatter";
 import { Logger, ResponseFormat, PricingInfo } from "../types";
 import { SDKEvents } from "../types/events";
+import type { AgentRoomManager } from "./agent-room-manager";
 import type { SecurePrivateKey } from "../utils/secure-private-key";
 export interface SendMessageOptions {
     room: string;
@@ -61,6 +62,7 @@ export interface MessageRouterConfig {
     paymentNetwork?: string;
     paymentAsset?: string;
     network?: string;
+    autoSummon?: boolean;
 }
 export declare class MessageRouter extends EventEmitter<SDKEvents> {
     private readonly wsClient;
@@ -78,6 +80,8 @@ export declare class MessageRouter extends EventEmitter<SDKEvents> {
     private readonly paymentNetwork;
     private readonly paymentAsset;
     private readonly networkName;
+    private readonly autoSummon;
+    private agentRoomManager;
     constructor(wsClient: WebSocketClient, webhookHandler: WebhookHandler, responseFormatter: ResponseFormatter, logger: Logger, config: MessageRouterConfig);
     /**
      * Gets the payment network CAIP-2 identifier, resolving from network name or default.
@@ -94,6 +98,10 @@ export declare class MessageRouter extends EventEmitter<SDKEvents> {
      * Must be called before using requestQuote/confirmQuote with paid tasks.
      */
     setPaymentClient(secureKey: SecurePrivateKey, walletAddress: string): void;
+    /**
+     * Sets the agent room manager for auto-summon functionality (v2.4.0).
+     */
+    setAgentRoomManager(manager: AgentRoomManager): void;
     /**
      * Sends a message to agents via the coordinator.
      * The coordinator intelligently selects the most appropriate agent.
@@ -164,6 +172,33 @@ export declare class MessageRouter extends EventEmitter<SDKEvents> {
      * Returns the quote data for manual confirmation.
      */
     requestQuote(content: string, room: string, networkOverride?: string | number): Promise<QuoteResult>;
+    /**
+     * Internal quote request with error racing and auto-summon support.
+     * @param isRetry - true on auto-summon retry to prevent infinite loops
+     */
+    private _requestQuoteInternal;
+    /**
+     * Pre-flight autosummon: adds agent to room before sending the command.
+     * Called when cache confirms agent is NOT in room, avoiding the reject-retry cycle.
+     */
+    private preFlightAutoSummon;
+    /**
+     * Handles auto-summon: finds the agent, adds it to the room, and retries the quote.
+     * Fallback path triggered by coordinator reject when pre-flight was skipped (cache empty).
+     */
+    private handleAutoSummon;
+    /**
+     * Checks if a message string indicates an agent-access error from the backend.
+     * Matches patterns like:
+     *   - "agent X not found"
+     *   - "agent X does not have access to room Y"
+     *   - "Agent not found. Check the agent name..."
+     */
+    private isAgentAccessErrorMessage;
+    /**
+     * Checks if an error is an "Agent not found / not in room" error from the backend.
+     */
+    private isAgentNotFoundError;
     /**
      * Confirms a quote and executes the task with payment.
      * Can optionally wait for the task response.

package/dist/managers/message-router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"message-router.d.ts","sourceRoot":"","sources":["../../src/managers/message-router.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"message-router.d.ts","sourceRoot":"","sources":["../../src/managers/message-router.ts"],"names":[],"mappings":"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"}

package/dist/managers/message-router.js

@@ -33,6 +33,9 @@ class MessageRouter extends eventemitter3_1.EventEmitter {
     paymentNetwork; // CAIP-2 format if set
     paymentAsset;
     networkName; // Network name (peaq, base, avalanche)
+    // Auto-summon (v2.4.0)
+    autoSummon;
+    agentRoomManager = null;
     constructor(wsClient, webhookHandler, responseFormatter, logger, config) {
         super();
         this.wsClient = wsClient;
@@ -51,6 +54,7 @@ class MessageRouter extends eventemitter3_1.EventEmitter {
         this.paymentNetwork = config.paymentNetwork ?? "";
         this.paymentAsset = config.paymentAsset ?? "";
         this.networkName = config.network ?? "";
+        this.autoSummon = config.autoSummon ?? false;
         this.setupEventForwarding();
     }
     /**
@@ -98,6 +102,12 @@ class MessageRouter extends eventemitter3_1.EventEmitter {
             asset: this.getResolvedPaymentAsset()
         });
     }
+    /**
+     * Sets the agent room manager for auto-summon functionality (v2.4.0).
+     */
+    setAgentRoomManager(manager) {
+        this.agentRoomManager = manager;
+    }
     /**
      * Sends a message to agents via the coordinator.
      * The coordinator intelligently selects the most appropriate agent.
@@ -251,18 +261,82 @@ class MessageRouter extends eventemitter3_1.EventEmitter {
      * Returns the quote data for manual confirmation.
      */
     async requestQuote(content, room, networkOverride) {
+        return this._requestQuoteInternal(content, room, networkOverride, false);
+    }
+    /**
+     * Internal quote request with error racing and auto-summon support.
+     * @param isRetry - true on auto-summon retry to prevent infinite loops
+     */
+    async _requestQuoteInternal(content, room, networkOverride, isRetry) {
         if (!this.wsClient.isConnected) {
             throw new events_1.SDKError("Not connected to Teneo network", error_codes_1.ErrorCode.NOT_CONNECTED);
         }
         // Include payment network in request so backend returns correct contract addresses
         const resolvedNetwork = this.getResolvedPaymentNetwork(networkOverride);
         const message = (0, types_1.createRequestTask)(content, room, resolvedNetwork);
-        this.logger.debug("MessageRouter: Requesting quote", { content, room, network: resolvedNetwork });
+        this.logger.debug("MessageRouter: Requesting quote", { content, room, network: resolvedNetwork, isRetry });
+        // Pre-flight autosummon: check cache before sending to avoid reject-retry cycle
+        if (this.autoSummon && this.agentRoomManager && !isRetry) {
+            const match = content.match(/^@(\S+)/);
+            if (match) {
+                const agentName = match[1];
+                const inRoom = this.agentRoomManager.checkAgentInRoom(room, agentName);
+                if (inRoom === false) {
+                    this.logger.info("MessageRouter: Pre-flight autosummon", { agentName, room });
+                    try {
+                        await this.preFlightAutoSummon(agentName, room);
+                    }
+                    catch (e) {
+                        this.logger.debug("MessageRouter: Pre-flight failed, falling back", { error: e.message });
+                    }
+                }
+            }
+        }
         await this.wsClient.sendMessage(message);
-        const quote = await (0, event_waiter_1.waitForEvent)(this.wsClient, "quote:received", {
+        // Race quote:received against error events to detect "Agent not found" quickly.
+        // The backend may signal "agent not in room" via:
+        //   1. An "error" event with "agent ... not found"
+        //   2. An "agent:response" from the coordinator with content like
+        //      "agent X does not have access to room Y"
+        // We race all three to catch whichever arrives first.
+        const quotePromise = (0, event_waiter_1.waitForEvent)(this.wsClient, "quote:received", {
             timeout: this.quoteTimeout,
             timeoutMessage: `Quote request timed out after ${this.quoteTimeout}ms`
         });
+        const errorPromise = (0, event_waiter_1.waitForEvent)(this.wsClient, "error", {
+            timeout: this.quoteTimeout + 1000,
+            filter: (err) => {
+                const msg = (err.message || "").toLowerCase();
+                return this.isAgentAccessErrorMessage(msg);
+            }
+        });
+        // Also race against agent:response that contains an access-denied error from the coordinator
+        const agentErrorPromise = (0, event_waiter_1.waitForEvent)(this.wsClient, "agent:response", {
+            timeout: this.quoteTimeout + 1000,
+            filter: (resp) => {
+                const msg = (resp.content || "").toLowerCase();
+                return this.isAgentAccessErrorMessage(msg);
+            }
+        });
+        let quote;
+        try {
+            quote = await Promise.race([
+                quotePromise,
+                errorPromise.then((err) => { throw err; }),
+                agentErrorPromise.then((resp) => {
+                    throw new events_1.SDKError(resp.content, error_codes_1.ErrorCode.AGENT_NOT_IN_ROOM);
+                })
+            ]);
+        }
+        catch (error) {
+            if (this.isAgentNotFoundError(error) && !isRetry) {
+                if (this.autoSummon) {
+                    return this.handleAutoSummon(content, room, networkOverride);
+                }
+                throw new events_1.SDKError("Agent not found in room. Enable autoSummon to automatically add agents.", error_codes_1.ErrorCode.AGENT_NOT_IN_ROOM);
+            }
+            throw error;
+        }
         const result = {
             taskId: quote.data.task_id,
             agentId: quote.data.agent_id,
@@ -290,6 +364,73 @@ class MessageRouter extends eventemitter3_1.EventEmitter {
         this.pendingQuotes.set(result.taskId, result);
         return result;
     }
+    /**
+     * Pre-flight autosummon: adds agent to room before sending the command.
+     * Called when cache confirms agent is NOT in room, avoiding the reject-retry cycle.
+     */
+    async preFlightAutoSummon(agentName, room) {
+        if (!this.agentRoomManager) {
+            throw new events_1.SDKError("Auto-summon requires AgentRoomManager", error_codes_1.ErrorCode.AUTOSUMMON_FAILED);
+        }
+        this.wsClient.emit("autosummon:start", agentName, room);
+        const available = await this.agentRoomManager.listAvailableAgents(room, false);
+        const agent = available.find((a) => a.agent_id === agentName || a.agent_name === agentName);
+        if (!agent) {
+            this.wsClient.emit("autosummon:failed", agentName, room, "Agent not found or offline");
+            throw new events_1.SDKError(`Agent '${agentName}' does not exist or is offline`, error_codes_1.ErrorCode.AGENT_NOT_FOUND);
+        }
+        await this.agentRoomManager.addAgentToRoom(room, agent.agent_id);
+        this.wsClient.emit("autosummon:success", agentName, agent.agent_id, room);
+        this.logger.info("MessageRouter: Pre-flight autosummon succeeded", { agentId: agent.agent_id });
+    }
+    /**
+     * Handles auto-summon: finds the agent, adds it to the room, and retries the quote.
+     * Fallback path triggered by coordinator reject when pre-flight was skipped (cache empty).
+     */
+    async handleAutoSummon(content, room, networkOverride) {
+        if (!this.agentRoomManager) {
+            throw new events_1.SDKError("Auto-summon requires AgentRoomManager", error_codes_1.ErrorCode.AUTOSUMMON_FAILED);
+        }
+        const match = content.match(/^@(\S+)/);
+        if (!match) {
+            throw new events_1.SDKError("Cannot extract agent name for auto-summon", error_codes_1.ErrorCode.AUTOSUMMON_FAILED);
+        }
+        const agentName = match[1];
+        this.logger.info("MessageRouter: Auto-summoning agent", { agentName, room });
+        this.wsClient.emit("autosummon:start", agentName, room);
+        const available = await this.agentRoomManager.listAvailableAgents(room, false);
+        const agent = available.find((a) => a.agent_id === agentName || a.agent_name === agentName);
+        if (!agent) {
+            this.wsClient.emit("autosummon:failed", agentName, room, "Agent not found or offline");
+            throw new events_1.SDKError(`Agent '${agentName}' does not exist or is offline`, error_codes_1.ErrorCode.AGENT_NOT_FOUND);
+        }
+        await this.agentRoomManager.addAgentToRoom(room, agent.agent_id);
+        this.wsClient.emit("autosummon:success", agentName, agent.agent_id, room);
+        this.logger.info("MessageRouter: Agent auto-summoned, retrying", { agentId: agent.agent_id });
+        return this._requestQuoteInternal(content, room, networkOverride, true);
+    }
+    /**
+     * Checks if a message string indicates an agent-access error from the backend.
+     * Matches patterns like:
+     *   - "agent X not found"
+     *   - "agent X does not have access to room Y"
+     *   - "Agent not found. Check the agent name..."
+     */
+    isAgentAccessErrorMessage(msg) {
+        if (!msg.includes("agent"))
+            return false;
+        return (msg.includes("not found") ||
+            msg.includes("does not have access") ||
+            msg.includes("not in room") ||
+            msg.includes("no access"));
+    }
+    /**
+     * Checks if an error is an "Agent not found / not in room" error from the backend.
+     */
+    isAgentNotFoundError(error) {
+        const msg = (error instanceof Error ? error.message : String(error)).toLowerCase();
+        return this.isAgentAccessErrorMessage(msg);
+    }
     /**
      * Confirms a quote and executes the task with payment.
      * Can optionally wait for the task response.