@gopherhole/sdk 0.1.0 → 0.1.1

package/src/index.ts

@@ -1,277 +1,680 @@
-import WebSocket from 'ws';
-import { EventEmitter } from 'events';
+import { EventEmitter } from 'eventemitter3';
+
+// Re-export types
+export * from './types';
 
 export interface GopherHoleOptions {
+  /** API key (starts with gph_) */
+  apiKey: string;
+  /** Hub URL (defaults to production) */
   hubUrl?: string;
-  reconnect?: boolean;
+  /** Agent card to register on connect */
+  agentCard?: AgentCardConfig;
+  /** Auto-reconnect on disconnect */
+  autoReconnect?: boolean;
+  /** Reconnect delay in ms */
   reconnectDelay?: number;
+  /** Max reconnect attempts */
+  maxReconnectAttempts?: number;
+}
+
+/** Agent card configuration for registration */
+export interface AgentCardConfig {
+  name: string;
+  description?: string;
+  url?: string;
+  version?: string;
+  skills?: AgentSkillConfig[];
+}
+
+/** Skill configuration */
+export interface AgentSkillConfig {
+  id: string;
+  name: string;
+  description?: string;
+  tags?: string[];
+  examples?: string[];
+  inputModes?: string[];
+  outputModes?: string[];
 }
 
 export interface Message {
   from: string;
-  to: string;
+  taskId?: string;
   payload: MessagePayload;
   timestamp: number;
 }
 
 export interface MessagePayload {
+  role: 'user' | 'agent';
   parts: MessagePart[];
-  contextId?: string;
 }
 
 export interface MessagePart {
-  kind: 'text' | 'data' | 'file';
+  kind: 'text' | 'file' | 'data';
   text?: string;
-  data?: unknown;
   mimeType?: string;
+  data?: string;
+  uri?: string;
+}
+
+export interface Task {
+  id: string;
+  contextId: string;
+  status: TaskStatus;
+  history?: MessagePayload[];
+  artifacts?: Artifact[];
+}
+
+export interface TaskStatus {
+  state: 'submitted' | 'working' | 'input-required' | 'completed' | 'failed' | 'canceled' | 'rejected';
+  timestamp: string;
+  message?: string;
+}
+
+export interface Artifact {
+  name: string;
+  mimeType: string;
+  data?: string;
   uri?: string;
 }
 
-interface HubMessage {
-  type: string;
-  id?: string;
-  from?: string;
-  to?: string;
-  payload?: MessagePayload;
-  agentId?: string;
-  error?: string;
-  timestamp?: number;
+export interface SendOptions {
+  /** Existing context/conversation ID */
+  contextId?: string;
+  /** Push notification URL */
+  pushNotificationUrl?: string;
+  /** History length to include */
+  historyLength?: number;
 }
 
-export class GopherHole extends EventEmitter {
+type EventMap = {
+  connect: () => void;
+  disconnect: (reason: string) => void;
+  error: (error: Error) => void;
+  message: (message: Message) => void;
+  taskUpdate: (task: Task) => void;
+};
+
+const DEFAULT_HUB_URL = 'wss://gopherhole.helixdata.workers.dev/ws';
+const DEFAULT_API_URL = 'https://gopherhole.helixdata.workers.dev';
+
+export class GopherHole extends EventEmitter<EventMap> {
   private apiKey: string;
   private hubUrl: string;
+  private apiUrl: string;
   private ws: WebSocket | null = null;
-  private reconnect: boolean;
+  private autoReconnect: boolean;
   private reconnectDelay: number;
-  private authenticated = false;
-  private pendingMessages: Map<string, { resolve: (v: unknown) => void; reject: (e: Error) => void }> = new Map();
-  private messageCounter = 0;
-  public agentId: string | null = null;
-
-  constructor(apiKey: string, options: GopherHoleOptions = {}) {
+  private maxReconnectAttempts: number;
+  private reconnectAttempts = 0;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private pingInterval: ReturnType<typeof setInterval> | null = null;
+  private agentId: string | null = null;
+  private agentCard: AgentCardConfig | null = null;
+
+  constructor(apiKeyOrOptions: string | GopherHoleOptions) {
     super();
-    this.apiKey = apiKey;
-    this.hubUrl = options.hubUrl || 'wss://gopherhole.ai/ws';
-    this.reconnect = options.reconnect ?? true;
-    this.reconnectDelay = options.reconnectDelay ?? 5000;
-  }
 
-  async connect(): Promise<void> {
-    return new Promise<void>((resolve, reject) => {
-      try {
-        this.ws = new WebSocket(this.hubUrl);
-
-        this.ws.on('open', () => {
-          console.log('[GopherHole] Connected, authenticating...');
-          this.ws!.send(JSON.stringify({ type: 'auth', token: this.apiKey }));
-        });
-
-        this.ws.on('message', (data) => {
-          try {
-            const msg: HubMessage = JSON.parse(data.toString());
-            this.handleMessage(msg, resolve, reject);
-          } catch (err) {
-            console.error('[GopherHole] Failed to parse message:', err);
-          }
-        });
-
-        this.ws.on('close', () => {
-          console.log('[GopherHole] Disconnected');
-          this.authenticated = false;
-          this.emit('disconnect');
-          
-          if (this.reconnect) {
-            console.log(`[GopherHole] Reconnecting in ${this.reconnectDelay}ms...`);
-            setTimeout(() => this.connect(), this.reconnectDelay);
-          }
-        });
-
-        this.ws.on('error', (err) => {
-          console.error('[GopherHole] WebSocket error:', err);
-          this.emit('error', err);
-          if (!this.authenticated) {
-            reject(err);
-          }
-        });
-      } catch (err) {
-        reject(err);
-      }
-    });
+    const options = typeof apiKeyOrOptions === 'string'
+      ? { apiKey: apiKeyOrOptions }
+      : apiKeyOrOptions;
+
+    this.apiKey = options.apiKey;
+    this.hubUrl = options.hubUrl || DEFAULT_HUB_URL;
+    this.apiUrl = this.hubUrl.replace('/ws', '').replace('wss://', 'https://').replace('ws://', 'http://');
+    this.agentCard = options.agentCard || null;
+    this.autoReconnect = options.autoReconnect ?? true;
+    this.reconnectDelay = options.reconnectDelay ?? 1000;
+    this.maxReconnectAttempts = options.maxReconnectAttempts ?? 10;
+  }
+  
+  /**
+   * Update agent card (sends to hub if connected)
+   */
+  async updateCard(card: AgentCardConfig): Promise<void> {
+    this.agentCard = card;
+    if (this.ws?.readyState === 1) {
+      this.ws.send(JSON.stringify({ type: 'update_card', agentCard: card }));
+    }
   }
 
-  private handleMessage(msg: HubMessage, resolve?: () => void, reject?: (e: Error) => void) {
-    switch (msg.type) {
-      case 'auth_ok':
-        console.log(`[GopherHole] Authenticated as ${msg.agentId}`);
-        this.authenticated = true;
-        this.agentId = msg.agentId || null;
-        this.emit('connected', { agentId: this.agentId });
-        resolve?.();
-        break;
-
-      case 'auth_error':
-        console.error('[GopherHole] Auth failed:', msg.error);
-        reject?.(new Error(msg.error || 'Authentication failed'));
-        break;
-
-      case 'message':
-        const incomingMsg: Message = {
-          from: msg.from!,
-          to: msg.to!,
-          payload: msg.payload!,
-          timestamp: msg.timestamp || Date.now(),
-        };
-        console.log(`[GopherHole] Message from ${msg.from}`);
-        this.emit('message', incomingMsg);
-        break;
-
-      case 'ack':
-        const pending = this.pendingMessages.get(msg.id!);
-        if (pending) {
-          pending.resolve({ id: msg.id, timestamp: msg.timestamp });
-          this.pendingMessages.delete(msg.id!);
+  /**
+   * Connect to the GopherHole hub via WebSocket
+   */
+  async connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      // Browser or Node WebSocket
+      const WS = typeof WebSocket !== 'undefined' ? WebSocket : require('ws');
+      
+      const ws = new WS(this.hubUrl, {
+        headers: {
+          'Authorization': `Bearer ${this.apiKey}`,
+        },
+      }) as WebSocket;
+      
+      this.ws = ws;
+      
+      ws.onopen = () => {
+        this.reconnectAttempts = 0;
+        this.startPing();
+        this.emit('connect');
+        resolve();
+      };
+
+      ws.onclose = (event: CloseEvent) => {
+        this.stopPing();
+        const reason = event.reason || 'Connection closed';
+        this.emit('disconnect', reason);
+        
+        if (this.autoReconnect && this.reconnectAttempts < this.maxReconnectAttempts) {
+          this.scheduleReconnect();
         }
-        break;
-
-      case 'error':
-        console.error('[GopherHole] Error:', msg.error);
-        const pendingErr = msg.id ? this.pendingMessages.get(msg.id) : null;
-        if (pendingErr) {
-          pendingErr.reject(new Error(msg.error));
-          this.pendingMessages.delete(msg.id!);
+      };
+
+      ws.onerror = () => {
+        const error = new Error('WebSocket error');
+        this.emit('error', error);
+        reject(error);
+      };
+
+      ws.onmessage = (event: MessageEvent) => {
+        try {
+          const data = JSON.parse(event.data.toString());
+          this.handleMessage(data);
+        } catch {
+          this.emit('error', new Error('Failed to parse message'));
         }
-        this.emit('error', new Error(msg.error));
-        break;
+      };
+    });
+  }
 
-      default:
-        console.log('[GopherHole] Unknown message type:', msg.type);
+  /**
+   * Disconnect from the hub
+   */
+  disconnect(): void {
+    this.autoReconnect = false;
+    this.stopPing();
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
     }
   }
 
-  async send(to: string, payload: MessagePayload): Promise<{ id: string; timestamp: number }> {
-    if (!this.authenticated || !this.ws) {
-      throw new Error('Not connected');
-    }
+  /**
+   * Send a message to another agent
+   */
+  async send(toAgentId: string, payload: MessagePayload, options?: SendOptions): Promise<Task> {
+    const response = await this.rpc('message/send', {
+      message: payload,
+      configuration: {
+        agentId: toAgentId,
+        ...options,
+      },
+    });
 
-    const id = `msg-${++this.messageCounter}-${Date.now()}`;
+    return response as Task;
+  }
 
-    return new Promise((resolve, reject) => {
-      this.pendingMessages.set(id, { resolve: resolve as (v: unknown) => void, reject });
-
-      this.ws!.send(JSON.stringify({
-        type: 'message',
-        id,
-        to,
-        payload,
-      }));
-
-      // Timeout after 30s
-      setTimeout(() => {
-        if (this.pendingMessages.has(id)) {
-          this.pendingMessages.delete(id);
-          reject(new Error('Message send timeout'));
-        }
-      }, 30000);
+  /**
+   * Send a text message to another agent
+   */
+  async sendText(toAgentId: string, text: string, options?: SendOptions): Promise<Task> {
+    return this.send(toAgentId, {
+      role: 'agent',
+      parts: [{ kind: 'text', text }],
+    }, options);
+  }
+
+  /**
+   * Get a task by ID
+   */
+  async getTask(taskId: string, historyLength?: number): Promise<Task> {
+    const response = await this.rpc('tasks/get', {
+      id: taskId,
+      historyLength,
+    });
+    return response as Task;
+  }
+
+  /**
+   * List tasks
+   */
+  async listTasks(options?: {
+    contextId?: string;
+    pageSize?: number;
+    pageToken?: string;
+  }): Promise<{ tasks: Task[]; nextPageToken?: string; totalSize: number }> {
+    const response = await this.rpc('tasks/list', options || {});
+    return response as { tasks: Task[]; nextPageToken?: string; totalSize: number };
+  }
+
+  /**
+   * Cancel a task
+   */
+  async cancelTask(taskId: string): Promise<Task> {
+    const response = await this.rpc('tasks/cancel', { id: taskId });
+    return response as Task;
+  }
+
+  /**
+   * Reply to a message/task (sends back to the original caller)
+   */
+  async reply(taskId: string, payload: MessagePayload, toAgentId?: string): Promise<Task> {
+    // If toAgentId not provided, we need to figure out who to reply to
+    // For now, require the caller to provide it or pass through the task context
+    if (!toAgentId) {
+      // Get task to use same context
+      const task = await this.getTask(taskId);
+      // Note: The task doesn't expose client_agent_id via API, so we send to context
+      // The server should route based on contextId
+      const response = await this.rpc('message/send', {
+        message: payload,
+        configuration: {
+          contextId: task.contextId,
+          // Server needs to handle replies via context routing
+        },
+      });
+      return response as Task;
+    }
+    
+    const response = await this.rpc('message/send', {
+      message: payload,
+      configuration: {
+        agentId: toAgentId,
+      },
     });
+
+    return response as Task;
   }
 
-  sendText(to: string, text: string, contextId?: string): Promise<{ id: string; timestamp: number }> {
-    return this.send(to, {
+  /**
+   * Reply with text
+   */
+  async replyText(taskId: string, text: string): Promise<Task> {
+    return this.reply(taskId, {
+      role: 'agent',
       parts: [{ kind: 'text', text }],
-      contextId,
     });
   }
 
-  disconnect() {
-    this.reconnect = false;
-    if (this.ws) {
-      this.ws.close();
-      this.ws = null;
+  /**
+   * Make a JSON-RPC call to the A2A endpoint
+   */
+  private async rpc(method: string, params: Record<string, unknown>): Promise<unknown> {
+    const response = await fetch(`${this.apiUrl}/a2a`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        method,
+        params,
+        id: Date.now(),
+      }),
+    });
+
+    const data = await response.json();
+
+    if (data.error) {
+      throw new Error(data.error.message || 'RPC error');
     }
-  }
 
-  isConnected(): boolean {
-    return this.authenticated && this.ws?.readyState === WebSocket.OPEN;
+    return data.result;
   }
 
   /**
-   * Create a GopherHole instance from environment variables
-   * Reads GOPHERHOLE_API_KEY and optionally GOPHERHOLE_HUB_URL
+   * Handle incoming WebSocket messages
    */
-  static fromEnv(options: Omit<GopherHoleOptions, 'hubUrl'> = {}): GopherHole {
-    const apiKey = process.env.GOPHERHOLE_API_KEY;
-    if (!apiKey) {
-      throw new Error('GOPHERHOLE_API_KEY environment variable is required');
+  private handleMessage(data: any): void {
+    if (data.type === 'message') {
+      this.emit('message', {
+        from: data.from,
+        taskId: data.taskId,
+        payload: data.payload,
+        timestamp: data.timestamp || Date.now(),
+      });
+    } else if (data.type === 'task_update') {
+      this.emit('taskUpdate', data.task);
+    } else if (data.type === 'pong') {
+      // Heartbeat response
+    } else if (data.type === 'welcome') {
+      this.agentId = data.agentId;
+      // Send agent card if configured
+      if (this.agentCard && this.ws?.readyState === 1) {
+        this.ws.send(JSON.stringify({ type: 'update_card', agentCard: this.agentCard }));
+      }
+    } else if (data.type === 'card_updated') {
+      // Agent card was successfully updated
+    } else if (data.type === 'warning') {
+      console.warn('GopherHole warning:', data.message);
     }
-    return new GopherHole(apiKey, {
-      ...options,
-      hubUrl: process.env.GOPHERHOLE_HUB_URL || 'wss://gopherhole.ai/ws',
-    });
   }
 
   /**
-   * Create a simple agent with a message handler
+   * Start ping interval
+   */
+  private startPing(): void {
+    this.pingInterval = setInterval(() => {
+      if (this.ws?.readyState === 1) { // OPEN
+        this.ws.send(JSON.stringify({ type: 'ping' }));
+      }
+    }, 30000);
+  }
+
+  /**
+   * Stop ping interval
    */
-  static agent(config: {
-    apiKey?: string;
-    hubUrl?: string;
-    onMessage: (msg: Message, hub: GopherHole) => Promise<string | MessagePayload | void> | string | MessagePayload | void;
-    onConnect?: (hub: GopherHole) => void;
-    onError?: (err: Error, hub: GopherHole) => void;
-  }): { start: () => Promise<void>; stop: () => void; hub: GopherHole } {
-    const apiKey = config.apiKey || process.env.GOPHERHOLE_API_KEY;
-    if (!apiKey) {
-      throw new Error('API key required: pass apiKey or set GOPHERHOLE_API_KEY');
+  private stopPing(): void {
+    if (this.pingInterval) {
+      clearInterval(this.pingInterval);
+      this.pingInterval = null;
     }
+  }
 
-    const hub = new GopherHole(apiKey, {
-      hubUrl: config.hubUrl || process.env.GOPHERHOLE_HUB_URL,
-    });
+  /**
+   * Schedule reconnection
+   */
+  private scheduleReconnect(): void {
+    if (this.reconnectTimer) return;
+
+    this.reconnectAttempts++;
+    const delay = this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1);
 
-    hub.on('message', async (msg: Message) => {
+    this.reconnectTimer = setTimeout(async () => {
+      this.reconnectTimer = null;
       try {
-        const response = await config.onMessage(msg, hub);
-        
-        // If handler returns a response, send it back
-        if (response) {
-          if (typeof response === 'string') {
-            await hub.sendText(msg.from, response);
-          } else {
-            await hub.send(msg.from, response);
-          }
-        }
-      } catch (err) {
-        console.error('[GopherHole Agent] Message handler error:', err);
-        if (config.onError) {
-          config.onError(err as Error, hub);
-        }
+        await this.connect();
+      } catch {
+        // Will retry via onclose handler
       }
+    }, delay);
+  }
+
+  /**
+   * Get connection state
+   */
+  get connected(): boolean {
+    return this.ws?.readyState === 1;
+  }
+
+  /**
+   * Get the agent ID (available after connect)
+   */
+  get id(): string | null {
+    return this.agentId;
+  }
+
+  // ============================================================
+  // DISCOVERY METHODS
+  // ============================================================
+
+  /**
+   * Discover public agents with comprehensive search
+   */
+  async discover(options?: DiscoverOptions): Promise<DiscoverResult> {
+    const params = new URLSearchParams();
+    
+    if (options?.query) params.set('q', options.query);
+    if (options?.category) params.set('category', options.category);
+    if (options?.tag) params.set('tag', options.tag);
+    if (options?.skillTag) params.set('skillTag', options.skillTag);
+    if (options?.contentMode) params.set('contentMode', options.contentMode);
+    if (options?.sort) params.set('sort', options.sort);
+    if (options?.limit) params.set('limit', String(options.limit));
+    if (options?.offset) params.set('offset', String(options.offset));
+    
+    // Include API key to see same-tenant agents (not just public)
+    const response = await fetch(`${this.apiUrl}/api/discover/agents?${params}`, {
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+      },
     });
+    return response.json();
+  }
 
-    hub.on('connected', () => {
-      console.log(`[GopherHole Agent] Connected as ${hub.agentId}`);
-      if (config.onConnect) {
-        config.onConnect(hub);
-      }
+  /**
+   * Search agents with fuzzy matching on description
+   */
+  async searchAgents(query: string, options?: Omit<DiscoverOptions, 'query'>): Promise<DiscoverResult> {
+    return this.discover({ ...options, query });
+  }
+
+  /**
+   * Find agents by category
+   */
+  async findByCategory(category: string, options?: Omit<DiscoverOptions, 'category'>): Promise<DiscoverResult> {
+    return this.discover({ ...options, category });
+  }
+
+  /**
+   * Find agents by tag
+   */
+  async findByTag(tag: string, options?: Omit<DiscoverOptions, 'tag'>): Promise<DiscoverResult> {
+    return this.discover({ ...options, tag });
+  }
+
+  /**
+   * Find agents by skill tag (searches within agent skills)
+   */
+  async findBySkillTag(skillTag: string, options?: Omit<DiscoverOptions, 'skillTag'>): Promise<DiscoverResult> {
+    return this.discover({ ...options, skillTag });
+  }
+
+  /**
+   * Find agents that support a specific input/output mode
+   */
+  async findByContentMode(mode: string, options?: Omit<DiscoverOptions, 'contentMode'>): Promise<DiscoverResult> {
+    return this.discover({ ...options, contentMode: mode });
+  }
+
+  /**
+   * Get top-rated agents
+   */
+  async getTopRated(limit = 10): Promise<DiscoverResult> {
+    return this.discover({ sort: 'rating', limit });
+  }
+
+  /**
+   * Get most popular agents (by usage)
+   */
+  async getPopular(limit = 10): Promise<DiscoverResult> {
+    return this.discover({ sort: 'popular', limit });
+  }
+
+  /**
+   * Get featured/curated agents
+   */
+  async getFeatured(): Promise<{ featured: PublicAgent[] }> {
+    const response = await fetch(`${this.apiUrl}/api/discover/featured`);
+    return response.json();
+  }
+
+  /**
+   * Get available categories
+   */
+  async getCategories(): Promise<{ categories: AgentCategory[] }> {
+    const response = await fetch(`${this.apiUrl}/api/discover/categories`);
+    return response.json();
+  }
+
+  /**
+   * Get detailed info about a public agent
+   */
+  async getAgentInfo(agentId: string): Promise<AgentInfoResult> {
+    const response = await fetch(`${this.apiUrl}/api/discover/agents/${agentId}`);
+    if (!response.ok) {
+      throw new Error('Agent not found');
+    }
+    return response.json();
+  }
+
+  /**
+   * Rate an agent (requires authentication)
+   */
+  async rateAgent(agentId: string, rating: number, review?: string): Promise<RatingResult> {
+    const response = await fetch(`${this.apiUrl}/api/discover/agents/${agentId}/rate`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({ rating, review }),
     });
+    if (!response.ok) {
+      const error = await response.json();
+      throw new Error(error.error || 'Failed to rate agent');
+    }
+    return response.json();
+  }
 
-    hub.on('error', (err: Error) => {
-      if (config.onError) {
-        config.onError(err, hub);
-      }
+  /**
+   * Get best agent for a task using smart matching
+   * Searches by query and returns the top-rated match
+   */
+  async findBestAgent(query: string, options?: {
+    category?: string;
+    minRating?: number;
+    pricing?: 'free' | 'paid' | 'any';
+  }): Promise<PublicAgent | null> {
+    const result = await this.discover({
+      query,
+      category: options?.category,
+      sort: 'rating',
+      limit: 10,
     });
+    
+    const agents = result.agents.filter(agent => {
+      if (options?.minRating && agent.avgRating < options.minRating) return false;
+      if (options?.pricing === 'free' && agent.pricing !== 'free') return false;
+      if (options?.pricing === 'paid' && agent.pricing === 'free') return false;
+      return true;
+    });
+    
+    return agents[0] || null;
+  }
 
-    return {
-      hub,
-      start: async () => {
-        await hub.connect();
-      },
-      stop: () => {
-        hub.disconnect();
-      },
-    };
+  /**
+   * Find agents similar to a given agent
+   */
+  async findSimilar(agentId: string, limit = 5): Promise<DiscoverResult> {
+    // Get the agent's info first
+    const info = await this.getAgentInfo(agentId);
+    const agent = info.agent;
+    
+    // Search by category and tags
+    if (agent.category) {
+      const result = await this.discover({
+        category: agent.category,
+        sort: 'rating',
+        limit: limit + 1, // +1 to exclude self
+      });
+      
+      // Filter out the original agent
+      result.agents = result.agents.filter(a => a.id !== agentId).slice(0, limit);
+      return result;
+    }
+    
+    // Fallback to top rated
+    return this.getTopRated(limit);
   }
 }
 
+// ============================================================
+// DISCOVERY TYPES
+// ============================================================
+
+export interface DiscoverOptions {
+  /** Search query (fuzzy matches name, description, tags) */
+  query?: string;
+  /** Filter by category */
+  category?: string;
+  /** Filter by tag */
+  tag?: string;
+  /** Filter by skill tag (searches within agent skills) */
+  skillTag?: string;
+  /** Filter by content mode (MIME type, e.g., 'text/markdown', 'image/png') */
+  contentMode?: string;
+  /** Sort order */
+  sort?: 'rating' | 'popular' | 'recent';
+  /** Max results (default 20, max 100) */
+  limit?: number;
+  /** Pagination offset */
+  offset?: number;
+}
+
+export interface DiscoverResult {
+  agents: PublicAgent[];
+  count: number;
+  offset: number;
+}
+
+export interface PublicAgent {
+  id: string;
+  name: string;
+  description: string | null;
+  category: string | null;
+  tags: string[];
+  pricing: 'free' | 'paid' | 'contact';
+  avgRating: number;
+  ratingCount: number;
+  tenantName: string;
+  websiteUrl: string | null;
+  docsUrl: string | null;
+}
+
+export interface AgentCategory {
+  name: string;
+  count: number;
+}
+
+export interface AgentInfoResult {
+  agent: PublicAgent & {
+    agentCard: {
+      name: string;
+      description?: string;
+      skills?: AgentSkill[];
+    } | null;
+    stats: {
+      avgRating: number;
+      ratingCount: number;
+      totalMessages: number;
+      successRate: number;
+      avgResponseTime: number;
+    };
+  };
+  reviews: AgentReview[];
+}
+
+/** Full A2A skill schema */
+export interface AgentSkill {
+  id: string;
+  name: string;
+  description?: string;
+  tags?: string[];
+  examples?: string[];
+  inputModes?: string[];
+  outputModes?: string[];
+}
+
+export interface AgentReview {
+  rating: number;
+  review: string;
+  created_at: number;
+  reviewer_name: string;
+}
+
+export interface RatingResult {
+  success: boolean;
+  avgRating: number;
+  ratingCount: number;
+}
+
+// Default export
 export default GopherHole;