@juspay/neurolink 12.11.2 → 12.11.3

package/dist/mcp/toolRegistry.js

@@ -167,6 +167,7 @@ export class MCPToolRegistry extends MCPRegistry {
             const toolId = isCustomTool ? tool.name : `${serverId}.${tool.name}`;
             const toolTimeoutMs = serverInfo.metadata?.toolTimeoutMs;
             const toolMaxRetries = serverInfo.metadata?.toolMaxRetries;
+            const toolTotalTimeoutMs = serverInfo.metadata?.toolTotalTimeoutMs;
             const toolInfo = {
                 name: tool.name,
                 description: tool.description,
@@ -180,6 +181,9 @@ export class MCPToolRegistry extends MCPRegistry {
                 permissions: [], // MCPServerInfo.tools doesn't have permissions
                 ...(toolTimeoutMs !== undefined && { timeoutMs: toolTimeoutMs }),
                 ...(toolMaxRetries !== undefined && { maxRetries: toolMaxRetries }),
+                ...(toolTotalTimeoutMs !== undefined && {
+                    totalTimeoutMs: toolTotalTimeoutMs,
+                }),
             };
             // Register only with fully-qualified toolId to avoid collisions
             this.tools.set(toolId, toolInfo);
@@ -197,6 +201,9 @@ export class MCPToolRegistry extends MCPRegistry {
                 }),
                 ...(toolTimeoutMs !== undefined && { timeoutMs: toolTimeoutMs }),
                 ...(toolMaxRetries !== undefined && { maxRetries: toolMaxRetries }),
+                ...(toolTotalTimeoutMs !== undefined && {
+                    totalTimeoutMs: toolTotalTimeoutMs,
+                }),
             });
             // Tool registered successfully
         }

package/dist/neurolink.d.ts

@@ -1587,8 +1587,15 @@ export declare class NeuroLink {
      * @returns Tool execution result
      */
     executeTool<T = unknown>(toolName: string, params?: unknown, options?: {
+        /** Bound on ONE attempt. */
         timeout?: number;
         maxRetries?: number;
+        /**
+         * Bound on the WHOLE execution — every attempt plus the delays between
+         * them. Defaults to `timeout * (maxRetries + 1)`, which is what the
+         * retry loop already spent, so omitting it changes nothing.
+         */
+        totalTimeoutMs?: number;
         retryDelayMs?: number;
         /** Disable tool result caching for this call */
         disableToolCache?: boolean;

package/dist/neurolink.js

@@ -9566,7 +9566,7 @@ Current user's request: ${currentInput}`;
                 };
             }
             // SMART DEFAULTS: Use utility to eliminate boilerplate creation
-            const mcpServerInfo = createCustomToolServerInfo(name, convertedTool, options?.timeout, options?.maxRetries);
+            const mcpServerInfo = createCustomToolServerInfo(name, convertedTool, options?.timeout, options?.maxRetries, options?.totalTimeoutMs);
             // Register with toolRegistry using MCPServerInfo directly
             this.toolRegistry.registerServer(mcpServerInfo);
             // Re-registration replaces options wholesale: omitting `cacheable`
@@ -10010,14 +10010,32 @@ Current user's request: ${currentInput}`;
             executionId: executionContext.executionId,
         }));
         const toolInfo = this.toolRegistry.getToolInfo(toolName);
+        const attemptTimeout = options?.timeout ??
+            toolInfo?.tool?.timeoutMs ??
+            TOOL_TIMEOUTS.EXECUTION_BATCH_MS;
+        const maxRetries = options?.maxRetries ??
+            toolInfo?.tool?.maxRetries ??
+            RETRY_ATTEMPTS.DEFAULT;
+        const retryDelayMs = options?.retryDelayMs || RETRY_DELAYS.BASE_MS;
         const finalOptions = {
-            timeout: options?.timeout ??
-                toolInfo?.tool?.timeoutMs ??
-                TOOL_TIMEOUTS.EXECUTION_BATCH_MS,
-            maxRetries: options?.maxRetries ??
-                toolInfo?.tool?.maxRetries ??
-                RETRY_ATTEMPTS.DEFAULT,
-            retryDelayMs: options?.retryDelayMs || RETRY_DELAYS.BASE_MS,
+            timeout: attemptTimeout,
+            maxRetries,
+            // Ceiling on the whole execution, not one attempt. The default is what
+            // the retry loop already spent, and that is BOTH terms: every attempt at
+            // full length PLUS the fixed wait between them. Omitting the delays
+            // makes the default ceiling shorter than the envelope it is meant to
+            // reproduce, so `attemptTimeout = min(timeout, remaining)` clamps a
+            // later attempt below its configured timeout — the opposite of the
+            // "unchanged unless you ask for less" contract this default exists to
+            // keep. Before any of this the total was unbounded and merely implied:
+            // a tool that reliably hung burned every attempt at full length, and
+            // the surfaced error reported the per-attempt bound beside the
+            // whole-execution elapsed time, which reads as a timeout that was never
+            // enforced.
+            totalTimeout: options?.totalTimeoutMs ??
+                toolInfo?.tool?.totalTimeoutMs ??
+                attemptTimeout * (maxRetries + 1) + retryDelayMs * maxRetries,
+            retryDelayMs,
             authContext: options?.authContext,
             disableToolCache: options?.disableToolCache,
         };
@@ -10062,11 +10080,43 @@ Current user's request: ${currentInput}`;
                 options: prepared.finalOptions,
                 circuitBreakerState: prepared.circuitBreaker.getState(),
             });
+            const maxAttempts = prepared.finalOptions.maxRetries + 1;
+            const totalTimeout = prepared.finalOptions.totalTimeout;
+            const budgetStart = Date.now();
+            const deadline = budgetStart + totalTimeout;
+            let attemptNumber = 0;
             const result = await prepared.circuitBreaker.execute(async () => {
-                return withRetry(async () => withTimeout(this.executeToolInternal(toolName, params, prepared.finalOptions, executionContext.hitlState), prepared.finalOptions.timeout, ErrorFactory.toolTimeout(toolName, prepared.finalOptions.timeout)), {
-                    maxAttempts: prepared.finalOptions.maxRetries + 1,
+                return withRetry(async () => {
+                    attemptNumber++;
+                    const remaining = deadline - Date.now();
+                    if (remaining <= 0) {
+                        throw ErrorFactory.toolTimeout(toolName, totalTimeout, undefined, {
+                            attempt: attemptNumber,
+                            maxAttempts,
+                            attemptTimeoutMs: prepared.finalOptions.timeout,
+                            totalTimeoutMs: totalTimeout,
+                            elapsedMs: Date.now() - budgetStart,
+                            exhausted: true,
+                        });
+                    }
+                    // Clamping to what is left is what makes the ceiling hard. Gating
+                    // retries alone would not: the last attempt could start just under
+                    // the deadline and still run a full attempt timeout past it.
+                    const attemptTimeout = Math.min(prepared.finalOptions.timeout, remaining);
+                    return withTimeout(this.executeToolInternal(toolName, params, prepared.finalOptions, executionContext.hitlState), attemptTimeout, ErrorFactory.toolTimeout(toolName, attemptTimeout, undefined, {
+                        attempt: attemptNumber,
+                        maxAttempts,
+                        attemptTimeoutMs: prepared.finalOptions.timeout,
+                        totalTimeoutMs: totalTimeout,
+                        elapsedMs: Date.now() - budgetStart,
+                    }));
+                }, {
+                    maxAttempts,
                     delayMs: prepared.finalOptions.retryDelayMs,
-                    isRetriable: isRetriableError,
+                    // Stop when there is not enough budget left for the retry delay
+                    // plus any real work after it.
+                    isRetriable: (error) => Date.now() + prepared.finalOptions.retryDelayMs < deadline &&
+                        isRetriableError(error),
                     onRetry: (attempt, error) => {
                         toolRetryCount = attempt;
                         mcpLogger.warn(`[${executionContext.functionTag}] Retrying tool execution (attempt ${attempt})`, {

package/dist/types/tools.d.ts

@@ -87,6 +87,12 @@ export type ToolInfo = {
     /** Per-tool timeout in milliseconds, set at registration time */
     timeoutMs?: number;
     maxRetries?: number;
+    /**
+     * Ceiling on the WHOLE execution — every attempt plus the delays between
+     * them. Declared explicitly rather than left to the index signature below,
+     * which would type it `unknown` and silently defeat the default.
+     */
+    totalTimeoutMs?: number;
     [key: string]: unknown;
 };
 /**
@@ -103,6 +109,13 @@ export type ToolImplementation = {
     /** Per-tool timeout in milliseconds, set at registration time */
     timeoutMs?: number;
     maxRetries?: number;
+    /**
+     * Ceiling on the WHOLE execution — every attempt plus the delays between
+     * them — in milliseconds. `timeoutMs` bounds one attempt; without this, a
+     * tool that reliably hangs burns `timeoutMs * (maxRetries + 1)`.
+     * Defaults to exactly that product, so behaviour is unchanged unless set.
+     */
+    totalTimeoutMs?: number;
 };
 /**
  * Tool execution options for enhanced control
@@ -130,6 +143,13 @@ export type ToolExecutionOptions = {
      */
     timeoutMs?: number;
     maxRetries?: number;
+    /**
+     * Ceiling on the WHOLE execution — every attempt plus the delays between
+     * them. `timeout` bounds one attempt. Defaults to
+     * `timeout * (maxRetries + 1)`, which is what the retry loop already spent,
+     * so supplying nothing changes nothing.
+     */
+    totalTimeoutMs?: number;
 };
 /**
  * Options for tool registration via registerTool()
@@ -153,6 +173,9 @@ export type ToolRegistrationOptions = {
      *  When omitted, the SDK's global default (2 retries) is used.
      *  Set to 0 to disable retries for this tool. */
     maxRetries?: number;
+    /** Ceiling on the whole execution across every attempt and the delays
+     *  between them. When omitted, `timeout * (maxRetries + 1)` is used. */
+    totalTimeoutMs?: number;
     /**
      * Whether this tool's result may be served from the tool-result cache
      * (default true).

package/dist/utils/errorHandling.d.ts

@@ -108,9 +108,26 @@ export declare class ErrorFactory {
      */
     static toolExecutionFailed(toolName: string, originalError: Error, serverId?: string): NeuroLinkError;
     /**
-     * Create a tool timeout error
-     */
-    static toolTimeout(toolName: string, timeoutMs: number, serverId?: string): NeuroLinkError;
+     * Create a tool timeout error.
+     *
+     * `timeoutMs` is the bound that was actually exceeded. Pass `budget` when
+     * the timeout happened inside a retry loop, so the error can say which
+     * number it is reporting: a reader who sees `timeoutMs: 120000` next to an
+     * `executionTime` of 483005 will otherwise conclude the timeout was never
+     * enforced, when in fact four attempts of 120s each were.
+     *
+     * `budget.exhausted` marks the case where the whole-execution ceiling ran
+     * out rather than a single attempt overrunning; that error is NOT retriable,
+     * because there is no budget left to retry into.
+     */
+    static toolTimeout(toolName: string, timeoutMs: number, serverId?: string, budget?: {
+        attempt?: number;
+        maxAttempts?: number;
+        attemptTimeoutMs?: number;
+        totalTimeoutMs?: number;
+        elapsedMs?: number;
+        exhausted?: boolean;
+    }): NeuroLinkError;
     /**
      * Create a parameter validation error
      */

package/dist/utils/errorHandling.js

@@ -164,16 +164,33 @@ export class ErrorFactory {
         });
     }
     /**
-     * Create a tool timeout error
+     * Create a tool timeout error.
+     *
+     * `timeoutMs` is the bound that was actually exceeded. Pass `budget` when
+     * the timeout happened inside a retry loop, so the error can say which
+     * number it is reporting: a reader who sees `timeoutMs: 120000` next to an
+     * `executionTime` of 483005 will otherwise conclude the timeout was never
+     * enforced, when in fact four attempts of 120s each were.
+     *
+     * `budget.exhausted` marks the case where the whole-execution ceiling ran
+     * out rather than a single attempt overrunning; that error is NOT retriable,
+     * because there is no budget left to retry into.
      */
-    static toolTimeout(toolName, timeoutMs, serverId) {
+    static toolTimeout(toolName, timeoutMs, serverId, budget) {
+        const scope = budget?.exhausted
+            ? `exhausted its ${budget.totalTimeoutMs}ms total budget`
+            : budget?.maxAttempts && budget.maxAttempts > 1
+                ? `timed out after ${timeoutMs}ms on attempt ${budget.attempt ?? 1} of ${budget.maxAttempts}`
+                : `timed out after ${timeoutMs}ms`;
         return new NeuroLinkError({
             code: ERROR_CODES.TOOL_TIMEOUT,
-            message: `Tool '${toolName}' timed out after ${timeoutMs}ms`,
+            message: `Tool '${toolName}' ${scope}`,
             category: ErrorCategory.TIMEOUT,
             severity: ErrorSeverity.HIGH,
-            retriable: true,
-            context: { timeoutMs },
+            // A single attempt timing out is worth another try; an exhausted total
+            // budget is not — retrying it can only overshoot the caller's ceiling.
+            retriable: budget?.exhausted !== true,
+            context: { timeoutMs, ...(budget ?? {}) },
             toolName,
             serverId,
         });

package/dist/utils/mcpDefaults.d.ts

@@ -37,7 +37,7 @@ export declare function createMCPServerInfo(options: {
  * Create MCPServerInfo for custom tool registration
  * Specialized version with smart defaults for registerTool usage
  */
-export declare function createCustomToolServerInfo(toolName: string, tool: MCPExecutableTool, timeoutMs?: number, maxRetries?: number): MCPServerInfo;
+export declare function createCustomToolServerInfo(toolName: string, tool: MCPExecutableTool, timeoutMs?: number, maxRetries?: number, totalTimeoutMs?: number): MCPServerInfo;
 /**
  * Create MCPServerInfo for external servers
  * Specialized version with smart defaults for external server usage

package/dist/utils/mcpDefaults.js

@@ -93,7 +93,7 @@ export function createMCPServerInfo(options) {
  * Create MCPServerInfo for custom tool registration
  * Specialized version with smart defaults for registerTool usage
  */
-export function createCustomToolServerInfo(toolName, tool, timeoutMs, maxRetries) {
+export function createCustomToolServerInfo(toolName, tool, timeoutMs, maxRetries, totalTimeoutMs) {
     const serverInfo = createMCPServerInfo({
         id: `custom-tool-${toolName}`,
         name: toolName,
@@ -112,6 +112,9 @@ export function createCustomToolServerInfo(toolName, tool, timeoutMs, maxRetries
         if (maxRetries !== undefined) {
             serverInfo.metadata.toolMaxRetries = maxRetries;
         }
+        if (totalTimeoutMs !== undefined) {
+            serverInfo.metadata.toolTotalTimeoutMs = totalTimeoutMs;
+        }
     }
     return serverInfo;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "12.11.2",
+  "version": "12.11.3",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (connect any MCP server), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {