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

package/test/searchProvider.spec.ts

@@ -11,7 +11,8 @@ describe('SearchProviderService', () => {
     service = new SearchProviderService({
       serperApiKey: 'test-serper-key',
       serpApiKey: 'test-serpapi-key',
-      braveApiKey: 'test-brave-key'
+      braveApiKey: 'test-brave-key',
+      searxngUrl: 'http://localhost:8888',
     });
     vi.clearAllMocks();
   });
@@ -53,23 +54,15 @@ describe('SearchProviderService', () => {
     
     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
+        json: async () => ({
+          Heading: 'Test Result',
+          AbstractText: 'Test snippet from DuckDuckGo',
+          AbstractURL: 'https://example.com',
+          RelatedTopics: [],
+        }),
       });
       
       const serviceNoKeys = new SearchProviderService({});
@@ -142,12 +135,264 @@ describe('SearchProviderService', () => {
     });
   });
   
+  describe('getAvailableProviders', () => {
+    it('should return providers with configured API keys', () => {
+      const providers = service.getAvailableProviders();
+      expect(providers).toEqual(['serper', 'serpapi', 'brave', 'searxng']);
+    });
+
+    it('should include searxng when URL is configured', () => {
+      const searxngService = new SearchProviderService({ searxngUrl: 'http://searxng:8080' });
+      expect(searxngService.getAvailableProviders()).toEqual(['searxng']);
+    });
+
+    it('should return empty array with no API keys', () => {
+      const emptyService = new SearchProviderService({});
+      expect(emptyService.getAvailableProviders()).toEqual([]);
+    });
+  });
+
+  describe('searchSearXNG', () => {
+    it('should format request with correct URL params', async () => {
+      const mockFetch = global.fetch as any;
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          results: [
+            { title: 'SearXNG Result', url: 'https://example.com/searxng', content: 'SearXNG snippet' },
+          ],
+        }),
+      });
+
+      const searxngService = new SearchProviderService({ searxngUrl: 'http://searxng:8080' });
+      const result = await searxngService.search('test query', { provider: 'searxng' });
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        expect.stringContaining('http://searxng:8080/search?'),
+      );
+      const calledUrl = mockFetch.mock.calls[0][0] as string;
+      expect(calledUrl).toContain('format=json');
+      expect(calledUrl).toContain('categories=general');
+      expect(result.provider).toBe('searxng');
+      expect(result.results).toHaveLength(1);
+    });
+
+    it('should map SearXNG "content" field to "snippet"', async () => {
+      const mockFetch = global.fetch as any;
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          results: [
+            { title: 'Title', url: 'https://example.com', content: 'SearXNG content field' },
+          ],
+        }),
+      });
+
+      const searxngService = new SearchProviderService({ searxngUrl: 'http://searxng:8080' });
+      const result = await searxngService.search('test', { provider: 'searxng' });
+
+      expect(result.results[0].snippet).toBe('SearXNG content field');
+    });
+
+    it('should pass category parameter to SearXNG', async () => {
+      const mockFetch = global.fetch as any;
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: async () => ({ results: [] }),
+      });
+
+      const searxngService = new SearchProviderService({ searxngUrl: 'http://searxng:8080' });
+      await searxngService.search('AI news', { provider: 'searxng', category: 'news' });
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string;
+      expect(calledUrl).toContain('categories=news');
+    });
+
+    it('should handle SearXNG API errors', async () => {
+      const mockFetch = global.fetch as any;
+      mockFetch.mockResolvedValueOnce({ ok: false, statusText: 'Service Unavailable' });
+      // DuckDuckGo fallback
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ Heading: 'DDG', AbstractText: 'Fallback', AbstractURL: 'https://example.com', RelatedTopics: [] }),
+      });
+
+      const searxngService = new SearchProviderService({ searxngUrl: 'http://searxng:8080' });
+      const result = await searxngService.search('test');
+
+      // Should fall through to DuckDuckGo
+      expect(result.provider).toBe('duckduckgo');
+    });
+
+    it('should strip trailing slashes from SearXNG URL', async () => {
+      const mockFetch = global.fetch as any;
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: async () => ({ results: [] }),
+      });
+
+      const searxngService = new SearchProviderService({ searxngUrl: 'http://searxng:8080///' });
+      await searxngService.search('test', { provider: 'searxng' });
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string;
+      expect(calledUrl).toMatch(/^http:\/\/searxng:8080\/search\?/);
+    });
+  });
+
+  describe('normalizeUrl', () => {
+    it('should strip www prefix', () => {
+      expect(SearchProviderService.normalizeUrl('https://www.example.com/page'))
+        .toBe('https://example.com/page');
+    });
+
+    it('should strip tracking params (utm_*, fbclid, gclid)', () => {
+      const url = 'https://example.com/page?utm_source=google&utm_medium=cpc&fbclid=abc&real=keep';
+      const normalized = SearchProviderService.normalizeUrl(url);
+      expect(normalized).toContain('real=keep');
+      expect(normalized).not.toContain('utm_source');
+      expect(normalized).not.toContain('fbclid');
+    });
+
+    it('should strip trailing slashes', () => {
+      expect(SearchProviderService.normalizeUrl('https://example.com/page/'))
+        .toBe('https://example.com/page');
+    });
+
+    it('should sort remaining query params', () => {
+      const url = 'https://example.com/page?z=1&a=2';
+      const normalized = SearchProviderService.normalizeUrl(url);
+      expect(normalized).toBe('https://example.com/page?a=2&z=1');
+    });
+
+    it('should handle invalid URLs gracefully', () => {
+      expect(SearchProviderService.normalizeUrl('not a url')).toBe('not a url');
+    });
+  });
+
+  describe('multiSearch', () => {
+    it('should fan out to all available providers + duckduckgo', async () => {
+      const mockFetch = global.fetch as any;
+      mockFetch.mockImplementation(async (url: string) => {
+        const urlStr = typeof url === 'string' ? url : url.toString();
+        if (urlStr.includes('serper.dev')) {
+          return { ok: true, json: async () => ({ organic: [
+            { title: 'Result A', link: 'https://example.com/a', snippet: 'Snippet A', position: 1 },
+            { title: 'Result B', link: 'https://example.com/b', snippet: 'Snippet B', position: 2 },
+          ] }) };
+        }
+        if (urlStr.includes('serpapi.com')) {
+          return { ok: true, json: async () => ({ organic_results: [
+            { title: 'Result A', link: 'https://example.com/a', snippet: 'Snippet A longer', position: 1 },
+            { title: 'Result C', link: 'https://example.com/c', snippet: 'Snippet C', position: 2 },
+          ] }) };
+        }
+        if (urlStr.includes('brave.com')) {
+          return { ok: true, json: async () => ({ web: { results: [
+            { title: 'Result A', url: 'https://example.com/a', description: 'Snippet A brave' },
+          ] } }) };
+        }
+        if (urlStr.includes('localhost:8888')) {
+          return { ok: true, json: async () => ({ results: [
+            { title: 'Result A', url: 'https://example.com/a', content: 'Snippet A searxng' },
+            { title: 'Result E', url: 'https://example.com/e', content: 'Snippet E' },
+          ] }) };
+        }
+        // duckduckgo
+        return { ok: true, json: async () => ({ Heading: 'Result D', AbstractText: 'DDG snippet', AbstractURL: 'https://example.com/d', RelatedTopics: [] }) };
+      });
+
+      const result = await service.multiSearch('test query');
+
+      expect(result.metadata.providersQueried).toContain('serper');
+      expect(result.metadata.providersQueried).toContain('searxng');
+      expect(result.metadata.providersQueried).toContain('duckduckgo');
+      expect(result.metadata.deduplicatedCount).toBeLessThanOrEqual(result.metadata.totalRawResults);
+    });
+
+    it('should deduplicate results across providers', async () => {
+      const mockFetch = global.fetch as any;
+      // Route mocks by URL since Promise.allSettled doesn't guarantee call order
+      mockFetch.mockImplementation(async (url: string) => {
+        const urlStr = typeof url === 'string' ? url : url.toString();
+        if (urlStr.includes('serper.dev')) {
+          return { ok: true, json: async () => ({ organic: [{ title: 'Same', link: 'https://example.com/same', snippet: 'Same snippet', position: 1 }] }) };
+        }
+        if (urlStr.includes('serpapi.com')) {
+          return { ok: true, json: async () => ({ organic_results: [{ title: 'Same', link: 'https://example.com/same', snippet: 'Same snippet', position: 1 }] }) };
+        }
+        if (urlStr.includes('brave.com')) {
+          return { ok: true, json: async () => ({ web: { results: [{ title: 'Same', url: 'https://example.com/same', description: 'Same snippet' }] } }) };
+        }
+        if (urlStr.includes('localhost:8888')) {
+          return { ok: true, json: async () => ({ results: [{ title: 'Same', url: 'https://example.com/same', content: 'Same snippet from SearXNG' }] }) };
+        }
+        // duckduckgo
+        return { ok: true, json: async () => ({ Heading: 'Same', AbstractText: 'Same', AbstractURL: 'https://example.com/same', RelatedTopics: [] }) };
+      });
+
+      const result = await service.multiSearch('test');
+
+      // Should be deduplicated to 1 result
+      expect(result.results).toHaveLength(1);
+      expect(result.results[0].agreementCount).toBeGreaterThanOrEqual(4);
+    });
+
+    it('should rank results with more provider agreement higher', async () => {
+      const mockFetch = global.fetch as any;
+      mockFetch.mockImplementation(async (url: string) => {
+        const urlStr = typeof url === 'string' ? url : url.toString();
+        if (urlStr.includes('serper.dev')) {
+          return { ok: true, json: async () => ({ organic: [
+            { title: 'A', link: 'https://example.com/a', snippet: 'A', position: 1 },
+            { title: 'B', link: 'https://example.com/b', snippet: 'B', position: 2 },
+          ] }) };
+        }
+        if (urlStr.includes('serpapi.com')) {
+          return { ok: true, json: async () => ({ organic_results: [
+            { title: 'A', link: 'https://example.com/a', snippet: 'A', position: 1 },
+          ] }) };
+        }
+        if (urlStr.includes('brave.com')) {
+          return { ok: true, json: async () => ({ web: { results: [
+            { title: 'A', url: 'https://example.com/a', description: 'A' },
+          ] } }) };
+        }
+        if (urlStr.includes('localhost:8888')) {
+          return { ok: true, json: async () => ({ results: [
+            { title: 'A', url: 'https://example.com/a', content: 'A' },
+          ] }) };
+        }
+        // duckduckgo returns B only
+        return { ok: true, json: async () => ({ Heading: 'B', AbstractText: 'B', AbstractURL: 'https://example.com/b', RelatedTopics: [] }) };
+      });
+
+      const result = await service.multiSearch('test');
+
+      // A appears in 4 providers, B in 2 — A should rank first
+      expect(result.results[0].url).toBe('https://example.com/a');
+      expect(result.results[0].confidenceScore).toBeGreaterThan(result.results[1].confidenceScore);
+    });
+
+    it('should handle all providers failing gracefully', async () => {
+      const mockFetch = global.fetch as any;
+      mockFetch.mockRejectedValue(new Error('Network error'));
+
+      const result = await service.multiSearch('test');
+
+      expect(result.results).toHaveLength(0);
+      expect(result.metadata.providersFailed.length).toBeGreaterThan(0);
+    });
+  });
+
   describe('getRecommendedProviders', () => {
-    it('should return provider recommendations', () => {
+    it('should return provider recommendations including SearXNG', () => {
       const providers = SearchProviderService.getRecommendedProviders();
-      expect(providers).toHaveLength(4);
+      expect(providers).toHaveLength(5);
       expect(providers[0].name).toBe('Serper');
       expect(providers[0].signupUrl).toContain('serper.dev');
+      const searxng = providers.find((p) => p.name === 'SearXNG');
+      expect(searxng).toBeDefined();
+      expect(searxng!.freeQuota).toContain('Unlimited');
     });
   });
 });

package/test/webSearch.spec.ts

@@ -8,7 +8,13 @@ vi.mock('../src/services/searchProvider');
 describe('WebSearchTool', () => {
   let tool: WebSearchTool;
   let mockSearchService: vi.Mocked<SearchProviderService>;
-  
+
+  const ctx: any = {
+    gmiId: 'test-gmi',
+    personaId: 'test-persona',
+    userContext: { userId: 'test-user' },
+  };
+
   beforeEach(() => {
     mockSearchService = new SearchProviderService({}) as any;
     tool = new WebSearchTool(mockSearchService);
@@ -17,8 +23,9 @@ describe('WebSearchTool', () => {
   
   describe('constructor', () => {
     it('should initialize with correct metadata', () => {
-      expect(tool.id).toBe('webSearch');
-      expect(tool.name).toBe('Web Search');
+      expect(tool.id).toBe('web-search-v1');
+      expect(tool.name).toBe('web_search');
+      expect(tool.displayName).toBe('Web Search');
       expect(tool.description).toContain('Search the web');
     });
   });
@@ -41,11 +48,12 @@ describe('WebSearchTool', () => {
         provider: 'serper' as const
       };
       
-      const result = await tool.execute(input);
+      const result = await tool.execute(input, ctx);
       
       expect(mockSearchService.search).toHaveBeenCalledWith('test query', {
         maxResults: 5,
-        provider: 'serper'
+        provider: 'serper',
+        category: undefined,
       });
       expect(result.success).toBe(true);
       expect(result.output).toEqual(mockResults);
@@ -56,7 +64,7 @@ describe('WebSearchTool', () => {
       mockSearchService.search = vi.fn().mockRejectedValue(error);
       
       const input = { query: 'test query' };
-      const result = await tool.execute(input);
+      const result = await tool.execute(input as any, ctx);
       
       expect(result.success).toBe(false);
       expect(result.error).toBe('API error');
@@ -68,61 +76,155 @@ describe('WebSearchTool', () => {
         results: [],
         metadata: {}
       });
-      
+
       const input = { query: 'test query' };
-      await tool.execute(input);
-      
+      await tool.execute(input as any, ctx);
+
       expect(mockSearchService.search).toHaveBeenCalledWith('test query', {
         maxResults: 10,
-        provider: undefined
+        provider: undefined,
+        category: undefined,
+      });
+    });
+
+    it('should pass category to search service', async () => {
+      mockSearchService.search = vi.fn().mockResolvedValue({
+        provider: 'searxng',
+        results: [],
+        metadata: {}
+      });
+
+      await tool.execute({ query: 'AI news', provider: 'searxng', category: 'news' }, ctx);
+
+      expect(mockSearchService.search).toHaveBeenCalledWith('AI news', {
+        maxResults: 10,
+        provider: 'searxng',
+        category: 'news',
       });
     });
   });
   
-  describe('validate', () => {
+  describe('validateArgs', () => {
     it('should validate required query parameter', () => {
-      const result = tool.validate({});
-      expect(result.valid).toBe(false);
+      const result = tool.validateArgs({});
+      expect(result.isValid).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);
+      const result = tool.validateArgs({ query: 123 });
+      expect(result.isValid).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);
+      const result = tool.validateArgs({ query: 'test', maxResults: -1 });
+      expect(result.isValid).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);
+      const result = tool.validateArgs({ query: 'test', provider: 'invalid' });
+      expect(result.isValid).toBe(false);
       expect(result.errors).toContain('Invalid provider');
     });
-    
+
     it('should pass validation with correct inputs', () => {
-      const result = tool.validate({ 
+      const result = tool.validateArgs({
         query: 'test query',
         maxResults: 5,
         provider: 'serper'
       });
-      expect(result.valid).toBe(true);
-      expect(result.errors).toHaveLength(0);
+      expect(result.isValid).toBe(true);
+    });
+
+    it('should accept searxng as a valid provider', () => {
+      const result = tool.validateArgs({ query: 'test', provider: 'searxng' });
+      expect(result.isValid).toBe(true);
     });
   });
   
-  describe('getSchema', () => {
+  describe('multiSearch', () => {
+    it('should call multiSearch when multiSearch input is true', async () => {
+      const mockMultiResults = {
+        results: [{ title: 'Multi', url: 'https://example.com', snippet: 'Multi result', providers: ['serper', 'brave'], agreementCount: 2, confidenceScore: 80, providerPositions: { serper: 1, brave: 1 } }],
+        metadata: { query: 'test', timestamp: new Date().toISOString(), totalResponseTime: 100, providersQueried: ['serper', 'brave'], providersSucceeded: ['serper', 'brave'], providersFailed: [], totalRawResults: 2, deduplicatedCount: 1 },
+      };
+      mockSearchService.multiSearch = vi.fn().mockResolvedValue(mockMultiResults);
+
+      const result = await tool.execute({ query: 'test', multiSearch: true }, ctx);
+
+      expect(mockSearchService.multiSearch).toHaveBeenCalledWith('test', { maxResults: 10 });
+      expect(result.success).toBe(true);
+      expect(result.output).toEqual(mockMultiResults);
+    });
+
+    it('should use defaultMultiSearch from constructor when input omits multiSearch', async () => {
+      const toolWithDefault = new WebSearchTool(mockSearchService, true);
+      const mockMultiResults = {
+        results: [],
+        metadata: { query: 'test', timestamp: new Date().toISOString(), totalResponseTime: 50, providersQueried: [], providersSucceeded: [], providersFailed: [], totalRawResults: 0, deduplicatedCount: 0 },
+      };
+      mockSearchService.multiSearch = vi.fn().mockResolvedValue(mockMultiResults);
+
+      await toolWithDefault.execute({ query: 'test' }, ctx);
+
+      expect(mockSearchService.multiSearch).toHaveBeenCalled();
+    });
+
+    it('should fall back to single search when provider is specified even with multiSearch', async () => {
+      mockSearchService.search = vi.fn().mockResolvedValue({ provider: 'serper', results: [], metadata: {} });
+
+      await tool.execute({ query: 'test', multiSearch: true, provider: 'serper' }, ctx);
+
+      // When provider is specified, multiSearch is ignored — single provider search is used
+      expect(mockSearchService.search).toHaveBeenCalled();
+    });
+  });
+
+  describe('validateArgs - multiSearch', () => {
+    it('should reject multiSearch + provider combination', () => {
+      const result = tool.validateArgs({ query: 'test', multiSearch: true, provider: 'serper' });
+      expect(result.isValid).toBe(false);
+      expect(result.errors).toContain('Cannot specify both multiSearch and a specific provider');
+    });
+
+    it('should reject non-boolean multiSearch', () => {
+      const result = tool.validateArgs({ query: 'test', multiSearch: 'yes' });
+      expect(result.isValid).toBe(false);
+      expect(result.errors).toContain('multiSearch must be a boolean');
+    });
+
+    it('should accept multiSearch: true without provider', () => {
+      const result = tool.validateArgs({ query: 'test', multiSearch: true });
+      expect(result.isValid).toBe(true);
+    });
+  });
+
+  describe('inputSchema', () => {
     it('should return proper JSON schema', () => {
-      const schema = tool.getSchema();
+      const schema = tool.inputSchema;
       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.maxResults.type).toBe('integer');
       expect(schema.properties.provider.enum).toContain('serper');
+      expect(schema.properties.provider.enum).toContain('searxng');
+    });
+
+    it('should include multiSearch in schema', () => {
+      const schema = tool.inputSchema;
+      expect(schema.properties.multiSearch).toBeDefined();
+      expect(schema.properties.multiSearch.type).toBe('boolean');
+      expect(schema.properties.multiSearch.default).toBe(false);
+    });
+
+    it('should include category field for SearXNG', () => {
+      const schema = tool.inputSchema;
+      expect(schema.properties.category).toBeDefined();
+      expect(schema.properties.category.type).toBe('string');
+      expect(schema.properties.category.enum).toContain('news');
+      expect(schema.properties.category.enum).toContain('science');
     });
   });
-});
+});

package/tsconfig.json

@@ -1,8 +1,14 @@
 {
   "compilerOptions": {
     "target": "ES2022",
-    "module": "commonjs",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
     "lib": ["ES2022"],
+    "baseUrl": ".",
+    "paths": {
+      "@framers/agentos": ["../../../../../agentos/dist/index.d.ts"],
+      "@framers/agentos/*": ["../../../../../agentos/dist/*"]
+    },
     "outDir": "./dist",
     "rootDir": "./src",
     "strict": true,
@@ -13,7 +19,6 @@
     "declarationMap": true,
     "sourceMap": true,
     "resolveJsonModule": true,
-    "moduleResolution": "node",
     "types": ["node"]
   },
   "include": ["src/**/*"],