@juspay/neurolink 12.7.6 → 12.7.8

package/dist/mcp/mcpClientFactory.js

@@ -9,7 +9,6 @@ import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { WebSocketClientTransport } from "@modelcontextprotocol/sdk/client/websocket.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { spawn } from "child_process";
 import { mcpLogger } from "../utils/logger.js";
 import { globalCircuitBreakerManager } from "./mcpCircuitBreaker.js";
 import { CircuitBreakerOpenError } from "../types/index.js";
@@ -26,6 +25,48 @@ import { getActiveTraceContext } from "../telemetry/traceContext.js";
  * especially when multiple MCP servers are started concurrently.
  */
 const DEFAULT_CLIENT_TIMEOUT = Math.max(5000, Number(process.env.MCP_CLIENT_TIMEOUT) || 60000);
+/**
+ * How many stderr lines to keep per stdio server. Enough for a Python
+ * traceback or an OOM message; small enough that a chatty server logging
+ * every request to stderr costs nothing.
+ */
+const STDERR_TAIL_LINES = 20;
+/**
+ * Bounded buffer of the most recent stderr lines a stdio server wrote.
+ *
+ * A crashing server explains itself on stderr and nowhere else. With the
+ * stream ignored — as it was — a `Connection closed` said nothing about
+ * why, and the ExternalServerManager could only report that a process it
+ * never saw had gone. Keeping a short tail per transport lets the
+ * disconnect log, the connect error and the `disconnected` event all carry
+ * the server's last words.
+ */
+class StderrTail {
+    lines = [];
+    partial = "";
+    append(chunk) {
+        this.partial += chunk.toString();
+        const pieces = this.partial.split(/\r?\n/);
+        this.partial = pieces.pop() ?? "";
+        for (const piece of pieces) {
+            if (piece.trim().length === 0) {
+                continue;
+            }
+            this.lines.push(piece);
+            if (this.lines.length > STDERR_TAIL_LINES) {
+                this.lines.shift();
+            }
+        }
+    }
+    snapshot() {
+        const out = [...this.lines];
+        if (this.partial.trim().length > 0) {
+            out.push(this.partial);
+        }
+        return out.slice(-STDERR_TAIL_LINES);
+    }
+}
+const stderrTails = new WeakMap();
 /**
  * MCPClientFactory
  * Factory class for creating MCP clients with different transports
@@ -164,10 +205,8 @@ export class MCPClientFactory {
     static async createClientInternal(config, timeout) {
         // Create transport
         const transportResult = await this.createTransport(config);
-        // Extract transport and process with necessary type assertions
-        // Note: Type assertions required due to TransportResult using 'unknown' to avoid circular imports
+        // Note: Type assertion required due to TransportResult using 'unknown' to avoid circular imports
         const transport = transportResult.transport;
-        const process = transportResult.process;
         try {
             // Create client
             const client = new Client(this.NEUROLINK_IMPLEMENTATION, {
@@ -186,24 +225,37 @@ export class MCPClientFactory {
             return {
                 client,
                 transport,
-                process,
                 capabilities: serverCapabilities,
             };
         }
         catch (error) {
-            // Clean up on failure
+            // Clean up on failure. For stdio, transport.close() ends stdin and
+            // escalates SIGTERM → SIGKILL on the child it spawned.
             try {
                 await transport.close();
             }
             catch (closeError) {
                 mcpLogger.debug(`[MCPClientFactory] Error closing transport during cleanup:`, closeError);
             }
-            if (process && !process.killed) {
-                process.kill("SIGTERM");
+            // A server that died during the handshake wrote its reason to stderr.
+            // Attach it, so "Connection closed" arrives with the traceback that
+            // explains it instead of leaving the operator to reproduce by hand.
+            const stderrTail = this.getStderrTail(transport);
+            if (error instanceof Error && stderrTail.length > 0) {
+                throw new Error(`${error.message}\nServer stderr (last ${stderrTail.length} lines):\n${stderrTail.join("\n")}`, { cause: error });
             }
             throw error;
         }
     }
+    /**
+     * The most recent stderr lines written by the stdio server behind
+     * `transport`. Empty for network transports and for servers that have
+     * written nothing. Lines are captured from before the process is even
+     * started, so an early boot failure is included.
+     */
+    static getStderrTail(transport) {
+        return stderrTails.get(transport)?.snapshot() ?? [];
+    }
     /**
      * Create transport based on configuration
      */
@@ -222,68 +274,28 @@ export class MCPClientFactory {
         }
     }
     /**
-     * Create stdio transport with process spawning
+     * Create a stdio transport.
+     *
+     * The SDK's StdioClientTransport owns the server process: it spawns the
+     * child inside `client.connect()` and reports the child's death through
+     * `transport.onclose`, which the Client forwards as `client.onclose`. There
+     * is deliberately no `spawn()` here. An earlier "startup probe" launched
+     * the command a second time, and that duplicate — never spoken to, never
+     * closed — was the process every lifecycle hook ended up watching while
+     * the real server could die unnoticed. It also leaked as an orphan on
+     * every shutdown.
+     *
+     * stderr is piped rather than ignored so a crashing server's last lines
+     * survive to the disconnect log and the connect error. A pipe nobody reads
+     * would back-pressure the child once the buffer fills, so the tail
+     * listener is attached before `start()`; the SDK creates the stderr
+     * PassThrough in its constructor for exactly this reason.
      */
     static async createStdioTransport(config) {
         mcpLogger.debug(`[MCPClientFactory] Creating stdio transport for ${config.id}`, {
             command: config.command,
             args: config.args,
         });
-        // Validate command is present
-        if (!config.command) {
-            throw new Error(`Command is required for stdio transport`);
-        }
-        // Spawn the process
-        const childProcess = spawn(config.command, config.args || [], {
-            stdio: ["pipe", "pipe", "pipe"],
-            env: Object.fromEntries(Object.entries({
-                ...process.env,
-                ...config.env,
-            })
-                .filter(([, value]) => value !== undefined)
-                .map(([k, v]) => [k, String(v)])),
-            cwd: config.cwd,
-        });
-        // Handle process errors
-        const processErrorPromise = new Promise((_, reject) => {
-            childProcess.on("error", (error) => {
-                reject(new Error(`Process spawn error: ${error.message}`));
-            });
-            childProcess.on("exit", (code, signal) => {
-                if (code !== 0) {
-                    reject(new Error(`Process exited with code ${code}, signal ${signal}`));
-                }
-            });
-        });
-        // Wait for process to be ready or fail using AbortController for better async patterns
-        const processStartupController = new AbortController();
-        const processStartupTimeout = setTimeout(() => {
-            processStartupController.abort();
-        }, 1000);
-        try {
-            await Promise.race([
-                new Promise((resolve) => {
-                    const checkReady = () => {
-                        if (processStartupController.signal.aborted) {
-                            resolve(); // Timeout reached, continue
-                        }
-                        else {
-                            setTimeout(checkReady, 100);
-                        }
-                    };
-                    checkReady();
-                }),
-                processErrorPromise,
-            ]);
-        }
-        finally {
-            clearTimeout(processStartupTimeout);
-        }
-        // Check if process is still running
-        if (childProcess.killed || childProcess.exitCode !== null) {
-            throw new Error("Process failed to start or exited immediately");
-        }
-        // Create transport
         if (!config.command) {
             throw new Error(`Command is required for stdio transport`);
         }
@@ -297,9 +309,20 @@ export class MCPClientFactory {
                 .filter(([, value]) => value !== undefined)
                 .map(([key, value]) => [key, String(value)])),
             cwd: config.cwd,
-            stderr: "ignore", // Suppress MCP server startup messages
+            stderr: "pipe",
+        });
+        const tail = new StderrTail();
+        stderrTails.set(transport, tail);
+        transport.stderr?.on("data", (chunk) => {
+            tail.append(chunk);
+            if (mcpLogger.shouldLog("debug")) {
+                const text = chunk.toString().trim();
+                if (text.length > 0) {
+                    mcpLogger.debug(`[MCPClientFactory] ${config.id} stderr:`, text);
+                }
+            }
         });
-        return { transport, process: childProcess };
+        return { transport };
     }
     /**
      * Create SSE transport

package/dist/providers/anthropic/client.js

@@ -26,7 +26,7 @@ import { stringifyAnthropicToolOutput } from "./toolOutput.js";
 import { createAnthropicLoopAdapter } from "./loopAdapter.js";
 import { runAgenticLoop } from "../../core/loopEngine.js";
 import { createAnthropicConfig, getProviderModel, validateApiKey, } from "../../utils/providerConfig.js";
-import { composeAbortSignals, createTimeoutController, mergeAbortSignals, } from "../../utils/timeout.js";
+import { composeAbortSignals, createTimeoutController, mergeAbortSignals, TimeoutError, } from "../../utils/timeout.js";
 import { resolveToolChoice } from "../../utils/toolChoice.js";
 import { emitToolEndFromStepFinish } from "../../utils/toolEndEmitter.js";
 import { NoOutputGeneratedError } from "../../utils/generationErrors.js";
@@ -1126,28 +1126,47 @@ export class AnthropicProvider extends BaseProvider {
                     ...(toolChoice ? { tool_choice: toolChoice } : {}),
                     ...(thinking ? { thinking } : {}),
                 };
-                // The 60s anthropic generate default was tuned for the old ~4096
-                // max_tokens. Now that the default ceiling is the model's real max,
-                // a large structured response needs more wall-clock to be produced —
-                // otherwise the inner controller aborts mid-generation (the AI-SDK
-                // doGenerate layer doesn't see the caller's `timeout`). Raise the
-                // floor to 5 min when a large output budget is in play — but only
-                // when the caller did NOT set an explicit timeout: an explicit value
-                // is a contract and must never be silently extended. The abort
-                // signal stays the real bound.
-                const callerTimeout = options
-                    .timeout;
-                const callerSpecifiedTimeout = callerTimeout !== undefined && callerTimeout !== null;
-                const generateTimeoutMs = params.max_tokens > 8192 && !callerSpecifiedTimeout
-                    ? Math.max(getTimeoutForOptions(options), 300_000)
-                    : getTimeoutForOptions(options);
+                // The caller's resolved `timeout` reaches this layer only through
+                // providerOptions.neurolink.timeoutMs (AI-SDK call options carry no
+                // `timeout`; the old `options.timeout` read here never fired on V3).
+                // An explicit value is a per-call contract: never floored, never
+                // extended. Without one, the 60s anthropic default was tuned for the
+                // old ~4096 max_tokens — now that the default ceiling is the model's
+                // real max, raise the floor to 5 min when a large output budget is
+                // in play. The abort signal stays the real bound.
+                const neurolinkNs = options.providerOptions?.neurolink;
+                const forwardedTimeoutMs = typeof neurolinkNs?.timeoutMs === "number" &&
+                    Number.isFinite(neurolinkNs.timeoutMs) &&
+                    neurolinkNs.timeoutMs > 0
+                    ? neurolinkNs.timeoutMs
+                    : undefined;
+                const generateTimeoutMs = forwardedTimeoutMs !== undefined
+                    ? forwardedTimeoutMs
+                    : params.max_tokens > 8192
+                        ? Math.max(getTimeoutForOptions(options), 300_000)
+                        : getTimeoutForOptions(options);
                 const timeoutController = createTimeoutController(generateTimeoutMs, providerName, "generate");
+                const requestSignal = composeAbortSignals(options.abortSignal, timeoutController?.controller.signal);
                 let response;
                 try {
                     response = await client.messages.create(params, {
-                        signal: composeAbortSignals(options.abortSignal, timeoutController?.controller.signal),
+                        signal: requestSignal,
                     });
                 }
+                catch (error) {
+                    // The Anthropic SDK collapses ANY fired signal into its generic
+                    // APIUserAbortError ("Request was aborted."), discarding the
+                    // signal's reason. When the abort came from one of NeuroLink's own
+                    // timers (this per-call timer, or the turn-level one upstream),
+                    // the TimeoutError reason is the honest identity — surface it.
+                    const reason = requestSignal?.aborted
+                        ? requestSignal.reason
+                        : undefined;
+                    if (reason instanceof TimeoutError) {
+                        throw reason;
+                    }
+                    throw error;
+                }
                 finally {
                     timeoutController?.cleanup();
                 }

package/dist/types/conversation.d.ts

@@ -60,6 +60,13 @@ export type ConversationMemoryConfig = {
     summarizationProvider?: string;
     /** Model to use for summarization */
     summarizationModel?: string;
+    /**
+     * Wall-clock cap for one summarization generate call, in milliseconds
+     * (default: 60000). A summary that overruns is dropped, not fatal — the
+     * turn continues without it — so size this for the slowest summary a real
+     * conversation produces rather than losing compaction summaries silently.
+     */
+    summarizationTimeoutMs?: number;
     /** Memory SDK config (condensed key-value memory per user). Set enabled: true to activate. */
     memory?: HippocampusMemory;
     /** Redis configuration (optional) - overrides environment variables */

package/dist/types/externalMcp.d.ts

@@ -51,8 +51,13 @@ export type ExternalMCPServerConfig = {
 export type ExternalMCPServerInstance = {
     /** Server configuration */
     config: ExternalMCPServerConfig;
-    /** Child process (for stdio transport) */
+    /**
+     * Child process handle. Always null for stdio servers: the SDK transport
+     * owns the process and does not expose the handle. Use `pid`.
+     */
     process: ChildProcess | null;
+    /** OS process id of the stdio server, once connected */
+    pid?: number;
     /** MCP client instance */
     client: Client | null;
     /** Transport instance */
@@ -305,8 +310,13 @@ export type ExternalMCPManagerConfig = {
  * active server management (process handles, clients, metrics, etc.)
  */
 export type RuntimeMCPServerInfo = MCPServerInfo & {
-    /** Child process handle (for stdio transport, null for HTTP transports) */
+    /**
+     * Child process handle. Always null for stdio servers: the SDK transport
+     * owns the process and does not expose the handle. Use `pid`.
+     */
     process: import("child_process").ChildProcess | null;
+    /** OS process id of the stdio server, once connected */
+    pid?: number;
     /** MCP client instance for communication */
     client: Client | null;
     /** Transport instance (renamed from 'transport' to avoid conflict with MCPServerInfo.transport) */

package/dist/types/generate.d.ts

@@ -348,7 +348,14 @@ export type GenerateOptions = {
      * 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.
+     * step (default 300s), and use `turnTimeoutMs` (or `abortSignal`) for a
+     * total-turn deadline.
+     *
+     * On the AI-SDK loop path (direct Anthropic, litellm, OpenAI-compatible)
+     * the same split holds only when `turnTimeoutMs` is ALSO set: then this
+     * value bounds each model call and `turnTimeoutMs` bounds the turn. With
+     * `turnTimeoutMs` unset, this value bounds the WHOLE turn there (the
+     * pre-existing defensive behavior, kept for backward compatibility).
      *
      * When set explicitly, a step timeout is surfaced immediately instead of
      * burning internal retries/fallbacks that would re-run the same
@@ -363,9 +370,11 @@ export type GenerateOptions = {
      * imposes no product policy).
      *
      * Enforced by the native Vertex loops (Gemini + Claude) AND the AI-SDK
-     * loop path (litellm and other OpenAI-compatible providers). On the AI-SDK
-     * path, an explicit `timeout` also engages the same wrap-up when
-     * `turnTimeoutMs` is unset. Once the wrap-up window begins (see
+     * loop path (direct Anthropic, litellm and other OpenAI-compatible
+     * providers). On the AI-SDK path this value also owns the whole-turn hard
+     * abort: when set, `timeout` keeps its per-model-call meaning instead of
+     * bounding the entire loop. An explicit `timeout` also engages the same
+     * wrap-up when `turnTimeoutMs` is unset. Once the wrap-up window begins (see
      * `wrapupTimeLeadMs`), the loop forcibly sets `toolChoice: "none"` for the
      * remaining steps — overriding any caller-supplied `toolChoice` or
      * `prepareStep` tool selection — and appends an honest time message that a

package/dist/utils/conversationMemory.js

@@ -593,7 +593,15 @@ export function getEffectiveTokenThreshold(provider, model, envOverride, session
 export async function generateSummary(messages, config, logPrefix = "[ConversationMemory]", previousSummary, requestId) {
     const summarizationPrompt = createSummarizationPrompt(messages, previousSummary);
     const SUMMARIZER_INIT_TIMEOUT = 15_000;
-    const SUMMARIZER_GENERATE_TIMEOUT = 60_000;
+    // Config-driven: a compaction summary of a large conversation routinely
+    // needs more than the old hard-coded 60s, and each overrun silently loses
+    // one summary (non-fatal — the turn continues) with no knob to raise it.
+    const configuredTimeoutMs = config.summarizationTimeoutMs;
+    const SUMMARIZER_GENERATE_TIMEOUT = typeof configuredTimeoutMs === "number" &&
+        Number.isFinite(configuredTimeoutMs) &&
+        configuredTimeoutMs > 0
+        ? configuredTimeoutMs
+        : 60_000;
     try {
         if (!cachedSummarizer) {
             cachedSummarizer = await withTimeout((async () => {

package/dist/utils/errorHandling.js

@@ -1189,7 +1189,11 @@ export function isAbortError(error) {
     if (error instanceof Error &&
         (error.message?.includes("This operation was aborted") ||
             error.message?.includes("The operation was aborted") ||
-            error.message?.includes("The user aborted a request"))) {
+            error.message?.includes("The user aborted a request") ||
+            // Anthropic SDK's APIUserAbortError — name is plain "Error", so only
+            // the message identifies it. Missing this classified real aborts as
+            // provider failures (ERROR log + fallback consulted on a user cancel).
+            error.message?.includes("Request was aborted"))) {
         return true;
     }
     return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "12.7.6",
+  "version": "12.7.8",
   "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": {
@@ -84,7 +84,8 @@
     "test:mcp:http": "pnpm exec tsx test/continuous-test-suite-mcp-http.ts",
     "test:mcp:sdk": "pnpm exec tsx test/continuous-test-suite-mcp-sdk.ts",
     "test:mcp:cli": "pnpm exec tsx test/continuous-test-suite-mcp-cli.ts",
-    "test:mcp:full": "pnpm run test:mcp:infra && pnpm run test:mcp:spans && pnpm run test:mcp:sdk && pnpm run test:mcp:cli && pnpm run test:mcp:http",
+    "test:mcp:stdio-lifecycle": "pnpm exec tsx test/continuous-test-suite-mcp-stdio-lifecycle.ts",
+    "test:mcp:full": "pnpm run test:mcp:infra && pnpm run test:mcp:spans && pnpm run test:mcp:stdio-lifecycle && pnpm run test:mcp:sdk && pnpm run test:mcp:cli && pnpm run test:mcp:http",
     "test:media": "pnpm exec tsx test/continuous-test-suite-media-gen.ts",
     "test:media-registry-collisions": "pnpm exec tsx test/continuous-test-suite-media-registry-collisions.ts",
     "test:memory": "pnpm exec tsx test/continuous-test-suite-memory.ts",