@gopherhole/sdk 0.1.3 → 0.2.1

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

@@ -97,13 +97,13 @@ interface A2AArtifact {
     lastChunk?: boolean;
     metadata?: Record<string, unknown>;
 }
-interface JsonRpcRequest {
+interface JsonRpcRequest$1 {
     jsonrpc: '2.0';
     method: string;
     params?: Record<string, unknown>;
     id: string | number;
 }
-interface JsonRpcResponse<T = unknown> {
+interface JsonRpcResponse$1<T = unknown> {
     jsonrpc: '2.0';
     result?: T;
     error?: JsonRpcError;
@@ -179,6 +179,116 @@ interface TaskArtifactUpdateEvent {
 }
 type TaskEvent = TaskStatusUpdateEvent | TaskArtifactUpdateEvent;
 
+/**
+ * GopherHoleAgent - Helper for building webhook-based A2A agents
+ *
+ * Use this to create agents that receive requests from the GopherHole hub
+ * via webhooks (e.g., Cloudflare Workers, Express servers).
+ */
+
+interface IncomingMessage {
+    role: 'user' | 'agent';
+    parts: AgentMessagePart[];
+    metadata?: Record<string, unknown>;
+}
+interface AgentMessagePart {
+    kind: 'text' | 'file' | 'data';
+    text?: string;
+    mimeType?: string;
+    data?: string;
+    uri?: string;
+}
+interface AgentTaskResult {
+    id: string;
+    contextId: string;
+    status: AgentTaskStatus;
+    messages: IncomingMessage[];
+    artifacts?: AgentArtifact[];
+}
+interface AgentTaskStatus {
+    state: 'submitted' | 'working' | 'input-required' | 'completed' | 'failed' | 'canceled';
+    timestamp: string;
+    message?: string;
+}
+interface AgentArtifact {
+    name?: string;
+    mimeType?: string;
+    parts?: AgentMessagePart[];
+}
+interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    method: string;
+    params?: Record<string, unknown>;
+    id?: string | number;
+}
+interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+    id?: string | number | null;
+}
+interface MessageContext {
+    /** The incoming message */
+    message: IncomingMessage;
+    /** Extracted text content from message parts */
+    text: string;
+    /** Task ID if provided */
+    taskId?: string;
+    /** Context ID if provided */
+    contextId?: string;
+    /** Full params from JSON-RPC request */
+    params: Record<string, unknown>;
+}
+type MessageHandler = (ctx: MessageContext) => Promise<string | AgentTaskResult> | string | AgentTaskResult;
+interface GopherHoleAgentOptions {
+    /** Agent card for discovery */
+    card: AgentCard;
+    /** API key for authentication (from GopherHole hub) */
+    apiKey?: string;
+    /** Handler for incoming messages */
+    onMessage: MessageHandler;
+}
+declare class GopherHoleAgent {
+    private card;
+    private apiKey?;
+    private onMessage;
+    constructor(options: GopherHoleAgentOptions);
+    /** Get the agent card */
+    getCard(): AgentCard;
+    /** Verify authorization header */
+    verifyAuth(authHeader: string | null): boolean;
+    /**
+     * Handle an incoming HTTP request
+     * Returns a Response object (works with Cloudflare Workers, Bun, etc.)
+     */
+    handleRequest(request: Request): Promise<Response>;
+    /**
+     * Handle a JSON-RPC request directly
+     */
+    handleJsonRpc(req: JsonRpcRequest): Promise<JsonRpcResponse>;
+    private handleMessageSend;
+    /**
+     * Create a completed task result from a text response
+     */
+    createTaskResult(originalMessage: IncomingMessage, responseText: string, contextId?: string): AgentTaskResult;
+    /**
+     * Helper to create a text message part
+     */
+    static textPart(text: string): AgentMessagePart;
+    /**
+     * Helper to create a file message part
+     */
+    static filePart(uri: string, mimeType: string): AgentMessagePart;
+    /**
+     * Helper to create a data message part (base64)
+     */
+    static dataPart(data: string, mimeType: string): AgentMessagePart;
+}
+
 interface GopherHoleOptions {
     /** API key (starts with gph_) */
     apiKey: string;
@@ -243,11 +353,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 +428,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 +644,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 AgentArtifact, type AgentAuthentication, type AgentCapabilities, type AgentCard, type AgentCardConfig, type AgentCategory, type AgentInfoResult, type AgentMessagePart, type AgentReview, type AgentSkill, type AgentSkillConfig, type AgentTaskResult, type AgentTaskStatus, type Artifact, type ContentMode, type DataContent, type DataPart, type DiscoverOptions, type DiscoverResult, type FileContent, type FilePart, GopherHole, GopherHoleAgent, type GopherHoleAgentOptions, type GopherHoleOptions, type IncomingMessage, type InputMode, type JsonRpcError, JsonRpcErrorCodes, type JsonRpcRequest$1 as JsonRpcRequest, type JsonRpcResponse$1 as JsonRpcResponse, type Message, type MessageContext, type MessageHandler, 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 AgentTaskResult as TaskResult, type TaskState, type TaskStatus, type TaskStatusUpdateEvent, type TextPart, GopherHole as default, getTaskResponseText };

package/dist/index.d.ts

@@ -97,13 +97,13 @@ interface A2AArtifact {
     lastChunk?: boolean;
     metadata?: Record<string, unknown>;
 }
-interface JsonRpcRequest {
+interface JsonRpcRequest$1 {
     jsonrpc: '2.0';
     method: string;
     params?: Record<string, unknown>;
     id: string | number;
 }
-interface JsonRpcResponse<T = unknown> {
+interface JsonRpcResponse$1<T = unknown> {
     jsonrpc: '2.0';
     result?: T;
     error?: JsonRpcError;
@@ -179,6 +179,116 @@ interface TaskArtifactUpdateEvent {
 }
 type TaskEvent = TaskStatusUpdateEvent | TaskArtifactUpdateEvent;
 
+/**
+ * GopherHoleAgent - Helper for building webhook-based A2A agents
+ *
+ * Use this to create agents that receive requests from the GopherHole hub
+ * via webhooks (e.g., Cloudflare Workers, Express servers).
+ */
+
+interface IncomingMessage {
+    role: 'user' | 'agent';
+    parts: AgentMessagePart[];
+    metadata?: Record<string, unknown>;
+}
+interface AgentMessagePart {
+    kind: 'text' | 'file' | 'data';
+    text?: string;
+    mimeType?: string;
+    data?: string;
+    uri?: string;
+}
+interface AgentTaskResult {
+    id: string;
+    contextId: string;
+    status: AgentTaskStatus;
+    messages: IncomingMessage[];
+    artifacts?: AgentArtifact[];
+}
+interface AgentTaskStatus {
+    state: 'submitted' | 'working' | 'input-required' | 'completed' | 'failed' | 'canceled';
+    timestamp: string;
+    message?: string;
+}
+interface AgentArtifact {
+    name?: string;
+    mimeType?: string;
+    parts?: AgentMessagePart[];
+}
+interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    method: string;
+    params?: Record<string, unknown>;
+    id?: string | number;
+}
+interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+    id?: string | number | null;
+}
+interface MessageContext {
+    /** The incoming message */
+    message: IncomingMessage;
+    /** Extracted text content from message parts */
+    text: string;
+    /** Task ID if provided */
+    taskId?: string;
+    /** Context ID if provided */
+    contextId?: string;
+    /** Full params from JSON-RPC request */
+    params: Record<string, unknown>;
+}
+type MessageHandler = (ctx: MessageContext) => Promise<string | AgentTaskResult> | string | AgentTaskResult;
+interface GopherHoleAgentOptions {
+    /** Agent card for discovery */
+    card: AgentCard;
+    /** API key for authentication (from GopherHole hub) */
+    apiKey?: string;
+    /** Handler for incoming messages */
+    onMessage: MessageHandler;
+}
+declare class GopherHoleAgent {
+    private card;
+    private apiKey?;
+    private onMessage;
+    constructor(options: GopherHoleAgentOptions);
+    /** Get the agent card */
+    getCard(): AgentCard;
+    /** Verify authorization header */
+    verifyAuth(authHeader: string | null): boolean;
+    /**
+     * Handle an incoming HTTP request
+     * Returns a Response object (works with Cloudflare Workers, Bun, etc.)
+     */
+    handleRequest(request: Request): Promise<Response>;
+    /**
+     * Handle a JSON-RPC request directly
+     */
+    handleJsonRpc(req: JsonRpcRequest): Promise<JsonRpcResponse>;
+    private handleMessageSend;
+    /**
+     * Create a completed task result from a text response
+     */
+    createTaskResult(originalMessage: IncomingMessage, responseText: string, contextId?: string): AgentTaskResult;
+    /**
+     * Helper to create a text message part
+     */
+    static textPart(text: string): AgentMessagePart;
+    /**
+     * Helper to create a file message part
+     */
+    static filePart(uri: string, mimeType: string): AgentMessagePart;
+    /**
+     * Helper to create a data message part (base64)
+     */
+    static dataPart(data: string, mimeType: string): AgentMessagePart;
+}
+
 interface GopherHoleOptions {
     /** API key (starts with gph_) */
     apiKey: string;
@@ -243,11 +353,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 +428,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 +644,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 AgentArtifact, type AgentAuthentication, type AgentCapabilities, type AgentCard, type AgentCardConfig, type AgentCategory, type AgentInfoResult, type AgentMessagePart, type AgentReview, type AgentSkill, type AgentSkillConfig, type AgentTaskResult, type AgentTaskStatus, type Artifact, type ContentMode, type DataContent, type DataPart, type DiscoverOptions, type DiscoverResult, type FileContent, type FilePart, GopherHole, GopherHoleAgent, type GopherHoleAgentOptions, type GopherHoleOptions, type IncomingMessage, type InputMode, type JsonRpcError, JsonRpcErrorCodes, type JsonRpcRequest$1 as JsonRpcRequest, type JsonRpcResponse$1 as JsonRpcResponse, type Message, type MessageContext, type MessageHandler, 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 AgentTaskResult as TaskResult, type TaskState, type TaskStatus, type TaskStatusUpdateEvent, type TextPart, GopherHole as default, getTaskResponseText };

package/dist/index.js

@@ -21,8 +21,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   GopherHole: () => GopherHole,
+  GopherHoleAgent: () => GopherHoleAgent,
   JsonRpcErrorCodes: () => JsonRpcErrorCodes,
-  default: () => index_default
+  default: () => index_default,
+  getTaskResponseText: () => getTaskResponseText
 });
 module.exports = __toCommonJS(index_exports);
 var import_eventemitter3 = require("eventemitter3");
@@ -43,7 +45,201 @@ var JsonRpcErrorCodes = {
   InvalidAgentCard: -32006
 };
 
+// src/agent.ts
+var GopherHoleAgent = class {
+  constructor(options) {
+    this.card = options.card;
+    this.apiKey = options.apiKey;
+    this.onMessage = options.onMessage;
+  }
+  /** Get the agent card */
+  getCard() {
+    return this.card;
+  }
+  /** Verify authorization header */
+  verifyAuth(authHeader) {
+    if (!this.apiKey) return true;
+    return authHeader === `Bearer ${this.apiKey}`;
+  }
+  /**
+   * Handle an incoming HTTP request
+   * Returns a Response object (works with Cloudflare Workers, Bun, etc.)
+   */
+  async handleRequest(request) {
+    const url = new URL(request.url);
+    const corsHeaders = {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+      "Access-Control-Allow-Headers": "Content-Type, Authorization"
+    };
+    if (request.method === "OPTIONS") {
+      return new Response(null, { headers: corsHeaders });
+    }
+    if (url.pathname === "/.well-known/agent.json" || url.pathname === "/agent.json") {
+      return Response.json(this.card, { headers: corsHeaders });
+    }
+    if (url.pathname === "/health") {
+      return Response.json(
+        { status: "ok", agent: this.card.name, version: this.card.version || "1.0.0" },
+        { headers: corsHeaders }
+      );
+    }
+    if (request.method === "POST" && (url.pathname === "/" || url.pathname === "/a2a")) {
+      if (this.apiKey && !this.verifyAuth(request.headers.get("Authorization"))) {
+        return Response.json(
+          { jsonrpc: "2.0", error: { code: -32001, message: "Unauthorized" }, id: null },
+          { status: 401, headers: corsHeaders }
+        );
+      }
+      try {
+        const body = await request.json();
+        const response = await this.handleJsonRpc(body);
+        return Response.json(response, { headers: corsHeaders });
+      } catch {
+        return Response.json(
+          { jsonrpc: "2.0", error: { code: -32700, message: "Parse error" }, id: null },
+          { status: 400, headers: corsHeaders }
+        );
+      }
+    }
+    return new Response("Not Found", { status: 404, headers: corsHeaders });
+  }
+  /**
+   * Handle a JSON-RPC request directly
+   */
+  async handleJsonRpc(req) {
+    const { method, params = {}, id } = req;
+    switch (method) {
+      case "message/send":
+        return this.handleMessageSend(params, id);
+      case "tasks/get":
+        return {
+          jsonrpc: "2.0",
+          error: { code: -32601, message: "This agent does not support persistent tasks" },
+          id
+        };
+      case "tasks/cancel":
+        return {
+          jsonrpc: "2.0",
+          error: { code: -32601, message: "This agent does not support task cancellation" },
+          id
+        };
+      default:
+        return {
+          jsonrpc: "2.0",
+          error: { code: -32601, message: `Method not found: ${method}` },
+          id
+        };
+    }
+  }
+  async handleMessageSend(params, id) {
+    const message = params.message;
+    if (!message?.parts) {
+      return {
+        jsonrpc: "2.0",
+        error: { code: -32602, message: "Invalid params: message with parts required" },
+        id
+      };
+    }
+    const text = message.parts.filter((p) => p.kind === "text" || p.text).map((p) => p.text || "").join("\n").trim();
+    const config = params.configuration;
+    const ctx = {
+      message,
+      text,
+      taskId: params.taskId,
+      contextId: config?.contextId,
+      params
+    };
+    try {
+      const result = await this.onMessage(ctx);
+      if (typeof result === "string") {
+        const taskResult = this.createTaskResult(message, result, ctx.contextId);
+        return { jsonrpc: "2.0", result: taskResult, id };
+      }
+      return { jsonrpc: "2.0", result, id };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Handler error";
+      return {
+        jsonrpc: "2.0",
+        error: { code: -32e3, message: errorMessage },
+        id
+      };
+    }
+  }
+  /**
+   * Create a completed task result from a text response
+   */
+  createTaskResult(originalMessage, responseText, contextId) {
+    return {
+      id: `task-${Date.now()}`,
+      contextId: contextId || `ctx-${Date.now()}`,
+      status: {
+        state: "completed",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      },
+      messages: [
+        originalMessage,
+        {
+          role: "agent",
+          parts: [{ kind: "text", text: responseText }],
+          metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString() }
+        }
+      ]
+    };
+  }
+  /**
+   * Helper to create a text message part
+   */
+  static textPart(text) {
+    return { kind: "text", text };
+  }
+  /**
+   * Helper to create a file message part
+   */
+  static filePart(uri, mimeType) {
+    return { kind: "file", uri, mimeType };
+  }
+  /**
+   * Helper to create a data message part (base64)
+   */
+  static dataPart(data, mimeType) {
+    return { kind: "data", data, mimeType };
+  }
+};
+
 // 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 +356,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)
    */
@@ -300,7 +507,7 @@ var GopherHole = class extends import_eventemitter3.EventEmitter {
       if (this.ws?.readyState === 1) {
         this.ws.send(JSON.stringify({ type: "ping" }));
       }
-    }, 3e4);
+    }, 15e3);
   }
   /**
    * Stop ping interval
@@ -494,5 +701,7 @@ var index_default = GopherHole;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   GopherHole,
-  JsonRpcErrorCodes
+  GopherHoleAgent,
+  JsonRpcErrorCodes,
+  getTaskResponseText
 });

package/dist/index.mjs

@@ -24,7 +24,201 @@ var JsonRpcErrorCodes = {
   InvalidAgentCard: -32006
 };
 
+// src/agent.ts
+var GopherHoleAgent = class {
+  constructor(options) {
+    this.card = options.card;
+    this.apiKey = options.apiKey;
+    this.onMessage = options.onMessage;
+  }
+  /** Get the agent card */
+  getCard() {
+    return this.card;
+  }
+  /** Verify authorization header */
+  verifyAuth(authHeader) {
+    if (!this.apiKey) return true;
+    return authHeader === `Bearer ${this.apiKey}`;
+  }
+  /**
+   * Handle an incoming HTTP request
+   * Returns a Response object (works with Cloudflare Workers, Bun, etc.)
+   */
+  async handleRequest(request) {
+    const url = new URL(request.url);
+    const corsHeaders = {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+      "Access-Control-Allow-Headers": "Content-Type, Authorization"
+    };
+    if (request.method === "OPTIONS") {
+      return new Response(null, { headers: corsHeaders });
+    }
+    if (url.pathname === "/.well-known/agent.json" || url.pathname === "/agent.json") {
+      return Response.json(this.card, { headers: corsHeaders });
+    }
+    if (url.pathname === "/health") {
+      return Response.json(
+        { status: "ok", agent: this.card.name, version: this.card.version || "1.0.0" },
+        { headers: corsHeaders }
+      );
+    }
+    if (request.method === "POST" && (url.pathname === "/" || url.pathname === "/a2a")) {
+      if (this.apiKey && !this.verifyAuth(request.headers.get("Authorization"))) {
+        return Response.json(
+          { jsonrpc: "2.0", error: { code: -32001, message: "Unauthorized" }, id: null },
+          { status: 401, headers: corsHeaders }
+        );
+      }
+      try {
+        const body = await request.json();
+        const response = await this.handleJsonRpc(body);
+        return Response.json(response, { headers: corsHeaders });
+      } catch {
+        return Response.json(
+          { jsonrpc: "2.0", error: { code: -32700, message: "Parse error" }, id: null },
+          { status: 400, headers: corsHeaders }
+        );
+      }
+    }
+    return new Response("Not Found", { status: 404, headers: corsHeaders });
+  }
+  /**
+   * Handle a JSON-RPC request directly
+   */
+  async handleJsonRpc(req) {
+    const { method, params = {}, id } = req;
+    switch (method) {
+      case "message/send":
+        return this.handleMessageSend(params, id);
+      case "tasks/get":
+        return {
+          jsonrpc: "2.0",
+          error: { code: -32601, message: "This agent does not support persistent tasks" },
+          id
+        };
+      case "tasks/cancel":
+        return {
+          jsonrpc: "2.0",
+          error: { code: -32601, message: "This agent does not support task cancellation" },
+          id
+        };
+      default:
+        return {
+          jsonrpc: "2.0",
+          error: { code: -32601, message: `Method not found: ${method}` },
+          id
+        };
+    }
+  }
+  async handleMessageSend(params, id) {
+    const message = params.message;
+    if (!message?.parts) {
+      return {
+        jsonrpc: "2.0",
+        error: { code: -32602, message: "Invalid params: message with parts required" },
+        id
+      };
+    }
+    const text = message.parts.filter((p) => p.kind === "text" || p.text).map((p) => p.text || "").join("\n").trim();
+    const config = params.configuration;
+    const ctx = {
+      message,
+      text,
+      taskId: params.taskId,
+      contextId: config?.contextId,
+      params
+    };
+    try {
+      const result = await this.onMessage(ctx);
+      if (typeof result === "string") {
+        const taskResult = this.createTaskResult(message, result, ctx.contextId);
+        return { jsonrpc: "2.0", result: taskResult, id };
+      }
+      return { jsonrpc: "2.0", result, id };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Handler error";
+      return {
+        jsonrpc: "2.0",
+        error: { code: -32e3, message: errorMessage },
+        id
+      };
+    }
+  }
+  /**
+   * Create a completed task result from a text response
+   */
+  createTaskResult(originalMessage, responseText, contextId) {
+    return {
+      id: `task-${Date.now()}`,
+      contextId: contextId || `ctx-${Date.now()}`,
+      status: {
+        state: "completed",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      },
+      messages: [
+        originalMessage,
+        {
+          role: "agent",
+          parts: [{ kind: "text", text: responseText }],
+          metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString() }
+        }
+      ]
+    };
+  }
+  /**
+   * Helper to create a text message part
+   */
+  static textPart(text) {
+    return { kind: "text", text };
+  }
+  /**
+   * Helper to create a file message part
+   */
+  static filePart(uri, mimeType) {
+    return { kind: "file", uri, mimeType };
+  }
+  /**
+   * Helper to create a data message part (base64)
+   */
+  static dataPart(data, mimeType) {
+    return { kind: "data", data, mimeType };
+  }
+};
+
 // 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 +335,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)
    */
@@ -281,7 +486,7 @@ var GopherHole = class extends EventEmitter {
       if (this.ws?.readyState === 1) {
         this.ws.send(JSON.stringify({ type: "ping" }));
       }
-    }, 3e4);
+    }, 15e3);
   }
   /**
    * Stop ping interval
@@ -474,6 +679,8 @@ var GopherHole = class extends EventEmitter {
 var index_default = GopherHole;
 export {
   GopherHole,
+  GopherHoleAgent,
   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.2.1",
   "description": "GopherHole SDK - Connect AI agents via the A2A protocol",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/agent.ts

@@ -0,0 +1,305 @@
+/**
+ * GopherHoleAgent - Helper for building webhook-based A2A agents
+ * 
+ * Use this to create agents that receive requests from the GopherHole hub
+ * via webhooks (e.g., Cloudflare Workers, Express servers).
+ */
+
+import type { AgentCard, AgentSkill } from './types';
+
+// Re-export types for convenience
+export type { AgentCard, AgentSkill };
+
+// ============================================================
+// TYPES
+// ============================================================
+
+export interface IncomingMessage {
+  role: 'user' | 'agent';
+  parts: AgentMessagePart[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface AgentMessagePart {
+  kind: 'text' | 'file' | 'data';
+  text?: string;
+  mimeType?: string;
+  data?: string;
+  uri?: string;
+}
+
+export interface AgentTaskResult {
+  id: string;
+  contextId: string;
+  status: AgentTaskStatus;
+  messages: IncomingMessage[];
+  artifacts?: AgentArtifact[];
+}
+
+export interface AgentTaskStatus {
+  state: 'submitted' | 'working' | 'input-required' | 'completed' | 'failed' | 'canceled';
+  timestamp: string;
+  message?: string;
+}
+
+export interface AgentArtifact {
+  name?: string;
+  mimeType?: string;
+  parts?: AgentMessagePart[];
+}
+
+interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  method: string;
+  params?: Record<string, unknown>;
+  id?: string | number;
+}
+
+interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+  id?: string | number | null;
+}
+
+// ============================================================
+// MESSAGE HANDLER TYPE
+// ============================================================
+
+export interface MessageContext {
+  /** The incoming message */
+  message: IncomingMessage;
+  /** Extracted text content from message parts */
+  text: string;
+  /** Task ID if provided */
+  taskId?: string;
+  /** Context ID if provided */
+  contextId?: string;
+  /** Full params from JSON-RPC request */
+  params: Record<string, unknown>;
+}
+
+export type MessageHandler = (ctx: MessageContext) => Promise<string | AgentTaskResult> | string | AgentTaskResult;
+
+// ============================================================
+// AGENT CLASS
+// ============================================================
+
+export interface GopherHoleAgentOptions {
+  /** Agent card for discovery */
+  card: AgentCard;
+  /** API key for authentication (from GopherHole hub) */
+  apiKey?: string;
+  /** Handler for incoming messages */
+  onMessage: MessageHandler;
+}
+
+export class GopherHoleAgent {
+  private card: AgentCard;
+  private apiKey?: string;
+  private onMessage: MessageHandler;
+
+  constructor(options: GopherHoleAgentOptions) {
+    this.card = options.card;
+    this.apiKey = options.apiKey;
+    this.onMessage = options.onMessage;
+  }
+
+  /** Get the agent card */
+  getCard(): AgentCard {
+    return this.card;
+  }
+
+  /** Verify authorization header */
+  verifyAuth(authHeader: string | null): boolean {
+    if (!this.apiKey) return true; // No auth configured
+    return authHeader === `Bearer ${this.apiKey}`;
+  }
+
+  /**
+   * Handle an incoming HTTP request
+   * Returns a Response object (works with Cloudflare Workers, Bun, etc.)
+   */
+  async handleRequest(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    const corsHeaders = {
+      'Access-Control-Allow-Origin': '*',
+      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+    };
+
+    // CORS preflight
+    if (request.method === 'OPTIONS') {
+      return new Response(null, { headers: corsHeaders });
+    }
+
+    // Agent card endpoints
+    if (url.pathname === '/.well-known/agent.json' || url.pathname === '/agent.json') {
+      return Response.json(this.card, { headers: corsHeaders });
+    }
+
+    // Health check
+    if (url.pathname === '/health') {
+      return Response.json(
+        { status: 'ok', agent: this.card.name, version: this.card.version || '1.0.0' },
+        { headers: corsHeaders }
+      );
+    }
+
+    // JSON-RPC endpoint
+    if (request.method === 'POST' && (url.pathname === '/' || url.pathname === '/a2a')) {
+      // Verify auth
+      if (this.apiKey && !this.verifyAuth(request.headers.get('Authorization'))) {
+        return Response.json(
+          { jsonrpc: '2.0', error: { code: -32001, message: 'Unauthorized' }, id: null },
+          { status: 401, headers: corsHeaders }
+        );
+      }
+
+      try {
+        const body = await request.json() as JsonRpcRequest;
+        const response = await this.handleJsonRpc(body);
+        return Response.json(response, { headers: corsHeaders });
+      } catch {
+        return Response.json(
+          { jsonrpc: '2.0', error: { code: -32700, message: 'Parse error' }, id: null },
+          { status: 400, headers: corsHeaders }
+        );
+      }
+    }
+
+    return new Response('Not Found', { status: 404, headers: corsHeaders });
+  }
+
+  /**
+   * Handle a JSON-RPC request directly
+   */
+  async handleJsonRpc(req: JsonRpcRequest): Promise<JsonRpcResponse> {
+    const { method, params = {}, id } = req;
+
+    switch (method) {
+      case 'message/send':
+        return this.handleMessageSend(params, id);
+
+      case 'tasks/get':
+        return {
+          jsonrpc: '2.0',
+          error: { code: -32601, message: 'This agent does not support persistent tasks' },
+          id,
+        };
+
+      case 'tasks/cancel':
+        return {
+          jsonrpc: '2.0',
+          error: { code: -32601, message: 'This agent does not support task cancellation' },
+          id,
+        };
+
+      default:
+        return {
+          jsonrpc: '2.0',
+          error: { code: -32601, message: `Method not found: ${method}` },
+          id,
+        };
+    }
+  }
+
+  private async handleMessageSend(
+    params: Record<string, unknown>,
+    id?: string | number
+  ): Promise<JsonRpcResponse> {
+    const message = params.message as IncomingMessage | undefined;
+
+    if (!message?.parts) {
+      return {
+        jsonrpc: '2.0',
+        error: { code: -32602, message: 'Invalid params: message with parts required' },
+        id,
+      };
+    }
+
+    // Extract text from message parts
+    const text = message.parts
+      .filter(p => p.kind === 'text' || p.text)
+      .map(p => p.text || '')
+      .join('\n')
+      .trim();
+
+    const config = params.configuration as Record<string, unknown> | undefined;
+    const ctx: MessageContext = {
+      message,
+      text,
+      taskId: params.taskId as string | undefined,
+      contextId: config?.contextId as string | undefined,
+      params,
+    };
+
+    try {
+      const result = await this.onMessage(ctx);
+      
+      // If handler returned a string, wrap it in a task result
+      if (typeof result === 'string') {
+        const taskResult = this.createTaskResult(message, result, ctx.contextId);
+        return { jsonrpc: '2.0', result: taskResult, id };
+      }
+
+      return { jsonrpc: '2.0', result, id };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Handler error';
+      return {
+        jsonrpc: '2.0',
+        error: { code: -32000, message: errorMessage },
+        id,
+      };
+    }
+  }
+
+  /**
+   * Create a completed task result from a text response
+   */
+  createTaskResult(
+    originalMessage: IncomingMessage,
+    responseText: string,
+    contextId?: string
+  ): AgentTaskResult {
+    return {
+      id: `task-${Date.now()}`,
+      contextId: contextId || `ctx-${Date.now()}`,
+      status: {
+        state: 'completed',
+        timestamp: new Date().toISOString(),
+      },
+      messages: [
+        originalMessage,
+        {
+          role: 'agent',
+          parts: [{ kind: 'text', text: responseText }],
+          metadata: { generatedAt: new Date().toISOString() },
+        },
+      ],
+    };
+  }
+
+  /**
+   * Helper to create a text message part
+   */
+  static textPart(text: string): AgentMessagePart {
+    return { kind: 'text', text };
+  }
+
+  /**
+   * Helper to create a file message part
+   */
+  static filePart(uri: string, mimeType: string): AgentMessagePart {
+    return { kind: 'file', uri, mimeType };
+  }
+
+  /**
+   * Helper to create a data message part (base64)
+   */
+  static dataPart(data: string, mimeType: string): AgentMessagePart {
+    return { kind: 'data', data, mimeType };
+  }
+}
+
+export default GopherHoleAgent;

package/src/index.ts

@@ -3,6 +3,22 @@ import { EventEmitter } from 'eventemitter3';
 // Re-export types
 export * from './types';
 
+// Re-export agent helper for webhook-based agents
+export { 
+  GopherHoleAgent,
+  GopherHoleAgentOptions,
+  IncomingMessage,
+  AgentMessagePart,
+  AgentTaskResult,
+  AgentTaskStatus,
+  AgentArtifact,
+  MessageContext,
+  MessageHandler,
+} from './agent';
+
+// Convenience type aliases
+export type { AgentTaskResult as TaskResult } from './agent';
+
 export interface GopherHoleOptions {
   /** API key (starts with gph_) */
   apiKey: string;
@@ -75,12 +91,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 +312,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)
    */
@@ -425,7 +496,7 @@ export class GopherHole extends EventEmitter<EventMap> {
       if (this.ws?.readyState === 1) { // OPEN
         this.ws.send(JSON.stringify({ type: 'ping' }));
       }
-    }, 30000);
+    }, 15000); // 15s ping to keep connection alive
   }
 
   /**