sofia-cli 0.1.1

package/dist/src/mcp/mcpTransport.js

@@ -0,0 +1,391 @@
+/**
+ * MCP Transport Layer.
+ *
+ * Provides the `McpTransport` interface and two implementations:
+ * - `StdioMcpTransport`: subprocess-based JSON-RPC 2.0 over stdin/stdout
+ * - `HttpMcpTransport`: stateless HTTPS JSON-RPC 2.0 via native fetch()
+ *
+ * These transports handle the *programmatic adapter path* — deterministic tool
+ * calls made by application code (GitHub adapter, Context7 enricher, Azure
+ * enricher) that bypass the LLM.
+ *
+ * LLM-initiated tool calls go through the Copilot SDK's native `mcpServers`
+ * support. See research.md Topic 1 for the dual-path architecture.
+ */
+import { spawn, execSync } from 'node:child_process';
+import { createInterface } from 'node:readline';
+/**
+ * Error type for MCP transport failures.
+ * Callers use `classifyMcpError()` to determine retry eligibility.
+ */
+export class McpTransportError extends Error {
+    serverName;
+    toolName;
+    cause;
+    constructor(message, serverName, toolName, cause) {
+        super(message);
+        this.serverName = serverName;
+        this.toolName = toolName;
+        this.cause = cause;
+        this.name = 'McpTransportError';
+    }
+}
+function normalizeRpcErrorMessage(message) {
+    const trimmed = message.trim();
+    const parseValidationArray = (raw) => {
+        try {
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed) || parsed.length === 0) {
+                return null;
+            }
+            const details = parsed
+                .map((item) => {
+                const path = Array.isArray(item.path) && item.path.length > 0 ? item.path.join('.') : 'input';
+                const detail = item.message ?? 'Invalid input';
+                return `${path}: ${detail}`;
+            })
+                .join('; ');
+            return details;
+        }
+        catch {
+            return null;
+        }
+    };
+    const arraySuffixMatch = trimmed.match(/^(.*?):\s*(\[[\s\S]*\])$/);
+    if (arraySuffixMatch) {
+        const details = parseValidationArray(arraySuffixMatch[2]);
+        if (details) {
+            return `${arraySuffixMatch[1]}: ${details}`;
+        }
+    }
+    const wholeArrayDetails = parseValidationArray(trimmed);
+    if (wholeArrayDetails) {
+        return `Input validation error: ${wholeArrayDetails}`;
+    }
+    return trimmed;
+}
+// ── StdioMcpTransport ────────────────────────────────────────────────────────
+/**
+ * MCP transport over stdio subprocess (JSON-RPC 2.0 newline-delimited).
+ *
+ * Used for: Context7, Azure MCP, WorkIQ, Playwright.
+ */
+export class StdioMcpTransport {
+    config;
+    logger;
+    process = null;
+    pendingRequests = new Map();
+    nextId = 1;
+    connected = false;
+    constructor(config, logger) {
+        this.config = config;
+        this.logger = logger;
+    }
+    /**
+     * Spawn the subprocess and perform the JSON-RPC `initialize` handshake.
+     * Must be called before `callTool()`.
+     */
+    async connect() {
+        const { command, args, env, cwd, name } = this.config;
+        const child = spawn(command, args, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: { ...process.env, ...env },
+            ...(cwd ? { cwd } : {}),
+        });
+        this.process = child;
+        // Parse stdout lines as JSON-RPC responses
+        const rl = createInterface({ input: child.stdout });
+        rl.on('line', (line) => {
+            try {
+                const msg = JSON.parse(line);
+                if (msg.id != null) {
+                    const pending = this.pendingRequests.get(msg.id);
+                    if (pending) {
+                        clearTimeout(pending.timer);
+                        this.pendingRequests.delete(msg.id);
+                        if (msg.error) {
+                            pending.reject(new McpTransportError(normalizeRpcErrorMessage(msg.error.message), name, 'rpc-error'));
+                        }
+                        else {
+                            pending.resolve({
+                                content: this.extractContent(msg.result),
+                                raw: msg,
+                            });
+                        }
+                    }
+                }
+            }
+            catch {
+                this.logger.debug({ line: line.slice(0, 200) }, 'Skipping non-JSON stdout line');
+            }
+        });
+        // Handle subprocess exit
+        child.on('exit', (code) => {
+            this.connected = false;
+            // Reject all pending requests
+            for (const [id, pending] of this.pendingRequests) {
+                clearTimeout(pending.timer);
+                this.pendingRequests.delete(id);
+                const err = new McpTransportError(`MCP subprocess exited with code ${code}`, name, 'subprocess-exit');
+                err.code = 'ECONNREFUSED';
+                pending.reject(err);
+            }
+        });
+        // Send initialize handshake
+        const initId = this.nextId++;
+        const initResult = await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingRequests.delete(initId);
+                child.kill('SIGTERM');
+                const err = new McpTransportError(`MCP stdio server '${name}' initialization timed out after 5 seconds`, name, 'initialize');
+                err.code = 'ETIMEDOUT';
+                reject(err);
+            }, 5000);
+            this.pendingRequests.set(initId, {
+                resolve: () => {
+                    resolve();
+                },
+                reject,
+                timer,
+            });
+            const initRequest = JSON.stringify({
+                jsonrpc: '2.0',
+                id: initId,
+                method: 'initialize',
+                params: {
+                    protocolVersion: '1.0',
+                    clientInfo: { name: 'sofIA', version: '0.1.0' },
+                    capabilities: {},
+                },
+            });
+            child.stdin.write(initRequest + '\n');
+        });
+        void initResult;
+        this.connected = true;
+        this.logger.info({ server: name }, 'MCP stdio server connected');
+    }
+    async callTool(toolName, args, timeoutMs) {
+        if (!this.connected || !this.process) {
+            throw new McpTransportError(`Transport not connected for server '${this.config.name}'`, this.config.name, toolName);
+        }
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingRequests.delete(id);
+                const err = new McpTransportError(`MCP tool call timed out after ${timeoutMs}ms: ${this.config.name}.${toolName}`, this.config.name, toolName);
+                err.code = 'ETIMEDOUT';
+                reject(err);
+            }, timeoutMs);
+            this.pendingRequests.set(id, { resolve, reject, timer });
+            const request = JSON.stringify({
+                jsonrpc: '2.0',
+                id,
+                method: 'tools/call',
+                params: { name: toolName, arguments: args },
+            });
+            this.process.stdin.write(request + '\n');
+        });
+    }
+    isConnected() {
+        return this.connected;
+    }
+    async disconnect() {
+        // Reject all pending requests
+        for (const [id, pending] of this.pendingRequests) {
+            clearTimeout(pending.timer);
+            this.pendingRequests.delete(id);
+            pending.reject(new McpTransportError('Transport disconnected', this.config.name, 'disconnect'));
+        }
+        if (this.process) {
+            this.process.kill('SIGTERM');
+            this.process = null;
+        }
+        this.connected = false;
+    }
+    /**
+     * Extract content from a JSON-RPC result.
+     * MCP responses may have `result.content[0].text` or just `result` directly.
+     */
+    extractContent(result) {
+        if (result && typeof result === 'object') {
+            const r = result;
+            if (Array.isArray(r.content) && r.content.length > 0) {
+                const first = r.content[0];
+                if (typeof first.text === 'string') {
+                    return first.text;
+                }
+                return first;
+            }
+            return r;
+        }
+        return String(result);
+    }
+}
+// ── HttpMcpTransport ─────────────────────────────────────────────────────────
+/**
+ * Retrieve GitHub token from GitHub CLI if available.
+ * @returns Token string or null if GitHub CLI is not installed/authenticated.
+ */
+function getGitHubCliToken() {
+    try {
+        const token = execSync('gh auth token', {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'ignore'], // suppress stderr
+            timeout: 2000,
+        }).trim();
+        return token || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * MCP transport over HTTPS (stateless JSON-RPC 2.0 via native fetch).
+ *
+ * Used for: GitHub MCP, Microsoft Docs MCP.
+ */
+export class HttpMcpTransport {
+    config;
+    logger;
+    nextId = 1;
+    constructor(config, logger) {
+        this.config = config;
+        this.logger = logger;
+    }
+    async callTool(toolName, args, timeoutMs) {
+        const id = this.nextId++;
+        const body = {
+            jsonrpc: '2.0',
+            id,
+            method: 'tools/call',
+            params: { name: toolName, arguments: args },
+        };
+        // Build headers
+        const headers = {
+            'Content-Type': 'application/json',
+            ...this.config.headers,
+        };
+        // Add auth token if available (GITHUB_TOKEN env var takes precedence, fallback to GitHub CLI)
+        const token = process.env.GITHUB_TOKEN || (this.config.name === 'github' ? getGitHubCliToken() : null);
+        if (token) {
+            headers['Authorization'] = `Bearer ${token}`;
+        }
+        // AbortController for timeout
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetch(this.config.url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            clearTimeout(timer);
+            // Handle HTTP error statuses
+            if (response.status === 401 || response.status === 403) {
+                const err = new McpTransportError(`HTTP ${response.status} from ${this.config.name}: authentication failed`, this.config.name, toolName);
+                err.code = 'ERR_TLS_CERT_ALTNAME_INVALID';
+                throw err;
+            }
+            if (response.status >= 500) {
+                throw new McpTransportError(`HTTP ${response.status} from ${this.config.name}: server error`, this.config.name, toolName);
+            }
+            // Parse response body (read as text first for better error reporting)
+            const bodyText = await response.text();
+            const contentType = response.headers.get('content-type') || '';
+            let parsed;
+            // Handle Server-Sent Events (SSE) format from GitHub Copilot MCP
+            if (contentType.includes('text/event-stream')) {
+                try {
+                    // Parse SSE format: "event: message\ndata: {...}\n\n"
+                    const dataMatch = bodyText.match(/^data:\s*(.+)$/m);
+                    if (!dataMatch) {
+                        throw new Error('No data field in SSE response');
+                    }
+                    parsed = JSON.parse(dataMatch[1]);
+                }
+                catch (_sseError) {
+                    this.logger.error({ status: response.status, contentType, bodyPreview: bodyText.slice(0, 500) }, `Invalid SSE format from ${this.config.name}`);
+                    throw new McpTransportError(`Invalid SSE format from ${this.config.name}`, this.config.name, toolName);
+                }
+            }
+            else {
+                // Regular JSON response
+                try {
+                    parsed = JSON.parse(bodyText);
+                }
+                catch (_parseError) {
+                    // Log response details for debugging
+                    const preview = bodyText.slice(0, 500);
+                    this.logger.error({ status: response.status, contentType, bodyPreview: preview }, `Non-JSON response from ${this.config.name}`);
+                    // Also output to stderr for visibility in tests
+                    console.error(`[McpTransport] Non-JSON response from ${this.config.name}:`);
+                    console.error(`  Status: ${response.status}`);
+                    console.error(`  Content-Type: ${contentType}`);
+                    console.error(`  Body preview: ${preview}`);
+                    throw new McpTransportError(`Non-JSON response from ${this.config.name} (HTTP ${response.status})`, this.config.name, toolName);
+                }
+            }
+            // Handle JSON-RPC error
+            if (parsed.error) {
+                const rpcError = parsed.error;
+                throw new McpTransportError(normalizeRpcErrorMessage(rpcError.message ?? 'JSON-RPC error'), this.config.name, toolName);
+            }
+            return {
+                content: this.extractContent(parsed.result),
+                raw: parsed,
+            };
+        }
+        catch (err) {
+            clearTimeout(timer);
+            // Re-throw McpTransportError as-is
+            if (err instanceof McpTransportError) {
+                throw err;
+            }
+            // Handle AbortError (timeout)
+            if (err instanceof Error && err.name === 'AbortError') {
+                const timeoutErr = new McpTransportError(`MCP HTTP call timed out after ${timeoutMs}ms: ${this.config.name}.${toolName}`, this.config.name, toolName);
+                timeoutErr.code = 'ETIMEDOUT';
+                throw timeoutErr;
+            }
+            // Re-throw other errors as McpTransportError
+            throw new McpTransportError(err instanceof Error ? err.message : String(err), this.config.name, toolName, err);
+        }
+    }
+    isConnected() {
+        return true; // HTTP is stateless
+    }
+    async disconnect() {
+        // No-op for HTTP
+    }
+    /**
+     * Extract content from a JSON-RPC result.
+     */
+    extractContent(result) {
+        if (result && typeof result === 'object') {
+            const r = result;
+            if (Array.isArray(r.content) && r.content.length > 0) {
+                const first = r.content[0];
+                if (typeof first.text === 'string') {
+                    return first.text;
+                }
+                return first;
+            }
+            return r;
+        }
+        return String(result);
+    }
+}
+// ── Factory ──────────────────────────────────────────────────────────────────
+/**
+ * Create the correct transport implementation for a server config.
+ */
+export function createTransport(config, logger) {
+    if (config.type === 'stdio') {
+        return new StdioMcpTransport(config, logger);
+    }
+    if (config.type === 'http') {
+        return new HttpMcpTransport(config, logger);
+    }
+    throw new Error(`Unsupported MCP transport type: ${config.type}`);
+}

package/dist/src/mcp/retryPolicy.js

@@ -0,0 +1,47 @@
+import { classifyMcpError } from './mcpManager.js';
+// ── Retryable error classes ──────────────────────────────────────────────────
+const RETRYABLE_CLASSES = new Set([
+    'connection-refused',
+    'timeout',
+    'dns-failure',
+]);
+/**
+ * Determine if an error is transient and should be retried.
+ */
+function isRetryable(err) {
+    return RETRYABLE_CLASSES.has(classifyMcpError(err));
+}
+// ── withRetry ────────────────────────────────────────────────────────────────
+/**
+ * Wrap an async function with a single-retry policy for transient MCP errors.
+ *
+ * On transient error: waits `initialDelayMs ± jitter`, then calls fn() once more.
+ * If the retry also fails, the second error is thrown (not the first).
+ *
+ * Non-retryable errors (auth-failure, unknown, validation) are thrown immediately.
+ */
+export async function withRetry(fn, options) {
+    const { serverName, toolName, initialDelayMs = 1000, jitter = 0.2, logger } = options;
+    try {
+        return await fn();
+    }
+    catch (firstError) {
+        if (!isRetryable(firstError)) {
+            throw firstError;
+        }
+        // Calculate delay with jitter: initialDelayMs * (1 ± jitter)
+        const jitterFactor = 1 + (Math.random() * 2 - 1) * jitter;
+        const delayMs = Math.round(initialDelayMs * jitterFactor);
+        const errorClass = classifyMcpError(firstError);
+        logger?.warn({ server: serverName, tool: toolName, attempt: 1, delayMs, errorClass }, `MCP transient error — retrying after ${delayMs}ms`);
+        await sleep(delayMs);
+        // Second attempt — if this fails, its error is thrown
+        return await fn();
+    }
+}
+/** Internal sleep helper. */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// Re-export for convenience
+export { classifyMcpError, isRetryable };

package/dist/src/mcp/webSearch.js

@@ -0,0 +1,254 @@
+// ── Tool definition ──────────────────────────────────────────────────────────
+export const WEB_SEARCH_TOOL_DEFINITION = {
+    name: 'web.search',
+    description: 'Search the web for information about companies, industries, technologies, and trends. ' +
+        'Returns structured results with title, URL, and snippet.',
+    parameters: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'The search query string.',
+            },
+        },
+        required: ['query'],
+    },
+};
+// ── Configuration check ──────────────────────────────────────────────────────
+/**
+ * Check if web search is configured via environment variables.
+ *
+ * Uses the new env vars (`FOUNDRY_PROJECT_ENDPOINT`, `FOUNDRY_MODEL_DEPLOYMENT_NAME`)
+ * instead of legacy vars (`SOFIA_FOUNDRY_AGENT_ENDPOINT`, `SOFIA_FOUNDRY_AGENT_KEY`).
+ */
+export function isWebSearchConfigured() {
+    return Boolean(process.env.FOUNDRY_PROJECT_ENDPOINT && process.env.FOUNDRY_MODEL_DEPLOYMENT_NAME);
+}
+// ── Citation extraction ──────────────────────────────────────────────────────
+/**
+ * Extract citations from a Foundry agent response.
+ *
+ * Parses `url_citation` annotations from the response output items and maps
+ * them into `WebSearchResultItem[]`. Deduplicates sources by URL.
+ */
+export function extractCitations(output) {
+    const results = [];
+    const seenUrls = new Set();
+    for (const item of output) {
+        const messageItem = item;
+        if (messageItem.type !== 'message')
+            continue;
+        const content = messageItem.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const contentBlock of content) {
+            const block = contentBlock;
+            if (block.type !== 'output_text')
+                continue;
+            const text = String(block.text ?? '');
+            const annotations = block.annotations;
+            if (!Array.isArray(annotations))
+                continue;
+            for (const annotation of annotations) {
+                const ann = annotation;
+                if (ann.type !== 'url_citation')
+                    continue;
+                const url = String(ann.url ?? '');
+                const title = String(ann.title ?? url);
+                const startIndex = Number(ann.start_index ?? 0);
+                const endIndex = Number(ann.end_index ?? text.length);
+                const snippet = text.slice(startIndex, Math.min(endIndex, startIndex + 200)) || title;
+                if (url && !seenUrls.has(url)) {
+                    seenUrls.add(url);
+                    results.push({ title, url, snippet });
+                }
+            }
+        }
+    }
+    return { results, sources: [...seenUrls] };
+}
+/**
+ * Fallback extraction when a response has no URL citations.
+ *
+ * Some Foundry responses can contain only plain output text without
+ * `url_citation` annotations. This extracts text blocks into lightweight
+ * snippets so downstream enrichment still has useful context.
+ */
+export function extractTextSnippets(output) {
+    const snippets = [];
+    for (const item of output) {
+        const messageItem = item;
+        if (messageItem.type !== 'message')
+            continue;
+        const content = messageItem.content;
+        if (!Array.isArray(content))
+            continue;
+        for (let i = 0; i < content.length; i++) {
+            const block = content[i];
+            if (block.type !== 'output_text')
+                continue;
+            const text = String(block.text ?? '').trim();
+            if (!text)
+                continue;
+            snippets.push({
+                title: 'Foundry response',
+                url: `foundry://response/${i + 1}`,
+                snippet: text.length > 300 ? `${text.slice(0, 300)}…` : text,
+            });
+        }
+    }
+    return snippets;
+}
+const MAX_QUERIES_PER_AGENT = 3;
+const MAX_RETRIES = 2;
+const RETRY_DELAY_MS = 2000; // 2 second initial delay
+let sessionState = null;
+let sessionDeps = null;
+/**
+ * Create default dependencies using the real Azure SDK.
+ */
+async function createDefaultDeps() {
+    const { AIProjectClient } = await import('@azure/ai-projects');
+    const { DefaultAzureCredential } = await import('@azure/identity');
+    return {
+        createClient: (endpoint) => new AIProjectClient(endpoint, new DefaultAzureCredential()),
+        getOpenAIClient: async (client) => client.getOpenAIClient(),
+        createAgentVersion: async (client, name, options) => {
+            const aiClient = client;
+            const result = await aiClient.agents.createVersion(name, options);
+            return { name: result.name, version: result.version };
+        },
+        deleteAgentVersion: async (client, name, version) => {
+            await client.agents.deleteVersion(name, version);
+        },
+        createConversation: async (openAIClient) => {
+            const oai = openAIClient;
+            return oai.conversations.create();
+        },
+        deleteConversation: async (openAIClient, id) => {
+            const oai = openAIClient;
+            await oai.conversations.delete(id);
+        },
+        createResponse: async (openAIClient, conversationId, input, agentName) => {
+            const oai = openAIClient;
+            return oai.responses.create({ conversation: conversationId, input }, { body: { agent: { name: agentName, type: 'agent_reference' } } });
+        },
+    };
+}
+// ── Tool factory ─────────────────────────────────────────────────────────────
+async function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function cleanupCurrentAgent(keepDeps) {
+    if (!sessionState?.initialized || !sessionDeps) {
+        sessionState = null;
+        return;
+    }
+    const { client, agentName, agentVersion } = sessionState;
+    sessionState = null;
+    try {
+        await sessionDeps.deleteAgentVersion(client, agentName, agentVersion);
+    }
+    catch {
+        // Best-effort cleanup.
+    }
+    if (!keepDeps) {
+        sessionDeps = null;
+    }
+}
+/**
+ * Create a web search function that calls the Azure AI Foundry Agent Service.
+ *
+ * The returned function:
+ * - Lazily creates an ephemeral agent with web_search_preview on first call
+ * - Reuses the agent for subsequent calls
+ * - Rotates the agent after a few queries to avoid stale response behavior
+ * - Uses a fresh conversation per query to keep citation output stable
+ * - Returns structured results with URL citations
+ * - Degrades gracefully on errors (returns empty results with degraded flag)
+ *
+ * Pass `deps` for testing to inject mocked SDK clients.
+ */
+export function createWebSearchTool(config, deps) {
+    sessionDeps = deps ?? null;
+    return async (query) => {
+        try {
+            const resolvedDeps = sessionDeps ?? (await createDefaultDeps());
+            sessionDeps = resolvedDeps;
+            if (sessionState?.initialized && sessionState.queryCount >= MAX_QUERIES_PER_AGENT) {
+                await cleanupCurrentAgent(true);
+            }
+            // Lazy initialization
+            if (!sessionState?.initialized) {
+                const client = resolvedDeps.createClient(config.projectEndpoint);
+                const openAIClient = await resolvedDeps.getOpenAIClient(client);
+                const agent = await resolvedDeps.createAgentVersion(client, 'sofia-web-search', {
+                    kind: 'prompt',
+                    model: config.modelDeploymentName,
+                    instructions: 'You are a web search assistant. Search the web and return relevant results with citations.',
+                    tools: [{ type: 'web_search_preview' }],
+                });
+                sessionState = {
+                    client,
+                    openAIClient,
+                    agentName: agent.name,
+                    agentVersion: agent.version,
+                    queryCount: 0,
+                    initialized: true,
+                };
+            }
+            // Execute query in an isolated conversation with retry logic for rate limiting.
+            const conversation = await sessionDeps.createConversation(sessionState.openAIClient);
+            let response;
+            for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+                try {
+                    response = await sessionDeps.createResponse(sessionState.openAIClient, conversation.id, query, sessionState.agentName);
+                    break;
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    // Check for 429 rate limiting
+                    if (message.includes('429') && attempt < MAX_RETRIES) {
+                        const delayMs = RETRY_DELAY_MS * Math.pow(2, attempt);
+                        await sleep(delayMs);
+                        continue;
+                    }
+                    throw err;
+                }
+            }
+            try {
+                await sessionDeps.deleteConversation(sessionState.openAIClient, conversation.id);
+            }
+            catch {
+                // Conversation cleanup failures should not fail web search results.
+            }
+            sessionState.queryCount += 1;
+            // Extract citations. response is guaranteed to be assigned by loop logic:
+            // either break assigns it, or catch throws (exiting function).
+            const { results: citationResults, sources } = extractCitations(response.output ?? []);
+            const results = citationResults.length > 0 ? citationResults : extractTextSnippets(response.output ?? []);
+            return { results, sources };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                results: [],
+                degraded: true,
+                error: message,
+            };
+        }
+    };
+}
+// ── Session cleanup ──────────────────────────────────────────────────────────
+/**
+ * Destroy the ephemeral web search agent and conversation.
+ *
+ * Safe to call multiple times. Logs warnings on cleanup failure but does not throw.
+ */
+export async function destroyWebSearchSession() {
+    await cleanupCurrentAgent(false);
+}
+// Register cleanup on process exit
+process.on('beforeExit', () => {
+    void destroyWebSearchSession();
+});