@juspay/neurolink 9.80.3 → 9.81.0

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

@@ -35,6 +35,16 @@ export type AnalyticsData = {
     timestamp: string;
     cost?: number;
     context?: JsonValue;
+    /** Number of agentic steps (model calls) the turn used. */
+    stepsUsed?: number;
+    /** Number of external tool calls the turn made (final_result excluded). */
+    toolCallCount?: number;
+    /** Why the turn ended — see GenerateStopReason. */
+    stopReason?: string;
+    /** Wall-clock duration of the turn in milliseconds. */
+    elapsedMs?: number;
+    /** Verbatim provider finish/stop reason for the terminal model call. */
+    rawFinishReason?: string;
 };
 /**
  * Stream Analytics Data - Enhanced for performance tracking

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

@@ -296,7 +296,52 @@ 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;
+    /**
+     * Hard wall-clock cap for the WHOLE agentic turn (all model calls + tool
+     * executions), in milliseconds. When the deadline passes the turn ends
+     * gracefully with `stopReason: "time-limit"` and an honest time message —
+     * never the step-cap text. Unset = no turn-level deadline (the library
+     * imposes no product policy).
+     *
+     * Enforced by the native Vertex loops (Gemini + Claude); AI-SDK-driven
+     * providers currently ignore it.
+     */
+    turnTimeoutMs?: number;
+    /**
+     * Maximum time with NO progress — no stream chunk received, no tool
+     * execution started or finished, no step started — before the turn ends
+     * with `stopReason: "stalled"`. Catches wedged tools and hung model calls
+     * that a whole-turn deadline would let run to the bitter end.
+     * Unset = disabled.
+     */
+    stallTimeoutMs?: number;
+    /**
+     * When the remaining turn time drops below this, a wrap-up nudge rides the
+     * next tool-result turn telling the model to consolidate what it has and
+     * produce its final answer. Defaults to 120_000 when `turnTimeoutMs` is
+     * set; ignored when it is not.
+     */
+    wrapupTimeLeadMs?: number;
+    /**
+     * Per-tool-execution timeout in milliseconds (default 300_000). 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.
+     */
+    toolTimeoutMs?: number;
     /** AbortSignal for external cancellation of the AI call */
     abortSignal?: AbortSignal;
     /**
@@ -549,6 +594,21 @@ export type AdditionalMemoryUser = {
     /** Max words for this user's condensed memory. Overrides the default maxWords. */
     maxWords?: number;
 };
+/**
+ * Why an agentic turn ended — the discriminator consumers should branch on
+ * instead of sniffing the provider-shaped `finishReason` (whose values are
+ * overloaded: e.g. "tool-calls" historically covered both step-cap exits and
+ * Gemini MALFORMED_FUNCTION_CALL provider errors).
+ *
+ * - `completed` — the model finished on its own (text answer or final_result)
+ * - `step-cap` — the `maxSteps` budget ran out while the model still wanted tools
+ * - `time-limit` — the `turnTimeoutMs` wall-clock deadline passed
+ * - `stalled` — no progress (no chunk, no tool start/finish) for `stallTimeoutMs`
+ * - `aborted` — the caller's `abortSignal` ended the turn
+ * - `provider-error` — the provider/model failed the turn (e.g. persistent
+ *   MALFORMED_FUNCTION_CALL after retry); usually worth a caller-side retry
+ */
+export type GenerateStopReason = "completed" | "step-cap" | "time-limit" | "stalled" | "aborted" | "provider-error";
 /**
  * Generate function result type - Primary output format
  * Future-ready for multi-modal outputs while maintaining text focus
@@ -649,6 +709,20 @@ export type GenerateResult = {
     provider?: string;
     model?: string;
     finishReason?: string;
+    /**
+     * Why the agentic turn ended, independent of the provider-shaped
+     * `finishReason`. Populated by the native Vertex loops (Gemini + Claude);
+     * undefined on providers that don't run a native loop — fall back to
+     * `finishReason` heuristics there.
+     */
+    stopReason?: GenerateStopReason;
+    /**
+     * Verbatim provider finish/stop reason for the turn's terminal model call
+     * (e.g. "MALFORMED_FUNCTION_CALL", "MAX_TOKENS", "max_tokens", "tool_use").
+     */
+    rawFinishReason?: string;
+    /** Number of agentic steps (model calls) the turn used. */
+    stepsUsed?: number;
     /**
      * True when the schema JSON in `content`/`structuredData` was repaired from
      * malformed model text (jsonrepair ran). The result is still valid JSON.
@@ -869,6 +943,14 @@ export type TextGenerationOptions = {
      */
     enabledToolNames?: string[];
     timeout?: number | string;
+    /** Wall-clock cap for the whole agentic turn (ms). See GenerateOptions.turnTimeoutMs. */
+    turnTimeoutMs?: number;
+    /** Max time with no progress before the turn ends as "stalled" (ms). See GenerateOptions.stallTimeoutMs. */
+    stallTimeoutMs?: number;
+    /** Remaining-time threshold that triggers the wrap-up nudge (ms). See GenerateOptions.wrapupTimeLeadMs. */
+    wrapupTimeLeadMs?: number;
+    /** Per-tool-execution timeout (ms, default 300_000). See GenerateOptions.toolTimeoutMs. */
+    toolTimeoutMs?: number;
     /** AbortSignal for external cancellation of the AI call */
     abortSignal?: AbortSignal;
     disableTools?: boolean;
@@ -1115,6 +1197,12 @@ export type TextGenerationResult = {
     /** Parsed structured object when a `schema` was requested (see GenerateResult.structuredData). */
     structuredData?: unknown;
     finishReason?: string;
+    /** Turn-exit discriminator from native agentic loops (see GenerateStopReason). */
+    stopReason?: GenerateStopReason;
+    /** Verbatim provider finish/stop reason for the turn's terminal model call. */
+    rawFinishReason?: string;
+    /** Number of agentic steps (model calls) the turn used. */
+    stepsUsed?: number;
     /** True when the schema JSON was repaired from malformed model text. */
     jsonRepaired?: boolean;
     /** True when the schema JSON appears truncated (output hit the token cap). */

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

@@ -8,7 +8,7 @@ import type { JsonValue, UnknownRecord } from "./common.js";
 import type { Content, ImageWithAltText } from "./content.js";
 import type { ChatMessage } from "./conversation.js";
 import type { StreamNoOutputSentinel } from "./noOutputSentinel.js";
-import type { AdditionalMemoryUser } from "./generate.js";
+import type { AdditionalMemoryUser, GenerateStopReason } from "./generate.js";
 import type { AIModelProviderConfig, NeurolinkCredentials } from "./providers.js";
 import type { TTSChunk, TTSOptions, TTSResult } from "./tts.js";
 import type { STTOptions, STTResult } from "./stt.js";
@@ -326,6 +326,14 @@ export type StreamOptions = {
     schema?: ValidationSchema;
     tools?: Record<string, Tool>;
     timeout?: number | string;
+    /** Wall-clock cap for the whole agentic turn (ms). See GenerateOptions.turnTimeoutMs. */
+    turnTimeoutMs?: number;
+    /** Max time with no progress before the turn ends as "stalled" (ms). See GenerateOptions.stallTimeoutMs. */
+    stallTimeoutMs?: number;
+    /** Remaining-time threshold that triggers the wrap-up nudge (ms). See GenerateOptions.wrapupTimeLeadMs. */
+    wrapupTimeLeadMs?: number;
+    /** Per-tool-execution timeout (ms, default 300_000). See GenerateOptions.toolTimeoutMs. */
+    toolTimeoutMs?: number;
     /** AbortSignal for external cancellation of the AI call */
     abortSignal?: AbortSignal;
     disableTools?: boolean;
@@ -518,6 +526,15 @@ export type StreamResult = {
     model?: string;
     usage?: TokenUsage;
     finishReason?: string;
+    /**
+     * Why the agentic turn ended (see GenerateStopReason). For background-loop
+     * streams (native Vertex paths) prefer `metadata.stopReason` after draining
+     * the stream — this top-level field may be a getter that resolves late, and
+     * wrapper spreads can snapshot it before the loop finishes.
+     */
+    stopReason?: GenerateStopReason;
+    /** Verbatim provider finish/stop reason for the turn's terminal model call. */
+    rawFinishReason?: string;
     toolCalls?: StreamToolCall[];
     toolResults?: StreamToolResult[];
     toolEvents?: AsyncIterable<ToolExecutionEvent>;
@@ -537,6 +554,9 @@ export type StreamResult = {
         guardrailsBlocked?: boolean;
         error?: string;
         finishReason?: string;
+        stopReason?: GenerateStopReason;
+        rawFinishReason?: string;
+        stepsUsed?: number;
         thoughtSignature?: string;
         thoughts?: Array<{
             id?: string;

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;