@juspay/neurolink 9.51.2 → 9.51.4

package/dist/lib/artifacts/artifactStore.js

@@ -0,0 +1,144 @@
+/**
+ * Artifact Store
+ *
+ * Pluggable storage for externalized MCP tool outputs.
+ *
+ * When `mcp.outputLimits.strategy = "externalize"` the full tool payload is
+ * written here instead of being sent inline to the LLM. The model receives a
+ * compact surrogate with a preview and an artifact ID. The full payload can be
+ * retrieved on demand via the `retrieve_context` tool.
+ *
+ * Architecture:
+ *   ArtifactStore (interface) — canonical types in src/lib/types/artifactTypes.ts
+ *   LocalTempArtifactStore   — single-process, filesystem-backed implementation
+ *
+ * Distributed backends (S3, Redis blobs) can be added later by implementing
+ * ArtifactStore from types/artifactTypes.ts.
+ *
+ * @module artifacts/artifactStore
+ */
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { logger } from "../utils/logger.js";
+// ---------------------------------------------------------------------------
+// LocalTempArtifactStore
+// ---------------------------------------------------------------------------
+/** Characters used for the quick preview embedded in surrogate results. */
+const DEFAULT_PREVIEW_CHARS = 500;
+/**
+ * Filesystem-backed artifact store using the OS temp directory.
+ *
+ * Files are written with mode 0o600 (owner read/write only).
+ * An in-memory index tracks metadata without a separate index file.
+ *
+ * Suitable for:
+ *  - CLI usage
+ *  - Single-process SDK deployments
+ *  - Multi-process deployments where each process manages its own artifacts
+ *    (artifacts created in one process are not visible to others)
+ *
+ * @example
+ * ```typescript
+ * const store = new LocalTempArtifactStore();
+ * const ref = await store.store(largeJson, {
+ *   toolName: "list_files",
+ *   serverId: "filesystem-server",
+ *   sizeBytes: Buffer.byteLength(largeJson),
+ *   contentType: "json",
+ * });
+ * // Later, via retrieve_context:
+ * const full = await store.retrieve(ref.id);
+ * ```
+ */
+export class LocalTempArtifactStore {
+    dir;
+    index = new Map();
+    constructor(dir) {
+        this.dir = dir ?? join(tmpdir(), "neurolink-artifacts");
+    }
+    generatePreview(payload) {
+        if (payload.length <= DEFAULT_PREVIEW_CHARS) {
+            return payload;
+        }
+        return `${payload.slice(0, DEFAULT_PREVIEW_CHARS)}…`;
+    }
+    async store(payload, meta) {
+        await mkdir(this.dir, { recursive: true, mode: 0o700 });
+        const id = randomUUID();
+        const ext = meta.contentType === "json" ? ".json" : ".txt";
+        const filePath = join(this.dir, `${id}${ext}`);
+        await writeFile(filePath, payload, { encoding: "utf-8", mode: 0o600 });
+        const fullMeta = {
+            ...meta,
+            createdAt: Date.now(),
+            path: filePath,
+        };
+        this.index.set(id, fullMeta);
+        logger.debug(`[ArtifactStore] Stored artifact ${id} for tool "${meta.toolName}" ` +
+            `(${formatBytes(meta.sizeBytes)})`);
+        return {
+            id,
+            preview: this.generatePreview(payload),
+            sizeBytes: meta.sizeBytes,
+            meta: { ...meta, createdAt: fullMeta.createdAt },
+        };
+    }
+    async retrieve(id) {
+        const entry = this.index.get(id);
+        if (!entry) {
+            logger.debug(`[ArtifactStore] Artifact ${id} not in index`);
+            return null;
+        }
+        try {
+            const content = await readFile(entry.path, "utf-8");
+            logger.debug(`[ArtifactStore] Retrieved artifact ${id} (${formatBytes(entry.sizeBytes)})`);
+            return content;
+        }
+        catch (err) {
+            logger.warn(`[ArtifactStore] Failed to read artifact ${id}: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    async delete(id) {
+        const entry = this.index.get(id);
+        if (!entry) {
+            return;
+        }
+        try {
+            await rm(entry.path, { force: true });
+        }
+        catch {
+            // Suppress — file may already be gone
+        }
+        this.index.delete(id);
+    }
+    async cleanup(olderThanMs) {
+        const cutoff = Date.now() - olderThanMs;
+        let count = 0;
+        for (const [id, entry] of this.index.entries()) {
+            if (entry.createdAt < cutoff) {
+                await this.delete(id);
+                count++;
+            }
+        }
+        if (count > 0) {
+            logger.debug(`[ArtifactStore] Cleaned up ${count} expired artifact(s)`);
+        }
+        return count;
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+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`;
+}
+//# sourceMappingURL=artifactStore.js.map

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

@@ -31,6 +31,16 @@ export declare class ToolsManager {
     protected sessionId?: string;
     protected userId?: string;
     constructor(providerName: AIProviderName, directTools: Record<string, unknown>, neurolink?: NeuroLink | undefined, utilities?: ToolUtilities | undefined);
+    /**
+     * BZ-666: Wrap tool execute with output truncation to prevent
+     * context overflow when large results flow into the AI SDK accumulator.
+     */
+    private wrapExecuteWithTruncation;
+    /**
+     * BZ-666: Apply generateToolOutputPreview to tool results to prevent
+     * context overflow when large results flow into the AI SDK accumulator.
+     */
+    private truncateToolResult;
     /**
      * Set session context for MCP tools
      */

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

@@ -22,6 +22,7 @@ import { SpanStatusCode } from "@opentelemetry/api";
 import { logger } from "../../utils/logger.js";
 import { getKeyCount } from "../../utils/transformationUtils.js";
 import { convertJsonSchemaToZod } from "../../utils/schemaConversion.js";
+import { generateToolOutputPreview } from "../../context/toolOutputLimits.js";
 /**
  * ToolsManager class - Handles all tool management operations
  */
@@ -44,6 +45,79 @@ export class ToolsManager {
         this.utilities = utilities;
         this.mcpTools = {};
     }
+    /**
+     * BZ-666: Wrap tool execute with output truncation to prevent
+     * context overflow when large results flow into the AI SDK accumulator.
+     */
+    wrapExecuteWithTruncation(toolName, originalExecute) {
+        return async (params) => {
+            const result = await originalExecute(params);
+            return this.truncateToolResult(toolName, result);
+        };
+    }
+    /**
+     * BZ-666: Apply generateToolOutputPreview to tool results to prevent
+     * context overflow when large results flow into the AI SDK accumulator.
+     */
+    truncateToolResult(toolName, result) {
+        if (result === null || result === undefined) {
+            return result;
+        }
+        // Handle string results directly
+        if (typeof result === "string") {
+            const { preview, truncated, originalSize } = generateToolOutputPreview(result);
+            if (truncated) {
+                logger.debug(`[ToolsManager] Truncated '${toolName}' string output: ${originalSize} bytes → ${Buffer.byteLength(preview, "utf-8")} bytes`);
+            }
+            return truncated ? preview : result;
+        }
+        // Handle object results (e.g. readFile returns { content, ... })
+        if (typeof result === "object") {
+            const obj = result;
+            let nextObj = null;
+            // Truncate "content" if present and oversized
+            if (typeof obj.content === "string") {
+                const { preview, truncated, originalSize } = generateToolOutputPreview(obj.content);
+                if (truncated) {
+                    logger.debug(`[ToolsManager] Truncated '${toolName}' content field: ${originalSize} bytes → ${Buffer.byteLength(preview, "utf-8")} bytes`);
+                    nextObj = { ...(nextObj ?? obj), content: preview };
+                }
+            }
+            // Truncate "data" if present and oversized — both fields can coexist
+            if (typeof obj.data === "string") {
+                const { preview, truncated, originalSize } = generateToolOutputPreview(obj.data);
+                if (truncated) {
+                    logger.debug(`[ToolsManager] Truncated '${toolName}' data field: ${originalSize} bytes → ${Buffer.byteLength(preview, "utf-8")} bytes`);
+                    nextObj = { ...(nextObj ?? obj), data: preview };
+                }
+            }
+            if (nextObj) {
+                return nextObj;
+            }
+            // For other objects, check if their JSON serialization is too large.
+            // Use UTF-8 byte length, not string length, to match the 50KB budget.
+            try {
+                const jsonStr = JSON.stringify(result);
+                if (Buffer.byteLength(jsonStr, "utf-8") > 51_200) {
+                    const { preview, truncated, originalSize } = generateToolOutputPreview(jsonStr);
+                    if (truncated) {
+                        logger.debug(`[ToolsManager] Truncated '${toolName}' JSON output: ${originalSize} bytes → ${Buffer.byteLength(preview, "utf-8")} bytes`);
+                        // Preserve object shape so callers reading structured fields don't
+                        // get a type surprise. Attach the preview under a sentinel field.
+                        return {
+                            _truncated: true,
+                            _originalSize: originalSize,
+                            _preview: preview,
+                        };
+                    }
+                }
+            }
+            catch {
+                // JSON serialization failed — return as-is
+            }
+        }
+        return result;
+    }
     /**
      * Set session context for MCP tools
      */
@@ -179,14 +253,15 @@ export class ToolsManager {
                 typeof directTool === "object" &&
                 "execute" in directTool) {
                 const originalExecute = directTool.execute;
-                // Create a new tool with wrapped execute function
+                // Create a new tool with wrapped execute function (BZ-666/BZ-664 guards applied)
+                const guardedExecute = this.wrapExecuteWithTruncation(toolName, originalExecute);
                 tools[toolName] = {
                     ...directTool,
                     execute: async (params) => {
                         const startTime = Date.now();
                         this.emitToolEvent("tool:start", toolName, { input: params });
                         try {
-                            const result = await originalExecute(params);
+                            const result = await guardedExecute(params);
                             this.emitToolEvent("tool:end", toolName, {
                                 result,
                                 success: true,
@@ -228,6 +303,12 @@ export class ToolsManager {
             if (toolInfo && typeof toolInfo.execute === "function") {
                 const tool = await this.createCustomToolFromDefinition(toolName, toolInfo);
                 if (tool && !tools[toolName]) {
+                    // BZ-666/BZ-664: Wrap custom tool execute with guards
+                    const origExec = tool.execute;
+                    if (origExec) {
+                        const guarded = this.wrapExecuteWithTruncation(toolName, origExec);
+                        tool.execute = guarded;
+                    }
                     tools[toolName] = tool;
                 }
             }
@@ -444,47 +525,42 @@ export class ToolsManager {
                     ? this.utilities.createPermissiveZodSchema()
                     : z.object({});
             }
+            // BZ-666/BZ-664: Wrap the raw MCP execute with guards before event wrapping
+            const rawExecute = async (params) => {
+                if (this.neurolink &&
+                    typeof this.neurolink.executeExternalMCPTool === "function") {
+                    return this.neurolink.executeExternalMCPTool(tool.serverId || "unknown", tool.name, params);
+                }
+                throw new Error(`Cannot execute external MCP tool: NeuroLink executeExternalMCPTool not available`);
+            };
+            const guardedExecute = this.wrapExecuteWithTruncation(tool.name, rawExecute);
             return createAISDKTool({
                 description: tool.description || `External MCP tool ${tool.name}`,
                 inputSchema: finalSchema, // AI SDK v6 uses inputSchema (not parameters)
                 execute: async (params) => {
                     const startTime = Date.now();
                     this.emitToolEvent("tool:start", tool.name, { input: params });
-                    // Execute via NeuroLink's direct tool execution
-                    if (this.neurolink &&
-                        typeof this.neurolink.executeExternalMCPTool === "function") {
-                        try {
-                            const result = await this.neurolink.executeExternalMCPTool(tool.serverId || "unknown", tool.name, params);
-                            this.emitToolEvent("tool:end", tool.name, {
-                                result,
-                                success: true,
-                                responseTime: Date.now() - startTime,
-                            });
-                            return result;
-                        }
-                        catch (mcpError) {
-                            const errorMsg = mcpError instanceof Error ? mcpError.message : String(mcpError);
-                            this.emitToolEvent("tool:end", tool.name, {
-                                error: errorMsg,
-                                success: false,
-                                responseTime: Date.now() - startTime,
-                            });
-                            logger.error(`External MCP tool failed: ${tool.name}`, {
-                                serverId: tool.serverId,
-                                error: errorMsg,
-                            });
-                            throw mcpError;
-                        }
+                    try {
+                        const result = await guardedExecute(params);
+                        this.emitToolEvent("tool:end", tool.name, {
+                            result,
+                            success: true,
+                            responseTime: Date.now() - startTime,
+                        });
+                        return result;
                     }
-                    else {
-                        const error = `Cannot execute external MCP tool: NeuroLink executeExternalMCPTool not available`;
+                    catch (mcpError) {
+                        const errorMsg = mcpError instanceof Error ? mcpError.message : String(mcpError);
                         this.emitToolEvent("tool:end", tool.name, {
-                            error,
+                            error: errorMsg,
                             success: false,
                             responseTime: Date.now() - startTime,
                         });
-                        logger.error(error);
-                        throw new Error(error);
+                        logger.error(`External MCP tool failed: ${tool.name}`, {
+                            serverId: tool.serverId,
+                            error: errorMsg,
+                        });
+                        throw mcpError;
                     }
                 },
             });

package/dist/lib/core/redisConversationMemoryManager.js

@@ -7,6 +7,7 @@ import { tracers } from "../telemetry/tracers.js";
 import { randomUUID } from "crypto";
 import { MESSAGES_PER_TURN } from "../config/conversationMemory.js";
 import { generateToolOutputPreview } from "../context/toolOutputLimits.js";
+import { NEUROLINK_ARTIFACT_ID_KEY } from "../mcp/mcpOutputNormalizer.js";
 import { SummarizationEngine } from "../context/summarizationEngine.js";
 import { NeuroLink } from "../neurolink.js";
 import { ConversationMemoryError } from "../types/conversation.js";
@@ -1320,11 +1321,30 @@ User message: "${userMessage}"`;
                     maxBytes: this.config?.contextCompaction?.maxToolOutputBytes,
                     maxLines: this.config?.contextCompaction?.maxToolOutputLines,
                 });
+                // Extract artifact ID if this result was externalized by McpOutputNormalizer.
+                // The surrogate carries `_meta.neurolinkArtifactId` on the raw result object.
+                let artifactId;
+                try {
+                    const rawResult = toolResult.result;
+                    if (rawResult && typeof rawResult === "object") {
+                        const meta = rawResult._meta;
+                        if (meta && typeof meta === "object") {
+                            const idValue = meta[NEUROLINK_ARTIFACT_ID_KEY];
+                            if (typeof idValue === "string") {
+                                artifactId = idValue;
+                            }
+                        }
+                    }
+                }
+                catch {
+                    // Ignore extraction errors — artifact ID is best-effort metadata
+                }
                 // Build metadata — only store preview when truncation occurred (no duplication)
                 const metadata = {
                     truncated,
                     ...(truncated && { toolOutputPreview: preview }),
                     ...(truncated && { originalSize }),
+                    ...(artifactId && { artifactId }),
                 };
                 // Build result — success/error metadata only, NOT the output data
                 const result = {

package/dist/lib/mcp/externalServerManager.d.ts

@@ -27,6 +27,12 @@ export declare class ExternalServerManager extends EventEmitter {
     constructor(config?: ExternalMCPManagerConfig, options?: {
         enableMainRegistryIntegration?: boolean;
     });
+    /**
+     * Attach a McpOutputNormalizer to the underlying ToolDiscoveryService.
+     * All tool outputs will be measured and (if oversized) replaced with compact
+     * surrogates before being returned to callers.
+     */
+    setOutputNormalizer(normalizer: import("./mcpOutputNormalizer.js").McpOutputNormalizer): void;
     /**
      * Set HITL manager for human-in-the-loop safety mechanisms
      * @param hitlManager - HITL manager instance (optional, can be undefined to disable)

package/dist/lib/mcp/externalServerManager.js

@@ -210,6 +210,15 @@ export class ExternalServerManager extends EventEmitter {
         process.on("SIGTERM", () => this.shutdown());
         process.on("beforeExit", () => this.shutdown());
     }
+    /**
+     * Attach a McpOutputNormalizer to the underlying ToolDiscoveryService.
+     * All tool outputs will be measured and (if oversized) replaced with compact
+     * surrogates before being returned to callers.
+     */
+    setOutputNormalizer(normalizer) {
+        this.toolDiscovery.setOutputNormalizer(normalizer);
+        mcpLogger.debug("[ExternalServerManager] MCP output normalizer attached to ToolDiscoveryService");
+    }
     /**
      * Set HITL manager for human-in-the-loop safety mechanisms
      * @param hitlManager - HITL manager instance (optional, can be undefined to disable)

package/dist/lib/mcp/mcpOutputNormalizer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 type { ArtifactStore } from "../artifacts/artifactStore.js";
+import type { McpOutputNormalizerConfig, McpOutputContext, NormalizedMcpOutput } from "../types/mcpOutputTypes.js";
+export type { McpOutputStrategy, McpOutputNormalizerConfig, McpOutputContext, NormalizedMcpOutput, } from "../types/mcpOutputTypes.js";
+/** Default byte ceiling above which externalize fires (100 KB). */
+export declare const DEFAULT_MAX_MCP_OUTPUT_BYTES: number;
+/** Default byte threshold for emitting a warning while still inline (50 KB). */
+export declare const DEFAULT_WARN_MCP_OUTPUT_BYTES: number;
+/** Metadata key embedded in surrogate `_meta` and used by memory manager. */
+export declare const NEUROLINK_ARTIFACT_ID_KEY = "neurolinkArtifactId";
+/**
+ * Stateless normalizer (state lives in the injected ArtifactStore).
+ *
+ * Construct once per NeuroLink instance and set via
+ * `ToolDiscoveryService.setOutputNormalizer()`.
+ */
+export declare class McpOutputNormalizer {
+    private readonly config;
+    private readonly artifactStore?;
+    constructor(config: McpOutputNormalizerConfig, artifactStore?: ArtifactStore | undefined);
+    /**
+     * 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.
+     */
+    normalize(callResult: unknown, context: McpOutputContext): Promise<NormalizedMcpOutput>;
+}

package/dist/lib/mcp/mcpOutputNormalizer.js

@@ -0,0 +1,182 @@
+/**
+ * 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`;
+}
+//# sourceMappingURL=mcpOutputNormalizer.js.map