@juspay/neurolink 9.80.3 → 9.81.0

package/dist/cli/loop/optionsSchema.js

@@ -49,6 +49,22 @@ export const textGenerationOptionsSchema = {
         type: "number",
         description: "Timeout for the generation request in milliseconds.",
     },
+    turnTimeoutMs: {
+        type: "number",
+        description: "Wall-clock cap for the whole agentic turn in milliseconds (all steps + tool executions).",
+    },
+    stallTimeoutMs: {
+        type: "number",
+        description: "Maximum time with no progress (no chunk, no tool activity) before the turn ends as stalled, in milliseconds.",
+    },
+    wrapupTimeLeadMs: {
+        type: "number",
+        description: "Remaining-turn-time threshold that triggers a wrap-up nudge to the model, in milliseconds.",
+    },
+    toolTimeoutMs: {
+        type: "number",
+        description: "Per-tool-execution timeout in milliseconds (default 300000). A timed-out tool fails that step; the turn continues.",
+    },
     disableTools: {
         type: "boolean",
         description: "Disable all tool usage for the AI.",

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/analytics.js

@@ -18,6 +18,15 @@ export function createAnalytics(provider, model, result, responseTime, context)
         const tokens = extractTokenUsage(result);
         // Estimate cost based on provider and tokens
         const cost = estimateCost(provider, model, tokens);
+        // Turn-lifecycle telemetry from native agentic loops (Vertex
+        // Gemini/Claude): stopReason / rawFinishReason / stepsUsed ride the
+        // provider result; toolCallCount and elapsedMs derive from it.
+        const turnResult = result;
+        const toolCallCount = Array.isArray(turnResult.toolExecutions)
+            ? turnResult.toolExecutions.length
+            : Array.isArray(turnResult.toolsUsed)
+                ? turnResult.toolsUsed.length
+                : undefined;
         const analytics = {
             provider,
             model,
@@ -26,6 +35,19 @@ export function createAnalytics(provider, model, result, responseTime, context)
             requestDuration: responseTime,
             context: context,
             timestamp: new Date().toISOString(),
+            ...(typeof turnResult.stepsUsed === "number" && {
+                stepsUsed: turnResult.stepsUsed,
+            }),
+            ...(toolCallCount !== undefined && { toolCallCount }),
+            ...(typeof turnResult.stopReason === "string" && {
+                stopReason: turnResult.stopReason,
+            }),
+            ...(typeof turnResult.responseTime === "number" && {
+                elapsedMs: turnResult.responseTime,
+            }),
+            ...(typeof turnResult.rawFinishReason === "string" && {
+                rawFinishReason: turnResult.rawFinishReason,
+            }),
         };
         logger.debug(`[${functionTag}] Analytics created`, {
             provider,

package/dist/core/constants.d.ts

@@ -23,6 +23,19 @@ export declare const DEFAULT_MAX_STEPS = 200;
 export declare const DEFAULT_TOOL_MAX_RETRIES = 2;
 /** Defensive wall-clock ceiling for a native Gemini-3 agentic turn (generate + stream). */
 export declare const DEFAULT_GEMINI_STREAM_TIMEOUT_MS = 300000;
+/**
+ * Default per-tool-execution timeout for native agentic loops. A tool that
+ * exceeds it fails with an error tool_result and costs one step — the turn
+ * continues instead of hanging on a wedged tool. Override per call with
+ * `toolTimeoutMs`.
+ */
+export declare const DEFAULT_TOOL_EXECUTION_TIMEOUT_MS = 300000;
+/**
+ * Default wrap-up lead applied when `turnTimeoutMs` is set but
+ * `wrapupTimeLeadMs` is not: with less than this much turn time remaining,
+ * a wrap-up nudge rides the next tool-result turn.
+ */
+export declare const DEFAULT_WRAPUP_TIME_LEAD_MS = 120000;
 export declare const TOOL_STORAGE_TIMEOUT_MS = 5000;
 export declare const STEP_LIMITS: {
     min: number;

package/dist/core/constants.js

@@ -109,6 +109,19 @@ export const DEFAULT_MAX_STEPS = 200;
 export const DEFAULT_TOOL_MAX_RETRIES = 2; // Maximum retries per tool before permanently failing
 /** Defensive wall-clock ceiling for a native Gemini-3 agentic turn (generate + stream). */
 export const DEFAULT_GEMINI_STREAM_TIMEOUT_MS = 300_000;
+/**
+ * Default per-tool-execution timeout for native agentic loops. A tool that
+ * exceeds it fails with an error tool_result and costs one step — the turn
+ * continues instead of hanging on a wedged tool. Override per call with
+ * `toolTimeoutMs`.
+ */
+export const DEFAULT_TOOL_EXECUTION_TIMEOUT_MS = 300_000;
+/**
+ * Default wrap-up lead applied when `turnTimeoutMs` is set but
+ * `wrapupTimeLeadMs` is not: with less than this much turn time remaining,
+ * a wrap-up nudge rides the next tool-result turn.
+ */
+export const DEFAULT_WRAPUP_TIME_LEAD_MS = 120_000;
 // Fire-and-forget tool storage writes (Redis). 5s is generous for a single
 // Redis write; if breached, the .catch logs a warning.
 export const TOOL_STORAGE_TIMEOUT_MS = 5000;

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/analytics.js

@@ -18,6 +18,15 @@ export function createAnalytics(provider, model, result, responseTime, context)
         const tokens = extractTokenUsage(result);
         // Estimate cost based on provider and tokens
         const cost = estimateCost(provider, model, tokens);
+        // Turn-lifecycle telemetry from native agentic loops (Vertex
+        // Gemini/Claude): stopReason / rawFinishReason / stepsUsed ride the
+        // provider result; toolCallCount and elapsedMs derive from it.
+        const turnResult = result;
+        const toolCallCount = Array.isArray(turnResult.toolExecutions)
+            ? turnResult.toolExecutions.length
+            : Array.isArray(turnResult.toolsUsed)
+                ? turnResult.toolsUsed.length
+                : undefined;
         const analytics = {
             provider,
             model,
@@ -26,6 +35,19 @@ export function createAnalytics(provider, model, result, responseTime, context)
             requestDuration: responseTime,
             context: context,
             timestamp: new Date().toISOString(),
+            ...(typeof turnResult.stepsUsed === "number" && {
+                stepsUsed: turnResult.stepsUsed,
+            }),
+            ...(toolCallCount !== undefined && { toolCallCount }),
+            ...(typeof turnResult.stopReason === "string" && {
+                stopReason: turnResult.stopReason,
+            }),
+            ...(typeof turnResult.responseTime === "number" && {
+                elapsedMs: turnResult.responseTime,
+            }),
+            ...(typeof turnResult.rawFinishReason === "string" && {
+                rawFinishReason: turnResult.rawFinishReason,
+            }),
         };
         logger.debug(`[${functionTag}] Analytics created`, {
             provider,

package/dist/lib/core/constants.d.ts

@@ -23,6 +23,19 @@ export declare const DEFAULT_MAX_STEPS = 200;
 export declare const DEFAULT_TOOL_MAX_RETRIES = 2;
 /** Defensive wall-clock ceiling for a native Gemini-3 agentic turn (generate + stream). */
 export declare const DEFAULT_GEMINI_STREAM_TIMEOUT_MS = 300000;
+/**
+ * Default per-tool-execution timeout for native agentic loops. A tool that
+ * exceeds it fails with an error tool_result and costs one step — the turn
+ * continues instead of hanging on a wedged tool. Override per call with
+ * `toolTimeoutMs`.
+ */
+export declare const DEFAULT_TOOL_EXECUTION_TIMEOUT_MS = 300000;
+/**
+ * Default wrap-up lead applied when `turnTimeoutMs` is set but
+ * `wrapupTimeLeadMs` is not: with less than this much turn time remaining,
+ * a wrap-up nudge rides the next tool-result turn.
+ */
+export declare const DEFAULT_WRAPUP_TIME_LEAD_MS = 120000;
 export declare const TOOL_STORAGE_TIMEOUT_MS = 5000;
 export declare const STEP_LIMITS: {
     min: number;

package/dist/lib/core/constants.js

@@ -109,6 +109,19 @@ export const DEFAULT_MAX_STEPS = 200;
 export const DEFAULT_TOOL_MAX_RETRIES = 2; // Maximum retries per tool before permanently failing
 /** Defensive wall-clock ceiling for a native Gemini-3 agentic turn (generate + stream). */
 export const DEFAULT_GEMINI_STREAM_TIMEOUT_MS = 300_000;
+/**
+ * Default per-tool-execution timeout for native agentic loops. A tool that
+ * exceeds it fails with an error tool_result and costs one step — the turn
+ * continues instead of hanging on a wedged tool. Override per call with
+ * `toolTimeoutMs`.
+ */
+export const DEFAULT_TOOL_EXECUTION_TIMEOUT_MS = 300_000;
+/**
+ * Default wrap-up lead applied when `turnTimeoutMs` is set but
+ * `wrapupTimeLeadMs` is not: with less than this much turn time remaining,
+ * a wrap-up nudge rides the next tool-result turn.
+ */
+export const DEFAULT_WRAPUP_TIME_LEAD_MS = 120_000;
 // Fire-and-forget tool storage writes (Redis). 5s is generous for a single
 // Redis write; if breached, the .catch logs a warning.
 export const TOOL_STORAGE_TIMEOUT_MS = 5000;

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;