@juspay/neurolink 9.51.3 → 9.51.4

package/dist/cli/commands/mcp.d.ts

@@ -67,6 +67,12 @@ export declare class MCPCommandFactory {
      * Execute exec command
      */
     private static executeExec;
+    /**
+     * Run the actual MCP tool execution and format/write the output.
+     * Extracted to keep executeExec nesting within ESLint max-depth limit.
+     * Returns 0 on success, 1 on failure.
+     */
+    private static runExecTool;
     /**
      * Execute remove command
      */

package/dist/cli/commands/mcp.js

@@ -656,104 +656,146 @@ export class MCPCommandFactory {
                 }
             }
             const sdk = new NeuroLink();
-            await this.getMCPStatusWithTimeout(sdk);
-            // Check if server exists and is connected
-            const allServers = await sdk.listMCPServers();
-            const server = allServers.find((s) => s.name === serverName);
-            if (!server) {
-                if (spinner) {
-                    spinner.fail();
-                }
-                logger.error(chalk.red(`❌ Server not found: ${serverName}`));
-                process.exit(1);
-            }
-            if (server.status !== "connected") {
-                if (spinner) {
-                    spinner.fail();
-                }
-                logger.error(chalk.red(`❌ Server not connected: ${serverName}`));
-                logger.always(chalk.yellow("💡 Try: neurolink mcp test " + serverName));
-                process.exit(1);
-            }
-            // Check if tool exists
-            const tool = server.tools?.find((t) => t.name === toolName);
-            if (!tool) {
-                if (spinner) {
-                    spinner.fail();
-                }
-                logger.error(chalk.red(`❌ Tool not found: ${toolName}`));
-                if (server.tools?.length) {
-                    logger.always(chalk.blue("Available tools:"));
-                    server.tools.forEach((t) => {
-                        logger.always(`  • ${t.name}: ${t.description}`);
-                    });
-                }
-                process.exit(1);
-            }
-            // Execute the tool using the NeuroLink MCP tool registry
+            let exitCode = 0;
             try {
-                const { toolRegistry } = await import("../../lib/mcp/toolRegistry.js");
-                const executionResult = await toolRegistry.executeTool(toolName, params, {
-                    sessionId: `cli-${Date.now()}`,
-                    userId: process.env.USER || "cli-user",
-                    config: {
-                        domainType: "cli-execution",
-                        customData: { serverName },
-                    },
-                });
-                const result = {
-                    tool: toolName,
-                    server: serverName,
-                    params,
-                    result: executionResult,
-                    success: true,
-                    timestamp: new Date().toISOString(),
-                };
-                if (spinner) {
-                    spinner.succeed(chalk.green("✅ Tool executed successfully"));
-                }
-                // Display results
-                if (argv.format === "json") {
-                    logger.always(JSON.stringify(result, null, 2));
-                }
-                else {
-                    logger.always(chalk.green("🔧 Tool Execution Results:"));
-                    logger.always(`   Tool: ${chalk.cyan(toolName)}`);
-                    logger.always(`   Server: ${chalk.cyan(serverName)}`);
-                    logger.always(`   Result: ${JSON.stringify(executionResult, null, 2)}`);
-                    logger.always(`   Timestamp: ${result.timestamp}`);
-                }
-            }
-            catch (toolError) {
-                const errorMessage = toolError instanceof Error ? toolError.message : String(toolError);
-                if (spinner) {
-                    spinner.fail(chalk.red("❌ Tool execution failed"));
+                await this.getMCPStatusWithTimeout(sdk);
+                // Check if server exists and is connected
+                const allServers = await sdk.listMCPServers();
+                const server = allServers.find((s) => s.name === serverName);
+                if (!server) {
+                    if (spinner) {
+                        spinner.fail();
+                    }
+                    logger.error(chalk.red(`❌ Server not found: ${serverName}`));
+                    exitCode = 1;
                 }
-                const result = {
-                    tool: toolName,
-                    server: serverName,
-                    params,
-                    _error: errorMessage,
-                    success: false,
-                    timestamp: new Date().toISOString(),
-                };
-                if (argv.format === "json") {
-                    logger.always(JSON.stringify(result, null, 2));
+                else if (server.status !== "connected") {
+                    if (spinner) {
+                        spinner.fail();
+                    }
+                    logger.error(chalk.red(`❌ Server not connected: ${serverName}`));
+                    logger.always(chalk.yellow("💡 Try: neurolink mcp test " + serverName));
+                    exitCode = 1;
                 }
                 else {
-                    logger.error(chalk.red("🔧 Tool Execution Failed:"));
-                    logger.error(`   Tool: ${chalk.cyan(toolName)}`);
-                    logger.error(`   Server: ${chalk.cyan(serverName)}`);
-                    logger.error(`   Error: ${chalk.red(errorMessage)}`);
+                    // Check if tool exists
+                    const tool = server.tools?.find((t) => t.name === toolName);
+                    if (!tool) {
+                        if (spinner) {
+                            spinner.fail();
+                        }
+                        logger.error(chalk.red(`❌ Tool not found: ${toolName}`));
+                        if (server.tools?.length) {
+                            logger.always(chalk.blue("Available tools:"));
+                            server.tools.forEach((t) => {
+                                logger.always(`  • ${t.name}: ${t.description}`);
+                            });
+                        }
+                        exitCode = 1;
+                    }
+                    else {
+                        exitCode = await this.runExecTool(toolName, serverName, params, argv, spinner);
+                    }
                 }
-                process.exit(1);
             }
+            finally {
+                // Always shut down MCP connections to prevent lingering child processes
+                await sdk.shutdown().catch(() => undefined);
+            }
+            // Flush stdout/stderr before exit so buffered output (spinner lines,
+            // result text) is not truncated by process.exit(). process.exit() is
+            // still required because MCP stdio connections and health-check timers
+            // keep the Node.js event loop alive even after sdk.shutdown().
+            await new Promise((resolve) => {
+                process.stdout.write("", () => {
+                    process.stderr.write("", () => resolve());
+                });
+            });
+            process.exit(exitCode);
         }
         catch (_error) {
             logger.error(chalk.red(`❌ Exec command failed: ${_error.message}`));
             process.exit(1);
         }
     }
+    /**
+     * Run the actual MCP tool execution and format/write the output.
+     * Extracted to keep executeExec nesting within ESLint max-depth limit.
+     * Returns 0 on success, 1 on failure.
+     */
+    static async runExecTool(toolName, serverName, params, argv, spinner) {
+        const WARN_BYTES = 50 * 1024; // 50 KB
+        try {
+            const { toolRegistry } = await import("../../lib/mcp/toolRegistry.js");
+            const executionResult = await withTimeout(toolRegistry.executeTool(toolName, params, {
+                sessionId: `cli-${Date.now()}`,
+                userId: process.env.USER || "cli-user",
+                config: { domainType: "cli-execution", customData: { serverName } },
+            }), MCP_STATUS_TIMEOUT_MS, ErrorFactory.toolTimeout(toolName, MCP_STATUS_TIMEOUT_MS));
+            const result = {
+                tool: toolName,
+                server: serverName,
+                params,
+                result: executionResult,
+                success: true,
+                timestamp: new Date().toISOString(),
+            };
+            if (spinner) {
+                spinner.succeed(chalk.green("✅ Tool executed successfully"));
+            }
+            const resultJson = JSON.stringify(result, null, 2);
+            const resultBytes = Buffer.byteLength(resultJson, "utf-8");
+            const outputFile = argv.output;
+            if (outputFile) {
+                await fs.promises.writeFile(outputFile, resultJson, "utf-8");
+                logger.always(chalk.green(`✅ Result saved to: ${chalk.cyan(outputFile)}`));
+                logger.always(`   Size: ${resultBytes >= 1024 ? `${(resultBytes / 1024).toFixed(1)} KB` : `${resultBytes} B`}`);
+            }
+            else if (argv.format === "json") {
+                if (resultBytes > WARN_BYTES) {
+                    logger.warn(chalk.yellow(`⚠  Large result (${(resultBytes / 1024).toFixed(1)} KB). ` +
+                        `Use --output <file> to save to disk instead.`));
+                }
+                logger.always(resultJson);
+            }
+            else {
+                if (resultBytes > WARN_BYTES) {
+                    logger.warn(chalk.yellow(`⚠  Large result (${(resultBytes / 1024).toFixed(1)} KB). ` +
+                        `Use --output <file> to save to disk instead.`));
+                }
+                logger.always(chalk.green("🔧 Tool Execution Results:"));
+                logger.always(`   Tool: ${chalk.cyan(toolName)}`);
+                logger.always(`   Server: ${chalk.cyan(serverName)}`);
+                logger.always(`   Result: ${JSON.stringify(executionResult, null, 2)}`);
+                logger.always(`   Timestamp: ${result.timestamp}`);
+            }
+            return 0;
+        }
+        catch (toolError) {
+            const errorMessage = toolError instanceof Error ? toolError.message : String(toolError);
+            if (spinner) {
+                spinner.fail(chalk.red("❌ Tool execution failed"));
+            }
+            const result = {
+                tool: toolName,
+                server: serverName,
+                params,
+                _error: errorMessage,
+                success: false,
+                timestamp: new Date().toISOString(),
+            };
+            if (argv.format === "json") {
+                logger.always(JSON.stringify(result, null, 2));
+            }
+            else {
+                logger.error(chalk.red("🔧 Tool Execution Failed:"));
+                logger.error(`   Tool: ${chalk.cyan(toolName)}`);
+                logger.error(`   Server: ${chalk.cyan(serverName)}`);
+                logger.error(`   Error: ${chalk.red(errorMessage)}`);
+            }
+            return 1;
+        }
+    }
     /**
      * Execute remove command
      */

package/dist/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/artifacts/artifactStore.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 type { ArtifactMeta, ArtifactRef, ArtifactStore } from "../types/artifactTypes.js";
+export type { ArtifactMeta, ArtifactRef, ArtifactStore, } from "../types/artifactTypes.js";
+/**
+ * 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 declare class LocalTempArtifactStore implements ArtifactStore {
+    private readonly dir;
+    private readonly index;
+    constructor(dir?: string);
+    generatePreview(payload: string): string;
+    store(payload: string, meta: Omit<ArtifactMeta, "createdAt">): Promise<ArtifactRef>;
+    retrieve(id: string): Promise<string | null>;
+    delete(id: string): Promise<void>;
+    cleanup(olderThanMs: number): Promise<number>;
+}

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/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>;
+}