@juspay/neurolink 9.10.0 → 9.11.0

package/dist/lib/core/conversationMemoryManager.d.ts

@@ -50,7 +50,7 @@ export declare class ConversationMemoryManager implements IConversationMemoryMan
      * Returns messages from pointer onwards (or all if no pointer)
      * Now consistently async to match Redis implementation
      */
-    buildContextMessages(sessionId: string): Promise<ChatMessage[]>;
+    buildContextMessages(sessionId: string, _userId?: string, _enableSummarization?: boolean, requestId?: string): Promise<ChatMessage[]>;
     getSession(sessionId: string, _userId?: string): SessionMemory | undefined;
     createSummarySystemMessage(content: string, summarizesFrom?: string, summarizesTo?: string): ChatMessage;
     private ensureInitialized;
@@ -59,4 +59,16 @@ export declare class ConversationMemoryManager implements IConversationMemoryMan
     getStats(): Promise<ConversationMemoryStats>;
     clearSession(sessionId: string): Promise<boolean>;
     clearAllSessions(): Promise<void>;
+    /**
+     * Get the raw messages array for a session.
+     * Returns the full messages list without context filtering or summarization.
+     * Returns a deep copy to prevent external mutation of internal state.
+     */
+    getSessionMessages(sessionId: string, _userId?: string): Promise<ChatMessage[]>;
+    /**
+     * Replace the entire messages array for a session.
+     * Creates the session if it does not exist.
+     * Resets summary pointers since old pointers may reference messages that no longer exist.
+     */
+    setSessionMessages(sessionId: string, messages: ChatMessage[], userId?: string): Promise<void>;
 }

package/dist/lib/core/conversationMemoryManager.js

@@ -92,11 +92,12 @@ export class ConversationMemoryManager {
                 if (!this.summarizationInProgress.has(options.sessionId)) {
                     setImmediate(async () => {
                         try {
-                            await this.checkAndSummarize(session, tokenThreshold);
+                            await this.checkAndSummarize(session, tokenThreshold, options.requestId);
                         }
                         catch (error) {
                             logger.error("Background summarization failed", {
                                 sessionId: session.sessionId,
+                                requestId: options.requestId,
                                 error: error instanceof Error ? error.message : String(error),
                             });
                         }
@@ -154,7 +155,7 @@ export class ConversationMemoryManager {
     /**
      * Check if summarization is needed based on token count
      */
-    async checkAndSummarize(session, threshold) {
+    async checkAndSummarize(session, threshold, requestId) {
         // Acquire lock - if already in progress, skip
         if (this.summarizationInProgress.has(session.sessionId)) {
             logger.debug("[ConversationMemoryManager] Summarization already in progress, skipping", {
@@ -164,7 +165,7 @@ export class ConversationMemoryManager {
         }
         this.summarizationInProgress.add(session.sessionId);
         try {
-            await this.summarizationEngine.checkAndSummarize(session, threshold, this.config, "[ConversationMemory]");
+            await this.summarizationEngine.checkAndSummarize(session, threshold, this.config, "[ConversationMemory]", requestId);
         }
         catch (error) {
             logger.error("Token counting or summarization failed", {
@@ -195,9 +196,9 @@ export class ConversationMemoryManager {
      * Returns messages from pointer onwards (or all if no pointer)
      * Now consistently async to match Redis implementation
      */
-    async buildContextMessages(sessionId) {
+    async buildContextMessages(sessionId, _userId, _enableSummarization, requestId) {
         const session = this.sessions.get(sessionId);
-        return session ? buildContextFromPointer(session) : [];
+        return session ? buildContextFromPointer(session, requestId) : [];
     }
     getSession(sessionId, _userId) {
         return this.sessions.get(sessionId);
@@ -263,5 +264,35 @@ export class ConversationMemoryManager {
         this.sessions.clear();
         logger.info("All sessions cleared", { clearedCount: sessionIds.length });
     }
+    /**
+     * Get the raw messages array for a session.
+     * Returns the full messages list without context filtering or summarization.
+     * Returns a deep copy to prevent external mutation of internal state.
+     */
+    async getSessionMessages(sessionId, _userId) {
+        await this.ensureInitialized();
+        const session = this.sessions.get(sessionId);
+        return session ? session.messages.map((msg) => ({ ...msg })) : [];
+    }
+    /**
+     * Replace the entire messages array for a session.
+     * Creates the session if it does not exist.
+     * Resets summary pointers since old pointers may reference messages that no longer exist.
+     */
+    async setSessionMessages(sessionId, messages, userId) {
+        await this.ensureInitialized();
+        let session = this.sessions.get(sessionId);
+        if (!session) {
+            session = this.createNewSession(sessionId, userId);
+            this.sessions.set(sessionId, session);
+            this.enforceSessionLimit();
+        }
+        session.messages = [...messages];
+        session.summarizedUpToMessageId = undefined;
+        session.summarizedMessage = undefined;
+        session.lastTokenCount = undefined;
+        session.lastCountedAt = undefined;
+        session.lastActivity = Date.now();
+    }
 }
 //# sourceMappingURL=conversationMemoryManager.js.map

package/dist/lib/core/modules/GenerationHandler.d.ts

@@ -38,6 +38,12 @@ export declare class GenerationHandler {
      * Execute the generation with AI SDK
      */
     executeGeneration(model: LanguageModelV1, messages: CoreMessage[], tools: Record<string, Tool>, options: TextGenerationOptions): Promise<Awaited<ReturnType<typeof generateText>>>;
+    /**
+     * Extract cache metrics from provider metadata (e.g. Anthropic's providerMetadata.anthropic)
+     * The Vercel AI SDK's LanguageModelUsage only has promptTokens/completionTokens/totalTokens.
+     * Cache metrics are surfaced via providerMetadata by provider-specific SDK adapters.
+     */
+    private extractCacheMetricsFromProviderMetadata;
     /**
      * Log generation completion information
      */

package/dist/lib/core/modules/GenerationHandler.js

@@ -14,8 +14,24 @@
  */
 import { generateText, Output, NoObjectGeneratedError } from "ai";
 import { logger } from "../../utils/logger.js";
-import { extractTokenUsage } from "../../utils/tokenUtils.js";
+import { extractTokenUsage, extractCacheCreationTokens, extractCacheReadTokens, calculateCacheSavingsPercent, } from "../../utils/tokenUtils.js";
 import { DEFAULT_MAX_STEPS } from "../constants.js";
+/**
+ * Safely preview-serialize a value for debug logging.
+ * Handles undefined, circular references, and non-serializable values.
+ */
+function safePreview(v) {
+    if (v === undefined) {
+        return "";
+    }
+    try {
+        const text = typeof v === "string" ? v : JSON.stringify(v);
+        return (text ?? "").substring(0, 200);
+    }
+    catch {
+        return "[unserializable]";
+    }
+}
 /**
  * GenerationHandler class - Handles text generation operations for AI providers
  */
@@ -39,16 +55,41 @@ export class GenerationHandler {
     async callGenerateText(model, messages, tools, options, shouldUseTools, includeStructuredOutput) {
         // Check if this is a Google provider (for provider-specific options)
         const isGoogleProvider = this.providerName === "google-ai" || this.providerName === "vertex";
-        // Check if this is an Anthropic provider
-        const isAnthropicProvider = this.providerName === "anthropic" || this.providerName === "bedrock";
+        // Check if this is an Anthropic provider (includes Vertex+Claude)
+        const isAnthropicProvider = this.providerName === "anthropic" ||
+            this.providerName === "bedrock" ||
+            (this.providerName === "vertex" && this.modelName?.startsWith("claude-"));
         const useStructuredOutput = includeStructuredOutput &&
             !!options.schema &&
             (options.output?.format === "json" ||
                 options.output?.format === "structured");
+        // Annotate the last tool with cache_control so the full tool-definition
+        // block becomes a cache breakpoint for Anthropic-family providers.
+        // Non-Anthropic providers harmlessly ignore unknown providerOptions.
+        // Note: The AI SDK Tool type doesn't yet include providerOptions, so we
+        // use a type assertion. The Anthropic adapter reads this at runtime.
+        const toolsWithCache = { ...tools };
+        if (isAnthropicProvider &&
+            shouldUseTools &&
+            Object.keys(toolsWithCache).length > 0) {
+            const toolNames = Object.keys(toolsWithCache);
+            const lastToolName = toolNames[toolNames.length - 1];
+            if (lastToolName && toolsWithCache[lastToolName]) {
+                const lastTool = toolsWithCache[lastToolName];
+                toolsWithCache[lastToolName] = {
+                    ...lastTool,
+                    providerOptions: {
+                        ...(lastTool.providerOptions ?? {}),
+                        anthropic: { cacheControl: { type: "ephemeral" } },
+                    },
+                };
+            }
+        }
         return await generateText({
             model,
             messages,
-            ...(shouldUseTools && Object.keys(tools).length > 0 && { tools }),
+            ...(shouldUseTools &&
+                Object.keys(toolsWithCache).length > 0 && { tools: toolsWithCache }),
             maxSteps: options.maxSteps ?? DEFAULT_MAX_STEPS,
             ...(shouldUseTools &&
                 options.toolChoice && { toolChoice: options.toolChoice }),
@@ -116,8 +157,90 @@ export class GenerationHandler {
         const useStructuredOutput = !!options.schema &&
             (options.output?.format === "json" ||
                 options.output?.format === "structured");
+        const requestId = options.requestId ||
+            options.context?.requestId ||
+            "unknown";
+        logger.info("[GenerationHandler] Calling generateText", {
+            requestId,
+            model: model.modelId || "unknown",
+            messageCount: messages.length,
+            toolCount: Object.keys(tools || {}).length,
+            maxSteps: options.maxSteps,
+            temperature: options.temperature,
+        });
+        if (logger.shouldLog("debug")) {
+            try {
+                logger.debug("[Observability] Full generateText parameters", {
+                    requestId,
+                    model: model.modelId || "unknown",
+                    messageCount: messages.length,
+                    messages: messages.map((msg, i) => ({
+                        index: i,
+                        role: msg.role,
+                        contentLength: typeof msg.content === "string"
+                            ? msg.content.length
+                            : safePreview(msg.content).length,
+                        contentPreview: typeof msg.content === "string"
+                            ? msg.content.substring(0, 200)
+                            : "[multimodal]",
+                    })),
+                    toolNames: Object.keys(tools || {}),
+                    toolCount: Object.keys(tools || {}).length,
+                    maxSteps: options.maxSteps,
+                    temperature: options.temperature,
+                    maxTokens: options.maxTokens,
+                });
+            }
+            catch {
+                // Ignore serialization errors in debug logging
+            }
+        }
+        const genStartTime = Date.now();
         try {
-            return await this.callGenerateText(model, messages, tools, options, shouldUseTools, true);
+            const result = await this.callGenerateText(model, messages, tools, options, shouldUseTools, true);
+            logger.info("[GenerationHandler] generateText returned", {
+                requestId,
+                durationMs: Date.now() - genStartTime,
+                finishReason: result.finishReason,
+                steps: result.steps?.length || 1,
+                toolCallsTotal: result.toolCalls?.length || 0,
+                responseChars: result.text?.length || 0,
+            });
+            if (logger.shouldLog("debug")) {
+                logger.debug("[Observability] Full LLM response", {
+                    requestId,
+                    finishReason: result.finishReason,
+                    responseTextPreview: result.text?.substring(0, 200) || "",
+                    responseTextLength: result.text?.length || 0,
+                    toolCalls: result.toolCalls?.map((tc) => ({
+                        toolName: tc.toolName,
+                        argsPreview: safePreview(tc.args),
+                    })),
+                    toolResults: result.toolResults?.map((tr) => ({
+                        toolName: tr.toolName,
+                        resultPreview: safePreview(tr.result),
+                    })),
+                    steps: result.steps?.map((step, i) => ({
+                        stepIndex: i,
+                        stepType: step.stepType,
+                        textPreview: step.text?.substring(0, 200),
+                        textLength: step.text?.length || 0,
+                        toolCalls: step.toolCalls?.map((tc) => ({
+                            toolName: tc.toolName,
+                            argsPreview: safePreview(tc.args),
+                        })),
+                        toolResults: step.toolResults?.map((tr) => ({
+                            toolName: tr.toolName,
+                            resultPreview: safePreview(tr.result),
+                        })),
+                        finishReason: step.finishReason,
+                    })),
+                    usage: result.usage,
+                    providerMetadata: result.experimental_providerMetadata ||
+                        result.providerMetadata,
+                });
+            }
+            return result;
         }
         catch (error) {
             // If NoObjectGeneratedError is thrown when using schema + tools together,
@@ -130,16 +253,50 @@ export class GenerationHandler {
                 });
                 // Retry without experimental_output - the formatEnhancedResult method
                 // will extract JSON from the text response
-                return await this.callGenerateText(model, messages, tools, options, shouldUseTools, false);
+                const result = await this.callGenerateText(model, messages, tools, options, shouldUseTools, false);
+                logger.info("[GenerationHandler] generateText returned (fallback)", {
+                    requestId,
+                    durationMs: Date.now() - genStartTime,
+                    finishReason: result.finishReason,
+                    steps: result.steps?.length || 1,
+                    toolCallsTotal: result.toolCalls?.length || 0,
+                    responseChars: result.text?.length || 0,
+                });
+                return result;
             }
             // Re-throw other errors
             throw error;
         }
     }
+    /**
+     * Extract cache metrics from provider metadata (e.g. Anthropic's providerMetadata.anthropic)
+     * The Vercel AI SDK's LanguageModelUsage only has promptTokens/completionTokens/totalTokens.
+     * Cache metrics are surfaced via providerMetadata by provider-specific SDK adapters.
+     */
+    extractCacheMetricsFromProviderMetadata(generateResult) {
+        const providerMeta = generateResult
+            .providerMetadata ||
+            generateResult.experimental_providerMetadata;
+        if (!providerMeta) {
+            return {};
+        }
+        // Anthropic surfaces cache metrics under providerMetadata.anthropic
+        const anthropicMeta = providerMeta.anthropic;
+        if (anthropicMeta) {
+            const cacheCreationTokens = extractCacheCreationTokens(anthropicMeta);
+            const cacheReadTokens = extractCacheReadTokens(anthropicMeta);
+            return {
+                ...(cacheCreationTokens !== undefined && { cacheCreationTokens }),
+                ...(cacheReadTokens !== undefined && { cacheReadTokens }),
+            };
+        }
+        return {};
+    }
     /**
      * Log generation completion information
      */
     logGenerationComplete(generateResult) {
+        const cacheMetrics = this.extractCacheMetricsFromProviderMetadata(generateResult);
         logger.debug(`generateText completed`, {
             provider: this.providerName,
             model: this.modelName,
@@ -147,6 +304,12 @@ export class GenerationHandler {
             toolResultsCount: generateResult.toolResults?.length || 0,
             finishReason: generateResult.finishReason,
             usage: generateResult.usage,
+            ...(cacheMetrics.cacheCreationTokens !== undefined && {
+                cacheCreationTokens: cacheMetrics.cacheCreationTokens,
+            }),
+            ...(cacheMetrics.cacheReadTokens !== undefined && {
+                cacheReadTokens: cacheMetrics.cacheReadTokens,
+            }),
             timestamp: Date.now(),
         });
     }
@@ -274,6 +437,28 @@ export class GenerationHandler {
         // Note: The AI SDK bundles thinking tokens into promptTokens for Google models.
         // Separate reasoningTokens tracking will work when/if the AI SDK adds support.
         const usage = extractTokenUsage(generateResult.usage);
+        // Merge cache metrics from providerMetadata if not already present in usage
+        // The AI SDK's LanguageModelUsage doesn't include cache tokens; they come from
+        // provider-specific metadata (e.g. Anthropic's providerMetadata.anthropic)
+        if (usage.cacheCreationTokens === undefined ||
+            usage.cacheReadTokens === undefined) {
+            const cacheMetrics = this.extractCacheMetricsFromProviderMetadata(generateResult);
+            if (usage.cacheCreationTokens === undefined &&
+                cacheMetrics.cacheCreationTokens !== undefined) {
+                usage.cacheCreationTokens = cacheMetrics.cacheCreationTokens;
+            }
+            if (usage.cacheReadTokens === undefined &&
+                cacheMetrics.cacheReadTokens !== undefined) {
+                usage.cacheReadTokens = cacheMetrics.cacheReadTokens;
+            }
+            // Recalculate cache savings if we added cache metrics
+            if (usage.cacheReadTokens !== undefined) {
+                const savingsPercent = calculateCacheSavingsPercent(usage.cacheReadTokens, usage.input);
+                if (savingsPercent !== undefined) {
+                    usage.cacheSavingsPercent = savingsPercent;
+                }
+            }
+        }
         return {
             content,
             usage,
@@ -309,7 +494,7 @@ export class GenerationHandler {
             provider: this.providerName,
             model: this.modelName,
             responseTextLength: result.text?.length || 0,
-            responsePreview: result.text?.substring(0, 500) + "...",
+            responsePreview: result.text?.substring(0, 500) ?? "",
             finishReason: result.finishReason,
             usage: result.usage,
         });

package/dist/lib/core/modules/MessageBuilder.js

@@ -76,25 +76,44 @@ export class MessageBuilder {
             messages = await buildMessagesArray(options);
         }
         // Convert messages to Vercel AI SDK format
+        // Preserve providerOptions (e.g. Anthropic cache_control) through conversion
         return messages.map((msg) => {
+            const providerOptions = msg
+                .providerOptions;
             if (typeof msg.content === "string") {
                 return {
                     role: msg.role,
                     content: msg.content,
+                    ...(providerOptions && { providerOptions }),
                 };
             }
             else {
                 return {
                     role: msg.role,
                     content: msg.content.map((item) => {
+                        const itemProviderOptions = item
+                            .providerOptions;
                         if (item.type === "text") {
-                            return { type: "text", text: item.text || "" };
+                            return {
+                                type: "text",
+                                text: item.text || "",
+                                ...(itemProviderOptions && {
+                                    providerOptions: itemProviderOptions,
+                                }),
+                            };
                         }
                         else if (item.type === "image") {
-                            return { type: "image", image: item.image || "" };
+                            return {
+                                type: "image",
+                                image: item.image || "",
+                                ...(itemProviderOptions && {
+                                    providerOptions: itemProviderOptions,
+                                }),
+                            };
                         }
                         return item;
                     }),
+                    ...(providerOptions && { providerOptions }),
                 };
             }
         });
@@ -159,25 +178,44 @@ export class MessageBuilder {
             messages = await buildMessagesArray(options);
         }
         // Convert messages to Vercel AI SDK format
+        // Preserve providerOptions (e.g. Anthropic cache_control) through conversion
         return messages.map((msg) => {
+            const providerOptions = msg
+                .providerOptions;
             if (typeof msg.content === "string") {
                 return {
                     role: msg.role,
                     content: msg.content,
+                    ...(providerOptions && { providerOptions }),
                 };
             }
             else {
                 return {
                     role: msg.role,
                     content: msg.content.map((item) => {
+                        const itemProviderOptions = item
+                            .providerOptions;
                         if (item.type === "text") {
-                            return { type: "text", text: item.text || "" };
+                            return {
+                                type: "text",
+                                text: item.text || "",
+                                ...(itemProviderOptions && {
+                                    providerOptions: itemProviderOptions,
+                                }),
+                            };
                         }
                         else if (item.type === "image") {
-                            return { type: "image", image: item.image || "" };
+                            return {
+                                type: "image",
+                                image: item.image || "",
+                                ...(itemProviderOptions && {
+                                    providerOptions: itemProviderOptions,
+                                }),
+                            };
                         }
                         return item;
                     }),
+                    ...(providerOptions && { providerOptions }),
                 };
             }
         });

package/dist/lib/core/modules/TelemetryHandler.js

@@ -17,6 +17,7 @@ import { nanoid } from "nanoid";
 import { logger } from "../../utils/logger.js";
 import { getPerformanceOptimizedProvider, recordProviderPerformanceFromMetrics, } from "../evaluationProviders.js";
 import { modelConfig } from "../modelConfiguration.js";
+import { TelemetryService } from "../../telemetry/telemetryService.js";
 /**
  * TelemetryHandler class - Handles analytics and telemetry for AI providers
  */
@@ -79,6 +80,8 @@ export class TelemetryHandler {
                 cost: actualCost,
                 success: true,
             });
+            // Wire TelemetryService metrics so OTEL counters/histograms are populated
+            TelemetryService.getInstance().recordAIRequest(this.providerName, this.modelName, usage?.totalTokens || 0, responseTime, actualCost > 0 ? actualCost : undefined);
             const optimizedProvider = getPerformanceOptimizedProvider("speed");
             logger.debug(`🚀 Performance recorded for ${this.providerName}:`, {
                 responseTime: `${responseTime}ms`,
@@ -147,7 +150,7 @@ export class TelemetryHandler {
             isEnabled: true,
             functionId,
             metadata,
-            recordInputs: false,
+            recordInputs: process.env.NEUROLINK_RECORD_INPUTS?.toLowerCase() === "true",
             recordOutputs: true,
         };
     }

package/dist/lib/core/redisConversationMemoryManager.d.ts

@@ -48,7 +48,13 @@ export declare class RedisConversationMemoryManager implements IConversationMemo
     /**
      * Get session by ID, reconstructing a SessionMemory from Redis storage.
      */
-    getSession(sessionId: string, userId?: string): Promise<SessionMemory | undefined>;
+    getSession(sessionId: string, userId?: string, requestId?: string): Promise<SessionMemory | undefined>;
+    /**
+     * Get raw session data without any filtering or transformation.
+     * Used by the memory retrieval tool and internal APIs that need
+     * access to full message data including unmodified tool outputs.
+     */
+    getSessionRaw(sessionId: string, userId?: string): Promise<RedisConversationObject | null>;
     /**
      * Get all sessions for a specific user
      */
@@ -90,9 +96,9 @@ export declare class RedisConversationMemoryManager implements IConversationMemo
     /**
      * Build context messages for AI prompt injection (TOKEN-BASED)
      * Returns messages from pointer onwards (or all if no pointer)
-     * Filters out tool_call and tool_result messages when summarization is enabled
+     * Applies sendToolPreview toggle and hydrates result.result for backward compat
      */
-    buildContextMessages(sessionId: string, userId?: string, enableSummarization?: boolean): Promise<ChatMessage[]>;
+    buildContextMessages(sessionId: string, userId?: string, enableSummarization?: boolean, requestId?: string): Promise<ChatMessage[]>;
     /**
      * Get session metadata for a specific user session (optimized for listing)
      * Fetches only essential metadata without heavy message arrays
@@ -131,6 +137,16 @@ export declare class RedisConversationMemoryManager implements IConversationMemo
      * Create summary system message
      */
     createSummarySystemMessage(content: string, summarizesFrom?: string, summarizesTo?: string): ChatMessage;
+    /**
+     * Get the raw messages array for a session.
+     * Returns the full messages list without context filtering or summarization.
+     */
+    getSessionMessages(sessionId: string, userId?: string): Promise<ChatMessage[]>;
+    /**
+     * Replace the entire messages array for a session.
+     * The session must already exist in Redis.
+     */
+    setSessionMessages(sessionId: string, messages: ChatMessage[], userId?: string): Promise<void>;
     /**
      * Close Redis connection
      */