@juspay/neurolink 9.51.3 → 9.51.4

package/dist/neurolink.js

@@ -40,6 +40,8 @@ import { ToolCallBatcher } from "./mcp/batching/index.js";
 import { ToolResultCache } from "./mcp/caching/index.js";
 import { EnhancedToolDiscovery } from "./mcp/enhancedToolDiscovery.js";
 import { ExternalServerManager } from "./mcp/externalServerManager.js";
+import { McpOutputNormalizer, DEFAULT_MAX_MCP_OUTPUT_BYTES, DEFAULT_WARN_MCP_OUTPUT_BYTES, } from "./mcp/mcpOutputNormalizer.js";
+import { LocalTempArtifactStore } from "./artifacts/artifactStore.js";
 import { ToolRouter } from "./mcp/routing/index.js";
 // Import direct tools server for automatic registration
 import { directToolsServer } from "./mcp/servers/agent/directToolsServer.js";
@@ -216,6 +218,8 @@ export class NeuroLink {
     mcpToolBatcher;
     mcpEnhancedDiscovery;
     mcpToolMiddlewares = [];
+    /** Artifact store for externalized MCP tool outputs (set when strategy=externalize). */
+    mcpArtifactStore;
     _disableToolCacheForCurrentRequest = false;
     mcpEnhancementsConfig;
     // Enhanced error handling support
@@ -818,6 +822,25 @@ export class NeuroLink {
             });
         }
         // ToolRouter — lazy-initialized when 2+ external servers exist (see addExternalMCPServer)
+        // McpOutputNormalizer — active when mcp.outputLimits is configured
+        if (mcpConfig?.outputLimits) {
+            const strategy = mcpConfig.outputLimits.strategy ?? "externalize";
+            const maxBytes = mcpConfig.outputLimits.maxBytes ?? DEFAULT_MAX_MCP_OUTPUT_BYTES;
+            const warnBytes = mcpConfig.outputLimits.warnBytes ?? DEFAULT_WARN_MCP_OUTPUT_BYTES;
+            let artifactStore;
+            if (strategy === "externalize") {
+                artifactStore = new LocalTempArtifactStore();
+                this.mcpArtifactStore = artifactStore;
+                logger.debug("[NeuroLink] MCP artifact store initialized (local-temp)");
+            }
+            const normalizer = new McpOutputNormalizer({ strategy, maxBytes, warnBytes }, artifactStore);
+            this.externalServerManager.setOutputNormalizer(normalizer);
+            logger.debug("[NeuroLink] MCP output normalizer initialized", {
+                strategy,
+                maxBytes,
+                warnBytes,
+            });
+        }
     }
     /**
      * Register file reference tools with the MCP tool registry.
@@ -937,90 +960,46 @@ export class NeuroLink {
                 "redis" in memConfig &&
                 !!memConfig.redis) ||
             process.env.STORAGE_TYPE === "redis";
-        if (!memConfig?.enabled || !hasRedisConfig) {
-            logger.debug("[NeuroLink] Skipping memory retrieval tools — requires Redis conversation memory");
+        const hasArtifactStore = !!this.mcpArtifactStore;
+        // Register when Redis is configured OR when an artifact store exists.
+        // Artifact store alone is sufficient for the artifactId retrieval path —
+        // session history retrieval just returns a clear error when Redis is absent.
+        if ((!memConfig?.enabled || !hasRedisConfig) && !hasArtifactStore) {
+            logger.debug("[NeuroLink] Skipping memory retrieval tools — requires Redis conversation memory or an artifact store");
             return;
         }
-        const tools = {
-            retrieve_context: {
-                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.",
-                execute: async (params) => {
-                    // Lazy access: conversationMemory is initialized on first generate() call
-                    const memoryManager = this.conversationMemory;
-                    if (!memoryManager || !("getSessionRaw" in memoryManager)) {
-                        return {
-                            success: false,
-                            error: "Memory retrieval not available — Redis memory manager not initialized",
-                            metadata: {
-                                toolName: "retrieve_context",
-                                serverId: "direct",
-                                executionTime: 0,
-                            },
-                        };
-                    }
-                    const actualTools = createMemoryRetrievalTools(memoryManager);
-                    const result = await actualTools.retrieve_context.execute(params, {
-                        toolCallId: "memory-retrieval",
-                        messages: [],
-                    });
-                    // Check if the tool itself reported an error
-                    const hasError = result &&
-                        typeof result === "object" &&
-                        "error" in result &&
-                        !("messages" in result);
-                    const errorMsg = hasError
-                        ? result.error
-                        : undefined;
-                    return {
-                        success: !hasError,
-                        data: result,
-                        ...(errorMsg ? { error: errorMsg } : {}),
-                        metadata: {
-                            toolName: "retrieve_context",
-                            serverId: "direct",
-                            executionTime: 0,
-                        },
-                    };
-                },
+        // Extract the canonical tool definition (schema + description) from the
+        // memoryRetrievalTools factory. We pass undefined as the memoryManager here
+        // because we only need the Zod inputSchema and description at registration
+        // time — the actual manager is resolved lazily at execution time.
+        const canonicalTools = createMemoryRetrievalTools(undefined, this.mcpArtifactStore);
+        const retrieveContextDef = canonicalTools.retrieve_context;
+        // Register via this.registerTool() so the tool ends up in the "user-defined"
+        // category inside toolRegistry. getCustomTools() returns that category, which
+        // is what ToolsManager reads to build the tool schema sent to the LLM.
+        // (Tools registered via toolRegistry.registerTool() directly land in the
+        // "built-in" category and are never included in the LLM's tool schema.)
+        this.registerTool("retrieve_context", {
+            name: "retrieve_context",
+            description: retrieveContextDef.description ?? "Retrieve context or artifacts",
+            // Pass the Zod schema so ToolsManager gives the LLM full parameter types.
+            // registerTool() detects isZodSchema on inputSchema and preserves it.
+            inputSchema: retrieveContextDef
+                .inputSchema,
+            execute: async (params) => {
+                // Lazy: conversationMemory is initialized on the first generate() call.
+                // When only an artifact store is present (no Redis), memoryManager is
+                // undefined — createMemoryRetrievalTools handles that via an explicit guard.
+                const memoryManager = this.conversationMemory;
+                const tools = createMemoryRetrievalTools(memoryManager, this.mcpArtifactStore);
+                // Return the result directly so the LLM receives clean output instead
+                // of a nested { success, data, metadata } wrapper.
+                // Bounded by TOOL_TIMEOUTS.EXECUTION_DEFAULT_MS so a stalled Redis or
+                // filesystem backend never hangs the tool call indefinitely.
+                return await withTimeout(tools.retrieve_context.execute(params, { toolCallId: "memory-retrieval", messages: [] }), TOOL_TIMEOUTS.EXECUTION_DEFAULT_MS, ErrorFactory.toolTimeout("retrieve_context", TOOL_TIMEOUTS.EXECUTION_DEFAULT_MS));
             },
-        };
-        const registrations = Object.entries(tools).map(async ([toolName, toolDef]) => {
-            const toolId = `direct.${toolName}`;
-            const toolInfo = {
-                name: toolName,
-                description: toolDef.description,
-                inputSchema: {},
-                serverId: "direct",
-                category: "built-in",
-            };
-            await this.toolRegistry.registerTool(toolId, toolInfo, {
-                execute: async (params) => {
-                    try {
-                        return await toolDef.execute(params);
-                    }
-                    catch (error) {
-                        // Known limitation: this non-throwing error path returns
-                        // { success: false } without recording errorCategories in
-                        // toolExecutionMetrics. These are internal memory-tool failures
-                        // (low frequency), so the risk of metric gaps is minimal.
-                        // A full fix would require access to the metrics map here,
-                        // which is not available in the registration closure.
-                        return {
-                            success: false,
-                            error: error instanceof Error ? error.message : String(error),
-                            metadata: { toolName, serverId: "direct", executionTime: 0 },
-                        };
-                    }
-                },
-                description: toolDef.description,
-                inputSchema: {},
-            });
-        });
-        void Promise.all(registrations).then(() => {
-            logger.info("[NeuroLink] Memory retrieval tools registered");
         });
+        logger.info("[NeuroLink] Memory retrieval tools registered");
     }
     /** Format memory context for prompt inclusion */
     formatMemoryContext(memoryContext, currentInput) {

package/dist/session/globalSessionState.js

@@ -1,6 +1,33 @@
 import { nanoid } from "nanoid";
 import { NeuroLink } from "../neurolink.js";
 import { buildObservabilityConfigFromEnv } from "../utils/observabilityHelpers.js";
+/**
+ * Build mcp.outputLimits config from environment variables.
+ * Reads NEUROLINK_MCP_OUTPUT_STRATEGY and NEUROLINK_MCP_MAX_OUTPUT_BYTES.
+ * Returns undefined when neither variable is set (no overhead).
+ */
+function buildMcpOutputLimitsFromEnv() {
+    const strategyRaw = process.env.NEUROLINK_MCP_OUTPUT_STRATEGY;
+    const maxBytesRaw = process.env.NEUROLINK_MCP_MAX_OUTPUT_BYTES;
+    const warnBytesRaw = process.env.NEUROLINK_MCP_WARN_OUTPUT_BYTES;
+    if (!strategyRaw && !maxBytesRaw) {
+        return undefined;
+    }
+    const strategy = strategyRaw === "inline" || strategyRaw === "externalize"
+        ? strategyRaw
+        : "externalize"; // safe default when only maxBytes is set
+    const maxBytes = maxBytesRaw ? parseInt(maxBytesRaw, 10) : undefined;
+    const warnBytes = warnBytesRaw ? parseInt(warnBytesRaw, 10) : undefined;
+    return {
+        strategy,
+        ...(maxBytes !== undefined && Number.isFinite(maxBytes) && maxBytes >= 0
+            ? { maxBytes }
+            : {}),
+        ...(warnBytes !== undefined && Number.isFinite(warnBytes) && warnBytes >= 0
+            ? { warnBytes }
+            : {}),
+    };
+}
 export class GlobalSessionManager {
     static instance;
     loopSession = null;
@@ -25,6 +52,14 @@ export class GlobalSessionManager {
         if (observabilityConfig) {
             neurolinkOptions.observability = observabilityConfig;
         }
+        // Add MCP output limits from environment variables (CLI usage)
+        const mcpOutputLimits = buildMcpOutputLimitsFromEnv();
+        if (mcpOutputLimits) {
+            neurolinkOptions.mcp = {
+                ...neurolinkOptions.mcp,
+                outputLimits: mcpOutputLimits,
+            };
+        }
         this.loopSession = {
             neurolinkInstance: new NeuroLink(neurolinkOptions),
             sessionId,
@@ -99,7 +134,15 @@ export class GlobalSessionManager {
         }
         // Create new NeuroLink with observability config from environment (CLI usage)
         const observabilityConfig = buildObservabilityConfigFromEnv();
-        return new NeuroLink(observabilityConfig ? { observability: observabilityConfig } : undefined);
+        const mcpOutputLimits = buildMcpOutputLimitsFromEnv();
+        const options = {};
+        if (observabilityConfig) {
+            options.observability = observabilityConfig;
+        }
+        if (mcpOutputLimits) {
+            options.mcp = { outputLimits: mcpOutputLimits };
+        }
+        return new NeuroLink(Object.keys(options).length ? options : undefined);
     }
     getCurrentSessionId() {
         return this.getLoopSession()?.sessionId;

package/dist/types/artifactTypes.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Artifact Store Types (canonical location)
+ *
+ * Types for the MCP large-output artifact storage system.
+ * When mcp.outputLimits.strategy = "externalize", oversized MCP tool outputs
+ * are stored as artifacts and the model receives a compact surrogate instead.
+ *
+ * @module types/artifactTypes
+ */
+/** Metadata recorded alongside a stored artifact. */
+export type ArtifactMeta = {
+    /** Tool name that produced the output. */
+    toolName: string;
+    /** MCP server ID. */
+    serverId: string;
+    /** Session that triggered the tool call (optional). */
+    sessionId?: string;
+    /** Serialized byte size of the full payload. */
+    sizeBytes: number;
+    /** Whether the payload is valid JSON or plain text. */
+    contentType: "json" | "text";
+    /** Unix epoch ms when the artifact was created. */
+    createdAt: number;
+};
+/** Lightweight descriptor returned after a successful ArtifactStore.store(). */
+export type ArtifactRef = {
+    /** UUID v4 — stable identifier used in surrogate results and metadata. */
+    id: string;
+    /** First N characters of the payload (for surrogate headers). */
+    preview: string;
+    /** Full serialized byte size. */
+    sizeBytes: number;
+    /** Stored metadata. */
+    meta: ArtifactMeta;
+};
+/**
+ * Pluggable storage contract for externalized MCP tool outputs.
+ *
+ * Default backend: LocalTempArtifactStore (filesystem, single-process).
+ * Future backends can implement this interface for S3, Redis blobs, etc.
+ */
+export interface ArtifactStore {
+    /**
+     * Persist a payload and return a lightweight reference.
+     * @param payload  Serialized tool output (JSON string or plain text).
+     * @param meta     Descriptor without `createdAt` (assigned internally).
+     */
+    store(payload: string, meta: Omit<ArtifactMeta, "createdAt">): Promise<ArtifactRef>;
+    /**
+     * Retrieve the full payload by artifact ID.
+     * Returns `null` if the artifact is not found or has been cleaned up.
+     */
+    retrieve(id: string): Promise<string | null>;
+    /** Delete a single artifact. No-op if the ID does not exist. */
+    delete(id: string): Promise<void>;
+    /**
+     * Delete all artifacts older than `olderThanMs` milliseconds.
+     * Returns the number of artifacts deleted.
+     */
+    cleanup(olderThanMs: number): Promise<number>;
+    /** Generate a short preview string from a serialized payload. */
+    generatePreview(payload: string): string;
+}

package/dist/types/artifactTypes.js

@@ -0,0 +1,10 @@
+/**
+ * Artifact Store Types (canonical location)
+ *
+ * Types for the MCP large-output artifact storage system.
+ * When mcp.outputLimits.strategy = "externalize", oversized MCP tool outputs
+ * are stored as artifacts and the model receives a compact surrogate instead.
+ *
+ * @module types/artifactTypes
+ */
+export {};

package/dist/types/configTypes.d.ts

@@ -90,6 +90,38 @@ export type MCPEnhancementsConfig = {
     };
     /** Global tool middleware applied to every tool execution. Default: empty. */
     middleware?: ToolMiddleware[];
+    /**
+     * Large MCP tool output handling.
+     *
+     * MCP servers can return arbitrarily large payloads. Without limits these
+     * are loaded entirely into memory, cached in full, stored whole in Redis, and
+     * injected into the LLM context window — all of which silently fail at scale.
+     *
+     * When configured, NeuroLink intercepts oversized outputs at the tool boundary
+     * (before caching and before memory persistence) and applies the chosen
+     * strategy so the model receives a compact surrogate instead of a firehose.
+     *
+     * Two strategies:
+     *  - "inline"      Keep sending the full payload to the model regardless of
+     *                  size. A warning is emitted above warnBytes.
+     *  - "externalize" Store the full payload on disk as an artifact and 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.
+     *
+     * Defaults (when `outputLimits` is set):
+     *  strategy  = "externalize"
+     *  maxBytes  = 100 KB (100 * 1024)
+     *  warnBytes =  50 KB  (50 * 1024)
+     */
+    outputLimits?: {
+        /** What to do when output exceeds maxBytes. Default: "externalize". */
+        strategy?: "inline" | "externalize";
+        /** Byte ceiling above which the strategy fires. Default: 102400 (100 KB). */
+        maxBytes?: number;
+        /** Bytes at which a warning is emitted even when still inline. Default: 51200 (50 KB). */
+        warnBytes?: number;
+    };
 };
 /**
  * Authentication configuration for NeuroLink SDK

package/dist/types/conversation.d.ts

@@ -231,6 +231,13 @@ export type ChatMessageMetadata = {
     toolOutputPreview?: string;
     /** Original byte size of the full tool output before any truncation */
     originalSize?: number;
+    /**
+     * Artifact store ID for an externalized MCP tool output.
+     * Set when `mcp.outputLimits.strategy = "externalize"` and the tool output
+     * exceeded `maxBytes`. Use retrieve_context with this ID to fetch the full
+     * payload from the local artifact store.
+     */
+    artifactId?: string;
 };
 /**
  * Chat message format for conversation history

package/dist/types/index.d.ts

@@ -6,6 +6,8 @@ export * from "./cli.js";
 export * from "./common.js";
 export type { AnalyticsConfig, BackupInfo, BackupMetadata, CacheConfig, ConfigUpdateOptions, ConfigValidationResult, FallbackConfig, MCPEnhancementsConfig, NeuroLinkConfig, PerformanceConfig, RetryConfig, ToolConfig, } from "./configTypes.js";
 export type { ExternalMCPConfigValidation, ExternalMCPManagerConfig, ExternalMCPOperationResult, ExternalMCPServerEvents, ExternalMCPServerHealth, ExternalMCPServerInstance, ExternalMCPServerStatus, ExternalMCPToolContext, ExternalMCPToolInfo, ExternalMCPToolResult, } from "./externalMcp.js";
+export type { ArtifactMeta, ArtifactRef, ArtifactStore, } from "./artifactTypes.js";
+export type { McpOutputContext, McpOutputNormalizerConfig, McpOutputStrategy, NormalizedMcpOutput, } from "./mcpOutputTypes.js";
 export type { AuthorizationUrlResult, CircuitBreakerConfig, CircuitBreakerEvents, CircuitBreakerState, CircuitBreakerStats, DiscoveredMcp, ExternalToolExecutionOptions, FlexibleValidationResult, HTTPRetryConfig, MCPClientResult, MCPConnectedServer, MCPDiscoveredServer, MCPExecutableTool, MCPOAuthConfig, MCPServerCategory, MCPServerConfig, MCPServerConnectionStatus, MCPServerInfo, MCPServerMetadata, MCPServerRegistryEntry, MCPServerStatus, MCPStatus, MCPToolInfo, MCPToolMetadata, MCPTransportType, McpMetadata, McpRegistry, NeuroLinkExecutionContext, NeuroLinkMCPServer, NeuroLinkMCPTool, OAuthClientInformation, OAuthTokens as McpOAuthTokens, RateLimitConfig, TokenBucketRateLimitConfig, TokenExchangeRequest, TokenStorage, ToolDiscoveryResult, ToolRegistryEvents, ToolValidationResult, } from "./mcpTypes.js";
 export type { ModelCapability, ModelFilter, ModelPricing, ModelResolutionContext, ModelStats, ModelUseCase, } from "./providers.js";
 export * from "./providers.js";

package/dist/types/mcpOutputTypes.d.ts

@@ -0,0 +1,40 @@
+/**
+ * MCP Output Normalizer Types (canonical location)
+ *
+ * Types for the large MCP response handling system.
+ *
+ * @module types/mcpOutputTypes
+ */
+/**
+ * Two honest strategies for oversized MCP tool outputs:
+ *  - "inline"      Full payload always sent to the model (warning logged above warnBytes).
+ *  - "externalize" Full payload stored as an artifact; model receives a compact
+ *                  surrogate with head/tail preview and an artifact ID it can
+ *                  resolve via retrieve_context with offset/limit pagination.
+ */
+export type McpOutputStrategy = "inline" | "externalize";
+/** Configuration for McpOutputNormalizer. */
+export type McpOutputNormalizerConfig = {
+    strategy: McpOutputStrategy;
+    /** Byte ceiling above which the strategy fires. */
+    maxBytes: number;
+    /** Bytes at which a warning is emitted while still inline. */
+    warnBytes: number;
+};
+/** Contextual info passed alongside the raw MCP callResult. */
+export type McpOutputContext = {
+    toolName: string;
+    serverId: string;
+    sessionId?: string;
+};
+/** Value returned by McpOutputNormalizer.normalize(). */
+export type NormalizedMcpOutput = {
+    /** The result to substitute for the raw callResult. May be a surrogate. */
+    result: unknown;
+    /** Whether the full payload was written to the artifact store. */
+    isExternalized: boolean;
+    /** Artifact ID when isExternalized === true. */
+    artifactId?: string;
+    /** Serialized byte size of the original payload. */
+    originalBytes: number;
+};

package/dist/types/mcpOutputTypes.js

@@ -0,0 +1,8 @@
+/**
+ * MCP Output Normalizer Types (canonical location)
+ *
+ * Types for the large MCP response handling system.
+ *
+ * @module types/mcpOutputTypes
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "9.51.3",
+  "version": "9.51.4",
   "packageManager": "pnpm@10.15.1",
   "description": "Universal AI Development Platform with working MCP integration, multi-provider support, and professional CLI. Built-in tools operational, 58+ external MCP servers discoverable. Connect to filesystem, GitHub, database operations, and more. Build, test, and deploy AI applications with 13 providers: OpenAI, Anthropic, Google AI, AWS Bedrock, Azure, Hugging Face, Ollama, and Mistral AI.",
   "author": {