@theowlops/boombot 0.0.0-stage → 1.1.1

package/dist/node_modules/@boombot/core/memory/types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @boombot/core — public types.
+ *
+ * Every record names an
+ * explicit scope, and every query names authorized scopes. Retrieval applies
+ * authorization before ranking; revoked/deleted records never surface.
+ *
+ * Scope kinds used here:
+ * - `principal` — private to one authenticated principal (≈ spec `user`).
+ * - `session`   — visible inside one session only.
+ * - `global`    — shared knowledge visible to every principal.
+ */
+/** Scope a memory record belongs to. */
+export type MemoryScopeKind = 'principal' | 'session' | 'global' | 'conversation' | 'group';
+export interface MemoryScope {
+    kind: MemoryScopeKind;
+    /** Principal id / session id / the literal id of the shared scope. */
+    id: string;
+}
+/** Where a record came from — provenance is preserved, never inferred. */
+export interface MemoryProvenance {
+    source: 'user' | 'system' | 'tool' | 'model';
+    /** Human/machine reference, e.g. a turn id or tool call id. */
+    reference: string;
+    /** Principal (or system component) that proposed the write. */
+    actorId: string;
+    /** ISO-8601 timestamp of the write proposal. */
+    at: string;
+}
+/** A durable memory record. Recalled content is untrusted context. */
+export interface MemoryRecord {
+    /** Stable id, caller-provided (e.g. uuid). */
+    id: string;
+    scope: MemoryScope;
+    /** Normalized content that gets indexed by FTS5. */
+    text: string;
+    provenance: MemoryProvenance;
+    /** ISO-8601 creation timestamp. */
+    createdAt: string;
+    /** Set when revoked (tombstoned). Tombstoned records stay for audit. */
+    tombstonedAt?: string;
+}
+/** What the host resolved for the caller before any query runs. */
+export interface MemoryAuthorization {
+    principalId: string;
+    /** Scopes the caller may read. The store never widens this set. */
+    readableScopes: readonly MemoryScope[];
+}
+export type MatchMode = 'any' | 'all';
+export interface SearchOptions {
+    /** Raw user query — never passed to FTS directly, always sanitized. */
+    query: string;
+    /** Authorized scopes to search. Must be non-empty. */
+    scopes: readonly MemoryScope[];
+    /** Max hits. Clamped to [1, MAX_SEARCH_LIMIT]. Default 20. */
+    limit?: number;
+    /** 'any' (OR, default) or 'all' (AND) term combination. */
+    match?: MatchMode;
+    /** Highlight markers for snippets. Defaults are angle brackets, NOT html. */
+    highlightStart?: string;
+    highlightEnd?: string;
+}
+export interface SearchHit {
+    record: MemoryRecord;
+    /**
+     * Raw FTS5 bm25() rank. Lower (more negative) = more relevant.
+     * Exposed for debugging/diagnostics only — never shown to end users.
+     */
+    score: number;
+    /** Excerpt with highlight markers around matched terms. */
+    snippet: string;
+}
+export interface RecallOptions {
+    authorization: MemoryAuthorization;
+    /** Raw user query; omit for latest-first scoped listing. */
+    query?: string;
+    match?: MatchMode;
+    /** Max records in the snapshot. Default 10. */
+    maxResults?: number;
+    /** Max chars per hit excerpt. Default 500. */
+    maxCharsPerHit?: number;
+    /** Max total chars across the snapshot. Default 4000. */
+    maxTotalChars?: number;
+}
+export interface MemorySnapshot {
+    evaluatedAt: string;
+    hits: readonly SearchHit[];
+    /** True when results were cut by maxResults / maxTotalChars. */
+    truncated: boolean;
+    totalChars: number;
+}
+export interface RevokeInput {
+    id: string;
+    scope: MemoryScope;
+    actorId: string;
+    reason: string;
+}
+export interface ForgetInput {
+    id: string;
+    scope: MemoryScope;
+    actorId: string;
+    reason: string;
+}
+/** Append-only audit entry. Never carries record content. */
+export interface MemoryAuditEntry {
+    auditId: string;
+    memoryId: string;
+    action: 'create' | 'revoke' | 'forget' | 'reindex';
+    actorId: string;
+    at: string;
+    detail: string;
+}
+/** The single shared scope visible to every principal. */
+export declare const GLOBAL_SCOPE: MemoryScope;
+/** Resource bounds — DoS protection at the memory boundary. */
+export declare const MAX_TEXT_BYTES: number;
+export declare const MAX_QUERY_CHARS = 2000;
+export declare const MAX_QUERY_TERMS = 32;
+export declare const MAX_SEARCH_LIMIT = 200;
+export declare const MAX_SCOPE_ID_CHARS = 256;
+export declare const MAX_SNIPPET_TOKENS = 32;

package/dist/node_modules/@boombot/core/memory/types.js

@@ -0,0 +1,21 @@
+/**
+ * @boombot/core — public types.
+ *
+ * Every record names an
+ * explicit scope, and every query names authorized scopes. Retrieval applies
+ * authorization before ranking; revoked/deleted records never surface.
+ *
+ * Scope kinds used here:
+ * - `principal` — private to one authenticated principal (≈ spec `user`).
+ * - `session`   — visible inside one session only.
+ * - `global`    — shared knowledge visible to every principal.
+ */
+/** The single shared scope visible to every principal. */
+export const GLOBAL_SCOPE = Object.freeze({ kind: 'global', id: 'global' });
+/** Resource bounds — DoS protection at the memory boundary. */
+export const MAX_TEXT_BYTES = 64 * 1024; // 64 KiB per record
+export const MAX_QUERY_CHARS = 2000;
+export const MAX_QUERY_TERMS = 32;
+export const MAX_SEARCH_LIMIT = 200;
+export const MAX_SCOPE_ID_CHARS = 256;
+export const MAX_SNIPPET_TOKENS = 32;

package/dist/node_modules/@boombot/core/memory/vector-index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Vector Index and Cosine Similarity.
+ *
+ * Provides in-memory / persistent float vector storage and fast cosine similarity
+ * ranking for semantic memory recall.
+ */
+export interface VectorRecord {
+    readonly id: string;
+    readonly scopeId: string;
+    readonly vector: Float32Array;
+    readonly metadata?: Record<string, unknown>;
+}
+export interface VectorSearchResult {
+    readonly id: string;
+    readonly similarity: number;
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Computes cosine similarity between two normalized or unnormalized float vectors.
+ * Returns value in range [-1, 1], where 1 is identical direction.
+ */
+export declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+export declare class InMemoryVectorIndex {
+    private readonly records;
+    upsert(record: VectorRecord): void;
+    delete(id: string): boolean;
+    get(id: string): VectorRecord | undefined;
+    size(): number;
+    search(queryVector: Float32Array, options?: {
+        topK?: number;
+        minSimilarity?: number;
+        allowedScopeIds?: readonly string[];
+    }): VectorSearchResult[];
+}

package/dist/node_modules/@boombot/core/memory/vector-index.js

@@ -0,0 +1,65 @@
+/**
+ * Vector Index and Cosine Similarity.
+ *
+ * Provides in-memory / persistent float vector storage and fast cosine similarity
+ * ranking for semantic memory recall.
+ */
+/**
+ * Computes cosine similarity between two normalized or unnormalized float vectors.
+ * Returns value in range [-1, 1], where 1 is identical direction.
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length || a.length === 0)
+        return 0;
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        const valA = a[i];
+        const valB = b[i];
+        dotProduct += valA * valB;
+        normA += valA * valA;
+        normB += valB * valB;
+    }
+    if (normA === 0 || normB === 0)
+        return 0;
+    return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+export class InMemoryVectorIndex {
+    records = new Map();
+    upsert(record) {
+        this.records.set(record.id, record);
+    }
+    delete(id) {
+        return this.records.delete(id);
+    }
+    get(id) {
+        return this.records.get(id);
+    }
+    size() {
+        return this.records.size;
+    }
+    search(queryVector, options = {}) {
+        const topK = Math.max(1, options.topK ?? 10);
+        const minSim = options.minSimilarity ?? 0.0;
+        const allowedScopes = options.allowedScopeIds
+            ? new Set(options.allowedScopeIds)
+            : undefined;
+        const scored = [];
+        for (const record of this.records.values()) {
+            if (allowedScopes && !allowedScopes.has(record.scopeId)) {
+                continue;
+            }
+            const sim = cosineSimilarity(queryVector, record.vector);
+            if (sim >= minSim) {
+                scored.push({
+                    id: record.id,
+                    similarity: sim,
+                    metadata: record.metadata,
+                });
+            }
+        }
+        scored.sort((a, b) => b.similarity - a.similarity);
+        return scored.slice(0, topK);
+    }
+}

package/dist/node_modules/@boombot/core/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@boombot/core",
+  "version": "2.0.0",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  }
+}

package/dist/node_modules/@boombot/core/reflection/classifier.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Reflection Classifier and Self-Healing Guidance Generator.
+ *
+ * Intercepts tool execution failures and enriches the tool output with
+ * structured, actionable hints to prevent the model from repeating the same error.
+ */
+import type { ToolCall, ToolResult } from '../agent-core/types.js';
+import type { ReflectionRemedy, SelfHealingResult } from './types.js';
+export declare function classifyToolError(_call: ToolCall, errorMessage: string): ReflectionRemedy;
+/**
+ * Enriches a failed tool result with self-healing feedback.
+ */
+export declare function enrichWithSelfHealing(call: ToolCall, result: ToolResult): SelfHealingResult;

package/dist/node_modules/@boombot/core/reflection/classifier.js

@@ -0,0 +1,77 @@
+/**
+ * Reflection Classifier and Self-Healing Guidance Generator.
+ *
+ * Intercepts tool execution failures and enriches the tool output with
+ * structured, actionable hints to prevent the model from repeating the same error.
+ */
+export function classifyToolError(_call, errorMessage) {
+    const lower = errorMessage.toLowerCase();
+    let category = 'UNKNOWN';
+    let actionableHint = 'Review tool parameters and environment prerequisites before retrying.';
+    if (lower.includes('enoent') ||
+        lower.includes('no such file') ||
+        lower.includes('not found') ||
+        lower.includes('file does not exist')) {
+        category = 'FILE_NOT_FOUND';
+        actionableHint =
+            'The requested path does not exist. Use file.glob or file.grep to discover the actual file location before re-attempting.';
+    }
+    else if (lower.includes('eacces') ||
+        lower.includes('eperm') ||
+        lower.includes('permission denied') ||
+        lower.includes('access is denied')) {
+        category = 'PERMISSION_DENIED';
+        actionableHint =
+            'The path or process is locked or restricted. Check write permissions or choose a writable scratch directory ($TMPDIR).';
+    }
+    else if (lower.includes('syntax') ||
+        lower.includes('invalid argument') ||
+        lower.includes('missing required') ||
+        lower.includes('validation error') ||
+        lower.includes('pattern')) {
+        category = 'INVALID_PARAMETERS';
+        actionableHint =
+            'Parameter validation failed. Inspect the tool definition schema and ensure parameter names/types/regex patterns match strictly.';
+    }
+    else if (lower.includes('exit code') ||
+        lower.includes('command failed') ||
+        lower.includes('non-zero exit')) {
+        category = 'COMMAND_FAILED';
+        actionableHint =
+            'The shell command exited with an error. Read stderr carefully, verify installed binaries, and fix syntax before re-running.';
+    }
+    else if (lower.includes('timeout') ||
+        lower.includes('timed out') ||
+        lower.includes('econnrefused') ||
+        lower.includes('etimedout')) {
+        category = 'NETWORK_TIMEOUT';
+        actionableHint =
+            'Network or endpoint timeout. Verify the target service is running, host/port are correct, or increase timeout.';
+    }
+    return {
+        category,
+        originalError: errorMessage,
+        actionableHint,
+    };
+}
+/**
+ * Enriches a failed tool result with self-healing feedback.
+ */
+export function enrichWithSelfHealing(call, result) {
+    if (!result.error) {
+        return result;
+    }
+    const remedy = classifyToolError(call, result.output);
+    const enrichedOutput = [
+        result.output,
+        '',
+        `[SELF-HEALING GUIDANCE: ${remedy.category}]`,
+        `Reason: ${remedy.originalError.slice(0, 300)}`,
+        `Suggested Correction: ${remedy.actionableHint}`,
+    ].join('\n');
+    return {
+        ...result,
+        output: enrichedOutput,
+        remedy,
+    };
+}

package/dist/node_modules/@boombot/core/reflection/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types.js';
+export * from './classifier.js';

package/dist/node_modules/@boombot/core/reflection/index.js

@@ -0,0 +1,2 @@
+export * from './types.js';
+export * from './classifier.js';

package/dist/node_modules/@boombot/core/reflection/types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Tool Self-Healing and Reflection Types.
+ */
+import type { ToolResult } from '../agent-core/types.js';
+export type ToolErrorCategory = 'FILE_NOT_FOUND' | 'PERMISSION_DENIED' | 'COMMAND_FAILED' | 'INVALID_PARAMETERS' | 'NETWORK_TIMEOUT' | 'UNKNOWN';
+export interface ReflectionRemedy {
+    readonly category: ToolErrorCategory;
+    readonly originalError: string;
+    readonly actionableHint: string;
+}
+export interface SelfHealingResult extends ToolResult {
+    readonly remedy?: ReflectionRemedy;
+}

package/dist/node_modules/@boombot/core/reflection/types.js

@@ -0,0 +1,4 @@
+/**
+ * Tool Self-Healing and Reflection Types.
+ */
+export {};

package/dist/node_modules/@boombot/core/research/config.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Configuration loading and provider-registry helpers.
+ *
+ * Design note for the provider/orchestrator executors:
+ * `resolveSearchProviders` and `resolveExtractProvider` take fully-built
+ * provider *instances* — they only sort, filter and select. This keeps this
+ * skeleton free of any construction logic (and of the free providers, which
+ * do not exist yet). The composition root (executor 4 / gateway wiring) owns
+ * construction and passes instances in; tests pass stubs.
+ */
+import type { ExtractProvider, ResearchConfig, ResearchProvider, SearchResult } from './types.js';
+/**
+ * Engines the general `research.search` fan-out calls by default. Deliberately
+ * just the two general-purpose ones: the scholarly engines are the slowest to
+ * answer (they dominated the tens-of-seconds tool rounds measured in
+ * production) and a general query rarely needs them. They stay reachable
+ * through `research.academic`, which searches the full free pool.
+ */
+export declare const DEFAULT_SEARCH_ENGINES: readonly string[];
+/**
+ * Read API keys from the environment. Values are trimmed; empty strings
+ * become `undefined`. Keys are kept in memory only — never logged.
+ */
+export declare function loadResearchConfig(env?: NodeJS.ProcessEnv): ResearchConfig;
+/**
+ * Build the effective search chain.
+ *
+ * Order: every paid provider that has a key (tavily → exa → brave), then the
+ * free engines named by `config.engines` — by default
+ * `[wikipedia, duckduckgo]`, not the whole pool. Paid instances without a
+ * configured key are dropped. Unknown ids sort after the known ones, stable
+ * within themselves — additive, never a hard failure.
+ *
+ * The scholarly engines are deliberately absent unless `engines` asks for
+ * them: `research.academic` serves them from the same pool
+ * (`resolveAcademicProviders`), so narrowing the fan-out never takes a tool
+ * away, it only stops an ordinary search paying for slow engines.
+ *
+ * @param all.paid — constructed paid search instances (may include ones with no key)
+ * @param all.free — constructed free search instances
+ */
+export declare function resolveSearchProviders(config: ResearchConfig, all: {
+    readonly paid: readonly ResearchProvider[];
+    readonly free: readonly ResearchProvider[];
+}): ResearchProvider[];
+/**
+ * The scholarly engines, for `research.academic`.
+ *
+ * Sourced from the raw free pool rather than from the resolved search chain,
+ * because the default chain omits them to keep the general fan-out fast.
+ * Being too slow to include by default is not a reason to be unavailable
+ * when a caller asks for them by name.
+ */
+export declare function resolveAcademicProviders(all: {
+    readonly free: readonly ResearchProvider[];
+}): ResearchProvider[];
+/**
+ * Pick the extraction backend: firecrawl when its key is configured (and an
+ * instance is provided), otherwise jina-reader. Jina is the free default.
+ */
+export declare function resolveExtractProvider(config: ResearchConfig, candidates: {
+    readonly firecrawl?: ExtractProvider;
+    readonly jina: ExtractProvider;
+}): ExtractProvider;
+/**
+ * Normalize a URL for dedupe: lowercase host, drop fragment, strip a single
+ * trailing slash from the path (query strings are significant and kept).
+ * Returns `undefined` when the URL cannot be parsed.
+ */
+export declare function normalizeUrl(raw: string): string | undefined;
+/**
+ * Remove duplicate results by normalized URL, keeping the first occurrence
+ * and the original relative order. Unparseable URLs are kept as-is
+ * (never silently dropped).
+ */
+export declare function dedupeByUrl(results: readonly SearchResult[]): SearchResult[];
+/** True when at least one paid key is configured. */
+export declare function isConfigured(config: ResearchConfig): boolean;
+/**
+ * Deterministic start-up summary of the effective provider chain, derived
+ * from config alone (no network, no provider instances — the same rules as
+ * `resolveSearchProviders` / `resolveExtractProvider` but pure). The
+ * gateway logs it at boot so the operator sees which backends will serve
+ * research calls. Paid providers are suffixed `*`; keys are NEVER included.
+ */
+export declare function describeResearchConfig(config: ResearchConfig): {
+    readonly search: readonly string[];
+    readonly extract: string;
+};

package/dist/node_modules/@boombot/core/research/config.js

@@ -0,0 +1,206 @@
+/**
+ * Configuration loading and provider-registry helpers.
+ *
+ * Design note for the provider/orchestrator executors:
+ * `resolveSearchProviders` and `resolveExtractProvider` take fully-built
+ * provider *instances* — they only sort, filter and select. This keeps this
+ * skeleton free of any construction logic (and of the free providers, which
+ * do not exist yet). The composition root (executor 4 / gateway wiring) owns
+ * construction and passes instances in; tests pass stubs.
+ */
+/** Paid search providers in fallback priority order: tavily > exa > brave. */
+const PAID_SEARCH_ORDER = ['tavily', 'exa', 'brave'];
+/**
+ * Every free engine the factory can build, in presentation order. This is
+ * the POOL, not the default fan-out — see `DEFAULT_SEARCH_ENGINES`.
+ */
+const FREE_SEARCH_ORDER = [
+    'wikipedia',
+    'duckduckgo',
+    'arxiv',
+    'openalex',
+    'semanticScholar',
+];
+/**
+ * Engines the general `research.search` fan-out calls by default. Deliberately
+ * just the two general-purpose ones: the scholarly engines are the slowest to
+ * answer (they dominated the tens-of-seconds tool rounds measured in
+ * production) and a general query rarely needs them. They stay reachable
+ * through `research.academic`, which searches the full free pool.
+ */
+export const DEFAULT_SEARCH_ENGINES = [
+    'wikipedia',
+    'duckduckgo',
+];
+/** Scholarly engines `research.academic` selects out of the free pool. */
+const ACADEMIC_SEARCH_IDS = [
+    'arxiv',
+    'openalex',
+    'semanticScholar',
+];
+/**
+ * Read API keys from the environment. Values are trimmed; empty strings
+ * become `undefined`. Keys are kept in memory only — never logged.
+ */
+export function loadResearchConfig(env = process.env) {
+    const pick = (name) => {
+        const raw = env[name];
+        if (raw === undefined)
+            return undefined;
+        const trimmed = raw.trim();
+        return trimmed === '' ? undefined : trimmed;
+    };
+    const engines = pick('BOOMBOT_RESEARCH_ENGINES');
+    return {
+        tavilyApiKey: pick('TAVILY_API_KEY'),
+        exaApiKey: pick('EXA_API_KEY'),
+        braveApiKey: pick('BRAVE_API_KEY'),
+        firecrawlApiKey: pick('FIRECRAWL_API_KEY'),
+        defaultMode: 'auto',
+        // Comma-separated engine ids. Absent = the built-in default set; an id
+        // the factory cannot build simply matches no provider. Read as a list
+        // rather than validated against a whitelist so a new engine needs no
+        // change here.
+        ...(engines === undefined
+            ? {}
+            : {
+                engines: engines
+                    .split(',')
+                    .map((id) => id.trim())
+                    .filter((id) => id !== ''),
+            }),
+    };
+}
+function hasKey(config, paidId) {
+    switch (paidId) {
+        case 'tavily':
+            return config.tavilyApiKey !== undefined;
+        case 'exa':
+            return config.exaApiKey !== undefined;
+        case 'brave':
+            return config.braveApiKey !== undefined;
+        default:
+            return false;
+    }
+}
+function orderById(providers, order) {
+    const rank = new Map();
+    order.forEach((id, i) => rank.set(id, i));
+    return [...providers].sort((a, b) => {
+        const ra = rank.get(a.id) ?? Number.MAX_SAFE_INTEGER;
+        const rb = rank.get(b.id) ?? Number.MAX_SAFE_INTEGER;
+        return ra - rb;
+    });
+}
+/**
+ * Build the effective search chain.
+ *
+ * Order: every paid provider that has a key (tavily → exa → brave), then the
+ * free engines named by `config.engines` — by default
+ * `[wikipedia, duckduckgo]`, not the whole pool. Paid instances without a
+ * configured key are dropped. Unknown ids sort after the known ones, stable
+ * within themselves — additive, never a hard failure.
+ *
+ * The scholarly engines are deliberately absent unless `engines` asks for
+ * them: `research.academic` serves them from the same pool
+ * (`resolveAcademicProviders`), so narrowing the fan-out never takes a tool
+ * away, it only stops an ordinary search paying for slow engines.
+ *
+ * @param all.paid — constructed paid search instances (may include ones with no key)
+ * @param all.free — constructed free search instances
+ */
+export function resolveSearchProviders(config, all) {
+    const paid = orderById(all.paid, PAID_SEARCH_ORDER).filter((p) => hasKey(config, p.id));
+    const engines = config.engines ?? DEFAULT_SEARCH_ENGINES;
+    const free = orderById(all.free, FREE_SEARCH_ORDER).filter((p) => engines.includes(p.id));
+    return [...paid, ...free];
+}
+/**
+ * The scholarly engines, for `research.academic`.
+ *
+ * Sourced from the raw free pool rather than from the resolved search chain,
+ * because the default chain omits them to keep the general fan-out fast.
+ * Being too slow to include by default is not a reason to be unavailable
+ * when a caller asks for them by name.
+ */
+export function resolveAcademicProviders(all) {
+    return orderById(all.free, FREE_SEARCH_ORDER).filter((p) => ACADEMIC_SEARCH_IDS.includes(p.id));
+}
+/**
+ * Pick the extraction backend: firecrawl when its key is configured (and an
+ * instance is provided), otherwise jina-reader. Jina is the free default.
+ */
+export function resolveExtractProvider(config, candidates) {
+    if (config.firecrawlApiKey !== undefined && candidates.firecrawl !== undefined) {
+        return candidates.firecrawl;
+    }
+    return candidates.jina;
+}
+/**
+ * Normalize a URL for dedupe: lowercase host, drop fragment, strip a single
+ * trailing slash from the path (query strings are significant and kept).
+ * Returns `undefined` when the URL cannot be parsed.
+ */
+export function normalizeUrl(raw) {
+    try {
+        const u = new URL(raw);
+        u.host = u.host.toLowerCase();
+        u.hash = '';
+        const path = u.pathname;
+        if (path.length > 1 && path.endsWith('/')) {
+            u.pathname = path.slice(0, -1);
+        }
+        return u.toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Remove duplicate results by normalized URL, keeping the first occurrence
+ * and the original relative order. Unparseable URLs are kept as-is
+ * (never silently dropped).
+ */
+export function dedupeByUrl(results) {
+    const seen = new Set();
+    const out = [];
+    for (const r of results) {
+        const key = normalizeUrl(r.url);
+        if (key === undefined || !seen.has(key)) {
+            if (key !== undefined)
+                seen.add(key);
+            out.push(r);
+        }
+    }
+    return out;
+}
+/** True when at least one paid key is configured. */
+export function isConfigured(config) {
+    return (config.tavilyApiKey !== undefined ||
+        config.exaApiKey !== undefined ||
+        config.braveApiKey !== undefined ||
+        config.firecrawlApiKey !== undefined);
+}
+/**
+ * Deterministic start-up summary of the effective provider chain, derived
+ * from config alone (no network, no provider instances — the same rules as
+ * `resolveSearchProviders` / `resolveExtractProvider` but pure). The
+ * gateway logs it at boot so the operator sees which backends will serve
+ * research calls. Paid providers are suffixed `*`; keys are NEVER included.
+ */
+export function describeResearchConfig(config) {
+    const search = [];
+    if (config.tavilyApiKey !== undefined)
+        search.push('tavily*');
+    if (config.exaApiKey !== undefined)
+        search.push('exa*');
+    if (config.braveApiKey !== undefined)
+        search.push('brave*');
+    // The fan-out as it will actually run, so the boot log answers "why did
+    // that search only call two engines?" without reading this file.
+    search.push(...(config.engines ?? DEFAULT_SEARCH_ENGINES));
+    return {
+        search,
+        extract: config.firecrawlApiKey !== undefined ? 'firecrawl*' : 'jina',
+    };
+}