@juspay/neurolink 9.51.3 → 9.52.0

package/dist/lib/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/lib/types/artifactTypes.js

@@ -0,0 +1,11 @@
+/**
+ * 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 {};
+//# sourceMappingURL=artifactTypes.js.map

package/dist/lib/types/configTypes.d.ts

@@ -11,6 +11,7 @@ import type { RoutingStrategy } from "../mcp/routing/index.js";
 import type { CacheStrategy } from "../mcp/caching/index.js";
 import type { ToolMiddleware } from "../mcp/toolIntegration.js";
 import type { MastraAuthProvider, AuthProviderType, AuthProviderConfig, Auth0Config, ClerkConfig, FirebaseConfig, SupabaseConfig, WorkOSConfig, BetterAuthConfig, JWTConfig, OAuth2Config, CognitoConfig, KeycloakConfig, AuthenticatedContext } from "./authTypes.js";
+import type { NeurolinkCredentials } from "./providers.js";
 /**
  * Main NeuroLink configuration type
  */
@@ -39,6 +40,12 @@ export type NeurolinkConstructorConfig = {
     auth?: NeuroLinkAuthConfig;
     /** TaskManager configuration (scheduled and self-running tasks) */
     tasks?: TaskManagerConfig;
+    /**
+     * Per-provider credential overrides.
+     * When set here, applies as the default for all generate()/stream() calls
+     * from this NeuroLink instance. Per-call credentials override these.
+     */
+    credentials?: NeurolinkCredentials;
 };
 /**
  * Configuration for MCP enhancement modules wired into generate()/stream() paths.
@@ -90,6 +97,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/lib/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/lib/types/generateTypes.d.ts

@@ -11,6 +11,7 @@ import type { DirectorModeOptions, DirectorSegment, VideoGenerationResult, Video
 import type { PPTGenerationResult, PPTOutputOptions } from "./pptTypes.js";
 import type { TTSOptions, TTSResult } from "./ttsTypes.js";
 import type { StandardRecord, ValidationSchema, ZodUnknownSchema } from "./typeAliases.js";
+import type { NeurolinkCredentials } from "./providers.js";
 /**
  * Generate function options type - Primary method for content generation
  * Supports multimodal content while maintaining backward compatibility
@@ -424,6 +425,12 @@ export type GenerateOptions = {
     auth?: {
         token: string;
     };
+    /**
+     * Per-provider credential overrides for this request.
+     * Overrides instance-level credentials set in `new NeuroLink({ credentials })`.
+     * Unset providers fall through to instance credentials, then environment variables.
+     */
+    credentials?: NeurolinkCredentials;
     /**
      * Per-call memory control.
      *
@@ -942,6 +949,12 @@ export type TextGenerationOptions = {
         /** Thinking level (Gemini 3: minimal|low|medium|high). Ignored for Anthropic. */
         thinkingLevel?: "minimal" | "low" | "medium" | "high";
     };
+    /**
+     * Per-provider credential overrides for this request.
+     * Overrides instance-level credentials set in `new NeuroLink({ credentials })`.
+     * Unset providers fall through to instance credentials, then environment variables.
+     */
+    credentials?: NeurolinkCredentials;
     /**
      * Optional request identifier for observability and log correlation.
      * When provided, this ID is forwarded to spans, logs, and telemetry so

package/dist/lib/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/lib/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/lib/types/mcpOutputTypes.js

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

package/dist/lib/types/providers.d.ts

@@ -71,6 +71,81 @@ export type AWSCredentialConfig = {
     /** Optional service endpoint override (e.g., VPC/Gov endpoints) */
     endpoint?: string;
 };
+/**
+ * Per-provider credential overrides for generate() / stream() calls.
+ *
+ * When set on `NeurolinkConstructorConfig.credentials`, applies as the default
+ * for all calls from that NeuroLink instance. When set on
+ * `GenerateOptions.credentials` or `StreamOptions.credentials`, overrides the
+ * instance default for that single call.
+ *
+ * Unset providers fall through to environment variables (existing behaviour).
+ */
+export type NeurolinkCredentials = {
+    openai?: {
+        apiKey?: string;
+        baseURL?: string;
+    };
+    anthropic?: {
+        apiKey?: string;
+        oauthToken?: string;
+    };
+    googleAiStudio?: {
+        apiKey?: string;
+    };
+    vertex?: {
+        projectId?: string;
+        location?: string;
+        /** Vertex Express Mode — simplified API-key auth */
+        apiKey?: string;
+        /** Full service-account JSON string */
+        serviceAccountKey?: string;
+        /** Inline service-account fields (alternative to serviceAccountKey) */
+        clientEmail?: string;
+        privateKey?: string;
+    };
+    bedrock?: {
+        accessKeyId?: string;
+        secretAccessKey?: string;
+        sessionToken?: string;
+        region?: string;
+    };
+    sagemaker?: {
+        accessKeyId?: string;
+        secretAccessKey?: string;
+        sessionToken?: string;
+        region?: string;
+        endpoint?: string;
+    };
+    azure?: {
+        apiKey?: string;
+        resourceName?: string;
+        deploymentName?: string;
+        apiVersion?: string;
+    };
+    mistral?: {
+        apiKey?: string;
+    };
+    huggingFace?: {
+        apiKey?: string;
+        baseURL?: string;
+    };
+    openrouter?: {
+        apiKey?: string;
+        baseURL?: string;
+    };
+    litellm?: {
+        apiKey?: string;
+        baseURL?: string;
+    };
+    openaiCompatible?: {
+        apiKey?: string;
+        baseURL?: string;
+    };
+    ollama?: {
+        baseURL?: string;
+    };
+};
 /**
  * AWS Credential Validation Result
  */

package/dist/lib/types/streamTypes.d.ts

@@ -9,7 +9,7 @@ import type { JsonValue, UnknownRecord } from "./common.js";
 import type { Content, ImageWithAltText } from "./content.js";
 import type { ChatMessage } from "./conversation.js";
 import type { AdditionalMemoryUser } from "./generateTypes.js";
-import type { AIModelProviderConfig } from "./providers.js";
+import type { AIModelProviderConfig, NeurolinkCredentials } from "./providers.js";
 import type { TTSChunk, TTSOptions } from "./ttsTypes.js";
 import type { StandardRecord, ValidationSchema } from "./typeAliases.js";
 /**
@@ -444,6 +444,12 @@ export type StreamOptions = {
     auth?: {
         token: string;
     };
+    /**
+     * Per-provider credential overrides for this request.
+     * Overrides instance-level credentials set in `new NeuroLink({ credentials })`.
+     * Unset providers fall through to instance credentials, then environment variables.
+     */
+    credentials?: NeurolinkCredentials;
     /**
      * Per-call memory control.
      *

package/dist/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/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/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/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
      */