@gopherhole/sdk 0.1.2 → 0.1.4

package/README.md

@@ -48,6 +48,7 @@ new GopherHole(options: GopherHoleOptions)
 - `autoReconnect` - Auto-reconnect on disconnect (default: true)
 - `reconnectDelay` - Initial reconnect delay in ms (default: 1000)
 - `maxReconnectAttempts` - Max reconnect attempts (default: 10)
+- `requestTimeout` - Default HTTP request timeout in ms (default: 30000)
 
 ### Methods
 
@@ -63,6 +64,25 @@ Send a message to another agent.
 #### `sendText(toAgentId: string, text: string, options?: SendOptions): Promise<Task>`
 Send a text message to another agent.
 
+#### `sendTextAndWait(toAgentId: string, text: string, options?: SendAndWaitOptions): Promise<Task>`
+Send a text message and wait for the task to complete. Polls until the task reaches a terminal state.
+
+**SendAndWaitOptions:**
+- `timeoutMs` - Request timeout in ms (overrides default)
+- `pollIntervalMs` - Polling interval in ms (default: 1000)
+- `maxWaitMs` - Maximum wait time in ms (default: 300000 = 5 min)
+
+#### `askText(toAgentId: string, text: string, options?: SendAndWaitOptions): Promise<string>`
+Send a text message and wait for the text response. This is the simplest way to get a response from another agent - it handles all the polling and text extraction automatically.
+
+```typescript
+const response = await hub.askText('weather-agent', 'What is the weather in Auckland?');
+console.log(response); // "Currently 18°C and sunny in Auckland"
+```
+
+#### `waitForTask(taskId: string, options?: SendAndWaitOptions): Promise<Task>`
+Wait for an existing task to complete by polling.
+
 #### `reply(taskId: string, payload: MessagePayload): Promise<Task>`
 Reply to an existing conversation.
 
@@ -102,6 +122,21 @@ hub.on('error', (error) => {
 });
 ```
 
+### Helper Functions
+
+#### `getTaskResponseText(task: Task): string`
+Extract text response from a completed task. Checks `artifacts` first (where responses from other agents appear), then falls back to `history`.
+
+```typescript
+import { GopherHole, getTaskResponseText } from '@gopherhole/sdk';
+
+const task = await hub.sendTextAndWait('agent-id', 'Hello!');
+const responseText = getTaskResponseText(task);
+console.log(responseText);
+```
+
+> **Note:** Response text is typically found in `task.artifacts[].parts`, not `task.history`. Use this helper or the `askText()` method to avoid having to know the internal structure.
+
 ### Types
 
 ```typescript
@@ -142,6 +177,30 @@ interface TaskStatus {
 
 ## Examples
 
+### Send and Wait for Response
+
+```typescript
+import { GopherHole, getTaskResponseText } from '@gopherhole/sdk';
+
+const hub = new GopherHole({
+  apiKey: process.env.GOPHERHOLE_API_KEY!,
+  requestTimeout: 60000, // 60s default timeout
+});
+
+// Option 1: Use askText() for simplest usage
+const response = await hub.askText('weather-agent', 'What is the weather in Auckland?');
+console.log('Response:', response);
+
+// Option 2: Use sendTextAndWait() with helper function for more control
+const task = await hub.sendTextAndWait('weather-agent', 'What is the weather in Auckland?', {
+  maxWaitMs: 120000,    // Wait up to 2 minutes
+  pollIntervalMs: 2000, // Poll every 2 seconds
+});
+const responseText = getTaskResponseText(task);
+console.log('Response:', responseText);
+console.log('Task status:', task.status.state);
+```
+
 ### Echo Bot
 
 ```typescript

package/dist/index.d.mts

@@ -192,6 +192,8 @@ interface GopherHoleOptions {
     reconnectDelay?: number;
     /** Max reconnect attempts */
     maxReconnectAttempts?: number;
+    /** Default request timeout in ms (default: 30000) */
+    requestTimeout?: number;
 }
 /** Agent card configuration for registration */
 interface AgentCardConfig {
@@ -241,11 +243,18 @@ interface TaskStatus {
     message?: string;
 }
 interface Artifact {
-    name: string;
-    mimeType: string;
+    name?: string;
+    artifactId?: string;
+    mimeType?: string;
+    parts?: MessagePart[];
     data?: string;
     uri?: string;
 }
+/**
+ * Extract text response from a completed task.
+ * Checks artifacts first (where responses live), then falls back to history.
+ */
+declare function getTaskResponseText(task: Task): string;
 interface SendOptions {
     /** Existing context/conversation ID */
     contextId?: string;
@@ -253,6 +262,14 @@ interface SendOptions {
     pushNotificationUrl?: string;
     /** History length to include */
     historyLength?: number;
+    /** Request timeout in ms (overrides default) */
+    timeoutMs?: number;
+}
+interface SendAndWaitOptions extends SendOptions {
+    /** Polling interval in ms (default: 1000) */
+    pollIntervalMs?: number;
+    /** Max wait time in ms (default: 300000 = 5 min) */
+    maxWaitMs?: number;
 }
 type EventMap = {
     connect: () => void;
@@ -269,6 +286,7 @@ declare class GopherHole extends EventEmitter<EventMap> {
     private autoReconnect;
     private reconnectDelay;
     private maxReconnectAttempts;
+    private requestTimeout;
     private reconnectAttempts;
     private reconnectTimer;
     private pingInterval;
@@ -295,6 +313,20 @@ declare class GopherHole extends EventEmitter<EventMap> {
      * Send a text message to another agent
      */
     sendText(toAgentId: string, text: string, options?: SendOptions): Promise<Task>;
+    /**
+     * Send a text message and wait for completion
+     * Returns the completed task with response artifacts
+     */
+    sendTextAndWait(toAgentId: string, text: string, options?: SendAndWaitOptions): Promise<Task>;
+    /**
+     * Send a text message and wait for the text response
+     * This is a convenience method that extracts the response text automatically
+     */
+    askText(toAgentId: string, text: string, options?: SendAndWaitOptions): Promise<string>;
+    /**
+     * Wait for a task to complete (polling)
+     */
+    waitForTask(taskId: string, options?: SendAndWaitOptions): Promise<Task>;
     /**
      * Get a task by ID
      */
@@ -502,4 +534,4 @@ interface RatingResult {
     ratingCount: number;
 }
 
-export { type A2AArtifact, type A2AMessage, type A2ATask, type A2ATaskStatus, type AgentAuthentication, type AgentCapabilities, type AgentCard, type AgentCardConfig, type AgentCategory, type AgentInfoResult, type AgentReview, type AgentSkill, type AgentSkillConfig, type Artifact, type ContentMode, type DataContent, type DataPart, type DiscoverOptions, type DiscoverResult, type FileContent, type FilePart, GopherHole, type GopherHoleOptions, type InputMode, type JsonRpcError, JsonRpcErrorCodes, type JsonRpcRequest, type JsonRpcResponse, type Message, type MessagePart, type MessagePayload, type MessageSendConfiguration, type OutputMode, type Part, type PublicAgent, type PushNotificationConfig, type RatingResult, type SendOptions, type Task, type TaskArtifactUpdateEvent, type TaskEvent, type TaskListConfiguration, type TaskPushNotificationConfig, type TaskQueryConfiguration, type TaskState, type TaskStatus, type TaskStatusUpdateEvent, type TextPart, GopherHole as default };
+export { type A2AArtifact, type A2AMessage, type A2ATask, type A2ATaskStatus, type AgentAuthentication, type AgentCapabilities, type AgentCard, type AgentCardConfig, type AgentCategory, type AgentInfoResult, type AgentReview, type AgentSkill, type AgentSkillConfig, type Artifact, type ContentMode, type DataContent, type DataPart, type DiscoverOptions, type DiscoverResult, type FileContent, type FilePart, GopherHole, type GopherHoleOptions, type InputMode, type JsonRpcError, JsonRpcErrorCodes, type JsonRpcRequest, type JsonRpcResponse, type Message, type MessagePart, type MessagePayload, type MessageSendConfiguration, type OutputMode, type Part, type PublicAgent, type PushNotificationConfig, type RatingResult, type SendAndWaitOptions, type SendOptions, type Task, type TaskArtifactUpdateEvent, type TaskEvent, type TaskListConfiguration, type TaskPushNotificationConfig, type TaskQueryConfiguration, type TaskState, type TaskStatus, type TaskStatusUpdateEvent, type TextPart, GopherHole as default, getTaskResponseText };

package/dist/index.d.ts

@@ -192,6 +192,8 @@ interface GopherHoleOptions {
     reconnectDelay?: number;
     /** Max reconnect attempts */
     maxReconnectAttempts?: number;
+    /** Default request timeout in ms (default: 30000) */
+    requestTimeout?: number;
 }
 /** Agent card configuration for registration */
 interface AgentCardConfig {
@@ -241,11 +243,18 @@ interface TaskStatus {
     message?: string;
 }
 interface Artifact {
-    name: string;
-    mimeType: string;
+    name?: string;
+    artifactId?: string;
+    mimeType?: string;
+    parts?: MessagePart[];
     data?: string;
     uri?: string;
 }
+/**
+ * Extract text response from a completed task.
+ * Checks artifacts first (where responses live), then falls back to history.
+ */
+declare function getTaskResponseText(task: Task): string;
 interface SendOptions {
     /** Existing context/conversation ID */
     contextId?: string;
@@ -253,6 +262,14 @@ interface SendOptions {
     pushNotificationUrl?: string;
     /** History length to include */
     historyLength?: number;
+    /** Request timeout in ms (overrides default) */
+    timeoutMs?: number;
+}
+interface SendAndWaitOptions extends SendOptions {
+    /** Polling interval in ms (default: 1000) */
+    pollIntervalMs?: number;
+    /** Max wait time in ms (default: 300000 = 5 min) */
+    maxWaitMs?: number;
 }
 type EventMap = {
     connect: () => void;
@@ -269,6 +286,7 @@ declare class GopherHole extends EventEmitter<EventMap> {
     private autoReconnect;
     private reconnectDelay;
     private maxReconnectAttempts;
+    private requestTimeout;
     private reconnectAttempts;
     private reconnectTimer;
     private pingInterval;
@@ -295,6 +313,20 @@ declare class GopherHole extends EventEmitter<EventMap> {
      * Send a text message to another agent
      */
     sendText(toAgentId: string, text: string, options?: SendOptions): Promise<Task>;
+    /**
+     * Send a text message and wait for completion
+     * Returns the completed task with response artifacts
+     */
+    sendTextAndWait(toAgentId: string, text: string, options?: SendAndWaitOptions): Promise<Task>;
+    /**
+     * Send a text message and wait for the text response
+     * This is a convenience method that extracts the response text automatically
+     */
+    askText(toAgentId: string, text: string, options?: SendAndWaitOptions): Promise<string>;
+    /**
+     * Wait for a task to complete (polling)
+     */
+    waitForTask(taskId: string, options?: SendAndWaitOptions): Promise<Task>;
     /**
      * Get a task by ID
      */
@@ -502,4 +534,4 @@ interface RatingResult {
     ratingCount: number;
 }
 
-export { type A2AArtifact, type A2AMessage, type A2ATask, type A2ATaskStatus, type AgentAuthentication, type AgentCapabilities, type AgentCard, type AgentCardConfig, type AgentCategory, type AgentInfoResult, type AgentReview, type AgentSkill, type AgentSkillConfig, type Artifact, type ContentMode, type DataContent, type DataPart, type DiscoverOptions, type DiscoverResult, type FileContent, type FilePart, GopherHole, type GopherHoleOptions, type InputMode, type JsonRpcError, JsonRpcErrorCodes, type JsonRpcRequest, type JsonRpcResponse, type Message, type MessagePart, type MessagePayload, type MessageSendConfiguration, type OutputMode, type Part, type PublicAgent, type PushNotificationConfig, type RatingResult, type SendOptions, type Task, type TaskArtifactUpdateEvent, type TaskEvent, type TaskListConfiguration, type TaskPushNotificationConfig, type TaskQueryConfiguration, type TaskState, type TaskStatus, type TaskStatusUpdateEvent, type TextPart, GopherHole as default };
+export { type A2AArtifact, type A2AMessage, type A2ATask, type A2ATaskStatus, type AgentAuthentication, type AgentCapabilities, type AgentCard, type AgentCardConfig, type AgentCategory, type AgentInfoResult, type AgentReview, type AgentSkill, type AgentSkillConfig, type Artifact, type ContentMode, type DataContent, type DataPart, type DiscoverOptions, type DiscoverResult, type FileContent, type FilePart, GopherHole, type GopherHoleOptions, type InputMode, type JsonRpcError, JsonRpcErrorCodes, type JsonRpcRequest, type JsonRpcResponse, type Message, type MessagePart, type MessagePayload, type MessageSendConfiguration, type OutputMode, type Part, type PublicAgent, type PushNotificationConfig, type RatingResult, type SendAndWaitOptions, type SendOptions, type Task, type TaskArtifactUpdateEvent, type TaskEvent, type TaskListConfiguration, type TaskPushNotificationConfig, type TaskQueryConfiguration, type TaskState, type TaskStatus, type TaskStatusUpdateEvent, type TextPart, GopherHole as default, getTaskResponseText };

package/dist/index.js

@@ -22,7 +22,8 @@ var index_exports = {};
 __export(index_exports, {
   GopherHole: () => GopherHole,
   JsonRpcErrorCodes: () => JsonRpcErrorCodes,
-  default: () => index_default
+  default: () => index_default,
+  getTaskResponseText: () => getTaskResponseText
 });
 module.exports = __toCommonJS(index_exports);
 var import_eventemitter3 = require("eventemitter3");
@@ -44,6 +45,38 @@ var JsonRpcErrorCodes = {
 };
 
 // src/index.ts
+function getTaskResponseText(task) {
+  if (task.artifacts?.length) {
+    const texts = [];
+    for (const artifact of task.artifacts) {
+      if (artifact.parts) {
+        for (const part of artifact.parts) {
+          if (part.kind === "text" && part.text) {
+            texts.push(part.text);
+          }
+        }
+      }
+    }
+    if (texts.length > 0) {
+      return texts.join("\n");
+    }
+  }
+  if (task.history?.length) {
+    const lastMessage = task.history[task.history.length - 1];
+    if (lastMessage.parts) {
+      const texts = [];
+      for (const part of lastMessage.parts) {
+        if (part.kind === "text" && part.text) {
+          texts.push(part.text);
+        }
+      }
+      if (texts.length > 0) {
+        return texts.join("\n");
+      }
+    }
+  }
+  return "";
+}
 var DEFAULT_HUB_URL = "wss://gopherhole.helixdata.workers.dev/ws";
 var GopherHole = class extends import_eventemitter3.EventEmitter {
   constructor(apiKeyOrOptions) {
@@ -62,6 +95,7 @@ var GopherHole = class extends import_eventemitter3.EventEmitter {
     this.autoReconnect = options.autoReconnect ?? true;
     this.reconnectDelay = options.reconnectDelay ?? 1e3;
     this.maxReconnectAttempts = options.maxReconnectAttempts ?? 10;
+    this.requestTimeout = options.requestTimeout ?? 3e4;
   }
   /**
    * Update agent card (sends to hub if connected)
@@ -132,13 +166,14 @@ var GopherHole = class extends import_eventemitter3.EventEmitter {
    * Send a message to another agent
    */
   async send(toAgentId, payload, options) {
+    const { timeoutMs, ...config } = options || {};
     const response = await this.rpc("message/send", {
       message: payload,
       configuration: {
         agentId: toAgentId,
-        ...options
+        ...config
       }
-    });
+    }, timeoutMs);
     return response;
   }
   /**
@@ -150,6 +185,41 @@ var GopherHole = class extends import_eventemitter3.EventEmitter {
       parts: [{ kind: "text", text }]
     }, options);
   }
+  /**
+   * Send a text message and wait for completion
+   * Returns the completed task with response artifacts
+   */
+  async sendTextAndWait(toAgentId, text, options) {
+    const task = await this.sendText(toAgentId, text, options);
+    return this.waitForTask(task.id, options);
+  }
+  /**
+   * Send a text message and wait for the text response
+   * This is a convenience method that extracts the response text automatically
+   */
+  async askText(toAgentId, text, options) {
+    const task = await this.sendTextAndWait(toAgentId, text, options);
+    if (task.status.state === "failed") {
+      throw new Error(task.status.message || "Task failed");
+    }
+    return getTaskResponseText(task);
+  }
+  /**
+   * Wait for a task to complete (polling)
+   */
+  async waitForTask(taskId, options) {
+    const pollInterval = options?.pollIntervalMs ?? 1e3;
+    const maxWait = options?.maxWaitMs ?? 3e5;
+    const startTime = Date.now();
+    while (Date.now() - startTime < maxWait) {
+      const task = await this.getTask(taskId);
+      if (task.status.state === "completed" || task.status.state === "failed" || task.status.state === "canceled" || task.status.state === "rejected") {
+        return task;
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+    throw new Error(`Task ${taskId} did not complete within ${maxWait}ms`);
+  }
   /**
    * Get a task by ID
    */
@@ -209,25 +279,38 @@ var GopherHole = class extends import_eventemitter3.EventEmitter {
   /**
    * Make a JSON-RPC call to the A2A endpoint
    */
-  async rpc(method, params) {
-    const response = await fetch(`${this.apiUrl}/a2a`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "Authorization": `Bearer ${this.apiKey}`
-      },
-      body: JSON.stringify({
-        jsonrpc: "2.0",
-        method,
-        params,
-        id: Date.now()
-      })
-    });
-    const data = await response.json();
-    if (data.error) {
-      throw new Error(data.error.message || "RPC error");
+  async rpc(method, params, timeoutMs) {
+    const timeout = timeoutMs ?? this.requestTimeout;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+      const response = await fetch(`${this.apiUrl}/a2a`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          method,
+          params,
+          id: Date.now()
+        }),
+        signal: controller.signal
+      });
+      const data = await response.json();
+      if (data.error) {
+        throw new Error(data.error.message || "RPC error");
+      }
+      return data.result;
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new Error(`Request timeout after ${timeout}ms`);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timeoutId);
     }
-    return data.result;
   }
   /**
    * Handle incoming WebSocket messages
@@ -455,5 +538,6 @@ var index_default = GopherHole;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   GopherHole,
-  JsonRpcErrorCodes
+  JsonRpcErrorCodes,
+  getTaskResponseText
 });

package/dist/index.mjs

@@ -25,6 +25,38 @@ var JsonRpcErrorCodes = {
 };
 
 // src/index.ts
+function getTaskResponseText(task) {
+  if (task.artifacts?.length) {
+    const texts = [];
+    for (const artifact of task.artifacts) {
+      if (artifact.parts) {
+        for (const part of artifact.parts) {
+          if (part.kind === "text" && part.text) {
+            texts.push(part.text);
+          }
+        }
+      }
+    }
+    if (texts.length > 0) {
+      return texts.join("\n");
+    }
+  }
+  if (task.history?.length) {
+    const lastMessage = task.history[task.history.length - 1];
+    if (lastMessage.parts) {
+      const texts = [];
+      for (const part of lastMessage.parts) {
+        if (part.kind === "text" && part.text) {
+          texts.push(part.text);
+        }
+      }
+      if (texts.length > 0) {
+        return texts.join("\n");
+      }
+    }
+  }
+  return "";
+}
 var DEFAULT_HUB_URL = "wss://gopherhole.helixdata.workers.dev/ws";
 var GopherHole = class extends EventEmitter {
   constructor(apiKeyOrOptions) {
@@ -43,6 +75,7 @@ var GopherHole = class extends EventEmitter {
     this.autoReconnect = options.autoReconnect ?? true;
     this.reconnectDelay = options.reconnectDelay ?? 1e3;
     this.maxReconnectAttempts = options.maxReconnectAttempts ?? 10;
+    this.requestTimeout = options.requestTimeout ?? 3e4;
   }
   /**
    * Update agent card (sends to hub if connected)
@@ -113,13 +146,14 @@ var GopherHole = class extends EventEmitter {
    * Send a message to another agent
    */
   async send(toAgentId, payload, options) {
+    const { timeoutMs, ...config } = options || {};
     const response = await this.rpc("message/send", {
       message: payload,
       configuration: {
         agentId: toAgentId,
-        ...options
+        ...config
       }
-    });
+    }, timeoutMs);
     return response;
   }
   /**
@@ -131,6 +165,41 @@ var GopherHole = class extends EventEmitter {
       parts: [{ kind: "text", text }]
     }, options);
   }
+  /**
+   * Send a text message and wait for completion
+   * Returns the completed task with response artifacts
+   */
+  async sendTextAndWait(toAgentId, text, options) {
+    const task = await this.sendText(toAgentId, text, options);
+    return this.waitForTask(task.id, options);
+  }
+  /**
+   * Send a text message and wait for the text response
+   * This is a convenience method that extracts the response text automatically
+   */
+  async askText(toAgentId, text, options) {
+    const task = await this.sendTextAndWait(toAgentId, text, options);
+    if (task.status.state === "failed") {
+      throw new Error(task.status.message || "Task failed");
+    }
+    return getTaskResponseText(task);
+  }
+  /**
+   * Wait for a task to complete (polling)
+   */
+  async waitForTask(taskId, options) {
+    const pollInterval = options?.pollIntervalMs ?? 1e3;
+    const maxWait = options?.maxWaitMs ?? 3e5;
+    const startTime = Date.now();
+    while (Date.now() - startTime < maxWait) {
+      const task = await this.getTask(taskId);
+      if (task.status.state === "completed" || task.status.state === "failed" || task.status.state === "canceled" || task.status.state === "rejected") {
+        return task;
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+    throw new Error(`Task ${taskId} did not complete within ${maxWait}ms`);
+  }
   /**
    * Get a task by ID
    */
@@ -190,25 +259,38 @@ var GopherHole = class extends EventEmitter {
   /**
    * Make a JSON-RPC call to the A2A endpoint
    */
-  async rpc(method, params) {
-    const response = await fetch(`${this.apiUrl}/a2a`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "Authorization": `Bearer ${this.apiKey}`
-      },
-      body: JSON.stringify({
-        jsonrpc: "2.0",
-        method,
-        params,
-        id: Date.now()
-      })
-    });
-    const data = await response.json();
-    if (data.error) {
-      throw new Error(data.error.message || "RPC error");
+  async rpc(method, params, timeoutMs) {
+    const timeout = timeoutMs ?? this.requestTimeout;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+      const response = await fetch(`${this.apiUrl}/a2a`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          method,
+          params,
+          id: Date.now()
+        }),
+        signal: controller.signal
+      });
+      const data = await response.json();
+      if (data.error) {
+        throw new Error(data.error.message || "RPC error");
+      }
+      return data.result;
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new Error(`Request timeout after ${timeout}ms`);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timeoutId);
     }
-    return data.result;
   }
   /**
    * Handle incoming WebSocket messages
@@ -436,5 +518,6 @@ var index_default = GopherHole;
 export {
   GopherHole,
   JsonRpcErrorCodes,
-  index_default as default
+  index_default as default,
+  getTaskResponseText
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gopherhole/sdk",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "GopherHole SDK - Connect AI agents via the A2A protocol",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/index.ts

@@ -16,6 +16,8 @@ export interface GopherHoleOptions {
   reconnectDelay?: number;
   /** Max reconnect attempts */
   maxReconnectAttempts?: number;
+  /** Default request timeout in ms (default: 30000) */
+  requestTimeout?: number;
 }
 
 /** Agent card configuration for registration */
@@ -73,12 +75,55 @@ export interface TaskStatus {
 }
 
 export interface Artifact {
-  name: string;
-  mimeType: string;
+  name?: string;
+  artifactId?: string;
+  mimeType?: string;
+  parts?: MessagePart[];
   data?: string;
   uri?: string;
 }
 
+/**
+ * Extract text response from a completed task.
+ * Checks artifacts first (where responses live), then falls back to history.
+ */
+export function getTaskResponseText(task: Task): string {
+  // Check artifacts first (this is where responses from other agents appear)
+  if (task.artifacts?.length) {
+    const texts: string[] = [];
+    for (const artifact of task.artifacts) {
+      if (artifact.parts) {
+        for (const part of artifact.parts) {
+          if (part.kind === 'text' && part.text) {
+            texts.push(part.text);
+          }
+        }
+      }
+    }
+    if (texts.length > 0) {
+      return texts.join('\n');
+    }
+  }
+
+  // Fall back to history (last message)
+  if (task.history?.length) {
+    const lastMessage = task.history[task.history.length - 1];
+    if (lastMessage.parts) {
+      const texts: string[] = [];
+      for (const part of lastMessage.parts) {
+        if (part.kind === 'text' && part.text) {
+          texts.push(part.text);
+        }
+      }
+      if (texts.length > 0) {
+        return texts.join('\n');
+      }
+    }
+  }
+
+  return '';
+}
+
 export interface SendOptions {
   /** Existing context/conversation ID */
   contextId?: string;
@@ -86,6 +131,15 @@ export interface SendOptions {
   pushNotificationUrl?: string;
   /** History length to include */
   historyLength?: number;
+  /** Request timeout in ms (overrides default) */
+  timeoutMs?: number;
+}
+
+export interface SendAndWaitOptions extends SendOptions {
+  /** Polling interval in ms (default: 1000) */
+  pollIntervalMs?: number;
+  /** Max wait time in ms (default: 300000 = 5 min) */
+  maxWaitMs?: number;
 }
 
 type EventMap = {
@@ -107,6 +161,7 @@ export class GopherHole extends EventEmitter<EventMap> {
   private autoReconnect: boolean;
   private reconnectDelay: number;
   private maxReconnectAttempts: number;
+  private requestTimeout: number;
   private reconnectAttempts = 0;
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
   private pingInterval: ReturnType<typeof setInterval> | null = null;
@@ -127,6 +182,7 @@ export class GopherHole extends EventEmitter<EventMap> {
     this.autoReconnect = options.autoReconnect ?? true;
     this.reconnectDelay = options.reconnectDelay ?? 1000;
     this.maxReconnectAttempts = options.maxReconnectAttempts ?? 10;
+    this.requestTimeout = options.requestTimeout ?? 30000;
   }
   
   /**
@@ -209,13 +265,14 @@ export class GopherHole extends EventEmitter<EventMap> {
    * Send a message to another agent
    */
   async send(toAgentId: string, payload: MessagePayload, options?: SendOptions): Promise<Task> {
+    const { timeoutMs, ...config } = options || {};
     const response = await this.rpc('message/send', {
       message: payload,
       configuration: {
         agentId: toAgentId,
-        ...options,
+        ...config,
       },
-    });
+    }, timeoutMs);
 
     return response as Task;
   }
@@ -230,6 +287,50 @@ export class GopherHole extends EventEmitter<EventMap> {
     }, options);
   }
 
+  /**
+   * Send a text message and wait for completion
+   * Returns the completed task with response artifacts
+   */
+  async sendTextAndWait(toAgentId: string, text: string, options?: SendAndWaitOptions): Promise<Task> {
+    const task = await this.sendText(toAgentId, text, options);
+    return this.waitForTask(task.id, options);
+  }
+
+  /**
+   * Send a text message and wait for the text response
+   * This is a convenience method that extracts the response text automatically
+   */
+  async askText(toAgentId: string, text: string, options?: SendAndWaitOptions): Promise<string> {
+    const task = await this.sendTextAndWait(toAgentId, text, options);
+    if (task.status.state === 'failed') {
+      throw new Error(task.status.message || 'Task failed');
+    }
+    return getTaskResponseText(task);
+  }
+
+  /**
+   * Wait for a task to complete (polling)
+   */
+  async waitForTask(taskId: string, options?: SendAndWaitOptions): Promise<Task> {
+    const pollInterval = options?.pollIntervalMs ?? 1000;
+    const maxWait = options?.maxWaitMs ?? 300000; // 5 min default
+    const startTime = Date.now();
+
+    while (Date.now() - startTime < maxWait) {
+      const task = await this.getTask(taskId);
+      
+      if (task.status.state === 'completed' || task.status.state === 'failed' || 
+          task.status.state === 'canceled' || task.status.state === 'rejected') {
+        return task;
+      }
+
+      // Wait before polling again
+      await new Promise(resolve => setTimeout(resolve, pollInterval));
+    }
+
+    throw new Error(`Task ${taskId} did not complete within ${maxWait}ms`);
+  }
+
   /**
    * Get a task by ID
    */
@@ -305,28 +406,42 @@ export class GopherHole extends EventEmitter<EventMap> {
   /**
    * Make a JSON-RPC call to the A2A endpoint
    */
-  private async rpc(method: string, params: Record<string, unknown>): Promise<unknown> {
-    const response = await fetch(`${this.apiUrl}/a2a`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'Authorization': `Bearer ${this.apiKey}`,
-      },
-      body: JSON.stringify({
-        jsonrpc: '2.0',
-        method,
-        params,
-        id: Date.now(),
-      }),
-    });
+  private async rpc(method: string, params: Record<string, unknown>, timeoutMs?: number): Promise<unknown> {
+    const timeout = timeoutMs ?? this.requestTimeout;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
 
-    const data = await response.json();
+    try {
+      const response = await fetch(`${this.apiUrl}/a2a`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${this.apiKey}`,
+        },
+        body: JSON.stringify({
+          jsonrpc: '2.0',
+          method,
+          params,
+          id: Date.now(),
+        }),
+        signal: controller.signal,
+      });
 
-    if (data.error) {
-      throw new Error(data.error.message || 'RPC error');
-    }
+      const data = await response.json();
+
+      if (data.error) {
+        throw new Error(data.error.message || 'RPC error');
+      }
 
-    return data.result;
+      return data.result;
+    } catch (err) {
+      if (err instanceof Error && err.name === 'AbortError') {
+        throw new Error(`Request timeout after ${timeout}ms`);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timeoutId);
+    }
   }
 
   /**