toolpack-sdk 0.1.0-SNAPSHOT

package/dist/client/index.js

@@ -0,0 +1,1246 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AIClient = void 0;
+const events_1 = require("events");
+const errors_1 = require("../errors");
+const router_js_1 = require("../tools/router.js");
+const types_js_1 = require("../tools/types.js");
+const index_js_1 = require("../tools/search/index.js");
+const base_agent_context_js_1 = require("./base-agent-context.js");
+const query_classifier_js_1 = require("./query-classifier.js");
+const tool_orchestrator_js_1 = require("./tool-orchestrator.js");
+const provider_logger_1 = require("../providers/provider-logger");
+let REQUEST_SEQ = 0;
+function newRequestId() {
+    REQUEST_SEQ += 1;
+    return `${Date.now()}-${REQUEST_SEQ}`;
+}
+function logRequestMessages(requestId, messages) {
+    if (!(0, provider_logger_1.isVerbose)())
+        return;
+    (0, provider_logger_1.log)(`[AIClient][${requestId}] Messages (${messages.length}):`);
+    messages.forEach((m, i) => {
+        const preview = (0, provider_logger_1.safePreview)(m.content, 300);
+        (0, provider_logger_1.log)(`[AIClient][${requestId}]  #${i} role=${m.role} content=${preview}`);
+    });
+}
+function extractLastUserText(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m?.role !== 'user')
+            continue;
+        const c = m?.content;
+        if (typeof c === 'string')
+            return c;
+        if (Array.isArray(c)) {
+            return c
+                .map((p) => (p?.type === 'text' ? p.text : ''))
+                .filter(Boolean)
+                .join('\n');
+        }
+        return '';
+    }
+    return '';
+}
+function inferNeedsTools(messages) {
+    const text = extractLastUserText(messages).toLowerCase();
+    if (!text)
+        return false;
+    const patterns = [
+        /\b(list|show|print|display)\b.*\b(files|folders|directory|dir)\b/,
+        /\b(current|this)\b.*\b(directory|folder|repo|repository)\b/,
+        /\b(read|open|view)\b.*\b(file|log|config|json|yaml|env)\b/,
+        /\b(write|create|update|modify|edit|patch|delete|remove|rename|move|copy)\b.*\b(file|folder|directory)\b/,
+        /\b(run|execute)\b.*\b(command|shell|script|tests?)\b/,
+        /\b(http|get|post|put|delete|download|fetch|curl)\b/,
+        /\b(web|search|scrape|crawl|map)\b/,
+        /https?:\/\//, // Contains a URL
+    ];
+    return patterns.some(r => r.test(text));
+}
+function isAfterToolCall(messages, maxDistance) {
+    // Find the last tool call in the conversation
+    let lastToolCallIndex = -1;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (msg.role === 'tool' || (msg.role === 'assistant' && msg.tool_calls && msg.tool_calls.length > 0)) {
+            lastToolCallIndex = i;
+            break;
+        }
+    }
+    if (lastToolCallIndex === -1)
+        return false;
+    // Check if current message is within maxDistance messages after the tool call
+    const distance = messages.length - 1 - lastToolCallIndex;
+    return distance > 0 && distance <= maxDistance;
+}
+function getFastModelForProvider(providerName) {
+    const defaultFastModels = {
+        openai: 'gpt-4.1-mini',
+        anthropic: 'claude-3-haiku-20240307',
+        gemini: 'gemini-2.0-flash-exp',
+        ollama: 'llama3.2',
+    };
+    return defaultFastModels[providerName] || 'default';
+}
+function extractToolContext(messages) {
+    // Extract context from recent tool calls (last 2 tool rounds)
+    const toolInfo = [];
+    let toolRoundsFound = 0;
+    for (let i = messages.length - 1; i >= 0 && toolRoundsFound < 2; i--) {
+        const msg = messages[i];
+        // Extract from assistant's tool calls
+        if (msg.role === 'assistant' && msg.tool_calls && msg.tool_calls.length > 0) {
+            toolRoundsFound++;
+            for (const toolCall of msg.tool_calls) {
+                const toolName = toolCall.function?.name || 'unknown';
+                const args = toolCall.function?.arguments;
+                // Extract relevant context from arguments
+                let context = `Tool: ${toolName}`;
+                if (args) {
+                    try {
+                        const parsedArgs = typeof args === 'string' ? JSON.parse(args) : args;
+                        // Extract URLs, file paths, sections, queries
+                        if (parsedArgs.url)
+                            context += ` (URL: ${parsedArgs.url})`;
+                        if (parsedArgs.file_path)
+                            context += ` (File: ${parsedArgs.file_path})`;
+                        if (parsedArgs.section)
+                            context += ` (Section: ${parsedArgs.section})`;
+                        if (parsedArgs.query)
+                            context += ` (Query: ${parsedArgs.query})`;
+                        if (parsedArgs.command)
+                            context += ` (Command: ${parsedArgs.command.substring(0, 50)})`;
+                    }
+                    catch (e) {
+                        // Ignore parse errors
+                    }
+                }
+                toolInfo.push(context);
+            }
+        }
+    }
+    return toolInfo.length > 0 ? toolInfo.join(', ') : 'None';
+}
+async function inferNeedsToolsWithAI(provider, providerName, messages, fastModel) {
+    const requestId = newRequestId();
+    (0, provider_logger_1.log)(`[AIClient][${requestId}] inferNeedsToolsWithAI() provider=${providerName} model=${fastModel}`);
+    // Extract tool context from recent tool calls
+    const toolContext = extractToolContext(messages);
+    // Get the last user message
+    const lastUserMessage = messages.filter((m) => m.role === 'user').slice(-1)[0];
+    const userMessage = lastUserMessage?.content || '';
+    // Build context-aware prompt
+    const prompt = `Recent tool usage: ${toolContext}
+
+User's new message: "${userMessage}"
+
+Does this message:
+1. Ask about the same topic/context as recent tools? OR
+2. Request new information that requires external tools (web search, file access, commands)?
+
+If the message is general knowledge (math, definitions, explanations) or completely unrelated to recent tool context, answer NO.
+If it asks about the same context OR needs new external information, answer YES.
+
+Answer only: YES or NO`;
+    try {
+        const response = await provider.generate({
+            model: fastModel,
+            messages: [{ role: 'user', content: prompt }],
+            max_tokens: 10,
+            temperature: 0,
+        });
+        const answer = (response.content || '').trim().toUpperCase();
+        const needsTools = answer.startsWith('YES');
+        (0, provider_logger_1.log)(`[AIClient][${requestId}] inferNeedsToolsWithAI() context="${toolContext}" message="${userMessage.substring(0, 50)}" result=${needsTools} (raw: ${answer})`);
+        return needsTools;
+    }
+    catch (error) {
+        (0, provider_logger_1.log)(`[AIClient][${requestId}] inferNeedsToolsWithAI() error=${error} - falling back to false`);
+        return false;
+    }
+}
+function inferLookupOnly(messages) {
+    const text = extractLastUserText(messages).toLowerCase();
+    if (!text)
+        return false;
+    const lookupPatterns = [
+        /\b(list|show|print|display)\b.*\b(files|folders|directory|dir)\b/,
+        /\b(current|this)\b.*\b(directory|folder|repo|repository)\b/,
+        /\b(read|open|view)\b.*\b(file|log|config|json|yaml|env)\b/,
+    ];
+    const mutatingPatterns = [
+        /\b(write|create|update|modify|edit|patch|delete|remove|rename|move|copy)\b/,
+        /\b(run|execute)\b.*\b(command|shell|script|tests?)\b/,
+        /\b(http|get|post|put|delete|download|fetch|curl)\b/,
+        /\b(web|search|scrape|crawl)\b/,
+    ];
+    return lookupPatterns.some(r => r.test(text)) && !mutatingPatterns.some(r => r.test(text));
+}
+const TOOL_RESULT_MAX_CHARS = (() => {
+    const raw = process.env.TOOLPACK_SDK_TOOL_RESULT_MAX_CHARS;
+    const n = raw ? Number(raw) : NaN;
+    return Number.isFinite(n) && n > 0 ? n : 20_000;
+})();
+class AIClient extends events_1.EventEmitter {
+    providers;
+    defaultProvider;
+    toolRegistry;
+    toolsConfig;
+    toolRouter;
+    bm25Engine;
+    queryClassifier;
+    toolOrchestrator;
+    activeMode = null;
+    overrideSystemPrompt;
+    disableBaseContext;
+    constructor(config) {
+        super();
+        this.providers = new Map(Object.entries(config.providers));
+        this.defaultProvider = config.defaultProvider;
+        this.toolRegistry = config.toolRegistry;
+        this.toolsConfig = config.toolsConfig || types_js_1.DEFAULT_TOOLS_CONFIG;
+        this.toolRouter = new router_js_1.ToolRouter();
+        this.bm25Engine = new index_js_1.BM25SearchEngine();
+        this.queryClassifier = new query_classifier_js_1.QueryClassifier();
+        this.toolOrchestrator = new tool_orchestrator_js_1.ToolOrchestrator();
+        this.overrideSystemPrompt = config.systemPrompt;
+        this.disableBaseContext = config.disableBaseContext || false;
+        // Index tools for BM25 search if registry is provided
+        if (this.toolRegistry) {
+            this.bm25Engine.index(this.toolRegistry.getAll());
+        }
+    }
+    /**
+     * Register a new provider instance.
+     */
+    registerProvider(name, provider) {
+        this.providers.set(name, provider);
+    }
+    /**
+     * Get a provider by name, or the default if none specified.
+     */
+    getProvider(name) {
+        const providerName = name || this.defaultProvider;
+        if (!providerName) {
+            throw new errors_1.SDKError('No provider specified and no default provider configured', 'NO_PROVIDER_CONFIGURED', 400);
+        }
+        const provider = this.providers.get(providerName);
+        if (!provider) {
+            throw new errors_1.SDKError(`Provider '${providerName}' not found`, 'PROVIDER_NOT_FOUND', 404);
+        }
+        return provider;
+    }
+    /**
+     * Set the default provider for this client.
+     */
+    setDefaultProvider(name) {
+        if (!this.providers.has(name)) {
+            throw new errors_1.SDKError(`Provider '${name}' not found`, 'PROVIDER_NOT_FOUND', 404);
+        }
+        this.defaultProvider = name;
+    }
+    /**
+     * Get the tool registry.
+     */
+    getToolRegistry() {
+        return this.toolRegistry;
+    }
+    /**
+     * Get all registered providers.
+     * Returns a copy of the internal map to prevent direct mutation.
+     */
+    getProviders() {
+        return new Map(this.providers);
+    }
+    /**
+     * Set or replace the tool registry.
+     */
+    setToolRegistry(registry) {
+        this.toolRegistry = registry;
+    }
+    /**
+     * Update tools config.
+     */
+    setToolsConfig(config) {
+        this.toolsConfig = config;
+    }
+    /**
+     * Set the override system prompt directly via code.
+     */
+    setSystemPrompt(prompt) {
+        this.overrideSystemPrompt = prompt;
+    }
+    /**
+     * Set the active mode. Pass null to clear.
+     */
+    setMode(mode) {
+        this.activeMode = mode;
+        (0, provider_logger_1.log)(`[AIClient] Mode set to: ${mode ? mode.displayName : 'none (cleared)'}`);
+    }
+    /**
+     * Get the currently active mode.
+     */
+    getMode() {
+        return this.activeMode;
+    }
+    /**
+     * Re-index tools for BM25 search.
+     * Call this after adding/removing tools from the registry.
+     */
+    reindexTools() {
+        if (this.toolRegistry) {
+            this.bm25Engine.index(this.toolRegistry.getAll());
+            (0, provider_logger_1.log)(`[AIClient] Re-indexed ${this.bm25Engine.getIndexedCount()} tools for BM25 search`);
+        }
+    }
+    /**
+     * Clear the tool discovery cache (call when starting a new conversation).
+     */
+    clearToolDiscoveryCache() {
+        this.toolRouter.clearDiscoveryCache();
+    }
+    /**
+     * unified generate completion
+     * When tools are enabled and autoExecute is true, handles the full
+     * tool call → execute → send result → get final answer loop.
+     */
+    async generate(request, providerName) {
+        const provider = this.getProvider(providerName);
+        try {
+            const requestId = newRequestId();
+            // System prompt injection chain (base → override → mode)
+            let modeAwareRequest = this.injectBaseAgentContext(request);
+            modeAwareRequest = this.injectOverrideSystemPrompt(modeAwareRequest);
+            modeAwareRequest = this.injectModeSystemPrompt(modeAwareRequest);
+            // Resolve tools to send with the request
+            const resolvedProviderName = providerName || this.defaultProvider;
+            const enrichedRequest = await this.enrichRequestWithTools(modeAwareRequest);
+            const policy = (process.env.TOOLPACK_SDK_TOOL_CHOICE_POLICY || this.toolsConfig.toolChoicePolicy || 'auto');
+            const hasTools = (enrichedRequest.tools?.length || 0) > 0;
+            const toolChoiceWasSet = enrichedRequest.tool_choice != null;
+            // Hybrid tool detection: regex first, then AI for follow-ups
+            let needsTools = inferNeedsTools(enrichedRequest.messages);
+            const intelligentDetection = this.toolsConfig.intelligentToolDetection;
+            let aiInferenceUsed = false;
+            if (!needsTools && intelligentDetection?.enabled && hasTools) {
+                const afterToolCall = isAfterToolCall(enrichedRequest.messages, intelligentDetection.maxFollowUpMessages);
+                if (afterToolCall) {
+                    (0, provider_logger_1.log)(`[AIClient][${requestId}] Message is after tool call, using AI to infer tool needs`);
+                    const fastModel = getFastModelForProvider(resolvedProviderName || 'openai');
+                    needsTools = await inferNeedsToolsWithAI(provider, resolvedProviderName || 'openai', enrichedRequest.messages, fastModel);
+                    aiInferenceUsed = true;
+                }
+            }
+            const lookupOnly = inferLookupOnly(enrichedRequest.messages);
+            const shouldForceRequired = !toolChoiceWasSet && hasTools && (policy === 'required' || (policy === 'required_for_actions' && needsTools));
+            const shouldForceNone = !toolChoiceWasSet && hasTools && aiInferenceUsed && !needsTools;
+            if (shouldForceRequired) {
+                enrichedRequest.tool_choice = 'required';
+            }
+            else if (shouldForceNone) {
+                enrichedRequest.tool_choice = 'none';
+                (0, provider_logger_1.log)(`[AIClient][${requestId}] AI inference determined no tools needed, setting tool_choice=none`);
+            }
+            const providerClass = provider?.constructor?.name || 'UnknownProvider';
+            const outboundReq = { ...enrichedRequest, __toolpack_request_id: requestId };
+            (0, provider_logger_1.log)(`[AIClient][${requestId}] generate() start provider=${resolvedProviderName} class=${providerClass} model=${enrichedRequest.model} messages=${enrichedRequest.messages.length} tools=${enrichedRequest.tools?.length || 0} tool_choice=${enrichedRequest.tool_choice ?? 'unset'} policy=${policy} needsTools=${needsTools} autoExecute=${this.toolsConfig.enabled && this.toolsConfig.autoExecute}`);
+            logRequestMessages(requestId, enrichedRequest.messages);
+            let response = await provider.generate(outboundReq);
+            (0, provider_logger_1.log)(`[AIClient][${requestId}] generate() initial response finish_reason=${response.finish_reason ?? 'unknown'} tool_calls=${response.tool_calls?.length || 0} content_preview=${(0, provider_logger_1.safePreview)(response.content || '', 200)}`);
+            // Auto-execute tool call loop
+            if (this.toolsConfig.enabled && this.toolsConfig.autoExecute && this.toolRegistry) {
+                // Classify query to adjust maxToolRounds
+                const userMessage = extractLastUserText(enrichedRequest.messages);
+                const classification = this.queryClassifier.classify(userMessage);
+                const baseMaxRounds = this.toolsConfig.maxToolRounds;
+                const maxRounds = this.queryClassifier.getToolRoundsAdjustment(classification, baseMaxRounds);
+                if (maxRounds !== baseMaxRounds) {
+                    (0, provider_logger_1.log)(`[AIClient][${requestId}] Query classified as ${classification.type} (confidence: ${classification.confidence.toFixed(2)}), adjusted maxToolRounds: ${baseMaxRounds} → ${maxRounds}`);
+                }
+                else {
+                    (0, provider_logger_1.log)(`[AIClient][${requestId}] Query classified as ${classification.type} (confidence: ${classification.confidence.toFixed(2)}), keeping maxToolRounds: ${maxRounds}`);
+                }
+                let rounds = 0;
+                const messages = [...enrichedRequest.messages];
+                if (response.tool_calls && response.tool_calls.length > 0) {
+                    (0, provider_logger_1.log)(`[AIClient] Received ${response.tool_calls.length} tool call(s): ${response.tool_calls.map(tc => tc.name).join(', ')}`);
+                }
+                while (response.tool_calls && response.tool_calls.length > 0 && rounds < maxRounds) {
+                    rounds++;
+                    (0, provider_logger_1.log)(`[AIClient][${requestId}] generate() tool round ${rounds}/${maxRounds} tool_calls=${response.tool_calls.length}`);
+                    // Add assistant message with tool calls to conversation
+                    messages.push({
+                        role: 'assistant',
+                        content: response.content || '',
+                        tool_calls: response.tool_calls.map(tc => ({
+                            id: tc.id,
+                            type: 'function',
+                            function: {
+                                name: tc.name,
+                                arguments: JSON.stringify(tc.arguments),
+                            },
+                        })),
+                    });
+                    // Execute tools with smart parallel/sequential orchestration
+                    const useParallel = this.toolOrchestrator.shouldUseParallelExecution(response.tool_calls);
+                    // Apply fan-out limits for web.fetch to prevent context overflow
+                    const MAX_WEB_FETCH_CALLS = 3;
+                    let toolCallsToExecute = response.tool_calls;
+                    const webFetchCalls = response.tool_calls.filter(tc => tc.name === 'web.fetch');
+                    if (webFetchCalls.length > MAX_WEB_FETCH_CALLS) {
+                        (0, provider_logger_1.log)(`[AIClient][${requestId}] Limiting web.fetch calls from ${webFetchCalls.length} → ${MAX_WEB_FETCH_CALLS} to prevent context overflow`);
+                        const limitedWebFetch = webFetchCalls.slice(0, MAX_WEB_FETCH_CALLS);
+                        const otherCalls = response.tool_calls.filter(tc => tc.name !== 'web.fetch');
+                        toolCallsToExecute = [...otherCalls, ...limitedWebFetch];
+                        // Add placeholder responses for excluded web.fetch calls to avoid orphaned tool_call_ids
+                        const excludedWebFetch = webFetchCalls.slice(MAX_WEB_FETCH_CALLS);
+                        for (const tc of excludedWebFetch) {
+                            messages.push({
+                                role: 'tool',
+                                tool_call_id: tc.id,
+                                content: '[Skipped: web.fetch fan-out limit exceeded]',
+                            });
+                        }
+                    }
+                    // Track tool output budget for this round
+                    const MAX_TOOL_OUTPUT_PER_ROUND = 50_000;
+                    let roundOutputSize = 0;
+                    if (useParallel) {
+                        (0, provider_logger_1.log)(`[AIClient][${requestId}] Using parallel execution for ${toolCallsToExecute.length} tools`);
+                        const toolResults = await this.toolOrchestrator.executeWithDependencies(toolCallsToExecute, (toolCall) => this.executeTool(toolCall), 5 // maxConcurrent
+                        );
+                        // Add results in original order with budget tracking
+                        let parallelBudgetExceeded = false;
+                        for (const toolCall of toolCallsToExecute) {
+                            if (parallelBudgetExceeded) {
+                                messages.push({
+                                    role: 'tool',
+                                    tool_call_id: toolCall.id,
+                                    content: '[Skipped: tool output budget exceeded for this round]',
+                                });
+                                continue;
+                            }
+                            const result = toolResults.get(toolCall.id);
+                            const resultStr = typeof result === 'string' ? result : JSON.stringify(result);
+                            // Check budget before adding
+                            if (roundOutputSize + resultStr.length > MAX_TOOL_OUTPUT_PER_ROUND) {
+                                (0, provider_logger_1.log)(`[AIClient][${requestId}] Tool output budget exceeded (${MAX_TOOL_OUTPUT_PER_ROUND} chars), adding placeholder for remaining tools`);
+                                messages.push({
+                                    role: 'tool',
+                                    tool_call_id: toolCall.id,
+                                    content: '[Skipped: tool output budget exceeded for this round]',
+                                });
+                                parallelBudgetExceeded = true;
+                                continue;
+                            }
+                            const content = typeof result === 'string' && result.length > TOOL_RESULT_MAX_CHARS
+                                ? `${result.slice(0, TOOL_RESULT_MAX_CHARS)}\n[TRUNCATED tool result: ${result.length} chars]`
+                                : result;
+                            const contentStr = typeof content === 'string' ? content : JSON.stringify(content);
+                            roundOutputSize += contentStr.length;
+                            messages.push({
+                                role: 'tool',
+                                tool_call_id: toolCall.id,
+                                content,
+                            });
+                        }
+                        (0, provider_logger_1.log)(`[AIClient][${requestId}] Round tool output size: ${roundOutputSize} chars (budget: ${MAX_TOOL_OUTPUT_PER_ROUND})`);
+                    }
+                    else {
+                        (0, provider_logger_1.log)(`[AIClient][${requestId}] Using sequential execution for ${toolCallsToExecute.length} tools`);
+                        // Sequential execution with budget tracking
+                        let seqBudgetExceeded = false;
+                        for (const toolCall of toolCallsToExecute) {
+                            if (seqBudgetExceeded) {
+                                messages.push({
+                                    role: 'tool',
+                                    tool_call_id: toolCall.id,
+                                    content: '[Skipped: tool output budget exceeded for this round]',
+                                });
+                                continue;
+                            }
+                            const result = await this.executeTool(toolCall);
+                            const resultStr = typeof result === 'string' ? result : JSON.stringify(result);
+                            // Check budget before adding
+                            if (roundOutputSize + resultStr.length > MAX_TOOL_OUTPUT_PER_ROUND) {
+                                (0, provider_logger_1.log)(`[AIClient][${requestId}] Tool output budget exceeded (${MAX_TOOL_OUTPUT_PER_ROUND} chars), adding placeholder for remaining tools`);
+                                messages.push({
+                                    role: 'tool',
+                                    tool_call_id: toolCall.id,
+                                    content: '[Skipped: tool output budget exceeded for this round]',
+                                });
+                                seqBudgetExceeded = true;
+                                continue;
+                            }
+                            const content = typeof result === 'string' && result.length > TOOL_RESULT_MAX_CHARS
+                                ? `${result.slice(0, TOOL_RESULT_MAX_CHARS)}\n[TRUNCATED tool result: ${result.length} chars]`
+                                : result;
+                            const contentStr = typeof content === 'string' ? content : JSON.stringify(content);
+                            roundOutputSize += contentStr.length;
+                            messages.push({
+                                role: 'tool',
+                                tool_call_id: toolCall.id,
+                                content,
+                            });
+                        }
+                        (0, provider_logger_1.log)(`[AIClient][${requestId}] Round tool output size: ${roundOutputSize} chars (budget: ${MAX_TOOL_OUTPUT_PER_ROUND})`);
+                    }
+                    // Call the model again with updated messages
+                    const rawFollowupReq = { ...enrichedRequest, messages, __toolpack_request_id: requestId };
+                    // Re-enrich to include any tools discovered in the previous round
+                    const followupReq = await this.enrichRequestWithTools(rawFollowupReq);
+                    if (followupReq.tool_choice === 'required') {
+                        followupReq.tool_choice = lookupOnly ? 'none' : 'auto';
+                        (0, provider_logger_1.log)(`[AIClient][${requestId}] generate() followup tool_choice override required->${followupReq.tool_choice}`);
+                    }
+                    if ((0, provider_logger_1.isVerbose)()) {
+                        (0, provider_logger_1.log)(`[AIClient][${requestId}] generate() followup request messages=${messages.length}`);
+                        logRequestMessages(requestId, messages);
+                    }
+                    response = await provider.generate(followupReq);
+                    (0, provider_logger_1.log)(`[AIClient][${requestId}] generate() followup response finish_reason=${response.finish_reason ?? 'unknown'} tool_calls=${response.tool_calls?.length || 0} content_preview=${(0, provider_logger_1.safePreview)(response.content || '', 200)}`);
+                }
+            }
+            return response;
+        }
+        catch (error) {
+            throw this.wrapError(error);
+        }
+    }
+    /**
+     * unified stream completion
+     * When tools are enabled and autoExecute is true, handles tool calls
+     * by collecting them, executing, and re-calling the model.
+     */
+    async *stream(request, providerName) {
+        const provider = this.getProvider(providerName);
+        try {
+            const requestId = newRequestId();
+            const resolvedProviderName = providerName || this.defaultProvider;
+            // System prompt injection chain (base → override → mode)
+            let modeAwareRequest = this.injectBaseAgentContext(request);
+            modeAwareRequest = this.injectOverrideSystemPrompt(modeAwareRequest);
+            modeAwareRequest = this.injectModeSystemPrompt(modeAwareRequest);
+            const enrichedRequest = await this.enrichRequestWithTools(modeAwareRequest);
+            const policy = (process.env.TOOLPACK_SDK_TOOL_CHOICE_POLICY || this.toolsConfig.toolChoicePolicy || 'auto');
+            const hasTools = (enrichedRequest.tools?.length || 0) > 0;
+            const toolChoiceWasSet = enrichedRequest.tool_choice != null;
+            // Hybrid tool detection: regex first, then AI for follow-ups
+            let needsTools = inferNeedsTools(enrichedRequest.messages);
+            const intelligentDetection = this.toolsConfig.intelligentToolDetection;
+            let aiInferenceUsed = false;
+            if (!needsTools && intelligentDetection?.enabled && hasTools) {
+                const afterToolCall = isAfterToolCall(enrichedRequest.messages, intelligentDetection.maxFollowUpMessages);
+                if (afterToolCall) {
+                    (0, provider_logger_1.log)(`[AIClient][${requestId}] Message is after tool call, using AI to infer tool needs`);
+                    const fastModel = getFastModelForProvider(resolvedProviderName || 'openai');
+                    needsTools = await inferNeedsToolsWithAI(provider, resolvedProviderName || 'openai', enrichedRequest.messages, fastModel);
+                    aiInferenceUsed = true;
+                }
+            }
+            const lookupOnly = inferLookupOnly(enrichedRequest.messages);
+            const shouldForceRequired = !toolChoiceWasSet && hasTools && (policy === 'required' || (policy === 'required_for_actions' && needsTools));
+            const shouldForceNone = !toolChoiceWasSet && hasTools && aiInferenceUsed && !needsTools;
+            if (shouldForceRequired) {
+                enrichedRequest.tool_choice = 'required';
+            }
+            else if (shouldForceNone) {
+                enrichedRequest.tool_choice = 'none';
+                (0, provider_logger_1.log)(`[AIClient][${requestId}] AI inference determined no tools needed, setting tool_choice=none`);
+            }
+            const providerClass = provider?.constructor?.name || 'UnknownProvider';
+            const baseReq = { ...enrichedRequest, __toolpack_request_id: requestId };
+            (0, provider_logger_1.log)(`[AIClient][${requestId}] stream() start provider=${resolvedProviderName} class=${providerClass} model=${enrichedRequest.model} messages=${enrichedRequest.messages.length} tools=${enrichedRequest.tools?.length || 0} tool_choice=${enrichedRequest.tool_choice ?? 'unset'} policy=${policy} needsTools=${needsTools} autoExecute=${this.toolsConfig.enabled && this.toolsConfig.autoExecute}`);
+            logRequestMessages(requestId, enrichedRequest.messages);
+            if (!this.toolsConfig.enabled || !this.toolsConfig.autoExecute || !this.toolRegistry) {
+                yield* provider.stream(baseReq);
+                return;
+            }
+            const messages = [...enrichedRequest.messages];
+            let rounds = 0;
+            // Classify query to adjust maxToolRounds (same as generate())
+            const userMessage = extractLastUserText(enrichedRequest.messages);
+            const classification = this.queryClassifier.classify(userMessage);
+            const baseMaxRounds = this.toolsConfig.maxToolRounds;
+            const maxRounds = this.queryClassifier.getToolRoundsAdjustment(classification, baseMaxRounds);
+            if (maxRounds !== baseMaxRounds) {
+                (0, provider_logger_1.log)(`[AIClient][${requestId}] stream() Query classified as ${classification.type} (confidence: ${classification.confidence.toFixed(2)}), adjusted maxToolRounds: ${baseMaxRounds} → ${maxRounds}`);
+            }
+            while (rounds <= maxRounds) {
+                // Check for abort signal at start of each round
+                if (request.signal?.aborted) {
+                    (0, provider_logger_1.log)(`[AIClient][${requestId}] stream() aborted by signal`);
+                    return;
+                }
+                let accumulatedContent = '';
+                const pendingToolCalls = [];
+                (0, provider_logger_1.log)(`[AIClient][${requestId}] stream() round_start ${rounds + 1}/${maxRounds}`);
+                let lastFinishReason = null;
+                const rawRoundReq = { ...baseReq, messages };
+                // Re-enrich to include any newly discovered tools from previous rounds
+                const roundReq = await this.enrichRequestWithTools(rawRoundReq);
+                if (rounds > 0 && roundReq.tool_choice === 'required') {
+                    roundReq.tool_choice = lookupOnly ? 'none' : 'auto';
+                    (0, provider_logger_1.log)(`[AIClient][${requestId}] stream() round_${rounds + 1} tool_choice override required->${roundReq.tool_choice}`);
+                }
+                for await (const chunk of provider.stream(roundReq)) {
+                    // Check for abort signal during streaming
+                    if (request.signal?.aborted) {
+                        (0, provider_logger_1.log)(`[AIClient][${requestId}] stream() aborted by signal during chunk processing`);
+                        return;
+                    }
+                    if (chunk.tool_calls && chunk.tool_calls.length > 0) {
+                        pendingToolCalls.push(...chunk.tool_calls);
+                        (0, provider_logger_1.log)(`[AIClient][${requestId}] stream() tool_calls_chunk count=${chunk.tool_calls.length} names=${chunk.tool_calls.map(tc => tc.name).join(', ')}`);
+                        // Yield tool calls in the chunk so consumers can track them
+                        yield chunk;
+                    }
+                    if (chunk.delta) {
+                        accumulatedContent += chunk.delta;
+                        yield chunk;
+                    }
+                    if (chunk.finish_reason) {
+                        lastFinishReason = chunk.finish_reason;
+                    }
+                    if (chunk.finish_reason === 'stop') {
+                        yield chunk;
+                    }
+                }
+                (0, provider_logger_1.log)(`[AIClient][${requestId}] stream() round_end finish_reason=${lastFinishReason ?? 'unknown'} accumulated_len=${accumulatedContent.length} tool_calls_total=${pendingToolCalls.length} content_preview=${(0, provider_logger_1.safePreview)(accumulatedContent, 200)}`);
+                // If no tool calls, we're done
+                if (pendingToolCalls.length === 0) {
+                    break;
+                }
+                (0, provider_logger_1.log)(`[AIClient][${requestId}] stream() received ${pendingToolCalls.length} tool call(s): ${pendingToolCalls.map(tc => tc.name).join(', ')}`);
+                rounds++;
+                if (rounds > maxRounds) {
+                    (0, provider_logger_1.log)(`[AIClient][${requestId}] stream() max tool rounds (${maxRounds}) reached`);
+                    break;
+                }
+                (0, provider_logger_1.log)(`[AIClient][${requestId}] stream() tool round ${rounds}/${maxRounds}`);
+                // Add assistant message and tool results to conversation
+                messages.push({
+                    role: 'assistant',
+                    content: accumulatedContent || '',
+                    tool_calls: pendingToolCalls.map(tc => ({
+                        id: tc.id,
+                        type: 'function',
+                        function: {
+                            name: tc.name,
+                            arguments: JSON.stringify(tc.arguments),
+                        },
+                    })),
+                });
+                // Apply fan-out limits for web.fetch to prevent context overflow
+                const MAX_WEB_FETCH_CALLS = 3;
+                let toolCallsToExecute = pendingToolCalls;
+                const webFetchCalls = pendingToolCalls.filter(tc => tc.name === 'web.fetch');
+                if (webFetchCalls.length > MAX_WEB_FETCH_CALLS) {
+                    (0, provider_logger_1.log)(`[AIClient][${requestId}] Limiting web.fetch calls from ${webFetchCalls.length} → ${MAX_WEB_FETCH_CALLS} to prevent context overflow`);
+                    const limitedWebFetch = webFetchCalls.slice(0, MAX_WEB_FETCH_CALLS);
+                    const otherCalls = pendingToolCalls.filter(tc => tc.name !== 'web.fetch');
+                    toolCallsToExecute = [...otherCalls, ...limitedWebFetch];
+                    // Add placeholder responses for excluded web.fetch calls to avoid orphaned tool_call_ids
+                    const excludedWebFetch = webFetchCalls.slice(MAX_WEB_FETCH_CALLS);
+                    for (const tc of excludedWebFetch) {
+                        messages.push({
+                            role: 'tool',
+                            tool_call_id: tc.id,
+                            content: '[Skipped: web.fetch fan-out limit exceeded]',
+                        });
+                    }
+                }
+                // Track tool output budget for this round
+                const MAX_TOOL_OUTPUT_PER_ROUND = 50_000;
+                let roundOutputSize = 0;
+                let budgetExceeded = false;
+                // Collect heartbeat chunks to yield while tools execute
+                const heartbeatChunks = [];
+                for (const toolCall of toolCallsToExecute) {
+                    if (budgetExceeded) {
+                        // Still must add a tool response for every tool_call to satisfy OpenAI API
+                        messages.push({
+                            role: 'tool',
+                            tool_call_id: toolCall.id,
+                            content: '[Skipped: tool output budget exceeded for this round]',
+                        });
+                        continue;
+                    }
+                    const startTime = Date.now();
+                    // Execute tool with heartbeat: yield empty chunks periodically
+                    // so UI consumers (e.g. terminal animations) stay alive
+                    let toolDone = false;
+                    const heartbeatInterval = setInterval(() => {
+                        if (!toolDone)
+                            heartbeatChunks.push({ delta: '' });
+                    }, 500);
+                    const result = await this.executeTool(toolCall);
+                    toolDone = true;
+                    clearInterval(heartbeatInterval);
+                    const duration = Date.now() - startTime;
+                    // Yield any queued heartbeat chunks
+                    while (heartbeatChunks.length > 0) {
+                        yield heartbeatChunks.shift();
+                    }
+                    // Extra yield point for event loop
+                    await new Promise(resolve => setTimeout(resolve, 0));
+                    const resultStr = typeof result === 'string' ? result : JSON.stringify(result);
+                    // Check budget before adding
+                    if (roundOutputSize + resultStr.length > MAX_TOOL_OUTPUT_PER_ROUND) {
+                        (0, provider_logger_1.log)(`[AIClient][${requestId}] Tool output budget exceeded (${MAX_TOOL_OUTPUT_PER_ROUND} chars), adding placeholder for remaining tools`);
+                        messages.push({
+                            role: 'tool',
+                            tool_call_id: toolCall.id,
+                            content: '[Skipped: tool output budget exceeded for this round]',
+                        });
+                        budgetExceeded = true;
+                        continue;
+                    }
+                    const content = typeof result === 'string' && result.length > TOOL_RESULT_MAX_CHARS
+                        ? `${result.slice(0, TOOL_RESULT_MAX_CHARS)}\n[TRUNCATED tool result: ${result.length} chars]`
+                        : result;
+                    const contentStr = typeof content === 'string' ? content : JSON.stringify(content);
+                    roundOutputSize += contentStr.length;
+                    messages.push({
+                        role: 'tool',
+                        tool_call_id: toolCall.id,
+                        content,
+                    });
+                    // Yield a chunk with the tool result so consumers can track it
+                    yield {
+                        delta: '',
+                        tool_calls: [{
+                                ...toolCall,
+                                result: typeof content === 'string' ? content : JSON.stringify(content),
+                                duration,
+                            }],
+                    };
+                }
+                (0, provider_logger_1.log)(`[AIClient][${requestId}] Round tool output size: ${roundOutputSize} chars (budget: ${MAX_TOOL_OUTPUT_PER_ROUND})`);
+                if ((0, provider_logger_1.isVerbose)()) {
+                    (0, provider_logger_1.log)(`[AIClient][${requestId}] stream() after_tools messages=${messages.length}`);
+                    logRequestMessages(requestId, messages);
+                }
+            }
+        }
+        catch (error) {
+            throw this.wrapError(error);
+        }
+    }
+    /**
+     * unified embed
+     */
+    async embed(request, providerName) {
+        const provider = this.getProvider(providerName);
+        try {
+            return await provider.embed(request);
+        }
+        catch (error) {
+            throw this.wrapError(error);
+        }
+    }
+    /**
+     * Enrich a request with tools based on the router config.
+     * Applies mode-based tool filtering when an active mode is set.
+     */
+    async enrichRequestWithTools(request) {
+        // If mode blocks ALL tools, return request with no tools
+        if (this.activeMode?.blockAllTools) {
+            (0, provider_logger_1.log)(`[AIClient] Mode "${this.activeMode.displayName}" blocks all tools`);
+            return request;
+        }
+        if (!this.toolsConfig.enabled || !this.toolRegistry) {
+            (0, provider_logger_1.log)(`[AIClient] Tools disabled or no registry`);
+            return request;
+        }
+        // Merge mode-specific tool search config with global config
+        let resolvedToolsConfig = this.toolsConfig;
+        if (this.activeMode?.toolSearch && this.toolsConfig.toolSearch) {
+            resolvedToolsConfig = {
+                ...this.toolsConfig,
+                toolSearch: {
+                    ...this.toolsConfig.toolSearch,
+                    ...(this.activeMode.toolSearch.enabled !== undefined ? { enabled: this.activeMode.toolSearch.enabled } : {}),
+                    ...(this.activeMode.toolSearch.alwaysLoadedTools ? { alwaysLoadedTools: this.activeMode.toolSearch.alwaysLoadedTools } : {}),
+                    ...(this.activeMode.toolSearch.alwaysLoadedCategories ? { alwaysLoadedCategories: this.activeMode.toolSearch.alwaysLoadedCategories } : {}),
+                }
+            };
+            (0, provider_logger_1.log)(`[AIClient] Merged mode toolSearch config: enabled=${resolvedToolsConfig.toolSearch?.enabled}, alwaysLoadedTools=${resolvedToolsConfig.toolSearch?.alwaysLoadedTools?.length || 0}`);
+        }
+        // If the request already has tools, only add newly discovered tools when tool.search mode is enabled
+        if (request.tools && request.tools.length > 0) {
+            if (!resolvedToolsConfig.toolSearch?.enabled || !this.toolRegistry) {
+                (0, provider_logger_1.log)(`[AIClient] Request already has ${request.tools.length} tools`);
+                return request;
+            }
+            let schemas = await this.toolRouter.resolve(request.messages, this.toolRegistry, resolvedToolsConfig);
+            (0, provider_logger_1.log)(`[AIClient] Resolved ${schemas.length} tools to send: ${schemas.map(s => s.name).join(', ') || 'none'}`);
+            if (this.activeMode && schemas.length > 0) {
+                const beforeCount = schemas.length;
+                schemas = this.filterSchemasByMode(schemas, this.activeMode);
+                const filteredCount = beforeCount - schemas.length;
+                if (filteredCount > 0) {
+                    (0, provider_logger_1.log)(`[AIClient] Mode "${this.activeMode.displayName}" filtered out ${filteredCount} tools`);
+                }
+            }
+            const existingToolNames = new Set(request.tools.map(tool => tool.function.name));
+            const newTools = schemas
+                .filter(schema => !existingToolNames.has(schema.name))
+                .map(schema => ({
+                type: 'function',
+                function: {
+                    name: schema.name,
+                    description: schema.description,
+                    parameters: schema.parameters,
+                },
+            }));
+            if (newTools.length === 0) {
+                (0, provider_logger_1.log)(`[AIClient] Request already has ${request.tools.length} tools (no new discoveries)`);
+                return request;
+            }
+            let enrichedRequest = {
+                ...request,
+                tools: [...request.tools, ...newTools],
+            };
+            if (resolvedToolsConfig.toolSearch?.enabled && this.toolRegistry) {
+                enrichedRequest = this.injectToolSearchPrompt(enrichedRequest);
+            }
+            return enrichedRequest;
+        }
+        let schemas = await this.toolRouter.resolve(request.messages, this.toolRegistry, resolvedToolsConfig);
+        (0, provider_logger_1.log)(`[AIClient] Resolved ${schemas.length} tools to send: ${schemas.map(s => s.name).join(', ') || 'none'}`);
+        // Apply mode-based filtering
+        if (this.activeMode && schemas.length > 0) {
+            const beforeCount = schemas.length;
+            schemas = this.filterSchemasByMode(schemas, this.activeMode);
+            const filteredCount = beforeCount - schemas.length;
+            if (filteredCount > 0) {
+                (0, provider_logger_1.log)(`[AIClient] Mode "${this.activeMode.displayName}" filtered out ${filteredCount} tools`);
+            }
+        }
+        if (schemas.length === 0) {
+            return request;
+        }
+        const tools = schemas.map(s => ({
+            type: 'function',
+            function: {
+                name: s.name,
+                description: s.description,
+                parameters: s.parameters,
+            },
+        }));
+        let enrichedRequest = { ...request, tools };
+        // Inject Tool Search system prompt if enabled
+        if (this.toolsConfig.toolSearch?.enabled && this.toolRegistry) {
+            enrichedRequest = this.injectToolSearchPrompt(enrichedRequest);
+        }
+        return enrichedRequest;
+    }
+    /**
+     * Filter tool schemas based on mode permissions.
+     * blockedTools/blockedToolCategories always take precedence.
+     */
+    filterSchemasByMode(schemas, mode) {
+        return schemas.filter(schema => {
+            // Check explicit blocks first (highest priority)
+            if (mode.blockedTools.includes(schema.name))
+                return false;
+            if (mode.blockedToolCategories.includes(schema.category))
+                return false;
+            // If allowlists are specified, tool must match at least one
+            const hasAllowedTools = mode.allowedTools.length > 0;
+            const hasAllowedCategories = mode.allowedToolCategories.length > 0;
+            if (hasAllowedTools || hasAllowedCategories) {
+                const nameAllowed = hasAllowedTools && mode.allowedTools.includes(schema.name);
+                const categoryAllowed = hasAllowedCategories && mode.allowedToolCategories.includes(schema.category);
+                return nameAllowed || categoryAllowed;
+            }
+            // No allowlists = everything is allowed (minus blocks)
+            return true;
+        });
+    }
+    /**
+     * Inject the active mode's system prompt into the request messages.
+     * For the "All" mode (empty systemPrompt), this is a no-op.
+     */
+    injectModeSystemPrompt(request) {
+        if (!this.activeMode || !this.activeMode.systemPrompt) {
+            (0, provider_logger_1.log)(`[AIClient] injectModeSystemPrompt: No active mode or empty systemPrompt. activeMode=${this.activeMode?.name}, systemPrompt=${this.activeMode?.systemPrompt?.substring(0, 50)}`);
+            return request;
+        }
+        const modePrompt = this.activeMode.systemPrompt;
+        (0, provider_logger_1.log)(`[AIClient] injectModeSystemPrompt: Injecting mode prompt for ${this.activeMode.name}, length=${modePrompt.length}`);
+        const hasSystemMessage = request.messages.some(m => m.role === 'system');
+        if (hasSystemMessage) {
+            // Prepend mode prompt to existing system message
+            const messages = request.messages.map(m => {
+                if (m.role === 'system') {
+                    const existingContent = typeof m.content === 'string' ? m.content : '';
+                    return {
+                        ...m,
+                        content: `${existingContent}\n\n${modePrompt}`
+                    };
+                }
+                return m;
+            });
+            return { ...request, messages };
+        }
+        else {
+            return {
+                ...request,
+                messages: [
+                    { role: 'system', content: modePrompt },
+                    ...request.messages
+                ]
+            };
+        }
+    }
+    /**
+     * Inject the overriding system prompt (from AIClientConfig) into the request.
+     */
+    injectOverrideSystemPrompt(request) {
+        if (!this.overrideSystemPrompt) {
+            return request;
+        }
+        const prompt = this.overrideSystemPrompt;
+        const hasSystemMessage = request.messages.some(m => m.role === 'system');
+        if (hasSystemMessage) {
+            const messages = request.messages.map(m => {
+                if (m.role === 'system') {
+                    const existingContent = typeof m.content === 'string' ? m.content : '';
+                    return {
+                        ...m,
+                        content: `${existingContent}\n\n${prompt}`
+                    };
+                }
+                return m;
+            });
+            return { ...request, messages };
+        }
+        else {
+            return {
+                ...request,
+                messages: [{ role: 'system', content: prompt }, ...request.messages]
+            };
+        }
+    }
+    /**
+     * Inject the Base Agent Context into the request.
+     * Tells the agent its CWD, tools, and to be proactive.
+     */
+    injectBaseAgentContext(request) {
+        // Check if active mode has per-mode baseContext config
+        let includeWd = true;
+        let includeCategories = true;
+        let customContext;
+        const disabled = this.disableBaseContext;
+        if (this.activeMode?.baseContext === false) {
+            // Mode explicitly disables base context entirely
+            return request;
+        }
+        else if (this.activeMode?.baseContext) {
+            // Mode has fine-grained base context config
+            includeWd = this.activeMode.baseContext.includeWorkingDirectory !== false;
+            includeCategories = this.activeMode.baseContext.includeToolCategories !== false;
+            customContext = this.activeMode.baseContext.custom;
+        }
+        const baseContext = customContext || (0, base_agent_context_js_1.generateBaseAgentContext)({
+            workingDirectory: process.cwd(),
+            toolCategories: this.toolRegistry ? this.toolRegistry.getCategories() : [],
+            disabled,
+            includeWorkingDirectory: includeWd,
+            includeToolCategories: includeCategories,
+        });
+        if (!baseContext) {
+            return request;
+        }
+        const hasSystemMessage = request.messages.some(m => m.role === 'system');
+        if (hasSystemMessage) {
+            const messages = request.messages.map(m => {
+                if (m.role === 'system') {
+                    const existingContent = typeof m.content === 'string' ? m.content : '';
+                    return {
+                        ...m,
+                        content: `${baseContext}\n\n${existingContent}`
+                    };
+                }
+                return m;
+            });
+            return { ...request, messages };
+        }
+        else {
+            return {
+                ...request,
+                messages: [{ role: 'system', content: baseContext }, ...request.messages]
+            };
+        }
+    }
+    /**
+     * Inject Tool Search system prompt to guide AI to use tool.search.
+     */
+    injectToolSearchPrompt(request) {
+        if (!this.toolRegistry)
+            return request;
+        // Check if system message already exists
+        const hasSystemMessage = request.messages.some(m => m.role === 'system');
+        const toolSearchInstructions = `
+IMPORTANT: Tool Discovery Instructions
+
+You have access to a limited set of tools. If you need a tool that is not in your current list, you MUST use the 'tool.search' tool to discover it.
+
+${(0, index_js_1.generateToolCategoriesPrompt)(this.toolRegistry)}
+
+When you need a tool:
+1. Check if it's in your current tool list
+2. If NOT found, call tool.search with a descriptive query (e.g., "delete file", "run command", "http request")
+3. After discovering tools, you can call them directly in subsequent turns
+
+NEVER guess or hallucinate tool names. ALWAYS use tool.search to discover tools you don't have.
+`.trim();
+        if (hasSystemMessage) {
+            // Append to existing system message
+            const messages = request.messages.map(m => {
+                if (m.role === 'system') {
+                    const existingContent = typeof m.content === 'string' ? m.content : '';
+                    return {
+                        ...m,
+                        content: `${existingContent}\n\n${toolSearchInstructions}`
+                    };
+                }
+                return m;
+            });
+            return { ...request, messages };
+        }
+        else {
+            // Prepend new system message
+            return {
+                ...request,
+                messages: [
+                    { role: 'system', content: toolSearchInstructions },
+                    ...request.messages
+                ]
+            };
+        }
+    }
+    /**
+     * Execute a single tool call via the registry.
+     * Emits 'tool:started', 'tool:completed', and 'tool:failed' events.
+     */
+    async executeTool(toolCall) {
+        const startTime = Date.now();
+        // Emit started event
+        this.emit('tool:started', {
+            toolName: toolCall.name,
+            toolCallId: toolCall.id,
+            status: 'started',
+            args: toolCall.arguments,
+        });
+        (0, provider_logger_1.log)(`[AIClient] Executing tool: ${toolCall.name} with args: ${(0, provider_logger_1.safePreview)(toolCall.arguments, 500)}`);
+        if (!this.toolRegistry) {
+            const error = 'No tool registry configured';
+            this.emit('tool:failed', {
+                toolName: toolCall.name,
+                toolCallId: toolCall.id,
+                status: 'failed',
+                error,
+                duration: Date.now() - startTime,
+            });
+            return JSON.stringify({ error });
+        }
+        // Special handling for tool.search (BM25 search)
+        if ((0, index_js_1.isToolSearchTool)(toolCall.name)) {
+            const result = this.executeToolSearch(toolCall.arguments);
+            const duration = Date.now() - startTime;
+            this.emit('tool:completed', {
+                toolName: toolCall.name,
+                toolCallId: toolCall.id,
+                status: 'completed',
+                result: typeof result === 'string' ? result.substring(0, 200) : JSON.stringify(result).substring(0, 200),
+                duration,
+            });
+            // Emit log event for tool.search
+            this.emit('tool:log', {
+                id: toolCall.id,
+                name: toolCall.name,
+                arguments: toolCall.arguments,
+                result,
+                duration,
+                status: 'success',
+                timestamp: Date.now(),
+            });
+            return result;
+        }
+        const tool = this.toolRegistry.get(toolCall.name);
+        if (!tool) {
+            (0, provider_logger_1.log)(`[AIClient] Tool '${toolCall.name}' not found in registry`);
+            // Fuzzy match: detect common hallucination patterns
+            const suggestion = this.findSimilarToolName(toolCall.name);
+            const errorMsg = suggestion
+                ? `Tool '${toolCall.name}' not found. Did you mean '${suggestion}'? Use tool.search to discover available tools.`
+                : `Tool '${toolCall.name}' not found. Use tool.search to discover available tools.`;
+            this.emit('tool:failed', {
+                toolName: toolCall.name,
+                toolCallId: toolCall.id,
+                status: 'failed',
+                error: errorMsg,
+                duration: Date.now() - startTime,
+            });
+            return JSON.stringify({ error: errorMsg });
+        }
+        try {
+            const ctx = {
+                workspaceRoot: process.cwd(),
+                config: this.toolsConfig?.additionalConfigurations ?? {},
+                log: (msg) => (0, provider_logger_1.log)(`[Tool] ${msg}`),
+            };
+            const result = await tool.execute(toolCall.arguments, ctx);
+            const duration = Date.now() - startTime;
+            // Emit completed event
+            this.emit('tool:completed', {
+                toolName: toolCall.name,
+                toolCallId: toolCall.id,
+                status: 'completed',
+                result: typeof result === 'string' ? result.substring(0, 200) : JSON.stringify(result).substring(0, 200),
+                duration,
+            });
+            // Emit log event with full details for history/logging
+            this.emit('tool:log', {
+                id: toolCall.id,
+                name: toolCall.name,
+                arguments: toolCall.arguments,
+                result,
+                duration,
+                status: 'success',
+                timestamp: Date.now(),
+            });
+            (0, provider_logger_1.log)(`[AIClient] Tool ${toolCall.name} executed successfully in ${duration}ms result_len=${result?.length ?? 0}`);
+            if ((0, provider_logger_1.isVerbose)()) {
+                (0, provider_logger_1.log)(`[AIClient] Tool ${toolCall.name} result_preview=${(0, provider_logger_1.safePreview)(result, 400)}`);
+            }
+            return result;
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            const errorMsg = error.message || 'Tool execution failed';
+            // Emit failed event
+            this.emit('tool:failed', {
+                toolName: toolCall.name,
+                toolCallId: toolCall.id,
+                status: 'failed',
+                error: errorMsg,
+                duration,
+            });
+            // Emit log event for errors too
+            this.emit('tool:log', {
+                id: toolCall.id,
+                name: toolCall.name,
+                arguments: toolCall.arguments,
+                result: JSON.stringify({ error: errorMsg }),
+                duration,
+                status: 'error',
+                timestamp: Date.now(),
+            });
+            (0, provider_logger_1.log)(`[AIClient] Tool ${toolCall.name} failed: ${(0, provider_logger_1.safePreview)(errorMsg, 300)}`);
+            return JSON.stringify({ error: errorMsg });
+        }
+    }
+    /**
+     * Find similar tool name to detect hallucinations.
+     * Detects common patterns like underscore vs dot (fs_delete_file vs fs.delete_file).
+     */
+    findSimilarToolName(hallucinatedName) {
+        if (!this.toolRegistry)
+            return null;
+        const allTools = this.toolRegistry.getAll();
+        // Pattern 1: underscore → dot (fs_delete_file → fs.delete_file)
+        const withDot = hallucinatedName.replace(/_/g, '.');
+        if (allTools.some(t => t.name === withDot)) {
+            return withDot;
+        }
+        // Pattern 2: dot → underscore (fs.delete.file → fs.delete_file)
+        const withUnderscore = hallucinatedName.replace(/\./g, '_');
+        if (allTools.some(t => t.name === withUnderscore)) {
+            return withUnderscore;
+        }
+        // Pattern 3: camelCase → dot.case (fsDeleteFile → fs.delete_file)
+        const fromCamelCase = hallucinatedName
+            .replace(/([a-z])([A-Z])/g, '$1_$2')
+            .toLowerCase()
+            .replace(/_/g, '.');
+        if (allTools.some(t => t.name === fromCamelCase)) {
+            return fromCamelCase;
+        }
+        // Pattern 4: Levenshtein distance for typos
+        let bestMatch = null;
+        let minDistance = Infinity;
+        for (const tool of allTools) {
+            const distance = this.levenshteinDistance(hallucinatedName.toLowerCase(), tool.name.toLowerCase());
+            // Only suggest if very close (1-2 character difference)
+            if (distance <= 2 && distance < minDistance) {
+                minDistance = distance;
+                bestMatch = tool.name;
+            }
+        }
+        return bestMatch;
+    }
+    /**
+     * Calculate Levenshtein distance between two strings.
+     */
+    levenshteinDistance(a, b) {
+        const matrix = [];
+        for (let i = 0; i <= b.length; i++) {
+            matrix[i] = [i];
+        }
+        for (let j = 0; j <= a.length; j++) {
+            matrix[0][j] = j;
+        }
+        for (let i = 1; i <= b.length; i++) {
+            for (let j = 1; j <= a.length; j++) {
+                if (b.charAt(i - 1) === a.charAt(j - 1)) {
+                    matrix[i][j] = matrix[i - 1][j - 1];
+                }
+                else {
+                    matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j] + 1);
+                }
+            }
+        }
+        return matrix[b.length][a.length];
+    }
+    /**
+     * Execute tool.search using BM25 engine.
+     */
+    executeToolSearch(args) {
+        const { query, category } = args;
+        const limit = this.toolsConfig.toolSearch?.searchResultLimit ?? 5;
+        (0, provider_logger_1.log)(`[AIClient] Executing tool.search: query="${query}" category=${category || 'all'} limit=${limit}`);
+        const results = this.bm25Engine.search(query, { limit, category });
+        // Record discovered tools in the cache
+        const toolNames = results.map(r => r.toolName);
+        this.toolRouter.getDiscoveryCache().recordDiscovery(query, toolNames);
+        (0, provider_logger_1.log)(`[AIClient] tool.search found ${results.length} tools: ${toolNames.join(', ') || 'none'}`);
+        return JSON.stringify({
+            query,
+            found: results.length,
+            tools: results.map(r => ({
+                name: r.tool.name,
+                displayName: r.tool.displayName,
+                description: r.tool.description,
+                category: r.tool.category,
+                parameters: r.tool.parameters,
+                relevanceScore: Math.round(r.score * 100) / 100,
+            })),
+            hint: results.length > 0
+                ? `Found ${results.length} tools. You can now call any of these tools directly.`
+                : `No tools found for "${query}". Try a different search term.`,
+        });
+    }
+    wrapError(error) {
+        if (error instanceof errors_1.SDKError) {
+            return error;
+        }
+        return new errors_1.ProviderError(error.message || 'Unknown provider error', 'UNKNOWN_PROVIDER_ERROR', 500, error);
+    }
+}
+exports.AIClient = AIClient;
+//# sourceMappingURL=index.js.map