@juspay/neurolink 9.80.3 → 9.80.4

package/dist/lib/providers/googleVertex.js

@@ -7,6 +7,8 @@ import { AIProviderName, ErrorCategory, ErrorSeverity, } from "../constants/enum
 import { BaseProvider } from "../core/baseProvider.js";
 import { DEFAULT_GEMINI_STREAM_TIMEOUT_MS, DEFAULT_MAX_STEPS, DEFAULT_TOOL_MAX_RETRIES, GLOBAL_LOCATION_MODELS, IMAGE_GENERATION_MODELS, TOOL_STORAGE_TIMEOUT_MS, } from "../core/constants.js";
 import { ModelConfigurationManager } from "../core/modelConfiguration.js";
+import { isSchemaComplexityError } from "../core/modules/structuredOutputPolicy.js";
+import { stringifyContentSafe } from "../utils/logSanitize.js";
 import { createProxyFetch } from "../proxy/proxyFetch.js";
 import { AuthenticationError, InvalidModelError, NetworkError, ProviderError, RateLimitError, } from "../types/index.js";
 import { ERROR_CODES, NeuroLinkError } from "../utils/errorHandling.js";
@@ -2351,7 +2353,25 @@ export class GoogleVertexProvider extends BaseProvider {
                         wasAborted = true;
                         break;
                     }
-                    logger.error("[GoogleVertex] Native SDK generate error", error);
+                    logger.error("[GoogleVertex] Native SDK generate error", {
+                        error,
+                        model: modelName,
+                        location: effectiveLocation,
+                        status: error?.status,
+                    });
+                    // Best-effort request context for formatProviderError —
+                    // this.modelName can be stale when options.model overrides the
+                    // instance default.
+                    try {
+                        if (error && typeof error === "object") {
+                            const e = error;
+                            e.requestModel = modelName;
+                            e.requestRegion = effectiveLocation;
+                        }
+                    }
+                    catch {
+                        /* frozen/sealed error — context stays best-effort */
+                    }
                     throw this.handleProviderError(error);
                 }
             }
@@ -2585,9 +2605,7 @@ export class GoogleVertexProvider extends BaseProvider {
                 if (msg.role === "user" || msg.role === "assistant") {
                     messages.push({
                         role: msg.role,
-                        content: typeof msg.content === "string"
-                            ? msg.content
-                            : JSON.stringify(msg.content),
+                        content: stringifyContentSafe(msg.content),
                     });
                 }
             }
@@ -3190,7 +3208,7 @@ export class GoogleVertexProvider extends BaseProvider {
                                 // so coerce defensively to keep the follow-up turn valid.
                                 const resultContent = typeof result === "string"
                                     ? result
-                                    : (JSON.stringify(result ?? null) ?? String(result));
+                                    : stringifyContentSafe(result ?? null);
                                 toolResults.push({
                                     type: "tool_result",
                                     tool_use_id: toolUse.id,
@@ -3651,9 +3669,7 @@ export class GoogleVertexProvider extends BaseProvider {
                 if (msg.role === "user" || msg.role === "assistant") {
                     messages.push({
                         role: msg.role,
-                        content: typeof msg.content === "string"
-                            ? msg.content
-                            : JSON.stringify(msg.content),
+                        content: stringifyContentSafe(msg.content),
                     });
                 }
             }
@@ -4032,7 +4048,7 @@ export class GoogleVertexProvider extends BaseProvider {
                             // so coerce defensively to keep the follow-up turn valid.
                             const resultContent = typeof result === "string"
                                 ? result
-                                : (JSON.stringify(result ?? null) ?? String(result));
+                                : stringifyContentSafe(result ?? null);
                             toolResults.push({
                                 type: "tool_result",
                                 tool_use_id: toolUse.id,
@@ -4158,7 +4174,22 @@ export class GoogleVertexProvider extends BaseProvider {
                     wasAborted = true;
                     break;
                 }
-                logger.error("[GoogleVertex] Native Anthropic SDK generate error", error);
+                logger.error("[GoogleVertex] Native Anthropic SDK generate error", {
+                    error,
+                    model: modelName,
+                    step,
+                    status: error?.status,
+                });
+                // Best-effort request context for formatProviderError — see the
+                // native Gemini catch for rationale.
+                try {
+                    if (error && typeof error === "object") {
+                        error.requestModel = modelName;
+                    }
+                }
+                catch {
+                    /* frozen/sealed error — context stays best-effort */
+                }
                 throw this.handleProviderError(error);
             }
         }
@@ -4622,8 +4653,49 @@ export class GoogleVertexProvider extends BaseProvider {
                             model: modelName,
                             totalToolCount: Object.keys(mergedOptions.tools).length,
                         });
-                        nativeResult =
-                            await this.executeNativeGemini3Generate(mergedOptions);
+                        try {
+                            nativeResult =
+                                await this.executeNativeGemini3Generate(mergedOptions);
+                        }
+                        catch (nativeError) {
+                            // Vertex rejects over-constrained responseSchemas with a
+                            // deterministic 400 ("too many states" — constrained-decoding
+                            // state explosion). Re-sending the same schema can never
+                            // succeed, so retry ONCE with the schema dropped but JSON
+                            // mode kept: output.format "json" still sets
+                            // responseMimeType application/json on the no-tools path,
+                            // so the model is forced to emit JSON — just without the
+                            // offending schema constraints. The NeuroLink layer then
+                            // coerces the JSON text into the caller's original schema
+                            // (generate({schema}) guarantee holds).
+                            const requestedStructured = mergedOptions.schema !== undefined ||
+                                mergedOptions.output?.format === "json";
+                            // Tools present → the executor skips responseMimeType, so a
+                            // schema-less retry would NOT actually run in JSON mode and
+                            // the structured-output contract would silently degrade to
+                            // prose. Only the no-tools case retries faithfully; with
+                            // tools, surface the 400 to the caller instead.
+                            const hasTools = !mergedOptions.disableTools &&
+                                Object.keys(mergedOptions.tools ?? {}).length > 0;
+                            if (requestedStructured &&
+                                !hasTools &&
+                                isSchemaComplexityError(nativeError)) {
+                                logger.warn("[GoogleVertex] responseSchema too complex for constrained decoding — retrying native generate in schema-less JSON mode", {
+                                    model: modelName,
+                                    error: nativeError instanceof Error
+                                        ? nativeError.message
+                                        : String(nativeError),
+                                });
+                                nativeResult = await this.executeNativeGemini3Generate({
+                                    ...mergedOptions,
+                                    schema: undefined,
+                                    output: { format: "json" },
+                                });
+                            }
+                            else {
+                                throw nativeError;
+                            }
+                        }
                     }
                     executionSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_OUTPUT, spanJsonAttribute(nativeResult?.content ?? ""));
                     return nativeResult;
@@ -4960,17 +5032,42 @@ export class GoogleVertexProvider extends BaseProvider {
                 `3. Ensure your project has access to the model ` +
                 `4. For Claude models, enable Anthropic integration in Google Cloud Console`, this.providerName);
         }
-        // Rate limit and quota errors
+        // Rate limit / quota / capacity errors. Anthropic-on-Vertex capacity
+        // exhaustion surfaces as overloaded_error (HTTP 529) — same operational
+        // meaning as a 429, so classify it here instead of the generic 5xx branch.
         if (message.includes("QUOTA_EXCEEDED") ||
             message.includes("RATE_LIMIT_EXCEEDED") ||
             message.includes("rate limit") ||
             message.includes("429") ||
-            statusCode === 429) {
-            return new RateLimitError(`Google Vertex AI quota/rate limit exceeded. ` +
-                `Solutions: 1. Check your Vertex AI quotas in Google Cloud Console ` +
-                `2. Request quota increase if needed ` +
-                `3. Try a different model or reduce request frequency ` +
-                `4. Consider using a different region`, this.providerName);
+            statusCode === 429 ||
+            statusCode === 529 ||
+            /overloaded/i.test(message)) {
+            // Surface retry guidance when the SDK error carries it. @google/genai
+            // ApiError nests RetryInfo inside the JSON error body's details array,
+            // so fall back to scraping retryDelay out of the raw message.
+            const retryDelay = typeof errorRecord?.retryDelay === "string"
+                ? errorRecord.retryDelay
+                : (/["']?retryDelay["']?\s*[:=]\s*["']?(\d+(?:\.\d+)?s)/.exec(message)?.[1] ?? undefined);
+            // Prefer the per-request context the native catches attach to the
+            // error (this.modelName can be stale when options.model overrides the
+            // instance default). Gemini models are force-routed to the "global"
+            // endpoint regardless of configured location — report the region the
+            // request actually hit.
+            const requestModel = typeof errorRecord?.requestModel === "string"
+                ? errorRecord.requestModel
+                : this.modelName;
+            const effectiveRegion = typeof errorRecord?.requestRegion === "string"
+                ? errorRecord.requestRegion
+                : resolveVertexRegionForModel(requestModel, this.location);
+            return new RateLimitError(`Google Vertex AI rate limit / shared-capacity exhausted (429 RESOURCE_EXHAUSTED / overloaded) ` +
+                `for model '${requestModel}' in region '${effectiveRegion}'.` +
+                (retryDelay
+                    ? ` Upstream suggests retrying after ${retryDelay}.`
+                    : "") +
+                ` Solutions: 1. Retry with backoff ` +
+                `2. Check your Vertex AI quotas in Google Cloud Console (shared-capacity 429s can occur below quota) ` +
+                `3. Try a different region or model ` +
+                `4. Request provisioned throughput for sustained load`, this.providerName);
         }
         // Network connectivity errors
         if (message.includes("ECONNRESET") ||

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

@@ -296,6 +296,19 @@ export type GenerateOptions = {
      * ```
      */
     enabledToolNames?: string[];
+    /**
+     * Request timeout (e.g. 30000, '30s', '2m').
+     *
+     * PER-STEP semantics in agentic loops: on providers that run a native
+     * multi-step tool loop (Vertex Gemini / Vertex Claude), this bounds EACH
+     * model call in the loop, not the whole turn — a tool-heavy turn may run
+     * far longer than this value in total. Size it for the slowest single
+     * step (default 300s), and use `abortSignal` for a total-turn deadline.
+     *
+     * When set explicitly, a step timeout is surfaced immediately instead of
+     * burning internal retries/fallbacks that would re-run the same
+     * provider+model with the same doomed budget.
+     */
     timeout?: number | string;
     /** AbortSignal for external cancellation of the AI call */
     abortSignal?: AbortSignal;

package/dist/lib/utils/conversationMemory.js

@@ -5,6 +5,7 @@
 import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
 import { tracers } from "../telemetry/tracers.js";
 import { withTimeout } from "./errorHandling.js";
+import { safeDebugSerialize, sanitizeRecord } from "./logSanitize.js";
 import { DEFAULT_FALLBACK_THRESHOLD, getConversationMemoryDefaults, MEMORY_THRESHOLD_PERCENTAGE, } from "../config/conversationMemory.js";
 import { getAvailableInputTokens } from "../constants/contextWindows.js";
 import { buildSummarizationPrompt } from "../context/prompts/summarizationPrompt.js";
@@ -106,20 +107,30 @@ export function applyConversationMemoryDefaults(userConfig) {
  * Get conversation history as message array, summarizing if needed.
  */
 export async function getConversationMessages(conversationMemory, options) {
-    logger.debug("[conversationMemoryUtils] getConversationMessages called", {
-        hasMemory: !!conversationMemory,
-        memoryType: conversationMemory?.constructor?.name || "NONE",
-        hasContext: !!options.context,
-        enableSummarization: options.enableSummarization ?? false,
-        options: JSON.stringify(options, null, 2),
-    });
+    // Logger Guard: options carries the full conversation history + tool
+    // outputs; eager JSON.stringify of it can throw RangeError: Invalid string
+    // length and abort the turn. Serialize lazily, bounded, never-throwing,
+    // and redacted (sanitizeRecord strips credential/PII keys).
+    if (logger.shouldLog("debug")) {
+        logger.debug("[conversationMemoryUtils] getConversationMessages called", {
+            hasMemory: !!conversationMemory,
+            memoryType: conversationMemory?.constructor?.name || "NONE",
+            hasContext: !!options.context,
+            enableSummarization: options.enableSummarization ?? false,
+            options: safeDebugSerialize(sanitizeRecord(options)),
+        });
+    }
     if (!conversationMemory || !options.context) {
         logger.warn("[conversationMemoryUtils] No memory or context, returning empty messages", {
             hasMemory: !!conversationMemory,
             memoryType: conversationMemory?.constructor?.name || "NONE",
             hasContext: !!options.context,
             enableSummarization: options.enableSummarization ?? false,
-            options: JSON.stringify(options, null, 2),
+            // The options dump is debug-grade detail — don't pay for (or leak)
+            // the serialization on every memory-disabled call at warn level.
+            ...(logger.shouldLog("debug")
+                ? { options: safeDebugSerialize(sanitizeRecord(options)) }
+                : {}),
         });
         return [];
     }

package/dist/lib/utils/logSanitize.d.ts

@@ -26,6 +26,32 @@
  * @param maxLen - Maximum number of characters to keep (default 500).
  */
 export declare function sanitizeForLog(text: string, maxLen?: number): string;
+/**
+ * Stringify non-string message/tool content without ever throwing.
+ * JSON.stringify on a giant multimodal/tool-result payload can exceed V8's
+ * maximum string length and throw `RangeError: Invalid string length` — a
+ * generation turn must degrade to a placeholder, not abort, when that
+ * happens. Shared by the SDK core and providers (single source of truth).
+ */
+export declare function stringifyContentSafe(content: unknown): string;
+/**
+ * Serialize an arbitrary value for a debug log without ever throwing or
+ * producing an unbounded string.
+ *
+ * `JSON.stringify` on a full options object (conversation history + tool
+ * outputs) can exceed V8's maximum string length and throw
+ * `RangeError: Invalid string length`, which — when evaluated eagerly inside
+ * a logger call — aborts the surrounding generation turn (observed in
+ * production). This helper caps the output and converts any stringify
+ * failure (RangeError, circular structure, BigInt, …) into a placeholder.
+ *
+ * Callers MUST still gate on `logger.shouldLog("debug")` per the Logger
+ * Guard rule — this helper makes serialization safe, not free.
+ *
+ * @param value  - Arbitrary value to serialize.
+ * @param maxLen - Maximum number of characters to keep (default 10 000).
+ */
+export declare function safeDebugSerialize(value: unknown, maxLen?: number): string;
 /**
  * Strip embedded `user:pass@` credentials from a URL's authority component
  * before logging it or surfacing it in a user-facing error.

package/dist/lib/utils/logSanitize.js

@@ -74,6 +74,13 @@ const SENSITIVE_OBJECT_KEYS = [
     "oauth",
     "oauthToken",
     "credentials",
+    "authContext",
+    "authToken",
+    "sessionToken",
+    "serviceAccountKey",
+    "secretAccessKey",
+    // PII, not a secret — but it has no business in debug log dumps.
+    "userEmail",
 ];
 /**
  * Truncate `text` to `maxLen` chars then replace embedded secrets with `***`.
@@ -91,6 +98,55 @@ export function sanitizeForLog(text, maxLen = 500) {
     }
     return text.slice(0, maxLen).replace(SECRET_PATTERN, "***");
 }
+/**
+ * Stringify non-string message/tool content without ever throwing.
+ * JSON.stringify on a giant multimodal/tool-result payload can exceed V8's
+ * maximum string length and throw `RangeError: Invalid string length` — a
+ * generation turn must degrade to a placeholder, not abort, when that
+ * happens. Shared by the SDK core and providers (single source of truth).
+ */
+export function stringifyContentSafe(content) {
+    if (typeof content === "string") {
+        return content;
+    }
+    try {
+        return JSON.stringify(content) ?? String(content);
+    }
+    catch {
+        return "[content too large to serialize]";
+    }
+}
+/**
+ * Serialize an arbitrary value for a debug log without ever throwing or
+ * producing an unbounded string.
+ *
+ * `JSON.stringify` on a full options object (conversation history + tool
+ * outputs) can exceed V8's maximum string length and throw
+ * `RangeError: Invalid string length`, which — when evaluated eagerly inside
+ * a logger call — aborts the surrounding generation turn (observed in
+ * production). This helper caps the output and converts any stringify
+ * failure (RangeError, circular structure, BigInt, …) into a placeholder.
+ *
+ * Callers MUST still gate on `logger.shouldLog("debug")` per the Logger
+ * Guard rule — this helper makes serialization safe, not free.
+ *
+ * @param value  - Arbitrary value to serialize.
+ * @param maxLen - Maximum number of characters to keep (default 10 000).
+ */
+export function safeDebugSerialize(value, maxLen = 10_000) {
+    try {
+        const json = JSON.stringify(value);
+        if (json === undefined) {
+            return String(value);
+        }
+        return json.length > maxLen
+            ? `${json.slice(0, maxLen)}…[truncated ${json.length - maxLen} chars]`
+            : json;
+    }
+    catch (error) {
+        return `[unserializable: ${error instanceof Error ? error.message : String(error)}]`;
+    }
+}
 /**
  * Strip embedded `user:pass@` credentials from a URL's authority component
  * before logging it or surfacing it in a user-facing error.

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