@gopherhole/sdk 0.1.3 → 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

@@ -243,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;
@@ -311,6 +318,11 @@ declare class GopherHole extends EventEmitter<EventMap> {
      * 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)
      */
@@ -522,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 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 };
+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

@@ -243,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;
@@ -311,6 +318,11 @@ declare class GopherHole extends EventEmitter<EventMap> {
      * 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)
      */
@@ -522,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 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 };
+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) {
@@ -160,6 +193,17 @@ var GopherHole = class extends import_eventemitter3.EventEmitter {
     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)
    */
@@ -494,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) {
@@ -141,6 +173,17 @@ var GopherHole = class extends EventEmitter {
     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)
    */
@@ -475,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.3",
+  "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

@@ -75,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;
@@ -253,6 +296,18 @@ export class GopherHole extends EventEmitter<EventMap> {
     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)
    */