@framers/agentos-ext-web-search 1.1.0 → 1.2.0

package/src/tools/webSearch.ts

@@ -1,128 +0,0 @@
-import { ITool } from '@framers/agentos';
-import { SearchProviderService } from '../services/searchProvider';
-
-/**
- * Web search tool that queries multiple search providers
- * 
- * @class WebSearchTool
- * @implements {ITool}
- * 
- * @example
- * ```typescript
- * const tool = new WebSearchTool(searchService);
- * const result = await tool.execute({
- *   query: 'AgentOS extensions',
- *   maxResults: 10,
- *   provider: 'serper'
- * });
- * ```
- */
-export class WebSearchTool implements ITool {
-  public readonly id = 'webSearch';
-  public readonly name = 'Web Search';
-  public readonly description = 'Search the web using multiple providers';
-  
-  /**
-   * Creates an instance of WebSearchTool
-   * @param {SearchProviderService} searchService - The search provider service
-   */
-  constructor(private searchService: SearchProviderService) {}
-  
-  /**
-   * Executes a web search query
-   * 
-   * @param {Object} input - The search parameters
-   * @param {string} input.query - The search query string
-   * @param {number} [input.maxResults=10] - Maximum number of results to return
-   * @param {string} [input.provider] - Specific provider to use (serper, serpapi, brave, duckduckgo)
-   * @returns {Promise<{success: boolean, output?: any, error?: string}>} The search results
-   * 
-   * @throws {Error} Throws if all providers fail
-   */
-  async execute(input: {
-    query: string;
-    maxResults?: number;
-    provider?: 'serper' | 'serpapi' | 'brave' | 'duckduckgo';
-  }): Promise<{ success: boolean; output?: any; error?: string }> {
-    try {
-      const results = await this.searchService.search(input.query, {
-        maxResults: input.maxResults || 10,
-        provider: input.provider
-      });
-      
-      return {
-        success: true,
-        output: results
-      };
-    } catch (error: any) {
-      return {
-        success: false,
-        error: error.message
-      };
-    }
-  }
-  
-  /**
-   * Validates input parameters for the web search
-   * 
-   * @param {any} input - The input to validate
-   * @returns {{valid: boolean, errors: string[]}} Validation result
-   */
-  validate(input: any): { valid: boolean; errors: string[] } {
-    const errors: string[] = [];
-    
-    if (!input.query) {
-      errors.push('Query is required');
-    } else if (typeof input.query !== 'string') {
-      errors.push('Query must be a string');
-    }
-    
-    if (input.maxResults !== undefined) {
-      if (typeof input.maxResults !== 'number' || input.maxResults <= 0) {
-        errors.push('maxResults must be a positive number');
-      }
-    }
-    
-    if (input.provider !== undefined) {
-      const validProviders = ['serper', 'serpapi', 'brave', 'duckduckgo'];
-      if (!validProviders.includes(input.provider)) {
-        errors.push('Invalid provider');
-      }
-    }
-    
-    return {
-      valid: errors.length === 0,
-      errors
-    };
-  }
-  
-  /**
-   * Returns the JSON schema for the tool's input
-   * 
-   * @returns {Object} JSON Schema object
-   */
-  getSchema(): any {
-    return {
-      type: 'object',
-      required: ['query'],
-      properties: {
-        query: {
-          type: 'string',
-          description: 'The search query'
-        },
-        maxResults: {
-          type: 'number',
-          description: 'Maximum number of results to return',
-          default: 10,
-          minimum: 1,
-          maximum: 50
-        },
-        provider: {
-          type: 'string',
-          description: 'Specific search provider to use',
-          enum: ['serper', 'serpapi', 'brave', 'duckduckgo']
-        }
-      }
-    };
-  }
-}

package/src/types.ts

@@ -1,41 +0,0 @@
-/**
- * @file Type definitions for search extension
- */
-
-export interface SearchResult {
-  title: string;
-  snippet: string;
-  url: string;
-  source?: string;
-  publishedDate?: string;
-  thumbnail?: string;
-}
-
-export interface SearchResponse {
-  results: SearchResult[];
-  query: string;
-  provider: string;
-  totalResults?: number;
-  searchTime?: number;
-}
-
-export interface ResearchResult {
-  topic: string;
-  searchCount: number;
-  aggregatedResults: {
-    query: string;
-    results: SearchResult[];
-  }[];
-  provider: string;
-}
-
-export interface FactCheckResult {
-  claim: string;
-  context?: string;
-  verificationResults: {
-    query: string;
-    results: SearchResult[];
-  }[];
-  sourcesChecked: number;
-  provider: string;
-}

package/test/integration.spec.ts

@@ -1,173 +0,0 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { createExtensionPack } from '../src';
-import { ExtensionContext } from '@framers/agentos';
-
-describe('Web Search Extension Integration', () => {
-  let extensionPack: any;
-  let context: ExtensionContext;
-  
-  beforeEach(() => {
-    context = {
-      options: {
-        serperApiKey: process.env.SERPER_API_KEY,
-        serpApiKey: process.env.SERPAPI_API_KEY,
-        braveApiKey: process.env.BRAVE_API_KEY
-      },
-      logger: {
-        info: () => {},
-        warn: () => {},
-        error: () => {},
-        debug: () => {}
-      }
-    } as any;
-    
-    extensionPack = createExtensionPack(context);
-  });
-  
-  describe('Extension Pack Creation', () => {
-    it('should create extension pack with correct metadata', () => {
-      expect(extensionPack.name).toBe('@framers/agentos-ext-web-search');
-      expect(extensionPack.version).toBe('1.0.0');
-      expect(extensionPack.descriptors).toHaveLength(3);
-    });
-    
-    it('should register all three tools', () => {
-      const toolIds = extensionPack.descriptors.map((d: any) => d.id);
-      expect(toolIds).toContain('webSearch');
-      expect(toolIds).toContain('researchAggregator');
-      expect(toolIds).toContain('factCheck');
-    });
-    
-    it('should set correct tool kinds', () => {
-      extensionPack.descriptors.forEach((descriptor: any) => {
-        expect(descriptor.kind).toBe('tool');
-      });
-    });
-  });
-  
-  describe('Tool Execution', () => {
-    it('should execute web search tool', async () => {
-      const webSearchDescriptor = extensionPack.descriptors.find(
-        (d: any) => d.id === 'webSearch'
-      );
-      const webSearchTool = webSearchDescriptor.payload;
-      
-      // Test with DuckDuckGo (no API key required)
-      const result = await webSearchTool.execute({
-        query: 'AgentOS extensions'
-      });
-      
-      expect(result.success).toBe(true);
-      expect(result.output).toHaveProperty('provider');
-      expect(result.output).toHaveProperty('results');
-      expect(result.output).toHaveProperty('metadata');
-    });
-    
-    it('should execute research aggregator tool', async () => {
-      const aggregatorDescriptor = extensionPack.descriptors.find(
-        (d: any) => d.id === 'researchAggregator'
-      );
-      const aggregatorTool = aggregatorDescriptor.payload;
-      
-      const result = await aggregatorTool.execute({
-        topic: 'TypeScript testing',
-        sources: 2
-      });
-      
-      expect(result.success).toBe(true);
-      expect(result.output).toHaveProperty('topic');
-      expect(result.output).toHaveProperty('sources');
-      expect(result.output).toHaveProperty('aggregatedResults');
-    });
-    
-    it('should execute fact check tool', async () => {
-      const factCheckDescriptor = extensionPack.descriptors.find(
-        (d: any) => d.id === 'factCheck'
-      );
-      const factCheckTool = factCheckDescriptor.payload;
-      
-      const result = await factCheckTool.execute({
-        statement: 'TypeScript was created by Microsoft',
-        checkSources: true
-      });
-      
-      expect(result.success).toBe(true);
-      expect(result.output).toHaveProperty('statement');
-      expect(result.output).toHaveProperty('verdict');
-      expect(result.output).toHaveProperty('confidence');
-      expect(result.output).toHaveProperty('sources');
-    });
-  });
-  
-  describe('Error Handling', () => {
-    it('should handle missing API keys gracefully', async () => {
-      const noKeysContext = {
-        options: {},
-        logger: context.logger
-      } as any;
-      
-      const pack = createExtensionPack(noKeysContext);
-      const webSearch = pack.descriptors[0].payload;
-      
-      const result = await webSearch.execute({
-        query: 'test query'
-      });
-      
-      // Should fallback to DuckDuckGo
-      expect(result.success).toBe(true);
-      expect(result.output.provider).toBe('duckduckgo');
-    });
-    
-    it('should validate inputs before execution', async () => {
-      const webSearchDescriptor = extensionPack.descriptors.find(
-        (d: any) => d.id === 'webSearch'
-      );
-      const webSearchTool = webSearchDescriptor.payload;
-      
-      const validation = webSearchTool.validate({
-        // Missing required 'query' field
-        maxResults: 5
-      });
-      
-      expect(validation.valid).toBe(false);
-      expect(validation.errors).toContain('Query is required');
-    });
-  });
-  
-  describe('Lifecycle Hooks', () => {
-    it('should call onActivate when extension is activated', async () => {
-      let activated = false;
-      
-      const customPack = createExtensionPack({
-        ...context,
-        onActivate: async () => {
-          activated = true;
-        }
-      });
-      
-      if (customPack.onActivate) {
-        await customPack.onActivate();
-      }
-      
-      expect(activated).toBe(true);
-    });
-    
-    it('should call onDeactivate when extension is deactivated', async () => {
-      let deactivated = false;
-      
-      const customPack = createExtensionPack({
-        ...context,
-        onDeactivate: async () => {
-          deactivated = true;
-        }
-      });
-      
-      if (customPack.onDeactivate) {
-        await customPack.onDeactivate();
-      }
-      
-      expect(deactivated).toBe(true);
-    });
-  });
-});
-

package/test/searchProvider.spec.ts

@@ -1,153 +0,0 @@
-import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { SearchProviderService } from '../src/services/searchProvider';
-
-// Mock fetch
-global.fetch = vi.fn();
-
-describe('SearchProviderService', () => {
-  let service: SearchProviderService;
-  
-  beforeEach(() => {
-    service = new SearchProviderService({
-      serperApiKey: 'test-serper-key',
-      serpApiKey: 'test-serpapi-key',
-      braveApiKey: 'test-brave-key'
-    });
-    vi.clearAllMocks();
-  });
-  
-  describe('constructor', () => {
-    it('should initialize with provided API keys', () => {
-      expect(service).toBeDefined();
-    });
-    
-    it('should initialize with empty config', () => {
-      const emptyService = new SearchProviderService({});
-      expect(emptyService).toBeDefined();
-    });
-  });
-  
-  describe('search', () => {
-    it('should fallback through providers on failure', async () => {
-      const mockFetch = global.fetch as any;
-      
-      // First provider fails
-      mockFetch.mockRejectedValueOnce(new Error('Serper API error'));
-      
-      // Second provider succeeds
-      mockFetch.mockResolvedValueOnce({
-        ok: true,
-        json: async () => ({
-          organic_results: [
-            { title: 'Test', link: 'https://example.com', snippet: 'Test snippet' }
-          ]
-        })
-      });
-      
-      const result = await service.search('test query');
-      
-      expect(result.provider).toBe('serpapi');
-      expect(result.results).toHaveLength(1);
-      expect(result.results[0].title).toBe('Test');
-    });
-    
-    it('should use DuckDuckGo as final fallback', async () => {
-      const mockFetch = global.fetch as any;
-      
-      // All API providers fail
-      mockFetch.mockRejectedValue(new Error('API error'));
-      
-      // Mock DuckDuckGo HTML response
-      const duckDuckGoHtml = `
-        <div class="result">
-          <h2 class="result__title">
-            <a href="https://example.com">Test Result</a>
-          </h2>
-          <a class="result__snippet">Test snippet from DuckDuckGo</a>
-        </div>
-      `;
-      
-      mockFetch.mockResolvedValueOnce({
-        ok: true,
-        text: async () => duckDuckGoHtml
-      });
-      
-      const serviceNoKeys = new SearchProviderService({});
-      const result = await serviceNoKeys.search('test query');
-      
-      expect(result.provider).toBe('duckduckgo');
-      expect(result.metadata.fallback).toBe(true);
-    });
-    
-    it('should respect rate limiting', async () => {
-      const mockFetch = global.fetch as any;
-      mockFetch.mockResolvedValue({
-        ok: true,
-        json: async () => ({ organic: [] })
-      });
-      
-      // Make multiple rapid requests
-      const promises = [];
-      for (let i = 0; i < 5; i++) {
-        promises.push(service.search(`query ${i}`));
-      }
-      
-      const startTime = Date.now();
-      await Promise.all(promises);
-      const endTime = Date.now();
-      
-      // Should take at least some time due to rate limiting
-      expect(endTime - startTime).toBeGreaterThanOrEqual(0);
-    });
-    
-    it('should respect maxResults parameter', async () => {
-      const mockFetch = global.fetch as any;
-      mockFetch.mockResolvedValue({
-        ok: true,
-        json: async () => ({
-          organic: Array(20).fill({
-            title: 'Test',
-            link: 'https://example.com',
-            snippet: 'Test'
-          })
-        })
-      });
-      
-      const result = await service.search('test', { maxResults: 5 });
-      expect(result.results).toHaveLength(5);
-    });
-  });
-  
-  describe('searchSerper', () => {
-    it('should format request correctly', async () => {
-      const mockFetch = global.fetch as any;
-      mockFetch.mockResolvedValue({
-        ok: true,
-        json: async () => ({ organic: [] })
-      });
-      
-      await service.search('test query', { provider: 'serper' });
-      
-      expect(mockFetch).toHaveBeenCalledWith(
-        'https://google.serper.dev/search',
-        expect.objectContaining({
-          method: 'POST',
-          headers: {
-            'X-API-KEY': 'test-serper-key',
-            'Content-Type': 'application/json'
-          },
-          body: JSON.stringify({ q: 'test query', num: 10 })
-        })
-      );
-    });
-  });
-  
-  describe('getRecommendedProviders', () => {
-    it('should return provider recommendations', () => {
-      const providers = SearchProviderService.getRecommendedProviders();
-      expect(providers).toHaveLength(4);
-      expect(providers[0].name).toBe('Serper');
-      expect(providers[0].signupUrl).toContain('serper.dev');
-    });
-  });
-});

package/test/webSearch.spec.ts

@@ -1,128 +0,0 @@
-import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { WebSearchTool } from '../src/tools/webSearch';
-import { SearchProviderService } from '../src/services/searchProvider';
-
-// Mock the search provider service
-vi.mock('../src/services/searchProvider');
-
-describe('WebSearchTool', () => {
-  let tool: WebSearchTool;
-  let mockSearchService: vi.Mocked<SearchProviderService>;
-  
-  beforeEach(() => {
-    mockSearchService = new SearchProviderService({}) as any;
-    tool = new WebSearchTool(mockSearchService);
-    vi.clearAllMocks();
-  });
-  
-  describe('constructor', () => {
-    it('should initialize with correct metadata', () => {
-      expect(tool.id).toBe('webSearch');
-      expect(tool.name).toBe('Web Search');
-      expect(tool.description).toContain('Search the web');
-    });
-  });
-  
-  describe('execute', () => {
-    it('should call search service with correct parameters', async () => {
-      const mockResults = {
-        provider: 'serper',
-        results: [
-          { title: 'Test', url: 'https://example.com', snippet: 'Test snippet' }
-        ],
-        metadata: { query: 'test query', timestamp: new Date().toISOString() }
-      };
-      
-      mockSearchService.search = vi.fn().mockResolvedValue(mockResults);
-      
-      const input = {
-        query: 'test query',
-        maxResults: 5,
-        provider: 'serper' as const
-      };
-      
-      const result = await tool.execute(input);
-      
-      expect(mockSearchService.search).toHaveBeenCalledWith('test query', {
-        maxResults: 5,
-        provider: 'serper'
-      });
-      expect(result.success).toBe(true);
-      expect(result.output).toEqual(mockResults);
-    });
-    
-    it('should handle errors gracefully', async () => {
-      const error = new Error('API error');
-      mockSearchService.search = vi.fn().mockRejectedValue(error);
-      
-      const input = { query: 'test query' };
-      const result = await tool.execute(input);
-      
-      expect(result.success).toBe(false);
-      expect(result.error).toBe('API error');
-    });
-    
-    it('should use default values when not provided', async () => {
-      mockSearchService.search = vi.fn().mockResolvedValue({
-        provider: 'duckduckgo',
-        results: [],
-        metadata: {}
-      });
-      
-      const input = { query: 'test query' };
-      await tool.execute(input);
-      
-      expect(mockSearchService.search).toHaveBeenCalledWith('test query', {
-        maxResults: 10,
-        provider: undefined
-      });
-    });
-  });
-  
-  describe('validate', () => {
-    it('should validate required query parameter', () => {
-      const result = tool.validate({});
-      expect(result.valid).toBe(false);
-      expect(result.errors).toContain('Query is required');
-    });
-    
-    it('should validate query is a string', () => {
-      const result = tool.validate({ query: 123 });
-      expect(result.valid).toBe(false);
-      expect(result.errors).toContain('Query must be a string');
-    });
-    
-    it('should validate maxResults is a positive number', () => {
-      const result = tool.validate({ query: 'test', maxResults: -1 });
-      expect(result.valid).toBe(false);
-      expect(result.errors).toContain('maxResults must be a positive number');
-    });
-    
-    it('should validate provider is from allowed list', () => {
-      const result = tool.validate({ query: 'test', provider: 'invalid' });
-      expect(result.valid).toBe(false);
-      expect(result.errors).toContain('Invalid provider');
-    });
-    
-    it('should pass validation with correct inputs', () => {
-      const result = tool.validate({ 
-        query: 'test query',
-        maxResults: 5,
-        provider: 'serper'
-      });
-      expect(result.valid).toBe(true);
-      expect(result.errors).toHaveLength(0);
-    });
-  });
-  
-  describe('getSchema', () => {
-    it('should return proper JSON schema', () => {
-      const schema = tool.getSchema();
-      expect(schema.type).toBe('object');
-      expect(schema.required).toEqual(['query']);
-      expect(schema.properties.query.type).toBe('string');
-      expect(schema.properties.maxResults.type).toBe('number');
-      expect(schema.properties.provider.enum).toContain('serper');
-    });
-  });
-});

package/tsconfig.json

@@ -1,21 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "commonjs",
-    "lib": ["ES2022"],
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
-    "resolveJsonModule": true,
-    "moduleResolution": "node",
-    "types": ["node"]
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "test"]
-}

package/vitest.config.ts

@@ -1,32 +0,0 @@
-import { defineConfig } from 'vitest/config';
-import path from 'path';
-
-export default defineConfig({
-  test: {
-    globals: true,
-    environment: 'node',
-    coverage: {
-      provider: 'v8',
-      reporter: ['text', 'json', 'html', 'lcov'],
-      exclude: [
-        'node_modules/',
-        'dist/',
-        'test/',
-        '*.config.ts'
-      ],
-      thresholds: {
-        branches: 80,
-        functions: 80,
-        lines: 80,
-        statements: 80
-      }
-    },
-    include: ['test/**/*.spec.ts'],
-    testTimeout: 10000
-  },
-  resolve: {
-    alias: {
-      '@framers/agentos': path.resolve(__dirname, '../../../../../packages/agentos/src')
-    }
-  }
-});