@mxf-dev/core 2.0.1 → 2.0.3

package/dist/protocols/mcp/providers/OpenRouterMcpClient.d.ts

@@ -76,19 +76,43 @@ export declare class OpenRouterMcpClient extends BaseMcpClient {
      * - absent/no enabled flag → send nothing and let the provider default apply.
      */
     private applyReasoningParam;
-    private static requestQueue;
-    private static isProcessingQueue;
+    private requestQueue;
+    private isProcessingQueue;
     private static readonly REQUEST_DELAY_MS;
     private networkRecovery;
     private jsonRecovery;
+    private requestTimeoutMs;
+    private streamIdleTimeoutMs;
+    private slowRequestWarnMs;
     /**
      * Process the request queue sequentially to prevent concurrent requests
      */
-    private static processQueue;
+    private processQueue;
     /**
      * Add a request to the queue and process it
      */
-    private static queueRequest;
+    private queueRequest;
+    /**
+     * Start the slow-request watchdog for one LLM request.
+     *
+     * Emits a WARN once the request has been in flight for slowRequestWarnMs, and
+     * another WARN at completion if the total time crossed the threshold. Together
+     * with the timeout ERROR this makes slow-vs-hung distinguishable in production
+     * logs: a slow request logs WARN…WARN(completed), a hung one WARN…ERROR(timeout).
+     *
+     * Returns a finish() that must be called exactly once when the request settles.
+     */
+    private startSlowRequestWatch;
+    /**
+     * Build, log, and return the error for a timed-out LLM request.
+     *
+     * The error is named 'TimeoutError' and flagged isRequestTimeout so
+     * classifyNetworkError maps it to the non-retryable REQUEST_TIMEOUT type:
+     * the caller sees the failure immediately instead of a silent retry loop.
+     * Logged at ERROR here — unconditionally — because this is the line that
+     * turns a production stall from invisible into diagnosable.
+     */
+    private buildRequestTimeoutError;
     /**
      * Initialize the OpenRouter provider
      */
@@ -138,6 +162,12 @@ export declare class OpenRouterMcpClient extends BaseMcpClient {
      * Makes the same request but with `stream: true`, parses SSE chunks,
      * calls onChunk for each partial token, and returns the accumulated final response.
      *
+     * Deliberately NOT wrapped in networkRecovery.executeWithRetry: by the time a
+     * streaming request fails, chunks may already have been delivered to the
+     * consumer via onChunk, and a retry would replay them. Failures — including
+     * the idle-watchdog timeout inside executeStreamingRequest — propagate to the
+     * caller instead.
+     *
      * @param context - Complete agent context from SDK
      * @param options - Additional options (must include stream: true)
      * @param onChunk - Callback invoked for each streaming chunk

package/dist/protocols/mcp/providers/OpenRouterMcpClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OpenRouterMcpClient.d.ts","sourceRoot":"","sources":["../../../../src/protocols/mcp/providers/OpenRouterMcpClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAElC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACH,UAAU,EACV,OAAO,EACP,cAAc,EAOjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AAyEnE;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,aAAa;IAElD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAG1D,OAAO,CAAC,MAAM,CAAwD;IAItE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAM7C;;IAOF;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAMhC;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IA6B1B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,sBAAsB;IAS9B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,mBAAmB;IAgB3B,OAAO,CAAC,MAAM,CAAC,YAAY,CAAiC;IAC5D,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAS;IAGzC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAwE;IAGhH,OAAO,CAAC,eAAe,CAAuC;IAG9D,OAAO,CAAC,YAAY,CAAsB;IAE1C;;OAEG;mBACkB,YAAY;IAwBjC;;OAEG;mBACkB,YAAY;IAgBjC;;OAEG;cACa,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BnD;;;OAGG;IACH,OAAO,CAAC,+BAA+B;IA8BvC;;;;;OAKG;IACH,OAAO,CAAC,wBAAwB;IAIhC;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAkG5B;;;;;;;;;;;;;;;OAeG;IACI,eAAe,CAClB,OAAO,EAAE,YAAY,EACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC9B,UAAU,CAAC,cAAc,CAAC;IAiC7B;;OAEG;YACW,mBAAmB;IA2CjC;;;;;;;;;OASG;YACW,wBAAwB;IAetC;;;;OAIG;YACW,uBAAuB;IA+NrC;;;;OAIG;IACH,OAAO,CAAC,4BAA4B;IAkGpC;;;;;;;OAOG;cACa,mBAAmB,CAC/B,QAAQ,EAAE,UAAU,EAAE,EACtB,KAAK,CAAC,EAAE,OAAO,EAAE,EACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC9B,OAAO,CAAC,cAAc,CAAC;IAmC1B;;;OAGG;YACW,8BAA8B;IAqB5C;;OAEG;YACW,4BAA4B;CA+J7C"}
+{"version":3,"file":"OpenRouterMcpClient.d.ts","sourceRoot":"","sources":["../../../../src/protocols/mcp/providers/OpenRouterMcpClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAElC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACH,UAAU,EACV,OAAO,EACP,cAAc,EAOjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AAqGnE;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,aAAa;IAElD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAG1D,OAAO,CAAC,MAAM,CAAwD;IAItE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAM7C;;IAOF;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAMhC;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IA6B1B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,sBAAsB;IAS9B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,mBAAmB;IAqB3B,OAAO,CAAC,YAAY,CAAiC;IACrD,OAAO,CAAC,iBAAiB,CAAS;IAGlC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAwE;IAGhH,OAAO,CAAC,eAAe,CAAuC;IAG9D,OAAO,CAAC,YAAY,CAAsB;IAK1C,OAAO,CAAC,gBAAgB,CAAU;IAKlC,OAAO,CAAC,mBAAmB,CAAU;IAIrC,OAAO,CAAC,iBAAiB,CAAS;IAElC;;OAEG;YACW,YAAY;IAwB1B;;OAEG;YACW,YAAY;IAgB1B;;;;;;;;;OASG;IACH,OAAO,CAAC,qBAAqB;IAoC7B;;;;;;;;OAQG;IACH,OAAO,CAAC,wBAAwB;IAsBhC;;OAEG;cACa,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IAsCnD;;;OAGG;IACH,OAAO,CAAC,+BAA+B;IA8BvC;;;;;OAKG;IACH,OAAO,CAAC,wBAAwB;IAIhC;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAkG5B;;;;;;;;;;;;;;;OAeG;IACI,eAAe,CAClB,OAAO,EAAE,YAAY,EACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC9B,UAAU,CAAC,cAAc,CAAC;IAiC7B;;OAEG;YACW,mBAAmB;IAgDjC;;;;;;;;;;;;;;;OAeG;YACW,wBAAwB;IAqBtC;;;;OAIG;YACW,uBAAuB;IAiTrC;;;;OAIG;IACH,OAAO,CAAC,4BAA4B;IAkGpC;;;;;;;OAOG;cACa,mBAAmB,CAC/B,QAAQ,EAAE,UAAU,EAAE,EACtB,KAAK,CAAC,EAAE,OAAO,EAAE,EACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC9B,OAAO,CAAC,cAAc,CAAC;IAmC1B;;;OAGG;YACW,8BAA8B;IAqB5C;;OAEG;YACW,4BAA4B;CAgM7C"}

package/dist/protocols/mcp/providers/OpenRouterMcpClient.js

@@ -36,6 +36,32 @@ import { convertToolsToProviderFormat } from '../utils/ToolHandlers.js';
 import { getMessageConverter } from '../converters/UnifiedMessageConverter.js';
 import { MessageFormat } from '../converters/IFormatConverter.js';
 import { OpenRouterMessageAdapter } from '../converters/adapters/OpenRouterMessageAdapter.js';
+/**
+ * Read a positive integer from the environment, failing fast on garbage.
+ * These values bound how long a hung request can stay silent — a NaN or zero
+ * from a typo'd env var must not silently disable that bound.
+ */
+const parsePositiveIntEnv = (name, defaultValue) => {
+    const raw = process.env[name];
+    if (raw === undefined || raw === '') {
+        return defaultValue;
+    }
+    const parsed = parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`${name} must be a positive integer, got "${raw}"`);
+    }
+    return parsed;
+};
+/**
+ * True when an error came from an aborted fetch. AbortSignal.timeout() rejects
+ * with a DOMException named 'TimeoutError' (Node and Bun); a manual
+ * controller.abort() rejects with 'AbortError'. This client owns every signal it
+ * passes to fetch, so either name means our own timeout fired.
+ */
+const isAbortOrTimeoutError = (error) => {
+    const name = error?.name;
+    return name === 'TimeoutError' || name === 'AbortError';
+};
 /**
  * OpenRouter implementation of the MCP client with network recovery
  */
@@ -142,9 +168,14 @@ export class OpenRouterMcpClient extends BaseMcpClient {
             requestBody.reasoning = { enabled: false };
         }
     }
-    // Request queue to prevent concurrent requests that might cause JSON parsing issues
-    static requestQueue = [];
-    static isProcessingQueue = false;
+    // Per-instance request queue: keeps one client's requests ordered and spaced.
+    // This used to be static (class-level), which serialized every request from
+    // every client instance in the process through one queue — one hung request
+    // starved every agent's LLM calls, not just its own. Instance scoping plus the
+    // per-request timeout below bounds the damage a single request can do to the
+    // agent that issued it.
+    requestQueue = [];
+    isProcessingQueue = false;
     // Configurable delay between requests - reduced from 500ms to 100ms default for better performance
     // Set OPENROUTER_REQUEST_QUEUE_DELAY_MS=0 to disable queueing delay entirely
     static REQUEST_DELAY_MS = parseInt(process.env.OPENROUTER_REQUEST_QUEUE_DELAY_MS || '100', 10);
@@ -152,16 +183,27 @@ export class OpenRouterMcpClient extends BaseMcpClient {
     networkRecovery = null;
     // JSON recovery manager
     jsonRecovery;
+    // Hard cap on a single completion request (fetch + body). Generous because
+    // reasoning models legitimately run for minutes; finite because a request
+    // with no bound turns a hung connection into permanent silence.
+    requestTimeoutMs = 300000;
+    // Max silence between SSE chunks on the streaming path. OpenRouter emits
+    // keepalive comment lines every few seconds while a model is thinking, so a
+    // long quiet gap means a dead connection, not a slow model.
+    streamIdleTimeoutMs = 120000;
+    // Threshold for the slow-request WARN that makes slow-vs-hung visible in
+    // production logs before any timeout fires.
+    slowRequestWarnMs = 60000;
     /**
      * Process the request queue sequentially to prevent concurrent requests
      */
-    static async processQueue() {
-        if (OpenRouterMcpClient.isProcessingQueue || OpenRouterMcpClient.requestQueue.length === 0) {
+    async processQueue() {
+        if (this.isProcessingQueue || this.requestQueue.length === 0) {
             return;
         }
-        OpenRouterMcpClient.isProcessingQueue = true;
-        while (OpenRouterMcpClient.requestQueue.length > 0) {
-            const request = OpenRouterMcpClient.requestQueue.shift();
+        this.isProcessingQueue = true;
+        while (this.requestQueue.length > 0) {
+            const request = this.requestQueue.shift();
             try {
                 await request();
             }
@@ -169,16 +211,16 @@ export class OpenRouterMcpClient extends BaseMcpClient {
                 // Request will handle its own error, just continue processing
             }
             // Wait between requests to prevent rate limiting
-            if (OpenRouterMcpClient.requestQueue.length > 0) {
+            if (this.requestQueue.length > 0) {
                 await new Promise(resolve => setTimeout(resolve, OpenRouterMcpClient.REQUEST_DELAY_MS));
             }
         }
-        OpenRouterMcpClient.isProcessingQueue = false;
+        this.isProcessingQueue = false;
     }
     /**
      * Add a request to the queue and process it
      */
-    static async queueRequest(requestFn) {
+    async queueRequest(requestFn) {
         return new Promise((resolve, reject) => {
             const wrappedRequest = async () => {
                 try {
@@ -189,14 +231,79 @@ export class OpenRouterMcpClient extends BaseMcpClient {
                     reject(error);
                 }
             };
-            OpenRouterMcpClient.requestQueue.push(wrappedRequest);
-            OpenRouterMcpClient.processQueue();
+            this.requestQueue.push(wrappedRequest);
+            this.processQueue();
         });
     }
+    /**
+     * Start the slow-request watchdog for one LLM request.
+     *
+     * Emits a WARN once the request has been in flight for slowRequestWarnMs, and
+     * another WARN at completion if the total time crossed the threshold. Together
+     * with the timeout ERROR this makes slow-vs-hung distinguishable in production
+     * logs: a slow request logs WARN…WARN(completed), a hung one WARN…ERROR(timeout).
+     *
+     * Returns a finish() that must be called exactly once when the request settles.
+     */
+    startSlowRequestWatch(kind, model, agentId, requestBytes) {
+        const startedAt = Date.now();
+        let finished = false;
+        const timer = setTimeout(() => {
+            this.logger.warn(`⏱️ OpenRouter ${kind} request still in flight after ${this.slowRequestWarnMs}ms: ` +
+                `model=${model}, agent=${agentId}, request=${(requestBytes / 1024).toFixed(1)}KB`);
+        }, this.slowRequestWarnMs);
+        return {
+            // Idempotent. The completed-WARN is success-only: failures carry their
+            // elapsed time in their own ERROR log, and a "completed" line for a
+            // request that timed out would be a lie.
+            finish: (succeeded = true) => {
+                if (finished) {
+                    return;
+                }
+                finished = true;
+                clearTimeout(timer);
+                const elapsedMs = Date.now() - startedAt;
+                if (succeeded && elapsedMs >= this.slowRequestWarnMs) {
+                    this.logger.warn(`⏱️ OpenRouter ${kind} request completed after ${elapsedMs}ms: ` +
+                        `model=${model}, agent=${agentId}`);
+                }
+            }
+        };
+    }
+    /**
+     * Build, log, and return the error for a timed-out LLM request.
+     *
+     * The error is named 'TimeoutError' and flagged isRequestTimeout so
+     * classifyNetworkError maps it to the non-retryable REQUEST_TIMEOUT type:
+     * the caller sees the failure immediately instead of a silent retry loop.
+     * Logged at ERROR here — unconditionally — because this is the line that
+     * turns a production stall from invisible into diagnosable.
+     */
+    buildRequestTimeoutError(params) {
+        const message = `⛔ OpenRouter ${params.kind} request timed out (${params.detail}) after ${params.elapsedMs}ms ` +
+            `(limit ${params.limitMs}ms): model=${params.model}, agent=${params.agentId}, ` +
+            `request=${(params.requestBytes / 1024).toFixed(1)}KB, messages=${params.messageCount}`;
+        this.logger.error(message);
+        const error = new Error(message);
+        error.name = 'TimeoutError';
+        error.isRequestTimeout = true;
+        return error;
+    }
     /**
      * Initialize the OpenRouter provider
      */
     async initializeProvider() {
+        // Per-request bounds. All three must be positive and finite — a missing or
+        // disabled bound is how a hung connection becomes permanent silence that
+        // only a consumer-side backstop can end.
+        //
+        // requestTimeoutMs defaults to 5 minutes: reasoning models legitimately run
+        // for minutes on large contexts, so this is a hang detector, not a latency
+        // budget. It is enforced twice: as an AbortSignal on the fetch itself and
+        // as an operation bound inside NetworkRecoveryManager.executeWithRetry.
+        this.requestTimeoutMs = parsePositiveIntEnv('OPENROUTER_REQUEST_TIMEOUT_MS', 300000);
+        this.streamIdleTimeoutMs = parsePositiveIntEnv('OPENROUTER_STREAM_IDLE_TIMEOUT_MS', 120000);
+        this.slowRequestWarnMs = parsePositiveIntEnv('OPENROUTER_SLOW_REQUEST_WARN_MS', 60000);
         // Initialize network recovery configuration from environment or defaults
         const networkRecoveryConfig = {
             ...DEFAULT_NETWORK_RECOVERY_CONFIG,
@@ -206,7 +313,7 @@ export class OpenRouterMcpClient extends BaseMcpClient {
             retryMultiplier: parseFloat(process.env.OPENROUTER_RETRY_MULTIPLIER || '2'),
             circuitBreakerThreshold: parseInt(process.env.OPENROUTER_CIRCUIT_BREAKER_THRESHOLD || '5'),
             circuitBreakerCooldownMs: parseInt(process.env.OPENROUTER_CIRCUIT_BREAKER_COOLDOWN_MS || '60000'),
-            requestTimeoutMs: parseInt(process.env.OPENROUTER_REQUEST_TIMEOUT_MS || '30000'),
+            requestTimeoutMs: this.requestTimeoutMs,
             enableGracefulDegradation: process.env.OPENROUTER_ENABLE_GRACEFUL_DEGRADATION !== 'false',
             enableDetailedLogging: process.env.OPENROUTER_ENABLE_DETAILED_LOGGING !== 'false'
         };
@@ -414,11 +521,13 @@ export class OpenRouterMcpClient extends BaseMcpClient {
             this.logger.debug(`Messages adjusted during transformation: ${openRouterMessages.length} → ${transformedMessages.length} (orphaned tool results dropped)`);
         }
         // Messages are already in OpenRouter format - send directly
-        return await OpenRouterMcpClient.queueRequest(async () => {
+        return await this.queueRequest(async () => {
             if (!this.networkRecovery) {
                 throw new Error('Network recovery not initialized');
             }
-            const result = await this.networkRecovery.executeWithRetry(() => this.executeOpenRouterRequestDirect(transformedMessages, context.availableTools, options), extractStatusCodeFromError);
+            const result = await this.networkRecovery.executeWithRetry(() => this.executeOpenRouterRequestDirect(transformedMessages, context.availableTools, 
+            // agentId rides along for the slow-request WARN and timeout logs
+            { ...options, agentId: context.agentId }), extractStatusCodeFromError);
             if (!result.success) {
                 if (result.circuitBreakerTriggered) {
                     throw new Error(result.error.message);
@@ -433,6 +542,12 @@ export class OpenRouterMcpClient extends BaseMcpClient {
      * Makes the same request but with `stream: true`, parses SSE chunks,
      * calls onChunk for each partial token, and returns the accumulated final response.
      *
+     * Deliberately NOT wrapped in networkRecovery.executeWithRetry: by the time a
+     * streaming request fails, chunks may already have been delivered to the
+     * consumer via onChunk, and a retry would replay them. Failures — including
+     * the idle-watchdog timeout inside executeStreamingRequest — propagate to the
+     * caller instead.
+     *
      * @param context - Complete agent context from SDK
      * @param options - Additional options (must include stream: true)
      * @param onChunk - Callback invoked for each streaming chunk
@@ -443,8 +558,10 @@ export class OpenRouterMcpClient extends BaseMcpClient {
         const openRouterMessages = this.structureMessagesFromContext(context);
         const converter = getMessageConverter('client');
         const transformedMessages = converter.transform(openRouterMessages, MessageFormat.OPENROUTER);
-        return await OpenRouterMcpClient.queueRequest(async () => {
-            return this.executeStreamingRequest(transformedMessages, context.availableTools, options, onChunk);
+        return await this.queueRequest(async () => {
+            return this.executeStreamingRequest(transformedMessages, context.availableTools, 
+            // agentId rides along for the slow-request WARN and timeout logs
+            { ...options, agentId: context.agentId }, onChunk);
         });
     }
     /**
@@ -479,20 +596,88 @@ export class OpenRouterMcpClient extends BaseMcpClient {
             Object.assign(requestBody, options.providerOptions);
         }
         const headers = this.buildOpenRouterHeaders(options);
-        const response = await fetch(`${this.baseUrl}/chat/completions`, {
-            method: 'POST',
-            headers,
-            body: JSON.stringify(requestBody)
+        // Serialize once so the logged request size is exactly what went on the wire
+        const requestBodyJson = JSON.stringify(requestBody);
+        const requestBytes = Buffer.byteLength(requestBodyJson, 'utf8');
+        const agentId = options?.agentId || 'unknown';
+        const requestStartedAt = Date.now();
+        const slowWatch = this.startSlowRequestWatch('streaming', model, agentId, requestBytes);
+        // Idle watchdog for the SSE stream. A healthy stream is never silent for
+        // long — OpenRouter emits keepalive comment lines every few seconds while a
+        // model is thinking — so silence past streamIdleTimeoutMs means the
+        // connection is dead, not that the model is slow. The watchdog is re-armed
+        // on every read; there is deliberately NO total-time cap here, because an
+        // actively producing stream is healthy no matter how long it runs.
+        //
+        // Each read (and the initial fetch) races against abortPromise as well as
+        // carrying the AbortController signal: the signal cancels the real network
+        // request, the race guarantees the await itself resolves even if the
+        // underlying stream implementation ignores the abort.
+        const controller = new AbortController();
+        let headersReceived = false;
+        let idleTimer;
+        const armIdleWatchdog = () => {
+            clearTimeout(idleTimer);
+            idleTimer = setTimeout(() => controller.abort(), this.streamIdleTimeoutMs);
+        };
+        // Plain sentinel rejection — enrichment and logging happen exactly once,
+        // in the catch blocks below, regardless of whether this promise or the
+        // fetch/read rejection wins the race.
+        const abortPromise = new Promise((_, reject) => {
+            controller.signal.addEventListener('abort', () => {
+                const sentinel = new Error('OpenRouter streaming request aborted by idle watchdog');
+                sentinel.name = 'AbortError';
+                reject(sentinel);
+            }, { once: true });
         });
-        if (!response.ok) {
-            const errorText = await response.text();
-            const error = new Error(`OpenRouter API error [${response.status}]: ${errorText}`);
-            error.status = response.status;
-            error.statusCode = response.status;
-            throw error;
+        // Converts an abort/timeout rejection into the logged, non-retryable
+        // request-timeout error; returns any other error unchanged.
+        const normalizeStreamError = (error) => {
+            if (error?.isRequestTimeout || !isAbortOrTimeoutError(error)) {
+                return error;
+            }
+            return this.buildRequestTimeoutError({
+                kind: 'streaming',
+                detail: headersReceived
+                    ? `no SSE data for ${this.streamIdleTimeoutMs}ms`
+                    : `no response headers within ${this.streamIdleTimeoutMs}ms`,
+                model,
+                agentId,
+                elapsedMs: Date.now() - requestStartedAt,
+                limitMs: this.streamIdleTimeoutMs,
+                requestBytes,
+                messageCount: openRouterMessages.length
+            });
+        };
+        armIdleWatchdog();
+        let response;
+        try {
+            response = await Promise.race([
+                fetch(`${this.baseUrl}/chat/completions`, {
+                    method: 'POST',
+                    headers,
+                    body: requestBodyJson,
+                    signal: controller.signal
+                }),
+                abortPromise
+            ]);
+            headersReceived = true;
+            armIdleWatchdog();
+            if (!response.ok) {
+                const errorText = await response.text();
+                const error = new Error(`OpenRouter API error [${response.status}]: ${errorText}`);
+                error.status = response.status;
+                error.statusCode = response.status;
+                throw error;
+            }
+            if (!response.body) {
+                throw new Error('No response body for streaming request');
+            }
         }
-        if (!response.body) {
-            throw new Error('No response body for streaming request');
+        catch (error) {
+            clearTimeout(idleTimer);
+            slowWatch.finish(false);
+            throw normalizeStreamError(error);
         }
         this.logger.debug(`📡 OpenRouter SSE: Response received, status=${response.status}, starting stream parse`);
         // Parse SSE stream and accumulate the full response
@@ -511,7 +696,10 @@ export class OpenRouterMcpClient extends BaseMcpClient {
         const toolCallAccumulators = new Map();
         try {
             while (true) {
-                const { done, value } = await reader.read();
+                // Race against the idle watchdog: reader.read() on a dead
+                // connection can otherwise pend forever with nothing logged.
+                const { done, value } = await Promise.race([reader.read(), abortPromise]);
+                armIdleWatchdog();
                 if (done)
                     break;
                 buffer += decoder.decode(value, { stream: true });
@@ -605,7 +793,17 @@ export class OpenRouterMcpClient extends BaseMcpClient {
                 }
             }
         }
+        catch (error) {
+            // Cancel the underlying stream so the connection is torn down; the
+            // losing reader.read() from the race is settled by the cancel/abort
+            // and its rejection is already observed by Promise.race.
+            slowWatch.finish(false);
+            reader.cancel().catch(() => undefined);
+            throw normalizeStreamError(error);
+        }
         finally {
+            clearTimeout(idleTimer);
+            slowWatch.finish();
             reader.releaseLock();
         }
         this.logger.debug(`📡 OpenRouter SSE: Stream complete. Content=${accumulatedContent.length}chars, Reasoning=${accumulatedReasoning.length}chars, ToolCalls=${toolCallAccumulators.size}, Finish=${finishReason}`);
@@ -745,7 +943,7 @@ export class OpenRouterMcpClient extends BaseMcpClient {
         // Apply transformations (reordering)
         const transformedMessages = converter.transform(openRouterMessages, MessageFormat.OPENROUTER);
         // Send directly
-        return await OpenRouterMcpClient.queueRequest(async () => {
+        return await this.queueRequest(async () => {
             if (!this.networkRecovery) {
                 throw new Error('Network recovery not initialized');
             }
@@ -845,44 +1043,73 @@ export class OpenRouterMcpClient extends BaseMcpClient {
             if (requestBody.tools && requestBody.tools.length > 0) {
                 // console.log(`   Tools: ${requestBody.tools.map((t: any) => t.function.name).join(', ')}`);
             }
-            // Make the API request
-            const response = await fetch(`${this.baseUrl}/chat/completions`, {
-                method: 'POST',
-                headers,
-                body: JSON.stringify(requestBody)
-            });
-            // Log response status
-            // Check for errors with enhanced error information
-            if (!response.ok) {
-                let errorText = await response.text();
-                this.logger.error(`🔧 DEBUG: Error response text: ${errorText}`);
-                let errorMessage = errorText;
-                let rateLimitInfo = {};
-                try {
-                    const errorJson = JSON.parse(errorText);
-                    errorMessage = errorJson.error?.message || errorText;
-                    // Extract rate limit information if available
-                    if (response.status === 429) {
-                        rateLimitInfo = {
-                            retryAfter: response.headers.get('retry-after'),
-                            rateLimitLimit: response.headers.get('x-ratelimit-limit'),
-                            rateLimitRemaining: response.headers.get('x-ratelimit-remaining'),
-                            rateLimitReset: response.headers.get('x-ratelimit-reset')
-                        };
+            // Serialize once so the logged request size is exactly what went on the wire
+            const requestBodyJson = JSON.stringify(requestBody);
+            const requestBytes = Buffer.byteLength(requestBodyJson, 'utf8');
+            const agentId = options?.agentId || 'unknown';
+            const requestStartedAt = Date.now();
+            const slowWatch = this.startSlowRequestWatch('completion', model, agentId, requestBytes);
+            let responseText;
+            try {
+                // AbortSignal.timeout bounds the entire request — connect, headers,
+                // and body read — so a hung connection surfaces as an error instead
+                // of indefinite silence. Reasoning models can legitimately take
+                // minutes; the default limit is sized for that (see initializeProvider).
+                const response = await fetch(`${this.baseUrl}/chat/completions`, {
+                    method: 'POST',
+                    headers,
+                    body: requestBodyJson,
+                    signal: AbortSignal.timeout(this.requestTimeoutMs)
+                });
+                // Check for errors with enhanced error information
+                if (!response.ok) {
+                    let errorText = await response.text();
+                    this.logger.error(`🔧 DEBUG: Error response text: ${errorText}`);
+                    let errorMessage = errorText;
+                    let rateLimitInfo = {};
+                    try {
+                        const errorJson = JSON.parse(errorText);
+                        errorMessage = errorJson.error?.message || errorText;
+                        // Extract rate limit information if available
+                        if (response.status === 429) {
+                            rateLimitInfo = {
+                                retryAfter: response.headers.get('retry-after'),
+                                rateLimitLimit: response.headers.get('x-ratelimit-limit'),
+                                rateLimitRemaining: response.headers.get('x-ratelimit-remaining'),
+                                rateLimitReset: response.headers.get('x-ratelimit-reset')
+                            };
+                        }
+                    }
+                    catch (e) {
+                        // Use error text as is if not JSON
                     }
+                    // Create detailed error with status code
+                    const error = new Error(`OpenRouter API error [${response.status}]: ${errorMessage}`);
+                    error.status = response.status;
+                    error.statusCode = response.status;
+                    error.rateLimitInfo = rateLimitInfo;
+                    throw error;
                 }
-                catch (e) {
-                    // Use error text as is if not JSON
+                // Get response text for JSON parsing
+                responseText = await response.text();
+                slowWatch.finish();
+            }
+            catch (error) {
+                slowWatch.finish(false);
+                if (isAbortOrTimeoutError(error)) {
+                    throw this.buildRequestTimeoutError({
+                        kind: 'completion',
+                        detail: 'no response within the request timeout',
+                        model,
+                        agentId,
+                        elapsedMs: Date.now() - requestStartedAt,
+                        limitMs: this.requestTimeoutMs,
+                        requestBytes,
+                        messageCount: openRouterMessages.length
+                    });
                 }
-                // Create detailed error with status code
-                const error = new Error(`OpenRouter API error [${response.status}]: ${errorMessage}`);
-                error.status = response.status;
-                error.statusCode = response.status;
-                error.rateLimitInfo = rateLimitInfo;
                 throw error;
             }
-            // Get response text for JSON parsing
-            const responseText = await response.text();
             // Check if response is empty
             if (!responseText || responseText.length === 0) {
                 this.logger.error('🔧 ERROR: Empty response from OpenRouter API');
@@ -901,6 +1128,11 @@ export class OpenRouterMcpClient extends BaseMcpClient {
             return this.convertToMcpResponse(openRouterResponse);
         }
         catch (error) {
+            // Request timeouts are already logged with full context and must keep
+            // their name/flags so NetworkRecovery classifies them as non-retryable.
+            if (error?.isRequestTimeout === true) {
+                throw error;
+            }
             this.logger.error(`🔧 ERROR in executeOpenRouterRequest: ${error instanceof Error ? error.message : String(error)}`);
             if (error instanceof Error && error.stack) {
                 this.logger.error(`🔧 ERROR STACK: ${error.stack}`);