@juspay/neurolink 9.80.3 → 9.80.4

package/dist/context/stages/structuredSummarizer.js

@@ -17,10 +17,21 @@ function findSplitIndexByTokens(messages, targetRecentTokens, provider) {
     let recentTokens = 0;
     let splitIndex = messages.length;
     for (let i = messages.length - 1; i >= 0; i--) {
-        const content = typeof messages[i].content === "string"
-            ? messages[i].content
-            : JSON.stringify(messages[i].content);
-        const msgTokens = estimateTokens(content, provider);
+        // Guarded: JSON.stringify on a giant single message can throw RangeError
+        // (V8 max string length). A message that big cannot be "recent-window"
+        // material anyway — treat it as effectively infinite tokens so it (and
+        // everything older) lands on the summarized side instead of aborting
+        // compaction.
+        let msgTokens;
+        try {
+            const content = typeof messages[i].content === "string"
+                ? messages[i].content
+                : (JSON.stringify(messages[i].content) ?? "");
+            msgTokens = estimateTokens(content, provider);
+        }
+        catch {
+            msgTokens = Number.MAX_SAFE_INTEGER;
+        }
         if (recentTokens + msgTokens > targetRecentTokens) {
             splitIndex = i + 1;
             break;

package/dist/core/modules/GenerationHandler.js

@@ -21,7 +21,7 @@ import { calculateCost } from "../../utils/pricing.js";
 import { withProviderRetry } from "../../utils/providerRetry.js";
 import { calculateCacheSavingsPercent, extractCacheCreationTokens, extractCacheReadTokens, extractTokenUsage, } from "../../utils/tokenUtils.js";
 import { DEFAULT_MAX_STEPS } from "../constants.js";
-import { isTemperatureDeprecatedError, isToolsSchemaConflictError, isToolsSchemaExclusionInForce, } from "./structuredOutputPolicy.js";
+import { isTemperatureDeprecatedError, isSchemaComplexityError, isToolsSchemaConflictError, isToolsSchemaExclusionInForce, } from "./structuredOutputPolicy.js";
 import { coerceJsonToSchema } from "../../utils/json/coerce.js";
 import { NoObjectGeneratedError } from "../../utils/generationErrors.js";
 import { Output, stepCountIs } from "../../utils/tool.js";
@@ -284,15 +284,20 @@ export class GenerationHandler {
             }
             catch (error) {
                 // Fall back to text-mode (no experimental_output) when structured
-                // output + tools failed, in two cases:
+                // output + tools failed, in three cases:
                 //   1. NoObjectGeneratedError — the SDK couldn't coerce the object.
                 //   2. The provider rejected json-mode-with-tools outright (e.g. Groq:
                 //      "json mode cannot be combined with tool/function calling").
-                // In both cases we retry without structured output and let
+                //   3. The provider rejected the schema as too complex for its
+                //      constrained decoding (Vertex Gemini 400 "too many states") —
+                //      deterministic, so re-sending the schema can never succeed.
+                // In all cases we retry without structured output and let
                 // formatEnhancedResult coerce the text response into valid JSON.
+                const schemaTooComplex = useStructuredOutput && isSchemaComplexityError(error);
                 const isStructuredOutputConflict = useStructuredOutput &&
                     (error instanceof NoObjectGeneratedError ||
-                        isToolsSchemaConflictError(error));
+                        isToolsSchemaConflictError(error) ||
+                        schemaTooComplex);
                 if (isStructuredOutputConflict) {
                     span.setAttribute("neurolink.has_fallback", true);
                     // NLK-GAP-007: Record initial failure event before fallback retry
@@ -301,13 +306,26 @@ export class GenerationHandler {
                         "retry.attempt": 1,
                         "retry.reason": error instanceof NoObjectGeneratedError
                             ? "NoObjectGeneratedError_structured_output_fallback"
-                            : "tools_schema_conflict_structured_output_fallback",
-                    });
-                    logger.debug("[GenerationHandler] structured-output conflict caught - falling back to manual JSON extraction", {
-                        provider: this.providerName,
-                        model: this.modelName,
-                        error: error instanceof Error ? error.message : String(error),
+                            : schemaTooComplex
+                                ? "schema_complexity_structured_output_fallback"
+                                : "tools_schema_conflict_structured_output_fallback",
                     });
+                    if (schemaTooComplex) {
+                        // warn (not debug): callers should simplify their schema — the
+                        // fallback keeps the turn alive but skips native enforcement.
+                        logger.warn("[GenerationHandler] schema too complex for provider constrained decoding — retrying with prompt-based JSON", {
+                            provider: this.providerName,
+                            model: this.modelName,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                    else {
+                        logger.debug("[GenerationHandler] structured-output conflict caught - falling back to manual JSON extraction", {
+                            provider: this.providerName,
+                            model: this.modelName,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
                     // Retry without experimental_output - the formatEnhancedResult method
                     // will extract JSON from the text response
                     const result = await withProviderRetry(() => this.callGenerateText(model, messages, tools, options, shouldUseTools, false), span, "generateText(fallback)");

package/dist/core/modules/structuredOutputPolicy.d.ts

@@ -41,6 +41,25 @@ export declare function isToolsSchemaExclusionInForce(providerName: string, mode
  * and retried without structured output instead of failing the call.
  */
 export declare function isToolsSchemaConflictError(error: unknown): boolean;
+/**
+ * True when a provider error indicates the request was rejected because the
+ * JSON schema is too complex for the provider's constrained decoding. Vertex
+ * Gemini enforces response schemas as a state machine and rejects
+ * "complex" schemas (regex patterns, string min/max lengths, nested array
+ * caps, long enums) with a deterministic 400 INVALID_ARGUMENT:
+ *
+ *   "The specified schema produces a constraint that has too many states
+ *    for serving. Typical causes of this error are schemas with lots of
+ *    text …, schemas with long array length limits …, or schemas using
+ *    complex value matchers …"
+ *
+ * The error arrives wrapped (provider error formatter + upstream JSON
+ * envelope), so match on the distinctive substring. Retrying with the same
+ * schema can never succeed — the correct recovery is to drop native schema
+ * enforcement and coerce the text response into the schema instead
+ * (same flow as isToolsSchemaConflictError).
+ */
+export declare function isSchemaComplexityError(error: unknown): boolean;
 /**
  * True when a provider error indicates the request was rejected because the
  * `temperature` parameter is deprecated / unsupported for the model. The newest

package/dist/core/modules/structuredOutputPolicy.js

@@ -68,6 +68,32 @@ export function isToolsSchemaConflictError(error) {
         /(tool|function)[\s-]?call[^.]{0,60}json[\s_-]?(mode|schema)/i.test(message) ||
         /response_format[^.]{0,60}(tool|function)/i.test(message));
 }
+/**
+ * True when a provider error indicates the request was rejected because the
+ * JSON schema is too complex for the provider's constrained decoding. Vertex
+ * Gemini enforces response schemas as a state machine and rejects
+ * "complex" schemas (regex patterns, string min/max lengths, nested array
+ * caps, long enums) with a deterministic 400 INVALID_ARGUMENT:
+ *
+ *   "The specified schema produces a constraint that has too many states
+ *    for serving. Typical causes of this error are schemas with lots of
+ *    text …, schemas with long array length limits …, or schemas using
+ *    complex value matchers …"
+ *
+ * The error arrives wrapped (provider error formatter + upstream JSON
+ * envelope), so match on the distinctive substring. Retrying with the same
+ * schema can never succeed — the correct recovery is to drop native schema
+ * enforcement and coerce the text response into the schema instead
+ * (same flow as isToolsSchemaConflictError).
+ */
+export function isSchemaComplexityError(error) {
+    const message = error instanceof Error
+        ? error.message
+        : typeof error === "string"
+            ? error
+            : "";
+    return /too many states/i.test(message);
+}
 /**
  * True when a provider error indicates the request was rejected because the
  * `temperature` parameter is deprecated / unsupported for the model. The newest

package/dist/lib/context/stages/structuredSummarizer.js

@@ -17,10 +17,21 @@ function findSplitIndexByTokens(messages, targetRecentTokens, provider) {
     let recentTokens = 0;
     let splitIndex = messages.length;
     for (let i = messages.length - 1; i >= 0; i--) {
-        const content = typeof messages[i].content === "string"
-            ? messages[i].content
-            : JSON.stringify(messages[i].content);
-        const msgTokens = estimateTokens(content, provider);
+        // Guarded: JSON.stringify on a giant single message can throw RangeError
+        // (V8 max string length). A message that big cannot be "recent-window"
+        // material anyway — treat it as effectively infinite tokens so it (and
+        // everything older) lands on the summarized side instead of aborting
+        // compaction.
+        let msgTokens;
+        try {
+            const content = typeof messages[i].content === "string"
+                ? messages[i].content
+                : (JSON.stringify(messages[i].content) ?? "");
+            msgTokens = estimateTokens(content, provider);
+        }
+        catch {
+            msgTokens = Number.MAX_SAFE_INTEGER;
+        }
         if (recentTokens + msgTokens > targetRecentTokens) {
             splitIndex = i + 1;
             break;

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

@@ -21,7 +21,7 @@ import { calculateCost } from "../../utils/pricing.js";
 import { withProviderRetry } from "../../utils/providerRetry.js";
 import { calculateCacheSavingsPercent, extractCacheCreationTokens, extractCacheReadTokens, extractTokenUsage, } from "../../utils/tokenUtils.js";
 import { DEFAULT_MAX_STEPS } from "../constants.js";
-import { isTemperatureDeprecatedError, isToolsSchemaConflictError, isToolsSchemaExclusionInForce, } from "./structuredOutputPolicy.js";
+import { isTemperatureDeprecatedError, isSchemaComplexityError, isToolsSchemaConflictError, isToolsSchemaExclusionInForce, } from "./structuredOutputPolicy.js";
 import { coerceJsonToSchema } from "../../utils/json/coerce.js";
 import { NoObjectGeneratedError } from "../../utils/generationErrors.js";
 import { Output, stepCountIs } from "../../utils/tool.js";
@@ -284,15 +284,20 @@ export class GenerationHandler {
             }
             catch (error) {
                 // Fall back to text-mode (no experimental_output) when structured
-                // output + tools failed, in two cases:
+                // output + tools failed, in three cases:
                 //   1. NoObjectGeneratedError — the SDK couldn't coerce the object.
                 //   2. The provider rejected json-mode-with-tools outright (e.g. Groq:
                 //      "json mode cannot be combined with tool/function calling").
-                // In both cases we retry without structured output and let
+                //   3. The provider rejected the schema as too complex for its
+                //      constrained decoding (Vertex Gemini 400 "too many states") —
+                //      deterministic, so re-sending the schema can never succeed.
+                // In all cases we retry without structured output and let
                 // formatEnhancedResult coerce the text response into valid JSON.
+                const schemaTooComplex = useStructuredOutput && isSchemaComplexityError(error);
                 const isStructuredOutputConflict = useStructuredOutput &&
                     (error instanceof NoObjectGeneratedError ||
-                        isToolsSchemaConflictError(error));
+                        isToolsSchemaConflictError(error) ||
+                        schemaTooComplex);
                 if (isStructuredOutputConflict) {
                     span.setAttribute("neurolink.has_fallback", true);
                     // NLK-GAP-007: Record initial failure event before fallback retry
@@ -301,13 +306,26 @@ export class GenerationHandler {
                         "retry.attempt": 1,
                         "retry.reason": error instanceof NoObjectGeneratedError
                             ? "NoObjectGeneratedError_structured_output_fallback"
-                            : "tools_schema_conflict_structured_output_fallback",
-                    });
-                    logger.debug("[GenerationHandler] structured-output conflict caught - falling back to manual JSON extraction", {
-                        provider: this.providerName,
-                        model: this.modelName,
-                        error: error instanceof Error ? error.message : String(error),
+                            : schemaTooComplex
+                                ? "schema_complexity_structured_output_fallback"
+                                : "tools_schema_conflict_structured_output_fallback",
                     });
+                    if (schemaTooComplex) {
+                        // warn (not debug): callers should simplify their schema — the
+                        // fallback keeps the turn alive but skips native enforcement.
+                        logger.warn("[GenerationHandler] schema too complex for provider constrained decoding — retrying with prompt-based JSON", {
+                            provider: this.providerName,
+                            model: this.modelName,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                    else {
+                        logger.debug("[GenerationHandler] structured-output conflict caught - falling back to manual JSON extraction", {
+                            provider: this.providerName,
+                            model: this.modelName,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
                     // Retry without experimental_output - the formatEnhancedResult method
                     // will extract JSON from the text response
                     const result = await withProviderRetry(() => this.callGenerateText(model, messages, tools, options, shouldUseTools, false), span, "generateText(fallback)");

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

@@ -41,6 +41,25 @@ export declare function isToolsSchemaExclusionInForce(providerName: string, mode
  * and retried without structured output instead of failing the call.
  */
 export declare function isToolsSchemaConflictError(error: unknown): boolean;
+/**
+ * True when a provider error indicates the request was rejected because the
+ * JSON schema is too complex for the provider's constrained decoding. Vertex
+ * Gemini enforces response schemas as a state machine and rejects
+ * "complex" schemas (regex patterns, string min/max lengths, nested array
+ * caps, long enums) with a deterministic 400 INVALID_ARGUMENT:
+ *
+ *   "The specified schema produces a constraint that has too many states
+ *    for serving. Typical causes of this error are schemas with lots of
+ *    text …, schemas with long array length limits …, or schemas using
+ *    complex value matchers …"
+ *
+ * The error arrives wrapped (provider error formatter + upstream JSON
+ * envelope), so match on the distinctive substring. Retrying with the same
+ * schema can never succeed — the correct recovery is to drop native schema
+ * enforcement and coerce the text response into the schema instead
+ * (same flow as isToolsSchemaConflictError).
+ */
+export declare function isSchemaComplexityError(error: unknown): boolean;
 /**
  * True when a provider error indicates the request was rejected because the
  * `temperature` parameter is deprecated / unsupported for the model. The newest

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

@@ -68,6 +68,32 @@ export function isToolsSchemaConflictError(error) {
         /(tool|function)[\s-]?call[^.]{0,60}json[\s_-]?(mode|schema)/i.test(message) ||
         /response_format[^.]{0,60}(tool|function)/i.test(message));
 }
+/**
+ * True when a provider error indicates the request was rejected because the
+ * JSON schema is too complex for the provider's constrained decoding. Vertex
+ * Gemini enforces response schemas as a state machine and rejects
+ * "complex" schemas (regex patterns, string min/max lengths, nested array
+ * caps, long enums) with a deterministic 400 INVALID_ARGUMENT:
+ *
+ *   "The specified schema produces a constraint that has too many states
+ *    for serving. Typical causes of this error are schemas with lots of
+ *    text …, schemas with long array length limits …, or schemas using
+ *    complex value matchers …"
+ *
+ * The error arrives wrapped (provider error formatter + upstream JSON
+ * envelope), so match on the distinctive substring. Retrying with the same
+ * schema can never succeed — the correct recovery is to drop native schema
+ * enforcement and coerce the text response into the schema instead
+ * (same flow as isToolsSchemaConflictError).
+ */
+export function isSchemaComplexityError(error) {
+    const message = error instanceof Error
+        ? error.message
+        : typeof error === "string"
+            ? error
+            : "";
+    return /too many states/i.test(message);
+}
 /**
  * True when a provider error indicates the request was rejected because the
  * `temperature` parameter is deprecated / unsupported for the model. The newest

package/dist/lib/mcp/externalServerManager.js

@@ -348,7 +348,9 @@ export class ExternalServerManager extends EventEmitter {
                 }
                 catch (error) {
                     const errorMsg = `Failed to load MCP server ${serverId}: ${error instanceof Error ? error.message : String(error)}`;
-                    mcpLogger.warn(`[ExternalServerManager] ${errorMsg}`);
+                    // No log here: the result-processing loop below owns the single
+                    // ERROR record for this failure (logging in both places
+                    // double-counted every parallel-load failure).
                     return { serverId, error: errorMsg };
                 }
             });
@@ -366,11 +368,16 @@ export class ExternalServerManager extends EventEmitter {
                     }
                     else if (error) {
                         errors.push(error);
+                        // Config-loaded servers never pass through
+                        // NeuroLink.addExternalMCPServer, so this is the outermost point
+                        // for them — it owns the single ERROR record per failed server.
+                        mcpLogger.error(`[ExternalServerManager] Failed to load server ${serverId}: ${error}`);
                     }
                     else if (serverResult && !serverResult.success) {
                         const errorMsg = `Failed to load server ${serverId}: ${serverResult.error}`;
                         errors.push(errorMsg);
-                        mcpLogger.warn(`[ExternalServerManager] ${errorMsg}`);
+                        // See above: outermost point for config-loaded servers.
+                        mcpLogger.error(`[ExternalServerManager] ${errorMsg}`);
                     }
                 }
                 else {
@@ -482,13 +489,17 @@ export class ExternalServerManager extends EventEmitter {
                     else {
                         const error = `Failed to load server ${serverId}: ${result.error}`;
                         errors.push(error);
-                        mcpLogger.warn(`[ExternalServerManager] ${error}`);
+                        // Config-loaded servers never pass through
+                        // NeuroLink.addExternalMCPServer — this sequential-load branch is
+                        // their outermost point and owns the single ERROR record.
+                        mcpLogger.error(`[ExternalServerManager] ${error}`);
                     }
                 }
                 catch (error) {
                     const errorMsg = `Failed to load MCP server ${serverId}: ${error instanceof Error ? error.message : String(error)}`;
                     errors.push(errorMsg);
-                    mcpLogger.warn(`[ExternalServerManager] ${errorMsg}`);
+                    // See above: outermost point for config-loaded servers.
+                    mcpLogger.error(`[ExternalServerManager] ${errorMsg}`);
                     // Continue with other servers - don't let one failure break everything
                 }
             }
@@ -708,7 +719,9 @@ export class ExternalServerManager extends EventEmitter {
             };
         }
         catch (error) {
-            mcpLogger.error(`[ExternalServerManager] Failed to add server ${serverId}:`, error);
+            // debug, not error: NeuroLink.addExternalMCPServer (the public entry
+            // point) emits the single ERROR record for a failed registration.
+            mcpLogger.debug(`[ExternalServerManager] Failed to add server ${serverId}:`, error);
             // Clean up if instance was created
             this.servers.delete(serverId);
             return {
@@ -851,7 +864,9 @@ export class ExternalServerManager extends EventEmitter {
             mcpLogger.info(`[ExternalServerManager] Server started successfully: ${serverId}`);
         }
         catch (error) {
-            mcpLogger.error(`[ExternalServerManager] Failed to start server ${serverId}:`, error);
+            // debug, not error: the failure is rethrown below and surfaces once at
+            // the NeuroLink.addExternalMCPServer entry point.
+            mcpLogger.debug(`[ExternalServerManager] Failed to start server ${serverId}:`, error);
             this.updateServerStatus(serverId, "failed");
             instance.lastError =
                 error instanceof Error ? error.message : String(error);

package/dist/lib/mcp/mcpClientFactory.js

@@ -142,7 +142,11 @@ export class MCPClientFactory {
                     duration: Date.now() - startTime,
                 };
             }
-            mcpLogger.error(`[MCPClientFactory] Failed to create client for ${config.id}:`, error);
+            // debug, not error: this failure propagates up through
+            // ExternalServerManager to NeuroLink.addExternalMCPServer, which emits
+            // the single ERROR record. Logging at every layer turned one failed
+            // server registration into 5 ERROR lines in production.
+            mcpLogger.debug(`[MCPClientFactory] Failed to create client for ${config.id}:`, error);
             obsSpan.durationMs = Date.now() - startTime;
             const endedObsSpan = SpanSerializer.endSpan(obsSpan, SpanStatus.ERROR);
             endedObsSpan.statusMessage = errorMessage;

package/dist/lib/neurolink.js

@@ -72,6 +72,7 @@ import { coerceJsonToSchema } from "./utils/json/coerce.js";
 // Factory processing imports
 import { createCleanStreamOptions, enhanceTextGenerationOptions, processFactoryOptions, processStreamingFactoryOptions, validateFactoryConfig, } from "./utils/factoryProcessing.js";
 import { logger, mcpLogger } from "./utils/logger.js";
+import { redactUrlCredentials, safeDebugSerialize, sanitizeRecord, stringifyContentSafe, } from "./utils/logSanitize.js";
 import { extractMcpErrorText } from "./utils/mcpErrorText.js";
 import { createCustomToolServerInfo, detectCategory, } from "./utils/mcpDefaults.js";
 import { resolveModel } from "./utils/modelAliasResolver.js";
@@ -2156,9 +2157,7 @@ Current user's request: ${currentInput}`;
         const anyOptions = optionsOrPrompt;
         if (anyOptions.messages && anyOptions.messages.length > 0) {
             const lastMessage = anyOptions.messages[anyOptions.messages.length - 1];
-            return typeof lastMessage.content === "string"
-                ? lastMessage.content
-                : JSON.stringify(lastMessage.content);
+            return stringifyContentSafe(lastMessage.content);
         }
         // Handle input.text format
         return optionsOrPrompt.input?.text || "";
@@ -3879,9 +3878,7 @@ Current user's request: ${currentInput}`;
                 ?.filter((m) => m.role === "user" || m.role === "assistant")
                 .map((m) => ({
                 role: m.role,
-                content: typeof m.content === "string"
-                    ? m.content
-                    : JSON.stringify(m.content),
+                content: stringifyContentSafe(m.content),
             })) ??
                 options.conversationHistory,
             timeout: options.timeout,
@@ -3978,9 +3975,7 @@ Current user's request: ${currentInput}`;
                 ?.filter((m) => m.role === "user" || m.role === "assistant")
                 .map((m) => ({
                 role: m.role,
-                content: typeof m.content === "string"
-                    ? m.content
-                    : JSON.stringify(m.content),
+                content: stringifyContentSafe(m.content),
             })) ??
                 options.conversationHistory,
             timeout: options.timeout,
@@ -4603,6 +4598,11 @@ Current user's request: ${currentInput}`;
      */
     async performMCPGenerationRetries(options, generateInternalId, generateInternalStartTime, generateInternalHrTimeStart, functionTag) {
         const maxMcpRetries = RETRY_ATTEMPTS.QUICK;
+        // Captured BEFORE the first attempt: ensureMCPGenerationBudget (inside
+        // tryMCPGeneration) auto-scales options.timeout for >100K-token contexts
+        // when the caller left it unset, so checking options.timeout inside the
+        // catch below could not tell caller-set apart from auto-scaled.
+        const callerSetTimeout = options.timeout !== undefined;
         // NL-007: Track retry metadata for observability
         const retryErrors = [];
         let retryCount = 0;
@@ -4645,6 +4645,20 @@ Current user's request: ${currentInput}`;
                     logger.debug(`[${functionTag}] AbortError detected on attempt ${attempt}, stopping retries`);
                     throw error;
                 }
+                // A TimeoutError against an explicit caller-set options.timeout is
+                // deterministic-by-construction: every remaining retry AND the
+                // direct-generation fallback would re-run the same provider+model
+                // under the same per-step budget. Observed in production as ~650s
+                // of doomed follow-ups after a 90s step timeout. Surface it now.
+                // Name check (not instanceof): two TimeoutError classes exist
+                // (utils/timeout.ts and utils/async/withTimeout.ts) and both stamp
+                // name = "TimeoutError".
+                if (callerSetTimeout &&
+                    error instanceof Error &&
+                    error.name === "TimeoutError") {
+                    logger.warn(`[${functionTag}] Per-step timeout (${String(options.timeout)}) exhausted on attempt ${attempt} — surfacing instead of retrying with the same budget`);
+                    throw error;
+                }
                 // NL-007: Record retry error for observability
                 retryCount++;
                 const errMsg = error instanceof Error ? error.message : String(error);
@@ -7220,11 +7234,18 @@ Current user's request: ${currentInput}`;
      */
     async storeStreamConversationMemory(params) {
         const { enhancedOptions, providerName, originalPrompt, accumulatedContent, startTime, eventSequence, } = params;
-        logger.debug("[NeuroLink.stream] Preparing to store conversation turn in memory", {
-            options: JSON.stringify(enhancedOptions),
-            sessionId: enhancedOptions.context
-                ?.sessionId,
-        });
+        // Logger Guard: the full options object (history + tool outputs) can be
+        // enormous — an eager JSON.stringify here threw RangeError: Invalid
+        // string length in production and killed the turn. Serialize lazily,
+        // bounded, and only when debug is actually enabled; sanitizeRecord
+        // redacts credentials/PII keys before anything reaches the sink.
+        if (logger.shouldLog("debug")) {
+            logger.debug("[NeuroLink.stream] Preparing to store conversation turn in memory", {
+                options: safeDebugSerialize(sanitizeRecord(enhancedOptions)),
+                sessionId: enhancedOptions.context
+                    ?.sessionId,
+            });
+        }
         // Guard: skip storing if no meaningful content was produced (no text AND no tool activity)
         const hasToolEvents = eventSequence.some((e) => e.type === "tool:start" || e.type === "tool:end");
         if (!accumulatedContent.trim() && !hasToolEvents) {
@@ -7234,12 +7255,16 @@ Current user's request: ${currentInput}`;
             });
             return;
         }
-        logger.debug("[NeuroLink.stream] Storing conversation turn in memory", {
-            options: JSON.stringify(enhancedOptions),
-            sessionId: enhancedOptions.context
-                ?.sessionId,
-            conversationMemoryExists: this.conversationMemory ? true : false,
-        });
+        // Logger Guard: see the matching block above — never eagerly stringify
+        // the full options object, and always redact before serializing.
+        if (logger.shouldLog("debug")) {
+            logger.debug("[NeuroLink.stream] Storing conversation turn in memory", {
+                options: safeDebugSerialize(sanitizeRecord(enhancedOptions)),
+                sessionId: enhancedOptions.context
+                    ?.sessionId,
+                conversationMemoryExists: this.conversationMemory ? true : false,
+            });
+        }
         // Store memory after stream consumption is complete
         if (this.conversationMemory && enhancedOptions.context?.sessionId) {
             const sessionId = enhancedOptions.context
@@ -8703,11 +8728,7 @@ Current user's request: ${currentInput}`;
             : this.getCustomTools().has(toolName)
                 ? "custom"
                 : "external";
-        const inputStr = typeof params === "string"
-            ? params
-            : params
-                ? JSON.stringify(params)
-                : "";
+        const inputStr = params ? stringifyContentSafe(params) : "";
         const executionStartTime = Date.now();
         // Per-invocation id so consumers can correlate a tool:start with its matching
         // tool:end even when the same tool runs multiple times concurrently.
@@ -10271,8 +10292,15 @@ Current user's request: ${currentInput}`;
                 });
             }
             else {
+                // Single ERROR record for a failed registration — the inner layers
+                // (client factory, server manager) log at debug so one root cause no
+                // longer fans out into 5 ERROR lines. Carry enough context here to
+                // diagnose without the inner lines.
                 mcpLogger.error(`[NeuroLink] Failed to add external MCP server: ${serverId}`, {
                     error: result.error,
+                    transport: config.transport,
+                    command: config.command,
+                    url: config.url ? redactUrlCredentials(config.url) : undefined,
                 });
             }
             return result;
@@ -10304,6 +10332,11 @@ Current user's request: ${currentInput}`;
                     timestamp: Date.now(),
                 });
             }
+            else if (result.error?.includes("not found")) {
+                // Expected no-op: consumers commonly call remove as cleanup after a
+                // failed add, when the server never registered. Not an error.
+                mcpLogger.debug(`[NeuroLink] Remove skipped — external MCP server not registered: ${serverId}`);
+            }
             else {
                 mcpLogger.error(`[NeuroLink] Failed to remove external MCP server: ${serverId}`, {
                     error: result.error,