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

package/src/tools/webSearch.ts

@@ -1,128 +1,129 @@
-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'
- * });
- * ```
+ * Web Search Tool — multi-provider search via SearchProviderService.
+ *
+ * Updated to conform to AgentOS `ITool` (inputSchema + ToolExecutionContext).
+ *
+ * @module @framers/agentos-ext-web-search
  */
-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 }> {
+
+import type { ITool, JSONSchemaObject, ToolExecutionContext, ToolExecutionResult } from '@framers/agentos';
+import type { ProviderResponse, MultiSearchResponse } from '../services/searchProvider.js';
+import { SearchProviderService } from '../services/searchProvider.js';
+
+export interface WebSearchInput {
+  query: string;
+  maxResults?: number;
+  provider?: 'serper' | 'serpapi' | 'brave' | 'searxng' | 'duckduckgo';
+  multiSearch?: boolean;
+  category?: string;
+}
+
+export type WebSearchOutput = ProviderResponse | MultiSearchResponse;
+
+export class WebSearchTool implements ITool<WebSearchInput, WebSearchOutput> {
+  public readonly id = 'web-search-v1';
+  /** Tool call name used by the LLM / ToolExecutor. */
+  public readonly name = 'web_search';
+  public readonly displayName = 'Web Search';
+  public readonly description =
+    'Search the web using multiple providers (Serper, SerpAPI, Brave, SearXNG, DuckDuckGo fallback). Set multiSearch=true to query ALL providers in parallel for higher-confidence, deduplicated results.';
+  public readonly category = 'research';
+  public readonly hasSideEffects = false;
+
+  public readonly inputSchema: JSONSchemaObject = {
+    type: 'object',
+    required: ['query'],
+    properties: {
+      query: {
+        type: 'string',
+        description: 'The search query',
+      },
+      maxResults: {
+        type: 'integer',
+        description: 'Maximum number of results to return',
+        default: 10,
+        minimum: 1,
+        maximum: 50,
+      },
+      provider: {
+        type: 'string',
+        description: 'Specific search provider to use (ignored when multiSearch is true)',
+        enum: ['serper', 'serpapi', 'brave', 'searxng', 'duckduckgo'],
+      },
+      multiSearch: {
+        type: 'boolean',
+        description:
+          'When true, searches ALL available providers in parallel and returns merged, deduplicated results ranked by cross-provider agreement. Useful for deep research or fact verification.',
+        default: false,
+      },
+      category: {
+        type: 'string',
+        description: 'Search category (SearXNG only). Options: general, news, images, videos, it, science, files, social_media',
+        enum: ['general', 'news', 'images', 'videos', 'it', 'science', 'files', 'social_media'],
+      },
+    },
+    additionalProperties: false,
+  };
+
+  public readonly requiredCapabilities = ['capability:web_search'];
+
+  constructor(
+    private readonly searchService: SearchProviderService,
+    private readonly defaultMultiSearch: boolean = false,
+  ) {}
+
+  async execute(input: WebSearchInput, _context: ToolExecutionContext): Promise<ToolExecutionResult<WebSearchOutput>> {
     try {
+      const useMultiSearch = input.multiSearch ?? this.defaultMultiSearch;
+
+      if (useMultiSearch && !input.provider) {
+        const results = await this.searchService.multiSearch(input.query, {
+          maxResults: input.maxResults || 10,
+        });
+        return { success: true, output: results };
+      }
+
       const results = await this.searchService.search(input.query, {
         maxResults: input.maxResults || 10,
-        provider: input.provider
+        provider: input.provider,
+        category: input.category,
       });
-      
-      return {
-        success: true,
-        output: results
-      };
+      return { success: true, output: results };
     } catch (error: any) {
-      return {
-        success: false,
-        error: error.message
-      };
+      return { success: false, error: error?.message || String(error) };
     }
   }
-  
-  /**
-   * 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[] } {
+
+  validateArgs(input: Record<string, any>): { isValid: boolean; errors?: any[] } {
     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'];
+      const validProviders = ['serper', 'serpapi', 'brave', 'searxng', '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']
-        }
-      }
-    };
+
+    if (input.multiSearch !== undefined && typeof input.multiSearch !== 'boolean') {
+      errors.push('multiSearch must be a boolean');
+    }
+
+    if (input.multiSearch && input.provider) {
+      errors.push('Cannot specify both multiSearch and a specific provider');
+    }
+
+    return errors.length === 0 ? { isValid: true } : { isValid: false, errors };
   }
-}
+}

package/test/integration.spec.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { createExtensionPack } from '../src';
 import { ExtensionContext } from '@framers/agentos';
 
@@ -7,6 +7,16 @@ describe('Web Search Extension Integration', () => {
   let context: ExtensionContext;
   
   beforeEach(() => {
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        Heading: 'Test',
+        AbstractText: 'Test abstract',
+        AbstractURL: 'https://example.com',
+        RelatedTopics: [],
+      }),
+    }) as any;
+
     context = {
       options: {
         serperApiKey: process.env.SERPER_API_KEY,
@@ -27,15 +37,15 @@ describe('Web Search Extension Integration', () => {
   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.version).toBe('1.1.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');
+      expect(toolIds).toContain('web_search');
+      expect(toolIds).toContain('research_aggregate');
+      expect(toolIds).toContain('fact_check');
     });
     
     it('should set correct tool kinds', () => {
@@ -48,13 +58,17 @@ describe('Web Search Extension Integration', () => {
   describe('Tool Execution', () => {
     it('should execute web search tool', async () => {
       const webSearchDescriptor = extensionPack.descriptors.find(
-        (d: any) => d.id === 'webSearch'
+        (d: any) => d.id === 'web_search'
       );
       const webSearchTool = webSearchDescriptor.payload;
       
       // Test with DuckDuckGo (no API key required)
       const result = await webSearchTool.execute({
         query: 'AgentOS extensions'
+      }, {
+        gmiId: 'test-gmi',
+        personaId: 'test-persona',
+        userContext: { userId: 'test-user' },
       });
       
       expect(result.success).toBe(true);
@@ -65,13 +79,17 @@ describe('Web Search Extension Integration', () => {
     
     it('should execute research aggregator tool', async () => {
       const aggregatorDescriptor = extensionPack.descriptors.find(
-        (d: any) => d.id === 'researchAggregator'
+        (d: any) => d.id === 'research_aggregate'
       );
       const aggregatorTool = aggregatorDescriptor.payload;
       
       const result = await aggregatorTool.execute({
         topic: 'TypeScript testing',
         sources: 2
+      }, {
+        gmiId: 'test-gmi',
+        personaId: 'test-persona',
+        userContext: { userId: 'test-user' },
       });
       
       expect(result.success).toBe(true);
@@ -82,13 +100,17 @@ describe('Web Search Extension Integration', () => {
     
     it('should execute fact check tool', async () => {
       const factCheckDescriptor = extensionPack.descriptors.find(
-        (d: any) => d.id === 'factCheck'
+        (d: any) => d.id === 'fact_check'
       );
       const factCheckTool = factCheckDescriptor.payload;
       
       const result = await factCheckTool.execute({
         statement: 'TypeScript was created by Microsoft',
         checkSources: true
+      }, {
+        gmiId: 'test-gmi',
+        personaId: 'test-persona',
+        userContext: { userId: 'test-user' },
       });
       
       expect(result.success).toBe(true);
@@ -111,6 +133,10 @@ describe('Web Search Extension Integration', () => {
       
       const result = await webSearch.execute({
         query: 'test query'
+      }, {
+        gmiId: 'test-gmi',
+        personaId: 'test-persona',
+        userContext: { userId: 'test-user' },
       });
       
       // Should fallback to DuckDuckGo
@@ -120,54 +146,229 @@ describe('Web Search Extension Integration', () => {
     
     it('should validate inputs before execution', async () => {
       const webSearchDescriptor = extensionPack.descriptors.find(
-        (d: any) => d.id === 'webSearch'
+        (d: any) => d.id === 'web_search'
       );
       const webSearchTool = webSearchDescriptor.payload;
       
-      const validation = webSearchTool.validate({
+      const validation = webSearchTool.validateArgs({
         // Missing required 'query' field
         maxResults: 5
       });
       
-      expect(validation.valid).toBe(false);
+      expect(validation.isValid).toBe(false);
       expect(validation.errors).toContain('Query is required');
     });
   });
   
+  describe('Multi-Search Integration', () => {
+    it('should create tools with defaultMultiSearch option', () => {
+      const multiContext = {
+        options: {
+          ...context.options,
+          defaultMultiSearch: true,
+        },
+        logger: context.logger,
+      } as any;
+
+      const multiPack = createExtensionPack(multiContext);
+      expect(multiPack.descriptors).toHaveLength(3);
+
+      // Verify tools were created (defaultMultiSearch is internal, just check they still work)
+      const webSearch = multiPack.descriptors.find((d: any) => d.id === 'web_search');
+      expect(webSearch).toBeDefined();
+    });
+
+    it('should execute web_search with multiSearch: true', async () => {
+      const webSearchTool = extensionPack.descriptors.find(
+        (d: any) => d.id === 'web_search'
+      ).payload;
+
+      const result = await webSearchTool.execute({
+        query: 'multi search test',
+        multiSearch: true,
+      }, {
+        gmiId: 'test-gmi',
+        personaId: 'test-persona',
+        userContext: { userId: 'test-user' },
+      });
+
+      expect(result.success).toBe(true);
+      // Multi-search returns metadata with provider info
+      expect(result.output).toHaveProperty('metadata');
+    });
+
+    it('should execute research_aggregate with multiSearch: true', async () => {
+      const aggregatorTool = extensionPack.descriptors.find(
+        (d: any) => d.id === 'research_aggregate'
+      ).payload;
+
+      const result = await aggregatorTool.execute({
+        topic: 'test topic',
+        sources: 1,
+        depth: 'quick',
+        multiSearch: true,
+      }, {
+        gmiId: 'test-gmi',
+        personaId: 'test-persona',
+        userContext: { userId: 'test-user' },
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.output).toHaveProperty('aggregatedResults');
+    });
+
+    it('should execute fact_check with multiSearch: true', async () => {
+      const factCheckTool = extensionPack.descriptors.find(
+        (d: any) => d.id === 'fact_check'
+      ).payload;
+
+      const result = await factCheckTool.execute({
+        statement: 'The sky is blue because of Rayleigh scattering',
+        multiSearch: true,
+      }, {
+        gmiId: 'test-gmi',
+        personaId: 'test-persona',
+        userContext: { userId: 'test-user' },
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.output).toHaveProperty('verdict');
+    });
+
+    it('should reject multiSearch + provider on web_search validation', () => {
+      const webSearchTool = extensionPack.descriptors.find(
+        (d: any) => d.id === 'web_search'
+      ).payload;
+
+      const validation = webSearchTool.validateArgs({
+        query: 'test',
+        multiSearch: true,
+        provider: 'serper',
+      });
+
+      expect(validation.isValid).toBe(false);
+      expect(validation.errors).toContain('Cannot specify both multiSearch and a specific provider');
+    });
+  });
+
+  describe('SearXNG Integration', () => {
+    it('should create extension pack with searxngUrl option', () => {
+      const searxngContext = {
+        options: {
+          searxngUrl: 'http://searxng:8080',
+        },
+        logger: context.logger,
+      } as any;
+
+      const pack = createExtensionPack(searxngContext);
+      expect(pack.descriptors).toHaveLength(3);
+      expect(pack.name).toBe('@framers/agentos-ext-web-search');
+    });
+
+    it('should execute web search with searxng provider', async () => {
+      const mockFetch = global.fetch as any;
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          results: [
+            { title: 'SearXNG Result', url: 'https://example.com/searxng', content: 'A result from SearXNG' },
+          ],
+        }),
+      });
+
+      const searxngContext = {
+        options: { searxngUrl: 'http://searxng:8080' },
+        logger: context.logger,
+      } as any;
+
+      const pack = createExtensionPack(searxngContext);
+      const webSearch = pack.descriptors.find((d: any) => d.id === 'web_search')!.payload;
+
+      const result = await webSearch.execute(
+        { query: 'test', provider: 'searxng' },
+        { gmiId: 'test-gmi', personaId: 'test-persona', userContext: { userId: 'test-user' } },
+      );
+
+      expect(result.success).toBe(true);
+      expect(result.output.provider).toBe('searxng');
+      expect(result.output.results[0].snippet).toBe('A result from SearXNG');
+    });
+
+    it('should pass category through to SearXNG', async () => {
+      const mockFetch = global.fetch as any;
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: async () => ({ results: [] }),
+      });
+
+      const searxngContext = {
+        options: { searxngUrl: 'http://searxng:8080' },
+        logger: context.logger,
+      } as any;
+
+      const pack = createExtensionPack(searxngContext);
+      const webSearch = pack.descriptors.find((d: any) => d.id === 'web_search')!.payload;
+
+      await webSearch.execute(
+        { query: 'AI news', provider: 'searxng', category: 'news' },
+        { gmiId: 'test-gmi', personaId: 'test-persona', userContext: { userId: 'test-user' } },
+      );
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string;
+      expect(calledUrl).toContain('categories=news');
+    });
+
+    it('should use SearXNG as primary when it is the only configured provider', async () => {
+      const mockFetch = global.fetch as any;
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          results: [
+            { title: 'SearXNG Primary', url: 'https://example.com/primary', content: 'Primary result' },
+          ],
+        }),
+      });
+
+      const searxngOnlyContext = {
+        options: { searxngUrl: 'http://searxng:8080' },
+        logger: context.logger,
+      } as any;
+
+      const pack = createExtensionPack(searxngOnlyContext);
+      const webSearch = pack.descriptors.find((d: any) => d.id === 'web_search')!.payload;
+
+      const result = await webSearch.execute(
+        { query: 'test' },
+        { gmiId: 'test-gmi', personaId: 'test-persona', userContext: { userId: 'test-user' } },
+      );
+
+      expect(result.success).toBe(true);
+      // SearXNG should be used as primary (not falling back to DDG)
+      expect(result.output.provider).toBe('searxng');
+    });
+  });
+
   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();
+      const logSpy = vi.fn();
+      const lc = { logger: { info: logSpy, warn: vi.fn(), error: vi.fn(), debug: vi.fn() } };
+
+      if (extensionPack.onActivate) {
+        await extensionPack.onActivate(lc);
       }
-      
-      expect(activated).toBe(true);
+
+      expect(logSpy).toHaveBeenCalledWith('Web Search Extension activated');
     });
-    
+
     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();
+      const logSpy = vi.fn();
+      const lc = { logger: { info: logSpy, warn: vi.fn(), error: vi.fn(), debug: vi.fn() } };
+
+      if (extensionPack.onDeactivate) {
+        await extensionPack.onDeactivate(lc);
       }
-      
-      expect(deactivated).toBe(true);
+
+      expect(logSpy).toHaveBeenCalledWith('Web Search Extension deactivated');
     });
   });
 });
-