@juspay/neurolink 9.51.3 → 9.51.4

package/dist/mcp/mcpOutputNormalizer.js

@@ -0,0 +1,181 @@
+/**
+ * MCP Output Normalizer
+ *
+ * Single responsibility: intercept a raw MCP `CallToolResult`, measure it,
+ * and apply the configured strategy so that oversized payloads never reach
+ * caches, Redis, or LLM context windows raw.
+ *
+ * Two strategies:
+ *  - "inline"      Pass through unchanged. The full payload enters the LLM
+ *                  context as-is. Emit a warning above warnBytes.
+ *  - "externalize" Write the full payload to the ArtifactStore, return a
+ *                  compact surrogate with a head/tail preview and an artifact
+ *                  ID. The model uses `retrieve_context` with that ID to read
+ *                  the full output on demand, with offset/limit pagination.
+ *
+ * The surrogate result is shaped as an MCP `CallToolResult` so it passes
+ * transparently through any downstream code that expects that format.
+ * A `_meta` extension carries the artifact ID for structured extraction in
+ * `redisConversationMemoryManager`.
+ *
+ * @module mcp/mcpOutputNormalizer
+ */
+import { generateToolOutputPreview } from "../context/toolOutputLimits.js";
+import { logger } from "../utils/logger.js";
+import { withTimeout } from "../utils/errorHandling.js";
+// ---------------------------------------------------------------------------
+// Public constants
+// ---------------------------------------------------------------------------
+/** Default byte ceiling above which externalize fires (100 KB). */
+export const DEFAULT_MAX_MCP_OUTPUT_BYTES = 100 * 1024;
+/** Default byte threshold for emitting a warning while still inline (50 KB). */
+export const DEFAULT_WARN_MCP_OUTPUT_BYTES = 50 * 1024;
+/** Metadata key embedded in surrogate `_meta` and used by memory manager. */
+export const NEUROLINK_ARTIFACT_ID_KEY = "neurolinkArtifactId";
+// ---------------------------------------------------------------------------
+// McpOutputNormalizer
+// ---------------------------------------------------------------------------
+/**
+ * Stateless normalizer (state lives in the injected ArtifactStore).
+ *
+ * Construct once per NeuroLink instance and set via
+ * `ToolDiscoveryService.setOutputNormalizer()`.
+ */
+export class McpOutputNormalizer {
+    config;
+    artifactStore;
+    constructor(config, artifactStore) {
+        this.config = config;
+        this.artifactStore = artifactStore;
+    }
+    /**
+     * Measure `callResult`, apply strategy if oversized, return normalized output.
+     *
+     * Never throws: on any internal failure the raw result is returned unchanged
+     * with a warning log so tool execution is never broken by the normalizer.
+     */
+    async normalize(callResult, context) {
+        const serialized = serialize(callResult);
+        const originalBytes = Buffer.byteLength(serialized, "utf-8");
+        // Fast path: below warn threshold — always inline, no logging
+        if (originalBytes <= this.config.warnBytes) {
+            return { result: callResult, isExternalized: false, originalBytes };
+        }
+        // Between warn and max: emit a warning but keep inline regardless of strategy
+        if (originalBytes <= this.config.maxBytes) {
+            logger.warn(`[McpOutputNormalizer] Large MCP output from "${context.toolName}" on ` +
+                `"${context.serverId}" (${formatBytes(originalBytes)}). ` +
+                `Approaching limit of ${formatBytes(this.config.maxBytes)}.`, {
+                toolName: context.toolName,
+                serverId: context.serverId,
+                originalBytes,
+            });
+            return { result: callResult, isExternalized: false, originalBytes };
+        }
+        // Above max — apply strategy
+        logger.warn(`[McpOutputNormalizer] MCP output from "${context.toolName}" on ` +
+            `"${context.serverId}" exceeds limit ` +
+            `(${formatBytes(originalBytes)} > ${formatBytes(this.config.maxBytes)}). ` +
+            `Applying strategy "${this.config.strategy}".`, { toolName: context.toolName, serverId: context.serverId, originalBytes });
+        if (this.config.strategy === "inline") {
+            // Caller explicitly opted in to inline regardless of size
+            return { result: callResult, isExternalized: false, originalBytes };
+        }
+        // strategy === "externalize"
+        if (!this.artifactStore) {
+            // Misconfiguration: externalize was chosen but no store was provided.
+            // Pass through inline so execution is never broken, but log loudly.
+            logger.error(`[McpOutputNormalizer] strategy="externalize" but no ArtifactStore ` +
+                `configured — passing through raw result for "${context.toolName}". ` +
+                `Set mcp.outputLimits.strategy="externalize" and ensure the NeuroLink ` +
+                `constructor creates a LocalTempArtifactStore.`);
+            return { result: callResult, isExternalized: false, originalBytes };
+        }
+        let ref;
+        try {
+            ref = await withTimeout(this.artifactStore.store(serialized, {
+                toolName: context.toolName,
+                serverId: context.serverId,
+                sessionId: context.sessionId,
+                sizeBytes: originalBytes,
+                contentType: isJsonLike(callResult) ? "json" : "text",
+            }), 10_000, new Error(`ArtifactStore.store() timed out for "${context.toolName}"`));
+        }
+        catch (err) {
+            // Storage failure or timeout — pass through inline so the call doesn't break.
+            logger.error(`[McpOutputNormalizer] ArtifactStore.store() failed for ` +
+                `"${context.toolName}": ${err instanceof Error ? err.message : String(err)} ` +
+                `— passing through raw result.`);
+            return { result: callResult, isExternalized: false, originalBytes };
+        }
+        // Generate a compact head/tail preview for the surrogate.
+        // Cap at warnBytes so the surrogate itself is always well within limits.
+        const { preview } = generateToolOutputPreview(serialized, {
+            maxBytes: Math.min(this.config.warnBytes, DEFAULT_WARN_MCP_OUTPUT_BYTES),
+        });
+        return {
+            result: buildSurrogate(preview, ref.id, context, originalBytes),
+            isExternalized: true,
+            artifactId: ref.id,
+            originalBytes,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Build a compact MCP-shaped surrogate the LLM receives instead of the
+ * raw oversized payload.
+ *
+ * Shape mirrors `CallToolResult` so downstream code that inspects
+ * `result.content` keeps working unchanged.
+ * `_meta` carries the artifact ID for structured extraction in
+ * `redisConversationMemoryManager`.
+ */
+function buildSurrogate(preview, artifactId, context, originalBytes) {
+    const text = `[MCP Tool Output — ${context.toolName} | ${context.serverId}]\n` +
+        `Original size: ${formatBytes(originalBytes)} | ` +
+        `Externalized — use retrieve_context with artifactId="${artifactId}" ` +
+        `to read the full output (supports offset + limit pagination)\n` +
+        `\n--- Preview (head + tail) ---\n` +
+        preview +
+        `\n--- End Preview ---\n` +
+        `[${NEUROLINK_ARTIFACT_ID_KEY}=${artifactId}]`;
+    return {
+        content: [{ type: "text", text }],
+        _meta: {
+            [NEUROLINK_ARTIFACT_ID_KEY]: artifactId,
+            originalBytes,
+            toolName: context.toolName,
+            serverId: context.serverId,
+        },
+    };
+}
+function serialize(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    try {
+        // Compact JSON keeps byte measurement accurate and size enforcement honest.
+        // Pretty-printing with null, 2 inflates every object by ~30–50 % and would
+        // shift the externalization threshold relative to what the LLM actually
+        // receives if the payload is ever inlined.
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function isJsonLike(value) {
+    return typeof value === "object" && value !== null;
+}
+function formatBytes(bytes) {
+    if (bytes < 1024) {
+        return `${bytes} B`;
+    }
+    if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    }
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}

package/dist/mcp/toolDiscoveryService.d.ts

@@ -8,6 +8,7 @@ import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { ExternalMCPToolInfo, ExternalMCPToolResult } from "../types/externalMcp.js";
 import type { ToolDiscoveryResult, ExternalToolExecutionOptions } from "../types/mcpTypes.js";
 import type { JsonObject } from "../types/common.js";
+import type { McpOutputNormalizer } from "./mcpOutputNormalizer.js";
 /**
  * ToolDiscoveryService
  * Handles automatic tool discovery and registration from external MCP servers
@@ -17,7 +18,16 @@ export declare class ToolDiscoveryService extends EventEmitter {
     private toolRegistry;
     private serverTools;
     private discoveryInProgress;
+    /** Optional normalizer applied to every tool output before it is returned. */
+    private outputNormalizer?;
     constructor();
+    /**
+     * Attach a McpOutputNormalizer.
+     * When set, every raw callTool() result is passed through the normalizer
+     * before being returned. Oversized outputs are replaced with compact
+     * surrogates according to the configured strategy.
+     */
+    setOutputNormalizer(normalizer: McpOutputNormalizer): void;
     /**
      * Discover tools from an external MCP server
      */

package/dist/mcp/toolDiscoveryService.js

@@ -26,9 +26,20 @@ export class ToolDiscoveryService extends EventEmitter {
     toolRegistry = new Map();
     serverTools = new Map();
     discoveryInProgress = new Set();
+    /** Optional normalizer applied to every tool output before it is returned. */
+    outputNormalizer;
     constructor() {
         super();
     }
+    /**
+     * Attach a McpOutputNormalizer.
+     * When set, every raw callTool() result is passed through the normalizer
+     * before being returned. Oversized outputs are replaced with compact
+     * surrogates according to the configured strategy.
+     */
+    setOutputNormalizer(normalizer) {
+        this.outputNormalizer = normalizer;
+    }
     /**
      * Discover tools from an external MCP server
      */
@@ -361,6 +372,26 @@ export class ToolDiscoveryService extends EventEmitter {
                             arguments: parameters,
                         }), timeout, new Error(`Tool execution timeout: ${toolName}`));
                         callSpan.setStatus({ code: SpanStatusCode.OK });
+                        // ── MCP output normalization ──────────────────────────────────
+                        // Intercept here — after receive, before cache, before memory,
+                        // before LLM context injection. Returns a compact surrogate when
+                        // the payload exceeds mcp.outputLimits.maxBytes.
+                        if (this.outputNormalizer) {
+                            try {
+                                const normalized = await this.outputNormalizer.normalize(callResult, { toolName, serverId });
+                                callSpan.setAttribute("mcp.output.strategy", normalized.isExternalized ? "externalize" : "inline");
+                                if (normalized.isExternalized) {
+                                    callSpan.setAttribute("mcp.output.original_bytes", normalized.originalBytes);
+                                }
+                                return normalized.result;
+                            }
+                            catch (normErr) {
+                                mcpLogger.warn(`[ToolDiscoveryService] McpOutputNormalizer failed for ` +
+                                    `${toolName}: ${normErr instanceof Error ? normErr.message : String(normErr)} ` +
+                                    `— returning raw result`);
+                            }
+                        }
+                        // ── end normalization ─────────────────────────────────────────
                         return callResult;
                     }
                     catch (err) {
@@ -385,7 +416,7 @@ export class ToolDiscoveryService extends EventEmitter {
             }
             mcpLogger.debug(`[ToolDiscoveryService] Tool execution completed: ${toolName}`, {
                 duration,
-                hasContent: !!result.content,
+                hasContent: !!result?.content,
             });
             return {
                 success: true,

package/dist/memory/memoryRetrievalTools.d.ts

@@ -7,14 +7,21 @@
  * @module
  */
 import type { RedisConversationMemoryManager } from "../core/redisConversationMemoryManager.js";
+import type { ArtifactStore } from "../artifacts/artifactStore.js";
 /**
  * Factory function that creates memory retrieval tools bound to a memory manager.
- * @param memoryManager - The Redis conversation memory manager instance
+ *
+ * @param memoryManager  Redis conversation memory manager instance.
+ * @param artifactStore  Optional artifact store for externalized MCP outputs.
+ *                       When provided, retrieve_context gains an `artifactId`
+ *                       parameter that fetches the full payload written by
+ *                       McpOutputNormalizer under strategy="externalize".
  * @returns Record of tool name to Vercel AI SDK tool definition
  */
-export declare function createMemoryRetrievalTools(memoryManager: RedisConversationMemoryManager): {
+export declare function createMemoryRetrievalTools(memoryManager: RedisConversationMemoryManager | undefined, artifactStore?: ArtifactStore): {
     retrieve_context: import("ai").Tool<{
-        sessionId: string;
+        sessionId?: string | undefined;
+        artifactId?: string | undefined;
         messageId?: string | undefined;
         role?: "system" | "user" | "assistant" | "tool_call" | "tool_result" | undefined;
         lastN?: number | undefined;
@@ -22,14 +29,62 @@ export declare function createMemoryRetrievalTools(memoryManager: RedisConversat
         limit?: number | undefined;
         search?: string | undefined;
     }, {
+        error: string;
+        artifactId: string;
+        content?: undefined;
+        totalSize?: undefined;
+        hasMore?: undefined;
+        offset?: undefined;
+        limit?: undefined;
+        sessionId?: undefined;
+        messageId?: undefined;
+        messages?: undefined;
+        totalMessages?: undefined;
+    } | {
+        artifactId: string;
+        content: string;
+        totalSize: number;
+        hasMore: boolean;
+        offset: number;
+        limit: number;
+        error?: undefined;
+        sessionId?: undefined;
+        messageId?: undefined;
+        messages?: undefined;
+        totalMessages?: undefined;
+    } | {
+        error: string;
+        artifactId?: undefined;
+        content?: undefined;
+        totalSize?: undefined;
+        hasMore?: undefined;
+        offset?: undefined;
+        limit?: undefined;
+        sessionId?: undefined;
+        messageId?: undefined;
+        messages?: undefined;
+        totalMessages?: undefined;
+    } | {
         error: string;
         sessionId: string;
+        artifactId?: undefined;
+        content?: undefined;
+        totalSize?: undefined;
+        hasMore?: undefined;
+        offset?: undefined;
+        limit?: undefined;
         messageId?: undefined;
         messages?: undefined;
         totalMessages?: undefined;
     } | {
         error: string;
         messageId: string;
+        artifactId?: undefined;
+        content?: undefined;
+        totalSize?: undefined;
+        hasMore?: undefined;
+        offset?: undefined;
+        limit?: undefined;
         sessionId?: undefined;
         messages?: undefined;
         totalMessages?: undefined;
@@ -70,13 +125,13 @@ export declare function createMemoryRetrievalTools(memoryManager: RedisConversat
         })[];
         totalMessages: number;
         error?: undefined;
+        artifactId?: undefined;
+        content?: undefined;
+        totalSize?: undefined;
+        hasMore?: undefined;
+        offset?: undefined;
+        limit?: undefined;
         sessionId?: undefined;
         messageId?: undefined;
-    } | {
-        error: string;
-        sessionId?: undefined;
-        messageId?: undefined;
-        messages?: undefined;
-        totalMessages?: undefined;
     }>;
 };

package/dist/memory/memoryRetrievalTools.js

@@ -9,6 +9,7 @@
 import { tool } from "ai";
 import { z } from "zod";
 import { logger } from "../utils/logger.js";
+import { withTimeout } from "../utils/errorHandling.js";
 import { SpanSerializer, SpanType, SpanStatus, } from "../observability/index.js";
 import { getMetricsAggregator } from "../observability/index.js";
 /** Maximum characters returned per retrieval request */
@@ -19,18 +20,36 @@ const MAX_RETRIEVAL_LIMIT = 200_000;
 const MAX_SEARCH_MATCHES = 50;
 /**
  * Factory function that creates memory retrieval tools bound to a memory manager.
- * @param memoryManager - The Redis conversation memory manager instance
+ *
+ * @param memoryManager  Redis conversation memory manager instance.
+ * @param artifactStore  Optional artifact store for externalized MCP outputs.
+ *                       When provided, retrieve_context gains an `artifactId`
+ *                       parameter that fetches the full payload written by
+ *                       McpOutputNormalizer under strategy="externalize".
  * @returns Record of tool name to Vercel AI SDK tool definition
  */
-export function createMemoryRetrievalTools(memoryManager) {
+export function createMemoryRetrievalTools(memoryManager, artifactStore) {
     return {
         retrieve_context: tool({
-            description: "Retrieve messages from conversation memory. Use this to access full tool " +
-                "outputs when a result was truncated, review previous assistant responses, " +
-                "or search through conversation history. Supports filtering by role, " +
-                "pagination for large content, and regex search within messages.",
+            description: "Retrieve messages from conversation memory, or fetch the full payload of " +
+                "an externalized MCP tool output by artifact ID. Use this to:\n" +
+                "• Access full tool outputs when a result was truncated or externalized\n" +
+                "• Review previous assistant responses\n" +
+                "• Search through conversation history\n" +
+                "Supports filtering by role, pagination for large content, and regex search.\n" +
+                "To fetch an externalized artifact, provide `artifactId` (omit sessionId).",
             inputSchema: z.object({
-                sessionId: z.string().describe("Session ID for the conversation"),
+                sessionId: z
+                    .string()
+                    .optional()
+                    .describe("Session ID for conversation history retrieval. " +
+                    "Required unless artifactId is provided."),
+                artifactId: z
+                    .string()
+                    .optional()
+                    .describe("Artifact ID from an externalized MCP tool output " +
+                    "(visible in the tool output as neurolinkArtifactId=<id>). " +
+                    "When provided, returns the full stored payload directly."),
                 messageId: z
                     .string()
                     .optional()
@@ -64,19 +83,68 @@ export function createMemoryRetrievalTools(memoryManager) {
                     "Returns matching lines with line numbers."),
             }),
             execute: async (args) => {
+                // ── Artifact resolution path ────────────────────────────────────────
+                // When the caller supplies an artifactId we short-circuit to the
+                // artifact store (bypassing Redis) and return the full payload with
+                // optional offset/limit pagination.
+                if (args.artifactId) {
+                    if (!artifactStore) {
+                        logger.warn("[MemoryRetrievalTools] retrieve_context called with artifactId " +
+                            "but no ArtifactStore is configured");
+                        return {
+                            error: "Artifact store not configured — " +
+                                "mcp.outputLimits.strategy must be set to 'externalize' to use artifactId retrieval",
+                            artifactId: args.artifactId,
+                        };
+                    }
+                    const content = await withTimeout(artifactStore.retrieve(args.artifactId), 10_000, new Error(`ArtifactStore.retrieve() timed out for artifact "${args.artifactId}"`));
+                    if (content === null) {
+                        return {
+                            error: "Artifact not found or has expired",
+                            artifactId: args.artifactId,
+                        };
+                    }
+                    const charLimit = Math.min(args.limit ?? DEFAULT_RETRIEVAL_LIMIT, MAX_RETRIEVAL_LIMIT);
+                    const start = args.offset ?? 0;
+                    const slice = content.slice(start, start + charLimit);
+                    return {
+                        artifactId: args.artifactId,
+                        content: slice,
+                        totalSize: content.length,
+                        hasMore: start + charLimit < content.length,
+                        offset: start,
+                        limit: charLimit,
+                    };
+                }
+                // ── End artifact resolution ─────────────────────────────────────────
+                if (!args.sessionId) {
+                    return {
+                        error: "sessionId is required when artifactId is not provided",
+                    };
+                }
+                if (!memoryManager) {
+                    return {
+                        error: "Session history retrieval requires Redis conversation memory — " +
+                            "enable mcp.conversationMemory with a Redis backend, or use " +
+                            "artifactId to retrieve an externalized MCP tool output.",
+                    };
+                }
                 const span = SpanSerializer.createSpan(SpanType.MEMORY, "memory.retrieve", {
                     "memory.operation": "retrieve",
                     "memory.store": "redis",
                     "memory.query": args.search || args.messageId || `lastN:${args.lastN ?? "all"}`,
                 });
                 const startTime = Date.now();
+                // args.sessionId is guaranteed non-null here — we returned early above
+                // when it was missing. Cast via string coercion to satisfy eslint.
+                const sessionId = String(args.sessionId);
                 try {
-                    const conversation = await memoryManager.getSessionRaw(args.sessionId);
+                    const conversation = await withTimeout(memoryManager.getSessionRaw(sessionId), 10_000, new Error(`getSessionRaw() timed out for session "${sessionId}"`));
                     if (!conversation) {
                         span.durationMs = Date.now() - startTime;
                         const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
                         getMetricsAggregator().recordSpan(endedSpan);
-                        return { error: "Session not found", sessionId: args.sessionId };
+                        return { error: "Session not found", sessionId };
                     }
                     let messages = conversation.messages;
                     // Filter by specific messageId

package/dist/neurolink.d.ts

@@ -47,6 +47,8 @@ export declare class NeuroLink {
     private mcpToolBatcher?;
     private mcpEnhancedDiscovery?;
     private mcpToolMiddlewares;
+    /** Artifact store for externalized MCP tool outputs (set when strategy=externalize). */
+    private mcpArtifactStore?;
     private _disableToolCacheForCurrentRequest;
     private mcpEnhancementsConfig?;
     private toolCircuitBreakers;