@juspay/neurolink 12.47.13 → 12.48.0

package/dist/core/baseProvider.js

@@ -5,7 +5,7 @@ import { defaultProviderFor } from "../factories/mediaHandlerCatalog.js";
 import { DECISION_PROVIDERS, PROVIDER_DESCRIPTORS_BY_NAME, } from "../factories/providerDescriptors.js";
 import { MiddlewareFactory } from "../middleware/factory.js";
 import { modelSupports } from "../models/modelRegistry.js";
-import { resolveRequestKind } from "./resolveRequestKind.js";
+import { resolveRequestKind, resolveTTSMode } from "./resolveRequestKind.js";
 import { ATTR, tracers } from "../telemetry/index.js";
 import { ERROR_CODES, isAbortError, NeuroLinkError, } from "../utils/errorHandling.js";
 import { InvalidModelError, ProviderError } from "../types/index.js";
@@ -34,7 +34,8 @@ import { composeAbortSignals, composeAbortSignalsScoped, createTimeoutController
 import { shouldDisableBuiltinTools } from "../utils/toolUtils.js";
 import { getKeyCount, getKeysAsString, transformToolExecutions, } from "../utils/transformationUtils.js";
 import { ToolExecutionRecorder } from "./toolExecutionRecorder.js";
-import { TTS_ERROR_CODES, TTSProcessor } from "../utils/ttsProcessor.js";
+import { resolveTTSHandlerBudgetMs, TTS_ERROR_CODES, TTSProcessor, } from "../utils/ttsProcessor.js";
+import { prepareTextForSpeech, resolveSpeechSanitizeOptions, } from "../utils/speechText.js";
 import { executeVideoAnalysis, hasVideoFrames, } from "../utils/videoAnalysisProcessor.js";
 import { dedupeTools } from "./toolDedup.js";
 import { resolveToolPolicy, toolNameMatcher } from "../tools/toolPolicy.js";
@@ -1074,6 +1075,7 @@ export class BaseProvider {
                 ? {
                     attempted: TTSProcessor.supports(ttsProvider),
                     success: false,
+                    mode: "response",
                 }
                 : result?.ttsMetadata;
             const onTTSComplete = incrementalTTS
@@ -1348,10 +1350,13 @@ export class BaseProvider {
     async prepareGenerationContext(options) {
         const shouldUseTools = this.shouldUseTools(options, true);
         const baseTools = shouldUseTools ? await this.getAllTools() : {};
+        // Registered and MCP tools arrive from ToolsManager already emitting
+        // tool:start / tool:end; per-call tools get the same wrapper here so the
+        // event bus sees every execution exactly once.
         let tools = shouldUseTools
             ? {
                 ...baseTools,
-                ...(options.tools || {}),
+                ...this.toolsManager.wrapExternalToolsWithEvents((options.tools || {})),
             }
             : {};
         // Apply per-call tool filtering (whitelist/blacklist)
@@ -1390,7 +1395,7 @@ export class BaseProvider {
             return {};
         }
         const baseTools = await this.getAllTools();
-        const externalTools = (options.tools || {});
+        const externalTools = this.toolsManager.wrapExternalToolsWithEvents((options.tools || {}));
         let merged = { ...baseTools, ...externalTools };
         // Apply per-call tool filtering (whitelist/blacklist)
         merged = this.applyToolFiltering(merged, options);
@@ -1430,8 +1435,44 @@ export class BaseProvider {
      * Build messages array for generation - delegated to MessageBuilder
      */
     async buildMessages(options) {
+        this.applyToolReplayDefault(options);
         return this.messageBuilder.buildMessages(options);
     }
+    /**
+     * Fold the instance's `conversationMemory.replayToolSteps` into the request
+     * when the caller set none, so every path into the message builder — text
+     * or multimodal, generate or stream — reads one resolved value. The
+     * builder itself defaults to `"marker"` when neither is set.
+     *
+     * Then degrade `"full"` to `"marker"` for a request that declares no tools:
+     * Anthropic rejects a prompt carrying tool_use / tool_result blocks without
+     * a `tools` field ("Requests which include tool_use or tool_result blocks
+     * must define tools"), so a tools-off call — `disableTools`, or a filter
+     * that removed every tool — in a session that already ran one would fail
+     * on every later turn. Runs after the provider has merged `options.tools`,
+     * which is where every native path calls the builder from.
+     */
+    applyToolReplayDefault(options) {
+        if (options.replayToolSteps === undefined) {
+            const configured = this.neurolink?.conversationMemory?.config?.replayToolSteps;
+            if (configured !== undefined) {
+                options.replayToolSteps = configured;
+            }
+        }
+        if (options.replayToolSteps !== "full") {
+            return;
+        }
+        const declaredTools = options.tools;
+        const declaresNoTools = options.disableTools === true ||
+            (declaredTools !== undefined &&
+                declaredTools !== null &&
+                typeof declaredTools === "object" &&
+                Object.keys(declaredTools).length === 0);
+        if (declaresNoTools) {
+            logger.debug(`[${this.providerName}] replayToolSteps "full" degraded to "marker": the request declares no tools`);
+            options.replayToolSteps = "marker";
+        }
+    }
     /**
      * Build messages array for streaming operations - delegated to MessageBuilder
      * This is a protected helper method that providers can use to build messages
@@ -1441,6 +1482,7 @@ export class BaseProvider {
      * @returns Promise resolving to ModelMessage array ready for AI SDK
      */
     async buildMessagesForStream(options) {
+        this.applyToolReplayDefault(options);
         return this.messageBuilder.buildMessagesForStream(options);
     }
     /**
@@ -1674,6 +1716,15 @@ export class BaseProvider {
             }
         }
     }
+    /**
+     * Mode 1 — synthesize the input text itself, with no LLM call.
+     *
+     * This is the documented default for `generate({ tts: { enabled: true } })`
+     * and what every "speak this text" caller relies on, so a request that
+     * looks like it wanted the model's reply (tools, a system prompt, message
+     * history, a schema, conversation memory) is warned about, never rejected:
+     * those options have no effect here, and the fix is `tts.mode: "response"`.
+     */
     async handleDirectTTSSynthesis(options, startTime) {
         const textToSynthesize = options.prompt ?? options.input?.text ?? "";
         const baseResult = {
@@ -1686,14 +1737,17 @@ export class BaseProvider {
         if (!ttsOptions) {
             return this.enhanceResult(baseResult, options, startTime);
         }
+        this.warnIfDirectTTSLooksLikeResponseRequest(options);
         const ttsStartTime = Date.now();
         const ttsProvider = ttsOptions.provider ?? options.provider ?? this.providerName;
-        const ttsTimeout = this.getTimeout(options);
+        const ttsTimeout = this.resolveTTSSynthesisTimeout(options, ttsOptions, ttsProvider);
+        const speechText = this.prepareTTSInput(textToSynthesize, ttsOptions);
         try {
-            baseResult.audio = await withTimeoutFn(() => TTSProcessor.synthesize(textToSynthesize, ttsProvider, ttsOptions), ttsTimeout, `TTS synthesis timed out after ${ttsTimeout}ms for provider "${ttsProvider}"`);
+            baseResult.audio = await this.runTTSSynthesis(speechText, ttsProvider, ttsOptions, ttsTimeout, options.abortSignal);
             baseResult.ttsMetadata = {
                 attempted: true,
                 success: true,
+                mode: "direct",
                 latency: Date.now() - ttsStartTime,
             };
         }
@@ -1703,6 +1757,7 @@ export class BaseProvider {
             baseResult.ttsMetadata = {
                 attempted: true,
                 success: false,
+                mode: "direct",
                 error,
                 latency,
             };
@@ -1711,6 +1766,105 @@ export class BaseProvider {
         }
         return this.enhanceResult(baseResult, options, startTime);
     }
+    /**
+     * One warning when a direct-synthesis request carries options that only a
+     * model call would honour and the caller never chose a mode. Silence is
+     * the wrong answer here — the caller gets `usage` of zero and `content`
+     * echoing their prompt, and would otherwise have to guess why.
+     *
+     * Only options the CALLER supplied count. `conversationMemoryConfig` is
+     * attached by NeuroLink to every request on a memory-enabled instance, and
+     * on such an instance `conversationMessages` is the stored history
+     * NeuroLink injected itself — neither is something the caller set, and a
+     * voice bot with memory used to see this warning on every turn after the
+     * first for options it never passed.
+     */
+    warnIfDirectTTSLooksLikeResponseRequest(options) {
+        const tts = options.tts;
+        if (!tts || tts.mode !== undefined || tts.useAiResponse !== undefined) {
+            return;
+        }
+        const memoryAttached = options.conversationMemoryConfig !== undefined;
+        const llmShaped = [];
+        if (options.tools && Object.keys(options.tools).length > 0) {
+            llmShaped.push("tools");
+        }
+        if (options.systemPrompt) {
+            llmShaped.push("systemPrompt");
+        }
+        if (!memoryAttached &&
+            options.conversationMessages &&
+            options.conversationMessages.length > 0) {
+            llmShaped.push("conversationMessages");
+        }
+        if (options.conversationHistory && options.conversationHistory.length > 0) {
+            llmShaped.push("conversationHistory");
+        }
+        if (options.schema) {
+            llmShaped.push("schema");
+        }
+        if (llmShaped.length === 0) {
+            return;
+        }
+        logger.warn(`[${this.providerName}] tts.enabled without tts.mode synthesizes the INPUT text and makes no model call, so ${llmShaped.join(", ")} will be ignored. Set tts.mode: "response" to speak the model's reply, or tts.mode: "direct" to silence this warning.`);
+    }
+    /**
+     * Outer bound on one synthesis call: the provider's request timeout, raised
+     * to whatever the handler itself may legitimately spend — `timeoutMs × (1 +
+     * retries)` plus retry pauses, with the handler defaults (30 s, one retry)
+     * standing in for a knob the caller left unset. Without the raise, a
+     * handler's own retry loop could be cut off from outside one attempt in:
+     * with the 60 s provider default, a first attempt that hung to its 30 s
+     * abort left no room for the documented default retry.
+     */
+    resolveTTSSynthesisTimeout(options, ttsOptions, ttsProvider) {
+        return Math.max(this.getTimeout(options), resolveTTSHandlerBudgetMs(ttsOptions, ttsProvider));
+    }
+    /**
+     * Apply `tts.sanitize` (off by default — existing callers see byte-identical
+     * input). Always runs when configured, regardless of the raw text's
+     * length against the provider's cap: sanitizing can shrink text a great
+     * deal (the default `codeBlocks: "phrase"` replaces a whole fenced block
+     * with one short phrase, `urls: "hostname"` shortens every link), so a
+     * reply that is over the cap raw can still fit after sanitizing — a coding
+     * answer with a large code block is exactly the reply this option is for.
+     * A reply still over the cap afterwards is rejected downstream by
+     * `TTSProcessor.synthesize` as `TTS_TEXT_TOO_LONG`, same as today.
+     */
+    prepareTTSInput(text, ttsOptions) {
+        const sanitizeOptions = resolveSpeechSanitizeOptions(ttsOptions.sanitize);
+        if (!sanitizeOptions) {
+            return text;
+        }
+        return prepareTextForSpeech(text, sanitizeOptions);
+    }
+    /**
+     * One synthesis call under the outer budget. The handler receives a signal
+     * that fires when that budget lapses or the caller's own `abortSignal`
+     * does, so a handler with a retry loop (ElevenLabs) stops rather than
+     * pausing and issuing a further billable request after the caller has
+     * already been told the synthesis failed.
+     */
+    async runTTSSynthesis(speechText, ttsProvider, ttsOptions, ttsTimeout, abortSignal) {
+        const cancel = new AbortController();
+        const signals = [cancel.signal];
+        if (abortSignal) {
+            signals.push(abortSignal);
+        }
+        if (ttsOptions.signal) {
+            signals.push(ttsOptions.signal);
+        }
+        const signal = AbortSignal.any(signals);
+        try {
+            return await withTimeoutFn(() => TTSProcessor.synthesize(speechText, ttsProvider, {
+                ...ttsOptions,
+                signal,
+            }), ttsTimeout, `TTS synthesis timed out after ${ttsTimeout}ms for provider "${ttsProvider}"`);
+        }
+        finally {
+            cancel.abort();
+        }
+    }
     async handleVideoFrameGeneration(options, messages, model, startTime) {
         if (!hasVideoFrames(messages)) {
             return null;
@@ -1795,15 +1949,93 @@ export class BaseProvider {
      * synthesis so telemetry sees the model's own usage, and `enhanceResult`
      * runs last so analytics and evaluation observe the final content.
      */
-    async finalizeNativeGenerate(result, options, startTime) {
+    async finalizeNativeGenerate(result, options, startTime, toolExecutionSummaries) {
         // onFinish is NOT fired here. `applyGenerateLifecycleMiddleware` folds it
         // into `options.middleware.middlewareConfig.lifecycle`, and the native
         // paths now wrap their model, so the lifecycle middleware fires it.
         // Firing it here too would deliver every callback twice.
         await this.recordPerformanceMetrics(result.usage, Date.now() - startTime);
+        await this.persistGenerateToolSteps(options, toolExecutionSummaries);
         const synthesized = await this.synthesizeAIResponseIfNeeded(result, options);
         return this.enhanceResult(synthesized, options, startTime);
     }
+    /**
+     * Persist a generate() turn's tool steps into conversation memory.
+     *
+     * The stream loops store each step's calls and results as they run;
+     * generate() never did, so the same session held tool rows for streamed
+     * turns and none for generated ones, and a later turn could not replay
+     * what generate() had called. Every native generate path closes out
+     * through finalizeNativeGenerate, so this is the one place to do it.
+     *
+     * Gated on a real session id: the storage helper otherwise invents a
+     * `session-<nanoid>` key, and on the in-memory backend that creates a
+     * throwaway session per tool-using call — evicting real ones once
+     * `maxSessions` is reached. A turn with no session has no history to
+     * replay into, so there is nothing to persist.
+     */
+    async persistGenerateToolSteps(options, summaries) {
+        if (!summaries || summaries.length === 0) {
+            return;
+        }
+        const sessionId = options.context?.sessionId ??
+            options.sessionId;
+        if (typeof sessionId !== "string" || sessionId.length === 0) {
+            return;
+        }
+        // One storage call per loop step, in step order. The stream loops store
+        // as each step finishes, so a step's calls and results sit together;
+        // storing a whole generate() turn as one batch replayed a sequential
+        // lookup-then-send as a single parallel step, with the second call's
+        // arguments appearing before the output they were built from.
+        //
+        // Summaries arrive in execution order, so a new batch starts whenever
+        // the step changes rather than grouping by stepIndex value: a provider
+        // can run the native loop more than once against the same summaries
+        // array (a response_format rejection retry, a schema-validation retry),
+        // and each run numbers its own steps from 0 — grouping by value would
+        // merge run 1's step 0 with run 2's step 0 into one parallel batch.
+        const batches = [];
+        for (const summary of summaries) {
+            const last = batches[batches.length - 1];
+            if (last && last[0].stepIndex === summary.stepIndex) {
+                last.push(summary);
+            }
+            else {
+                batches.push([summary]);
+            }
+        }
+        for (const stepSummaries of batches) {
+            const toolCalls = stepSummaries.map((s) => ({
+                toolCallId: s.toolCallId,
+                toolName: s.toolName,
+                args: s.input !== null &&
+                    typeof s.input === "object" &&
+                    !Array.isArray(s.input)
+                    ? s.input
+                    : {},
+                ...(s.stepIndex !== undefined ? { stepIndex: s.stepIndex } : {}),
+                timestamp: s.startTime,
+            }));
+            const toolResults = stepSummaries.map((s) => ({
+                toolCallId: s.toolCallId,
+                toolName: s.toolName,
+                output: s.output,
+                ...(s.error ? { error: s.error } : {}),
+                ...(s.stepIndex !== undefined ? { stepIndex: s.stepIndex } : {}),
+                timestamp: s.endTime,
+            }));
+            try {
+                await this.handleToolExecutionStorage(toolCalls, toolResults, options, new Date());
+            }
+            catch (error) {
+                logger.warn(`[${this.providerName}] Failed to store tool executions`, {
+                    provider: this.providerName,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
     /**
      * Invoke a caller's `onFinish` for a native turn.
      *
@@ -1838,7 +2070,7 @@ export class BaseProvider {
         }
     }
     async synthesizeAIResponseIfNeeded(enhancedResult, options) {
-        if (!options.tts?.enabled || !options.tts?.useAiResponse) {
+        if (!options.tts?.enabled || resolveTTSMode(options.tts) !== "response") {
             return enhancedResult;
         }
         const ttsOptions = options.tts;
@@ -1852,6 +2084,7 @@ export class BaseProvider {
                 hasProvider: !!ttsProvider,
                 ttsConfig: {
                     enabled: options.tts?.enabled,
+                    mode: options.tts?.mode,
                     useAiResponse: options.tts?.useAiResponse,
                 },
                 reason: !aiResponse
@@ -1863,19 +2096,22 @@ export class BaseProvider {
                 ttsMetadata: {
                     attempted: false,
                     success: false,
+                    mode: "response",
                 },
             };
         }
         const ttsStartTime = Date.now();
-        const ttsTimeout = this.getTimeout(options);
+        const ttsTimeout = this.resolveTTSSynthesisTimeout(options, ttsOptions, ttsProvider);
+        const speechText = this.prepareTTSInput(aiResponse, ttsOptions);
         try {
-            const ttsResult = await withTimeoutFn(() => TTSProcessor.synthesize(aiResponse, ttsProvider, ttsOptions), ttsTimeout, `TTS synthesis timed out after ${ttsTimeout}ms for provider "${ttsProvider}"`);
+            const ttsResult = await this.runTTSSynthesis(speechText, ttsProvider, ttsOptions, ttsTimeout, options.abortSignal);
             return {
                 ...enhancedResult,
                 audio: ttsResult,
                 ttsMetadata: {
                     attempted: true,
                     success: true,
+                    mode: "response",
                     latency: Date.now() - ttsStartTime,
                 },
             };
@@ -1890,6 +2126,7 @@ export class BaseProvider {
                 ttsMetadata: {
                     attempted: true,
                     success: false,
+                    mode: "response",
                     error,
                     latency,
                 },
@@ -2385,6 +2622,13 @@ export class BaseProvider {
         this.fileToolRootsBound = true;
         this.toolsManager.setDirectTools(policy.roots === null ? this.directTools : createDirectAgentTools(policy));
     }
+    /**
+     * Emit the start/end pair for a tool call a loop rejected before execute
+     * (unknown tool, schema rejection). See ToolsManager.emitRejectedToolCall.
+     */
+    emitRejectedToolCall(toolName, error, toolCallId) {
+        this.toolsManager.emitRejectedToolCall(toolName, error, toolCallId);
+    }
     /**
      * Resolve roots for a provider called directly, without NeuroLink. A
      * policy NeuroLink already bound is left alone unless these options carry

package/dist/core/conversationMemoryManager.js

@@ -11,6 +11,7 @@ import { tracers, withSpan } from "../telemetry/index.js";
 import { ConversationMemoryError } from "../types/index.js";
 import { buildContextFromPointer, getEffectiveTokenThreshold, } from "../utils/conversationMemory.js";
 import { logger } from "../utils/logger.js";
+import { extractIsErrorText } from "../utils/toolResultStatus.js";
 export class ConversationMemoryManager {
     sessions = new Map();
     config;
@@ -421,6 +422,7 @@ export class ConversationMemoryManager {
             if (toolCallId) {
                 toolNameById.set(toolCallId, toolName);
             }
+            const callStepIndex = toolCall.stepIndex;
             session.messages.push({
                 id: randomUUID(),
                 role: "tool_call",
@@ -428,6 +430,10 @@ export class ConversationMemoryManager {
                 tool: toolName,
                 ...(toolCallId ? { toolCallId } : {}),
                 args: (toolCall.args ?? {}),
+                // Zero-based loop step, so replay can keep sequential steps apart.
+                ...(typeof callStepIndex === "number"
+                    ? { metadata: { stepIndex: callStepIndex } }
+                    : {}),
                 timestamp,
             });
         }
@@ -448,6 +454,14 @@ export class ConversationMemoryManager {
                     content = `[Serialization failed: ${error instanceof Error ? error.message : String(error)}]`;
                 }
             }
+            // A result the tool RETURNED with `isError: true` (a thrown error that
+            // neurolink.executeTool converted, a breaker refusal, an MCP failure)
+            // is a failure too; recording it as success made the next turn's
+            // replay say "→ ok" for a call that failed.
+            const error = toolResult.error !== undefined && toolResult.error !== null
+                ? String(toolResult.error)
+                : extractIsErrorText(rawOutput);
+            const stepIndex = toolResult.stepIndex;
             session.messages.push({
                 id: randomUUID(),
                 role: "tool_result",
@@ -455,9 +469,10 @@ export class ConversationMemoryManager {
                 tool: toolName,
                 ...(toolCallId ? { toolCallId } : {}),
                 result: {
-                    success: !toolResult.error,
-                    ...(toolResult.error ? { error: String(toolResult.error) } : {}),
+                    success: error === undefined,
+                    ...(error !== undefined ? { error } : {}),
                 },
+                ...(typeof stepIndex === "number" ? { metadata: { stepIndex } } : {}),
                 timestamp,
             });
         }

package/dist/core/loopEngine.js

@@ -324,7 +324,7 @@ export function runAgenticLoop(adapter, initialConversation, options) {
                         break;
                     }
                 }
-                const request = adapter.buildStepRequest(conversation, step);
+                const request = await adapter.buildStepRequest(conversation, step);
                 // A tool that just became callable starts clean. Its TOOL_NOT_FOUND
                 // strikes were recorded against a name that genuinely did not resolve
                 // yet, and the breaker is consulted before the lookup, so without this

package/dist/core/modules/MessageBuilder.js

@@ -1,6 +1,6 @@
 import { tracers, ATTR, withSpan } from "../../telemetry/index.js";
 import { logger } from "../../utils/logger.js";
-import { buildMessagesArray, buildMultimodalMessagesArray, } from "../../utils/messageBuilder.js";
+import { buildMessagesArray, buildMultimodalModelMessages, } from "../../utils/messageBuilder.js";
 /**
  * Compute total content length across all messages for span attributes.
  */
@@ -127,11 +127,12 @@ export class MessageBuilder {
                     enableEvaluation: options.enableEvaluation,
                     context: options.context,
                     conversationHistory: options.conversationMessages,
+                    replayToolSteps: options.replayToolSteps,
                     schema: options.schema,
                     output: options.output,
                     fileRegistry: options.fileRegistry,
                 };
-                messages = await buildMultimodalMessagesArray(multimodalOptions, this.providerName, this.modelName);
+                messages = await buildMultimodalModelMessages(multimodalOptions, this.providerName, this.modelName);
                 // Propagate any systemPrompt augmentation (e.g. inline-file
                 // handling guidance from processUnifiedFilesArray) back to the
                 // caller's options. Providers like GoogleVertex's native
@@ -163,6 +164,9 @@ export class MessageBuilder {
                 }
                 else {
                     return {
+                        // `tool` rides through untouched: a replayed tool step
+                        // (replayToolSteps: "full") is a tool turn of tool-result parts,
+                        // and its tool-call parts fall to the passthrough branch below.
                         role: msg.role,
                         content: msg.content.map((item) => {
                             const itemProviderOptions = item.providerOptions;
@@ -272,11 +276,12 @@ export class MessageBuilder {
                     context: options.context,
                     conversationHistory: options
                         .conversationMessages,
+                    replayToolSteps: options.replayToolSteps,
                     schema: options.schema,
                     output: options.output,
                     fileRegistry: options.fileRegistry,
                 };
-                messages = await buildMultimodalMessagesArray(multimodalOptions, this.providerName, this.modelName);
+                messages = await buildMultimodalModelMessages(multimodalOptions, this.providerName, this.modelName);
                 // Propagate any systemPrompt augmentation (e.g. inline-file
                 // handling guidance from processUnifiedFilesArray) back to the
                 // caller's options. Providers like GoogleVertex's native
@@ -308,6 +313,9 @@ export class MessageBuilder {
                 }
                 else {
                     return {
+                        // `tool` rides through untouched: a replayed tool step
+                        // (replayToolSteps: "full") is a tool turn of tool-result parts,
+                        // and its tool-call parts fall to the passthrough branch below.
                         role: msg.role,
                         content: msg.content.map((item) => {
                             const itemProviderOptions = item.providerOptions;

package/dist/core/modules/TelemetryHandler.d.ts

@@ -14,7 +14,7 @@
  * @module core/modules/TelemetryHandler
  */
 import type { NeuroLink } from "../../neurolink.js";
-import type { StreamOptions, AIProviderName, AnalyticsData, EnhancedGenerateResult, EvaluationData, RawUsageObject, TextGenerationOptions, TokenUsage, TTSMetadata } from "../../types/index.js";
+import type { StreamOptions, AIProviderName, AnalyticsData, EnhancedGenerateResult, EvaluationData, MemoryToolCallRecord, MemoryToolResultRecord, RawUsageObject, TextGenerationOptions, TokenUsage, TTSMetadata } from "../../types/index.js";
 /**
  * TelemetryHandler class - Handles analytics and telemetry for AI providers
  */
@@ -66,5 +66,5 @@ export declare class TelemetryHandler {
     /**
      * Handle tool execution storage if available
      */
-    handleToolExecutionStorage(toolCalls: unknown[], toolResults: unknown[], options: TextGenerationOptions | StreamOptions, currentTime: Date): Promise<void>;
+    handleToolExecutionStorage(toolCalls: MemoryToolCallRecord[], toolResults: MemoryToolResultRecord[], options: TextGenerationOptions | StreamOptions, currentTime: Date): Promise<void>;
 }

package/dist/core/modules/ToolsManager.d.ts

@@ -28,6 +28,7 @@ export declare class ToolsManager {
     protected toolExecutor?: (toolName: string, params: unknown, options?: Record<string, unknown>) => Promise<unknown>;
     protected sessionId?: string;
     protected userId?: string;
+    private readonly eventWrappedExecutes;
     constructor(providerName: AIProviderName, directTools: Record<string, unknown>, neurolink?: NeuroLink | undefined, utilities?: ToolUtilities | undefined);
     /**
      * BZ-666: Wrap tool execute with output truncation to prevent
@@ -93,7 +94,41 @@ export declare class ToolsManager {
      * Set session context for MCP tools
      */
     setSessionContext(sessionId?: string, userId?: string): void;
+    /**
+     * Emit one tool event. A listener that throws must never reach the tool
+     * loop: it would turn a successful execution into a failed one (the model
+     * then retries a side effect that already happened) and, from inside the
+     * wrapper's catch, produce a second `tool:end` for the same call. Listener
+     * failures are logged and swallowed here instead.
+     */
     private emitToolEvent;
+    /**
+     * Wrap an execute function so one `tool:start` and exactly one `tool:end`
+     * (with the real duration) fire per invocation. Idempotent: a function this
+     * manager already wrapped is returned as is, so a tool that re-enters
+     * resolution (the stream → generate fallback re-resolves `options.tools`)
+     * never emits twice.
+     *
+     * A result the tool RETURNED with `isError: true` (MCP failure, breaker
+     * refusal, a thrown error already converted by `neurolink.executeTool`) is
+     * a failure: `tool:end` carries `success: false` and the extracted text,
+     * as the step-finish emitter this wrapper replaced did.
+     */
+    private wrapExecuteWithEvents;
+    /**
+     * Report a tool call the loop rejected BEFORE any execute ran — an unknown
+     * tool name, arguments the schema rejected, a breaker skip. Nothing else
+     * emits for such a call, so listeners (memory event capture, tool spans,
+     * error-rate metrics) saw zero attempts while the result list held the
+     * failures. One `tool:start` / `tool:end(success: false)` pair.
+     */
+    emitRejectedToolCall(toolName: string, error: string, toolCallId?: string): void;
+    /**
+     * Give per-call tools (`options.tools`) the same `tool:start` / `tool:end`
+     * emission that registered and MCP tools get from their executors. Tools
+     * without an `execute` pass through untouched.
+     */
+    wrapExternalToolsWithEvents(tools: Record<string, Tool>): Record<string, Tool>;
     /**
      * Set up tool executor for a provider to enable actual tool execution
      * @param sdk - The NeuroLinkSDK instance for tool execution