@gopherhole/sdk 0.1.4 → 0.2.2

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;
@@ -194,6 +304,8 @@ interface GopherHoleOptions {
     maxReconnectAttempts?: number;
     /** Default request timeout in ms (default: 30000) */
     requestTimeout?: number;
+    /** Default message response timeout in ms (default: 30000) */
+    messageTimeout?: number;
 }
 /** Agent card configuration for registration */
 interface AgentCardConfig {
@@ -287,12 +399,17 @@ declare class GopherHole extends EventEmitter<EventMap> {
     private reconnectDelay;
     private maxReconnectAttempts;
     private requestTimeout;
+    private messageTimeout;
     private reconnectAttempts;
     private reconnectTimer;
     private pingInterval;
     private agentId;
     private agentCard;
     constructor(apiKeyOrOptions: string | GopherHoleOptions);
+    /**
+     * Get the configured message timeout
+     */
+    getMessageTimeout(): number;
     /**
      * Update agent card (sends to hub if connected)
      */
@@ -347,12 +464,28 @@ declare class GopherHole extends EventEmitter<EventMap> {
      * Cancel a task
      */
     cancelTask(taskId: string): Promise<Task>;
+    /**
+     * Respond to an incoming task via WebSocket (completes the task)
+     * Use this when you receive a 'message' event and want to send back a response
+     * that completes the original task.
+     */
+    respond(taskId: string, text: string, options?: {
+        status?: 'completed' | 'failed';
+        message?: string;
+    }): void;
+    /**
+     * Respond with a failure to an incoming task
+     */
+    respondError(taskId: string, errorMessage: string): void;
     /**
      * Reply to a message/task (sends back to the original caller)
+     * Note: This creates a NEW task via HTTP. For completing an existing task,
+     * use respond() instead.
      */
     reply(taskId: string, payload: MessagePayload, toAgentId?: string): Promise<Task>;
     /**
-     * Reply with text
+     * Reply with text (creates new task)
+     * Note: For completing an existing task, use respond() instead.
      */
     replyText(taskId: string, text: string): Promise<Task>;
     /**
@@ -534,4 +667,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, getTaskResponseText };
+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;
@@ -194,6 +304,8 @@ interface GopherHoleOptions {
     maxReconnectAttempts?: number;
     /** Default request timeout in ms (default: 30000) */
     requestTimeout?: number;
+    /** Default message response timeout in ms (default: 30000) */
+    messageTimeout?: number;
 }
 /** Agent card configuration for registration */
 interface AgentCardConfig {
@@ -287,12 +399,17 @@ declare class GopherHole extends EventEmitter<EventMap> {
     private reconnectDelay;
     private maxReconnectAttempts;
     private requestTimeout;
+    private messageTimeout;
     private reconnectAttempts;
     private reconnectTimer;
     private pingInterval;
     private agentId;
     private agentCard;
     constructor(apiKeyOrOptions: string | GopherHoleOptions);
+    /**
+     * Get the configured message timeout
+     */
+    getMessageTimeout(): number;
     /**
      * Update agent card (sends to hub if connected)
      */
@@ -347,12 +464,28 @@ declare class GopherHole extends EventEmitter<EventMap> {
      * Cancel a task
      */
     cancelTask(taskId: string): Promise<Task>;
+    /**
+     * Respond to an incoming task via WebSocket (completes the task)
+     * Use this when you receive a 'message' event and want to send back a response
+     * that completes the original task.
+     */
+    respond(taskId: string, text: string, options?: {
+        status?: 'completed' | 'failed';
+        message?: string;
+    }): void;
+    /**
+     * Respond with a failure to an incoming task
+     */
+    respondError(taskId: string, errorMessage: string): void;
     /**
      * Reply to a message/task (sends back to the original caller)
+     * Note: This creates a NEW task via HTTP. For completing an existing task,
+     * use respond() instead.
      */
     reply(taskId: string, payload: MessagePayload, toAgentId?: string): Promise<Task>;
     /**
-     * Reply with text
+     * Reply with text (creates new task)
+     * Note: For completing an existing task, use respond() instead.
      */
     replyText(taskId: string, text: string): Promise<Task>;
     /**
@@ -534,4 +667,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, getTaskResponseText };
+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,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   GopherHole: () => GopherHole,
+  GopherHoleAgent: () => GopherHoleAgent,
   JsonRpcErrorCodes: () => JsonRpcErrorCodes,
   default: () => index_default,
   getTaskResponseText: () => getTaskResponseText
@@ -44,6 +45,168 @@ 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) {
@@ -96,6 +259,13 @@ var GopherHole = class extends import_eventemitter3.EventEmitter {
     this.reconnectDelay = options.reconnectDelay ?? 1e3;
     this.maxReconnectAttempts = options.maxReconnectAttempts ?? 10;
     this.requestTimeout = options.requestTimeout ?? 3e4;
+    this.messageTimeout = options.messageTimeout ?? 3e4;
+  }
+  /**
+   * Get the configured message timeout
+   */
+  getMessageTimeout() {
+    return this.messageTimeout;
   }
   /**
    * Update agent card (sends to hub if connected)
@@ -244,8 +414,41 @@ var GopherHole = class extends import_eventemitter3.EventEmitter {
     const response = await this.rpc("tasks/cancel", { id: taskId });
     return response;
   }
+  /**
+   * Respond to an incoming task via WebSocket (completes the task)
+   * Use this when you receive a 'message' event and want to send back a response
+   * that completes the original task.
+   */
+  respond(taskId, text, options) {
+    if (!this.ws || this.ws.readyState !== 1) {
+      throw new Error("WebSocket not connected");
+    }
+    const response = {
+      type: "task_response",
+      taskId,
+      status: {
+        state: options?.status ?? "completed",
+        message: options?.message
+      },
+      artifact: {
+        artifactId: `response-${Date.now()}`,
+        mimeType: "text/plain",
+        parts: [{ kind: "text", text }]
+      },
+      lastChunk: true
+    };
+    this.ws.send(JSON.stringify(response));
+  }
+  /**
+   * Respond with a failure to an incoming task
+   */
+  respondError(taskId, errorMessage) {
+    this.respond(taskId, errorMessage, { status: "failed", message: errorMessage });
+  }
   /**
    * Reply to a message/task (sends back to the original caller)
+   * Note: This creates a NEW task via HTTP. For completing an existing task,
+   * use respond() instead.
    */
   async reply(taskId, payload, toAgentId) {
     if (!toAgentId) {
@@ -268,7 +471,8 @@ var GopherHole = class extends import_eventemitter3.EventEmitter {
     return response;
   }
   /**
-   * Reply with text
+   * Reply with text (creates new task)
+   * Note: For completing an existing task, use respond() instead.
    */
   async replyText(taskId, text) {
     return this.reply(taskId, {
@@ -344,7 +548,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
@@ -538,6 +742,7 @@ var index_default = GopherHole;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   GopherHole,
+  GopherHoleAgent,
   JsonRpcErrorCodes,
   getTaskResponseText
 });

package/dist/index.mjs

@@ -24,6 +24,168 @@ 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) {
@@ -76,6 +238,13 @@ var GopherHole = class extends EventEmitter {
     this.reconnectDelay = options.reconnectDelay ?? 1e3;
     this.maxReconnectAttempts = options.maxReconnectAttempts ?? 10;
     this.requestTimeout = options.requestTimeout ?? 3e4;
+    this.messageTimeout = options.messageTimeout ?? 3e4;
+  }
+  /**
+   * Get the configured message timeout
+   */
+  getMessageTimeout() {
+    return this.messageTimeout;
   }
   /**
    * Update agent card (sends to hub if connected)
@@ -224,8 +393,41 @@ var GopherHole = class extends EventEmitter {
     const response = await this.rpc("tasks/cancel", { id: taskId });
     return response;
   }
+  /**
+   * Respond to an incoming task via WebSocket (completes the task)
+   * Use this when you receive a 'message' event and want to send back a response
+   * that completes the original task.
+   */
+  respond(taskId, text, options) {
+    if (!this.ws || this.ws.readyState !== 1) {
+      throw new Error("WebSocket not connected");
+    }
+    const response = {
+      type: "task_response",
+      taskId,
+      status: {
+        state: options?.status ?? "completed",
+        message: options?.message
+      },
+      artifact: {
+        artifactId: `response-${Date.now()}`,
+        mimeType: "text/plain",
+        parts: [{ kind: "text", text }]
+      },
+      lastChunk: true
+    };
+    this.ws.send(JSON.stringify(response));
+  }
+  /**
+   * Respond with a failure to an incoming task
+   */
+  respondError(taskId, errorMessage) {
+    this.respond(taskId, errorMessage, { status: "failed", message: errorMessage });
+  }
   /**
    * Reply to a message/task (sends back to the original caller)
+   * Note: This creates a NEW task via HTTP. For completing an existing task,
+   * use respond() instead.
    */
   async reply(taskId, payload, toAgentId) {
     if (!toAgentId) {
@@ -248,7 +450,8 @@ var GopherHole = class extends EventEmitter {
     return response;
   }
   /**
-   * Reply with text
+   * Reply with text (creates new task)
+   * Note: For completing an existing task, use respond() instead.
    */
   async replyText(taskId, text) {
     return this.reply(taskId, {
@@ -324,7 +527,7 @@ var GopherHole = class extends EventEmitter {
       if (this.ws?.readyState === 1) {
         this.ws.send(JSON.stringify({ type: "ping" }));
       }
-    }, 3e4);
+    }, 15e3);
   }
   /**
    * Stop ping interval
@@ -517,6 +720,7 @@ var GopherHole = class extends EventEmitter {
 var index_default = GopherHole;
 export {
   GopherHole,
+  GopherHoleAgent,
   JsonRpcErrorCodes,
   index_default as default,
   getTaskResponseText

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gopherhole/sdk",
-  "version": "0.1.4",
+  "version": "0.2.2",
   "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;
@@ -18,6 +34,8 @@ export interface GopherHoleOptions {
   maxReconnectAttempts?: number;
   /** Default request timeout in ms (default: 30000) */
   requestTimeout?: number;
+  /** Default message response timeout in ms (default: 30000) */
+  messageTimeout?: number;
 }
 
 /** Agent card configuration for registration */
@@ -162,6 +180,7 @@ export class GopherHole extends EventEmitter<EventMap> {
   private reconnectDelay: number;
   private maxReconnectAttempts: number;
   private requestTimeout: number;
+  private messageTimeout: number;
   private reconnectAttempts = 0;
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
   private pingInterval: ReturnType<typeof setInterval> | null = null;
@@ -183,6 +202,14 @@ export class GopherHole extends EventEmitter<EventMap> {
     this.reconnectDelay = options.reconnectDelay ?? 1000;
     this.maxReconnectAttempts = options.maxReconnectAttempts ?? 10;
     this.requestTimeout = options.requestTimeout ?? 30000;
+    this.messageTimeout = options.messageTimeout ?? 30000;
+  }
+  
+  /**
+   * Get the configured message timeout
+   */
+  getMessageTimeout(): number {
+    return this.messageTimeout;
   }
   
   /**
@@ -362,8 +389,45 @@ export class GopherHole extends EventEmitter<EventMap> {
     return response as Task;
   }
 
+  /**
+   * Respond to an incoming task via WebSocket (completes the task)
+   * Use this when you receive a 'message' event and want to send back a response
+   * that completes the original task.
+   */
+  respond(taskId: string, text: string, options?: { status?: 'completed' | 'failed'; message?: string }): void {
+    if (!this.ws || this.ws.readyState !== 1) {
+      throw new Error('WebSocket not connected');
+    }
+
+    const response = {
+      type: 'task_response',
+      taskId,
+      status: { 
+        state: options?.status ?? 'completed',
+        message: options?.message,
+      },
+      artifact: {
+        artifactId: `response-${Date.now()}`,
+        mimeType: 'text/plain',
+        parts: [{ kind: 'text', text }],
+      },
+      lastChunk: true,
+    };
+
+    this.ws.send(JSON.stringify(response));
+  }
+
+  /**
+   * Respond with a failure to an incoming task
+   */
+  respondError(taskId: string, errorMessage: string): void {
+    this.respond(taskId, errorMessage, { status: 'failed', message: errorMessage });
+  }
+
   /**
    * Reply to a message/task (sends back to the original caller)
+   * Note: This creates a NEW task via HTTP. For completing an existing task,
+   * use respond() instead.
    */
   async reply(taskId: string, payload: MessagePayload, toAgentId?: string): Promise<Task> {
     // If toAgentId not provided, we need to figure out who to reply to
@@ -394,7 +458,8 @@ export class GopherHole extends EventEmitter<EventMap> {
   }
 
   /**
-   * Reply with text
+   * Reply with text (creates new task)
+   * Note: For completing an existing task, use respond() instead.
    */
   async replyText(taskId: string, text: string): Promise<Task> {
     return this.reply(taskId, {
@@ -480,7 +545,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
   }
 
   /**