@pellux/goodvibes-sdk 0.18.14 → 0.18.15

package/dist/_internal/platform/web-search/providers/searxng.js

@@ -0,0 +1,79 @@
+import { buildDescriptor, executeJsonRequest, firstString, resultFromRecord, } from './shared.js';
+const SEARXNG_ENV_KEYS = ['SEARXNG_BASE_URL'];
+const SEARXNG_SERVICE_NAME = 'searxng';
+function mapTimeRange(value) {
+    switch (value) {
+        case 'day':
+            return 'day';
+        case 'month':
+            return 'month';
+        case 'year':
+            return 'year';
+        default:
+            return undefined;
+    }
+}
+export function createSearxngSearchProvider(context) {
+    const env = context.env;
+    const serviceRegistry = context.serviceRegistry;
+    return {
+        id: 'searxng',
+        label: 'SearXNG',
+        capabilities: ['search', 'evidence'],
+        descriptor() {
+            return buildDescriptor({
+                id: 'searxng',
+                label: 'SearXNG',
+                note: 'Uses a SearXNG instance via its JSON search API. Configure SEARXNG_BASE_URL or a searxng service entry.',
+                requiresAuth: false,
+                serviceName: SEARXNG_SERVICE_NAME,
+                baseUrlEnvCandidates: SEARXNG_ENV_KEYS,
+            }, { env, serviceRegistry });
+        },
+        async search(request) {
+            const maxResults = Math.max(1, Math.min(25, request.maxResults ?? 10));
+            const baseUrl = (env.SEARXNG_BASE_URL ?? serviceRegistry.get(SEARXNG_SERVICE_NAME)?.baseUrl ?? '').trim().replace(/\/+$/, '');
+            if (!baseUrl) {
+                throw new Error('SearXNG requires SEARXNG_BASE_URL or a searxng service entry with baseUrl.');
+            }
+            const { payload } = await executeJsonRequest({
+                url: `${baseUrl}/search`,
+                params: {
+                    q: request.query,
+                    format: 'json',
+                    pageno: '1',
+                    ...(request.region ? { language: request.region } : {}),
+                    ...(mapTimeRange(request.timeRange) ? { time_range: mapTimeRange(request.timeRange) } : {}),
+                },
+                headers: { Accept: 'application/json' },
+                service: serviceRegistry.get(SEARXNG_SERVICE_NAME) ? SEARXNG_SERVICE_NAME : undefined,
+                fetcher: context.fetcher,
+            });
+            const results = Array.isArray(payload.results)
+                ? payload.results
+                    .slice(0, maxResults)
+                    .map((entry, index) => {
+                    if (!entry || typeof entry !== 'object')
+                        return null;
+                    const record = entry;
+                    return resultFromRecord('searxng', index + 1, record, {
+                        urlKeys: ['url'],
+                        titleKeys: ['title'],
+                        snippetKeys: ['content'],
+                        metadata: {
+                            engine: firstString(record, ['engine']),
+                            publishedDate: firstString(record, ['publishedDate', 'published_date']),
+                        },
+                    });
+                })
+                    .filter((entry) => entry !== null)
+                : [];
+            return {
+                results,
+                metadata: {
+                    numberOfResults: typeof payload.number_of_results === 'number' ? payload.number_of_results : undefined,
+                },
+            };
+        },
+    };
+}

package/dist/_internal/platform/web-search/providers/shared.d.ts

@@ -0,0 +1,56 @@
+import type { ServiceRegistry } from '../../config/service-registry.js';
+import { type FetchOutput, type FetchUrlResult } from '../../tools/fetch/index.js';
+import type { FetchAuthInput, FetchInput } from '@pellux/goodvibes-sdk/platform/tools/fetch/schema';
+import type { WebSearchEvidence, WebSearchProviderDescriptor, WebSearchResult } from '@pellux/goodvibes-sdk/platform/web-search/types';
+type EnvMap = Record<string, string | undefined>;
+type FetchExecutor = (input: FetchInput) => Promise<FetchOutput>;
+export interface SearchProviderContext {
+    readonly fetcher?: FetchExecutor;
+    readonly env: EnvMap;
+    readonly serviceRegistry: Pick<ServiceRegistry, 'get'>;
+}
+export interface SearchProviderConfig {
+    readonly id: string;
+    readonly label: string;
+    readonly note: string;
+    readonly envKeyCandidates?: readonly string[];
+    readonly serviceName?: string;
+    readonly baseUrlEnvCandidates?: readonly string[];
+    readonly defaultBaseUrl?: string;
+    readonly requiresAuth?: boolean;
+}
+export interface JsonRequestConfig {
+    readonly url: string;
+    readonly method?: 'GET' | 'POST';
+    readonly params?: Record<string, string>;
+    readonly body?: Record<string, unknown>;
+    readonly headers?: Record<string, string>;
+    readonly service?: string;
+    readonly auth?: FetchAuthInput;
+    readonly fetcher?: FetchExecutor;
+    readonly maxContentLength?: number;
+}
+export interface JsonRequestResult<T = unknown> {
+    readonly payload: T;
+    readonly response: FetchUrlResult;
+}
+export declare function resolveDomain(url: string): string | undefined;
+export declare function trimSnippet(value: unknown, limit?: number): string | undefined;
+export declare function makeEvidence(url: string, content: unknown, metadata?: Record<string, unknown>, extract?: 'raw' | 'text' | 'json' | 'markdown' | 'readable' | 'code_blocks' | 'links' | 'metadata' | 'structured' | 'tables' | 'pdf' | 'summary'): WebSearchEvidence[] | undefined;
+export declare function withInlineApiKey(env: EnvMap, envKeys: readonly string[] | undefined, headerName: string): FetchAuthInput | undefined;
+export declare function withInlineBearer(env: EnvMap, envKeys: readonly string[] | undefined): FetchAuthInput | undefined;
+export declare function hasConfiguredCredential(serviceRegistry: Pick<ServiceRegistry, 'get'>, env: EnvMap, envKeys: readonly string[] | undefined, serviceName?: string): boolean;
+export declare function resolveBaseUrl(serviceRegistry: Pick<ServiceRegistry, 'get'>, env: EnvMap, envKeys: readonly string[] | undefined, serviceName: string | undefined, defaultBaseUrl?: string): string | null;
+export declare function buildDescriptor(config: SearchProviderConfig, context: SearchProviderContext): WebSearchProviderDescriptor;
+export declare function executeJsonRequest<T = unknown>(config: JsonRequestConfig): Promise<JsonRequestResult<T>>;
+export declare function resultFromRecord(providerId: string, rank: number, record: Record<string, unknown>, options?: {
+    readonly urlKeys?: readonly string[];
+    readonly titleKeys?: readonly string[];
+    readonly snippetKeys?: readonly string[];
+    readonly displayUrlKeys?: readonly string[];
+    readonly evidenceKeys?: readonly string[];
+    readonly metadata?: Record<string, unknown>;
+}): WebSearchResult | null;
+export declare function firstString(record: Record<string, unknown>, keys: readonly string[]): string | undefined;
+export {};
+//# sourceMappingURL=shared.d.ts.map

package/dist/_internal/platform/web-search/providers/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/web-search/providers/shared.ts"],"names":[],"mappings":"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"}

package/dist/_internal/platform/web-search/providers/shared.js

@@ -0,0 +1,169 @@
+import { executeFetchInput } from '../../tools/fetch/index.js';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+export function resolveDomain(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function trimSnippet(value, limit = 320) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.replace(/\s+/g, ' ').trim();
+    if (!normalized)
+        return undefined;
+    if (normalized.length <= limit)
+        return normalized;
+    return `${normalized.slice(0, Math.max(0, limit - 3)).trimEnd()}...`;
+}
+export function makeEvidence(url, content, metadata = {}, extract = 'summary') {
+    if (typeof content !== 'string')
+        return undefined;
+    const normalized = content.trim();
+    if (!normalized)
+        return undefined;
+    return [{
+            url,
+            extract,
+            content: normalized,
+            tokensUsed: Math.ceil(normalized.length / 4),
+            metadata,
+        }];
+}
+export function withInlineApiKey(env, envKeys, headerName) {
+    if (!envKeys || envKeys.length === 0)
+        return undefined;
+    for (const key of envKeys) {
+        const value = env[key];
+        if (typeof value === 'string' && value.trim().length > 0) {
+            return {
+                type: 'api-key',
+                header: headerName,
+                key: value.trim(),
+            };
+        }
+    }
+    return undefined;
+}
+export function withInlineBearer(env, envKeys) {
+    if (!envKeys || envKeys.length === 0)
+        return undefined;
+    for (const key of envKeys) {
+        const value = env[key];
+        if (typeof value === 'string' && value.trim().length > 0) {
+            return {
+                type: 'bearer',
+                token: value.trim(),
+            };
+        }
+    }
+    return undefined;
+}
+export function hasConfiguredCredential(serviceRegistry, env, envKeys, serviceName) {
+    const envConfigured = (envKeys ?? []).some((key) => typeof env[key] === 'string' && env[key].trim().length > 0);
+    if (envConfigured)
+        return true;
+    return Boolean(serviceName && serviceRegistry.get(serviceName));
+}
+export function resolveBaseUrl(serviceRegistry, env, envKeys, serviceName, defaultBaseUrl) {
+    for (const key of envKeys ?? []) {
+        const value = env[key];
+        if (typeof value === 'string' && value.trim().length > 0) {
+            return value.trim().replace(/\/+$/, '');
+        }
+    }
+    const configuredService = serviceName ? serviceRegistry.get(serviceName) : null;
+    const serviceUrl = configuredService?.baseUrl?.trim();
+    if (serviceUrl)
+        return serviceUrl.replace(/\/+$/, '');
+    return defaultBaseUrl ? defaultBaseUrl.replace(/\/+$/, '') : null;
+}
+export function buildDescriptor(config, context) {
+    const configured = config.requiresAuth === false
+        ? resolveBaseUrl(context.serviceRegistry, context.env, config.baseUrlEnvCandidates, config.serviceName, config.defaultBaseUrl) != null
+        : hasConfiguredCredential(context.serviceRegistry, context.env, config.envKeyCandidates, config.serviceName);
+    return {
+        id: config.id,
+        label: config.label,
+        capabilities: ['search', 'evidence'],
+        requiresAuth: config.requiresAuth ?? true,
+        configured,
+        note: config.note,
+    };
+}
+export async function executeJsonRequest(config) {
+    const fetcher = config.fetcher ?? executeFetchInput;
+    const urlInput = {
+        url: config.url,
+        method: config.method ?? 'GET',
+        extract: 'json',
+        ...(config.params ? { params: config.params } : {}),
+        ...(config.headers ? { headers: config.headers } : {}),
+        ...(config.body ? { body_type: 'json', body: JSON.stringify(config.body) } : {}),
+        ...(config.service ? { service: config.service } : {}),
+        ...(config.auth ? { auth: config.auth } : {}),
+        ...(config.maxContentLength ? { max_content_length: config.maxContentLength } : {}),
+    };
+    const output = await fetcher({
+        urls: [urlInput],
+        parallel: false,
+        verbosity: 'standard',
+        sanitize_mode: 'safe-text',
+        max_content_length: config.maxContentLength ?? 512_000,
+    });
+    const response = output.results?.[0];
+    if (!response || response.error || typeof response.content !== 'string') {
+        throw new Error(response?.error ?? `Search provider request failed for ${config.url}`);
+    }
+    let payload;
+    try {
+        payload = JSON.parse(response.content);
+    }
+    catch (error) {
+        throw new Error(`Search provider returned invalid JSON for ${config.url}: ${summarizeError(error)}`);
+    }
+    return { payload, response };
+}
+export function resultFromRecord(providerId, rank, record, options = {}) {
+    const url = firstString(record, options.urlKeys ?? ['url', 'link', 'id']);
+    if (!url)
+        return null;
+    return {
+        rank,
+        url,
+        ...(firstString(record, options.titleKeys ?? ['title', 'name', 'heading']) ? { title: firstString(record, options.titleKeys ?? ['title', 'name', 'heading']) } : {}),
+        ...(trimSnippet(firstString(record, options.snippetKeys ?? ['snippet', 'description', 'content', 'text'])) ? { snippet: trimSnippet(firstString(record, options.snippetKeys ?? ['snippet', 'description', 'content', 'text'])) } : {}),
+        ...(firstString(record, options.displayUrlKeys ?? ['displayUrl', 'display_url']) ? { displayUrl: firstString(record, options.displayUrlKeys ?? ['displayUrl', 'display_url']) } : {}),
+        ...(resolveDomain(url) ? { domain: resolveDomain(url) } : {}),
+        type: 'organic',
+        providerId,
+        metadata: {
+            ...(options.metadata ?? {}),
+            ...(options.evidenceKeys
+                ? {
+                    hasProviderEvidence: options.evidenceKeys.some((key) => typeof record[key] === 'string' && String(record[key]).trim().length > 0),
+                }
+                : {}),
+        },
+        ...(providerEvidence(url, record, options.evidenceKeys) ? { evidence: providerEvidence(url, record, options.evidenceKeys) } : {}),
+    };
+}
+export function firstString(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === 'string' && value.trim().length > 0)
+            return value.trim();
+    }
+    return undefined;
+}
+function providerEvidence(url, record, keys) {
+    for (const key of keys ?? []) {
+        const value = record[key];
+        if (typeof value !== 'string' || value.trim().length === 0)
+            continue;
+        return makeEvidence(url, value, { providerField: key });
+    }
+    return undefined;
+}

package/dist/_internal/platform/web-search/providers/tavily.d.ts

@@ -0,0 +1,4 @@
+import type { WebSearchProvider } from '@pellux/goodvibes-sdk/platform/web-search/types';
+import { type SearchProviderContext } from './shared.js';
+export declare function createTavilySearchProvider(context: SearchProviderContext): WebSearchProvider;
+//# sourceMappingURL=tavily.d.ts.map

package/dist/_internal/platform/web-search/providers/tavily.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tavily.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/web-search/providers/tavily.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA0B,iBAAiB,EAA+C,MAAM,iDAAiD,CAAC;AAC9J,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,aAAa,CAAC;AAkBrB,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,qBAAqB,GAAG,iBAAiB,CA+D5F"}

package/dist/_internal/platform/web-search/providers/tavily.js

@@ -0,0 +1,81 @@
+import { buildDescriptor, executeJsonRequest, firstString, resultFromRecord, withInlineBearer, } from './shared.js';
+const TAVILY_DEFAULT_BASE_URL = 'https://api.tavily.com';
+const TAVILY_ENV_KEYS = ['TAVILY_API_KEY'];
+const TAVILY_SERVICE_NAME = 'tavily';
+function buildInstantAnswer(payload) {
+    const answer = firstString(payload, ['answer']);
+    if (!answer)
+        return undefined;
+    return {
+        heading: 'Tavily Answer',
+        answer,
+        type: 'answer',
+        related: [],
+        metadata: {},
+    };
+}
+export function createTavilySearchProvider(context) {
+    const env = context.env;
+    const serviceRegistry = context.serviceRegistry;
+    return {
+        id: 'tavily',
+        label: 'Tavily',
+        capabilities: ['search', 'instant_answer', 'evidence'],
+        descriptor() {
+            return buildDescriptor({
+                id: 'tavily',
+                label: 'Tavily',
+                note: 'Uses Tavily Search JSON results. Configure via TAVILY_API_KEY or a tavily service entry.',
+                envKeyCandidates: TAVILY_ENV_KEYS,
+                serviceName: TAVILY_SERVICE_NAME,
+                defaultBaseUrl: TAVILY_DEFAULT_BASE_URL,
+            }, { env, serviceRegistry });
+        },
+        async search(request) {
+            const maxResults = Math.max(1, Math.min(20, request.maxResults ?? 10));
+            const baseUrl = (serviceRegistry.get(TAVILY_SERVICE_NAME)?.baseUrl ?? TAVILY_DEFAULT_BASE_URL).replace(/\/+$/, '');
+            const { payload } = await executeJsonRequest({
+                url: `${baseUrl}/search`,
+                method: 'POST',
+                headers: { Accept: 'application/json' },
+                body: {
+                    query: request.query,
+                    max_results: maxResults,
+                    include_answer: request.includeInstantAnswer !== false,
+                    search_depth: request.includeEvidence || request.verbosity === 'evidence' || request.verbosity === 'full'
+                        ? 'advanced'
+                        : 'basic',
+                },
+                service: serviceRegistry.get(TAVILY_SERVICE_NAME) ? TAVILY_SERVICE_NAME : undefined,
+                auth: serviceRegistry.get(TAVILY_SERVICE_NAME) ? undefined : withInlineBearer(env, TAVILY_ENV_KEYS),
+                fetcher: context.fetcher,
+            });
+            const results = Array.isArray(payload.results)
+                ? payload.results
+                    .map((entry, index) => {
+                    if (!entry || typeof entry !== 'object')
+                        return null;
+                    const record = entry;
+                    return resultFromRecord('tavily', index + 1, record, {
+                        urlKeys: ['url'],
+                        titleKeys: ['title'],
+                        snippetKeys: ['content'],
+                        evidenceKeys: ['raw_content'],
+                        metadata: {
+                            score: typeof record.score === 'number' ? record.score : undefined,
+                        },
+                    });
+                })
+                    .filter((entry) => entry !== null)
+                : [];
+            return {
+                results,
+                ...(buildInstantAnswer(payload) ? { instantAnswer: buildInstantAnswer(payload) } : {}),
+                metadata: {
+                    requestId: firstString(payload, ['request_id']),
+                    responseTime: firstString(payload, ['response_time']),
+                },
+            };
+        },
+    };
+}

package/dist/_internal/platform/web-search/service.d.ts

@@ -0,0 +1,19 @@
+import { type FetchRuntimeDeps } from '../tools/fetch/index.js';
+import { WebSearchProviderRegistry } from './provider-registry.js';
+import type { WebSearchRequest, WebSearchResponse } from '@pellux/goodvibes-sdk/platform/web-search/types';
+export interface WebSearchServiceStatus {
+    readonly enabled: boolean;
+    readonly providerCount: number;
+    readonly providers: ReturnType<WebSearchProviderRegistry['list']>;
+    readonly note: string;
+}
+export declare class WebSearchService {
+    private readonly registry;
+    private readonly fetchDeps;
+    private readonly fetchRuntime;
+    constructor(registry: WebSearchProviderRegistry, fetchDeps?: FetchRuntimeDeps);
+    getStatus(): Promise<WebSearchServiceStatus>;
+    search(request: WebSearchRequest): Promise<WebSearchResponse>;
+    private attachEvidence;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/_internal/platform/web-search/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/web-search/service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAErF,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,KAAK,EAGV,gBAAgB,EAChB,iBAAiB,EAGlB,MAAM,iDAAiD,CAAC;AAEzD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC,yBAAyB,CAAC,MAAM,CAAC,CAAC,CAAC;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAkCD,qBAAa,gBAAgB;IAIzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAJ5B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;gBAGvC,QAAQ,EAAE,yBAAyB,EACnC,SAAS,GAAE,gBAAqB;IAG7C,SAAS,IAAI,OAAO,CAAC,sBAAsB,CAAC;IAU5C,MAAM,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;YAyBrD,cAAc;CA+C7B"}

package/dist/_internal/platform/web-search/service.js

@@ -0,0 +1,120 @@
+import { FetchRuntimeService } from '../tools/fetch/index.js';
+import { WebSearchProviderRegistry } from './provider-registry.js';
+function selectEvidenceExtract(request, verbosity) {
+    if (request.evidenceExtract)
+        return request.evidenceExtract;
+    return verbosity === 'full' ? 'readable' : 'summary';
+}
+function shapeResultForVerbosity(result, verbosity) {
+    switch (verbosity) {
+        case 'urls_only':
+            return {
+                rank: result.rank,
+                url: result.url,
+                ...(result.domain ? { domain: result.domain } : {}),
+                type: result.type,
+                providerId: result.providerId,
+                metadata: result.metadata,
+            };
+        case 'titles':
+            return {
+                ...shapeResultForVerbosity(result, 'urls_only'),
+                ...(result.title ? { title: result.title } : {}),
+                ...(result.displayUrl ? { displayUrl: result.displayUrl } : {}),
+            };
+        case 'snippets':
+            return {
+                ...shapeResultForVerbosity(result, 'titles'),
+                ...(result.snippet ? { snippet: result.snippet } : {}),
+            };
+        default:
+            return result;
+    }
+}
+export class WebSearchService {
+    registry;
+    fetchDeps;
+    fetchRuntime = new FetchRuntimeService();
+    constructor(registry, fetchDeps = {}) {
+        this.registry = registry;
+        this.fetchDeps = fetchDeps;
+    }
+    async getStatus() {
+        const providers = this.registry.list();
+        return {
+            enabled: providers.length > 0,
+            providerCount: providers.length,
+            providers,
+            note: 'Web search uses provider-backed discovery and normalizes results before they reach the model.',
+        };
+    }
+    async search(request) {
+        const provider = this.registry.find(request.providerId);
+        if (!provider) {
+            throw new Error(request.providerId ? `Web search provider unavailable: ${request.providerId}` : 'No web search provider is registered');
+        }
+        const verbosity = request.verbosity ?? 'snippets';
+        const baseResponse = await provider.search(request);
+        const evidenceEnabled = request.includeEvidence || verbosity === 'evidence' || verbosity === 'full';
+        const resultsWithEvidence = evidenceEnabled
+            ? await this.attachEvidence(baseResponse.results, request)
+            : baseResponse.results;
+        const shapedResults = resultsWithEvidence.map((result) => shapeResultForVerbosity(result, verbosity));
+        return {
+            providerId: provider.id,
+            providerLabel: provider.label,
+            query: request.query,
+            verbosity,
+            results: shapedResults,
+            ...(baseResponse.instantAnswer ? { instantAnswer: baseResponse.instantAnswer } : {}),
+            metadata: baseResponse.metadata,
+        };
+    }
+    async attachEvidence(results, request) {
+        const evidenceTopN = Math.max(1, Math.min(10, request.evidenceTopN ?? 3));
+        const extract = selectEvidenceExtract(request, request.verbosity ?? 'snippets');
+        const selectedIndexes = results
+            .map((result, index) => ({ result, index }))
+            .filter(({ result, index }) => index < evidenceTopN && (!result.evidence || result.evidence.length === 0));
+        if (selectedIndexes.length === 0)
+            return results;
+        const fetched = await this.fetchRuntime.execute({
+            urls: selectedIndexes.map(({ result }) => ({
+                url: result.url,
+                extract,
+                max_content_length: extract === 'readable' ? 20_000 : 10_000,
+            })),
+            parallel: true,
+            verbosity: 'standard',
+            sanitize_mode: 'safe-text',
+            ...(request.trustedHosts ? { trusted_hosts: [...request.trustedHosts] } : {}),
+            ...(request.blockedHosts ? { blocked_hosts: [...request.blockedHosts] } : {}),
+        }, this.fetchDeps);
+        const evidenceByUrl = new Map();
+        for (const result of fetched.results ?? []) {
+            if (!result.content || result.error)
+                continue;
+            evidenceByUrl.set(result.url, {
+                url: result.final_url ?? result.url,
+                extract,
+                content: result.content,
+                tokensUsed: result.tokens_used ?? Math.ceil(result.content.length / 4),
+                ...(result.status ? { status: result.status } : {}),
+                ...(result.contentType ? { contentType: result.contentType } : {}),
+                ...(result.truncated ? { truncated: true } : {}),
+                metadata: {
+                    redirected: result.redirected ?? false,
+                },
+            });
+        }
+        return results.map((result) => {
+            const evidence = evidenceByUrl.get(result.url);
+            if (!evidence)
+                return result;
+            return {
+                ...result,
+                evidence: [...(result.evidence ?? []), evidence],
+            };
+        });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-sdk",
-  "version": "0.18.14",
+  "version": "0.18.15",
   "description": "Umbrella GoodVibes SDK with operator, peer, daemon, transport, and runtime-specific integration layers.",
   "type": "module",
   "main": "./dist/index.js",