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

package/src/tools/webSearch.ts

@@ -1,129 +0,0 @@
-/**
- * Web Search Tool — multi-provider search via SearchProviderService.
- *
- * Updated to conform to AgentOS `ITool` (inputSchema + ToolExecutionContext).
- *
- * @module @framers/agentos-ext-web-search
- */
-
-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,
-        category: input.category,
-      });
-      return { success: true, output: results };
-    } catch (error: any) {
-      return { success: false, error: error?.message || String(error) };
-    }
-  }
-
-  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', 'searxng', 'duckduckgo'];
-      if (!validProviders.includes(input.provider)) {
-        errors.push('Invalid provider');
-      }
-    }
-
-    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/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,374 +0,0 @@
-import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { createExtensionPack } from '../src';
-import { ExtensionContext } from '@framers/agentos';
-
-describe('Web Search Extension Integration', () => {
-  let extensionPack: any;
-  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,
-        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.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('web_search');
-      expect(toolIds).toContain('research_aggregate');
-      expect(toolIds).toContain('fact_check');
-    });
-    
-    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 === '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);
-      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 === '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);
-      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 === '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);
-      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'
-      }, {
-        gmiId: 'test-gmi',
-        personaId: 'test-persona',
-        userContext: { userId: 'test-user' },
-      });
-      
-      // 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 === 'web_search'
-      );
-      const webSearchTool = webSearchDescriptor.payload;
-      
-      const validation = webSearchTool.validateArgs({
-        // Missing required 'query' field
-        maxResults: 5
-      });
-      
-      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 () => {
-      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(logSpy).toHaveBeenCalledWith('Web Search Extension activated');
-    });
-
-    it('should call onDeactivate when extension is deactivated', async () => {
-      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(logSpy).toHaveBeenCalledWith('Web Search Extension deactivated');
-    });
-  });
-});