@juspay/neurolink 12.26.0 → 12.26.1

package/dist/mcp/externalServerManager.js

@@ -1702,11 +1702,25 @@ export class ExternalServerManager extends EventEmitter {
             instance.metrics.averageResponseTime =
                 totalTime / instance.metrics.totalToolCalls;
             if (result.success) {
-                mcpLogger.debug(`[ExternalServerManager] Tool executed successfully: ${toolName} on ${serverId}`, {
+                // A resolved `{ isError: true }` still comes back with success:true so
+                // the caller receives the MCP error payload as-is, but it is a failed
+                // call for telemetry: label mcp_tool_calls_total accordingly instead
+                // of counting every resolved error as a success.
+                const resolvedError = result.isErrorResult === true;
+                if (resolvedError) {
+                    // Keep this instance's totalErrors (and the getStatistics() /
+                    // getExternalMCPStatistics() it feeds) consistent with the breaker,
+                    // TelemetryService and ToolDiscoveryService's failedCalls, all of
+                    // which already count a resolved isError result as a failure.
+                    instance.metrics.totalErrors++;
+                }
+                mcpLogger.debug(resolvedError
+                    ? `[ExternalServerManager] Tool returned a resolved MCP error: ${toolName} on ${serverId}`
+                    : `[ExternalServerManager] Tool executed successfully: ${toolName} on ${serverId}`, {
                     duration,
                 });
                 try {
-                    TelemetryService.getInstance()?.recordMCPToolCall(toolName, duration, true);
+                    TelemetryService.getInstance()?.recordMCPToolCall(toolName, duration, !resolvedError);
                 }
                 catch {
                     /* telemetry should not break execution */

package/dist/mcp/mcpCircuitBreaker.d.ts

@@ -21,9 +21,30 @@ export declare class MCPCircuitBreaker extends EventEmitter {
     private cleanupTimer?;
     constructor(name: string, config?: Partial<CircuitBreakerConfig>);
     /**
-     * Execute an operation with circuit breaker protection
-     */
-    execute<T>(operation: () => Promise<T>): Promise<T>;
+     * Execute an operation with circuit breaker protection.
+     *
+     * `operation` is handed a `recordResolvedFailure` callback so it can flag a
+     * *resolved* result as a logical failure without throwing. This matters for
+     * MCP tool calls: the client does not throw on a protocol error, it
+     * resolves with `{ isError: true, ... }`. Before this callback existed,
+     * such a call always fell through to the success path below — the breaker
+     * could never open for a tool that only ever "fails" by resolving an error
+     * result, and callers still need that resolved value returned as-is (not
+     * replaced by a thrown transport error). Call `recordResolvedFailure()`
+     * from inside `operation` when that resolved value represents a failure;
+     * the call is still counted as a normal, non-throwing success from the
+     * `Promise.race` below, so this callback is what tells `execute()`
+     * otherwise. Callers that never call it see no behavior change.
+     */
+    execute<T>(operation: (recordResolvedFailure: (reason?: string) => void) => Promise<T>): Promise<T>;
+    /**
+     * Shared bookkeeping for a failed outcome — a thrown error, or a resolved
+     * result the caller flagged via `recordResolvedFailure`. Records the call
+     * as a failure, emits `callFailure`, and runs the state transitions that
+     * used to live inline in the `catch` block: half-open failure immediately
+     * re-opens the circuit; closed checks the failure threshold.
+     */
+    private recordFailureOutcome;
     /**
      * Record a call in the history
      */

package/dist/mcp/mcpCircuitBreaker.js

@@ -46,7 +46,20 @@ export class MCPCircuitBreaker extends EventEmitter {
         this.cleanupTimer = setInterval(() => this.cleanupCallHistory(), 60000);
     }
     /**
-     * Execute an operation with circuit breaker protection
+     * Execute an operation with circuit breaker protection.
+     *
+     * `operation` is handed a `recordResolvedFailure` callback so it can flag a
+     * *resolved* result as a logical failure without throwing. This matters for
+     * MCP tool calls: the client does not throw on a protocol error, it
+     * resolves with `{ isError: true, ... }`. Before this callback existed,
+     * such a call always fell through to the success path below — the breaker
+     * could never open for a tool that only ever "fails" by resolving an error
+     * result, and callers still need that resolved value returned as-is (not
+     * replaced by a thrown transport error). Call `recordResolvedFailure()`
+     * from inside `operation` when that resolved value represents a failure;
+     * the call is still counted as a normal, non-throwing success from the
+     * `Promise.race` below, so this callback is what tells `execute()`
+     * otherwise. Callers that never call it see no behavior change.
      */
     async execute(operation) {
         const startTime = Date.now();
@@ -91,11 +104,29 @@ export class MCPCircuitBreaker extends EventEmitter {
                     });
                 }
             }
+            // resolvedFailureReason is set (via recordResolvedFailure, passed into
+            // operation() below) when operation() resolves normally but represents
+            // a logical failure — e.g. an MCP tool call that resolved
+            // { isError: true } instead of throwing. It is call-scoped (a local,
+            // not instance state), so concurrent execute() calls on the same
+            // breaker (the same tool invoked in parallel) can't cross-contaminate
+            // each other's outcome.
+            let resolvedFailureReason;
+            const recordResolvedFailure = (reason) => {
+                resolvedFailureReason = reason || "Operation resolved a failure result";
+            };
             // Execute operation with timeout
             const result = await Promise.race([
-                operation(),
+                operation(recordResolvedFailure),
                 this.timeoutPromise(this.config.operationTimeout),
             ]);
+            if (resolvedFailureReason !== undefined) {
+                // Same bookkeeping as a thrown error below, but the resolved value
+                // is still returned to the caller unchanged — no transport error is
+                // synthesized for a result the protocol itself resolved successfully.
+                this.recordFailureOutcome(resolvedFailureReason, Date.now() - startTime);
+                return result;
+            }
             // Record successful call
             this.recordCall(true, Date.now() - startTime);
             // Handle half-open success
@@ -111,26 +142,34 @@ export class MCPCircuitBreaker extends EventEmitter {
         catch (error) {
             // Record failed call
             const duration = Date.now() - startTime;
-            this.recordCall(false, duration);
             const errorMessage = error instanceof Error ? error.message : String(error);
-            // Emit failure event
-            this.emit("callFailure", {
-                error: errorMessage,
-                duration,
-                timestamp: new Date(),
-            });
-            // Handle state transitions on failure
-            if (this.state === "half-open") {
-                // Failure in half-open immediately opens circuit
-                this.changeState("open", `Half-open test failed: ${errorMessage}`);
-            }
-            else if (this.state === "closed") {
-                // Check if we should open the circuit
-                this.checkFailureThreshold();
-            }
+            this.recordFailureOutcome(errorMessage, duration);
             throw error;
         }
     }
+    /**
+     * Shared bookkeeping for a failed outcome — a thrown error, or a resolved
+     * result the caller flagged via `recordResolvedFailure`. Records the call
+     * as a failure, emits `callFailure`, and runs the state transitions that
+     * used to live inline in the `catch` block: half-open failure immediately
+     * re-opens the circuit; closed checks the failure threshold.
+     */
+    recordFailureOutcome(reason, duration) {
+        this.recordCall(false, duration);
+        this.emit("callFailure", {
+            error: reason,
+            duration,
+            timestamp: new Date(),
+        });
+        if (this.state === "half-open") {
+            // Failure in half-open immediately opens circuit
+            this.changeState("open", `Half-open test failed: ${reason}`);
+        }
+        else if (this.state === "closed") {
+            // Check if we should open the circuit
+            this.checkFailureThreshold();
+        }
+    }
     /**
      * Record a call in the history
      */

package/dist/mcp/toolDiscoveryService.js

@@ -435,8 +435,13 @@ export class ToolDiscoveryService extends EventEmitter {
                 resetTimeout: 30000,
                 operationTimeout: effectiveTimeout,
             });
-            // Execute tool with circuit breaker protection
-            const result = await circuitBreaker.execute(async () => {
+            // Execute tool with circuit breaker protection. `recordResolvedFailure`
+            // lets the callback below tell the breaker that a *resolved* MCP
+            // isError result is a failure — the MCP client does not throw on a
+            // protocol error, so without this the breaker would only ever see a
+            // clean resolve and could never open for a tool that fails this way.
+            let isErrorResultDetected = false;
+            const result = await circuitBreaker.execute(async (recordResolvedFailure) => {
                 return mcpTracer.startActiveSpan("neurolink.mcp.callTool", {
                     kind: SpanKind.CLIENT,
                     attributes: {
@@ -479,6 +484,11 @@ export class ToolDiscoveryService extends EventEmitter {
                                 code: SpanStatusCode.ERROR,
                                 message: errorText || `Tool ${toolName} returned isError`,
                             });
+                            // NLK: count a resolved isError result as a breaker failure
+                            // and label completion telemetry as error below — without
+                            // throwing, so the protocol result is still returned as-is.
+                            isErrorResultDetected = true;
+                            recordResolvedFailure(errorText || `Tool ${toolName} returned isError`);
                         }
                         else {
                             callSpan.setStatus({ code: SpanStatusCode.OK });
@@ -528,8 +538,13 @@ export class ToolDiscoveryService extends EventEmitter {
                 });
             });
             const duration = Date.now() - startTime;
-            // Update tool statistics
-            this.updateToolStats(toolKey, true, duration);
+            // Update tool statistics. A resolved isError result is a failed call
+            // for completion telemetry purposes even though the wrapper below
+            // still returns success:true / data:result unchanged — flipping
+            // `success` here would make externalServerManager.executeTool() throw
+            // instead of returning the resolved MCP error, which is exactly the
+            // "thrown transport error" this fix must not introduce.
+            this.updateToolStats(toolKey, !isErrorResultDetected, duration);
             // Validate output if requested
             if (options.validateOutput !== false) {
                 this.validateToolOutput(result);
@@ -541,6 +556,7 @@ export class ToolDiscoveryService extends EventEmitter {
             return {
                 success: true,
                 data: result,
+                isErrorResult: isErrorResultDetected,
                 duration,
                 metadata: {
                     toolName,

package/dist/types/externalMcp.d.ts

@@ -234,6 +234,13 @@ export type ExternalMCPToolResult = {
     data?: unknown;
     /** Error message if failed */
     error?: string;
+    /**
+     * True when the call completed at the transport level but the MCP result
+     * itself is `{ isError: true }`. `success` stays true for such results so
+     * the resolved MCP error payload still reaches the caller unchanged; this
+     * flag is what lets stats and telemetry count the call as a failure.
+     */
+    isErrorResult?: boolean;
     /** Execution duration in milliseconds */
     duration: number;
     /** Tool execution metadata */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "12.26.0",
+  "version": "12.26.1",
   "packageManager": "pnpm@10.15.1",
   "description": "The pipe layer of an AI nervous system: one interface connecting provider neurons to your application, across three inference types — generate, stream and decide. `decide` returns typed, calibrated judgements from a non-generative model (~400ms, ~$0.00002/call) for routing, tool selection and context budgeting. MCP-native (4 transports), voice TTS/STT/realtime, RAG, agents, memory, compaction, 9 observability exporters. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · TypeSafe Jev and more.",
   "author": {
@@ -181,7 +181,7 @@
     "// CI tier — fast, no live AI calls, safe for every commit (test:unit; also see the separate provider-safety-net CI job, which runs build + test:providers-mocked + test:provider-structure + test:error-classifier-contract on every PR)": "",
     "test:tool-routing": "pnpm exec tsx test/continuous-test-suite-tool-routing.ts",
     "test:tool-routing-semantic": "pnpm exec tsx test/continuous-test-suite-tool-routing-semantic.ts",
-    "test:unit": "pnpm run test:bugfixes && pnpm run test:mcp:infra && pnpm run test:mcp:spans && pnpm run test:tool-routing && pnpm run test:tool-routing-cli && pnpm run test:tool-dedup && pnpm run test:model-pool && pnpm run test:classifier-router && pnpm run test:tool-routing-semantic && pnpm run test:mcp-result-cache && pnpm run test:mcp-direct-name-repair && pnpm run test:model-not-found-retryable && pnpm run test:archive:security && pnpm run test:office:security && pnpm run test:vector-chroma && pnpm run test:vector-pgvector && pnpm run test:vector-pinecone && pnpm run test:provider-wiring && pnpm run test:docs-mcp",
+    "test:unit": "pnpm run test:bugfixes && pnpm run test:mcp:infra && pnpm run test:mcp:spans && pnpm run test:tool-routing && pnpm run test:tool-routing-cli && pnpm run test:tool-dedup && pnpm run test:model-pool && pnpm run test:classifier-router && pnpm run test:tool-routing-semantic && pnpm run test:mcp-result-cache && pnpm run test:mcp-direct-name-repair && pnpm run test:mcp-breaker-resolved-errors && pnpm run test:model-not-found-retryable && pnpm run test:archive:security && pnpm run test:office:security && pnpm run test:vector-chroma && pnpm run test:vector-pgvector && pnpm run test:vector-pinecone && pnpm run test:provider-wiring && pnpm run test:docs-mcp",
     "// CI tier — live providers, runs only when API keys are present (test:credentials and test:dynamic make real provider calls when keys are set, so they live here, not in test:unit; test:matrix, a different suite covering the full provider capability matrix, runs nightly via .github/workflows/live-matrix.yml — test:providers itself is still only wired into test:live, not any GitHub Actions workflow)": "",
     "test:live": "pnpm run test:providers && pnpm run test:mcp:http && pnpm run test:mcp:sdk && pnpm run test:mcp:cli && pnpm run test:observability && pnpm run test:context && pnpm run test:memory && pnpm run test:tool-reliability && pnpm run test:evaluation && pnpm run test:autoresearch && pnpm run test:credentials && pnpm run test:dynamic",
     "// CI tier — product output (image/video/TTS/PPT) — costs $$ per run (not wired into any GitHub Actions workflow as of this comment; run manually or add to live-matrix.yml if nightly coverage is needed)": "",
@@ -243,6 +243,7 @@
     "test:multimodal": "pnpm run test:file-formats && pnpm run test:multimodal:sdk",
     "test:multimodal:sdk": "pnpm exec tsx test/continuous-test-suite-multimodal-sdk.ts",
     "test:mcp-result-cache": "pnpm exec tsx test/continuous-test-suite-mcp-result-cache.ts",
+    "test:mcp-breaker-resolved-errors": "pnpm exec tsx test/continuous-test-suite-mcp-breaker-resolved-errors.ts",
     "test:archive:security": "pnpm exec tsx test/continuous-test-suite-archive-security.ts",
     "test:office:security": "pnpm exec tsx test/continuous-test-suite-office-security.ts",
     "test:vision-image-format": "pnpm exec tsx test/continuous-test-suite-vision-image-format.ts",