@animalabs/agent-framework 0.5.7 → 0.6.2

package/dist/src/mcpl/server-connection.js

@@ -1,17 +1,25 @@
 /**
  * McplServerConnection — manages a single JSON-RPC 2.0 connection to an MCPL server.
  *
- * Spawns a child process (stdio transport), performs the MCP initialize handshake
- * with MCPL capability negotiation, and provides typed methods for all outbound
- * MCPL messages plus EventEmitter events for inbound messages.
+ * Connects over a pluggable {@link McplTransport} (a spawned stdio child OR a
+ * WebSocket), performs the MCP initialize handshake with MCPL capability
+ * negotiation, and provides typed methods for all outbound MCPL messages plus
+ * EventEmitter events for inbound messages. The handshake, message routing, and
+ * every send path are transport-agnostic — they operate on NDJSON lines, so
+ * stdio and WebSocket behave identically above the transport seam.
  */
-import { spawn } from 'node:child_process';
-import { createInterface } from 'node:readline';
 import { EventEmitter } from 'node:events';
+import { openTransport } from './transport.js';
 import { McplMethod } from './types.js';
 /** Timeout for the initialize handshake in milliseconds.
  *  Spring Boot + JDA servers can take 5-10s to boot, so 30s is safe. */
 const INITIALIZE_TIMEOUT_MS = 30_000;
+/** Default per-request timeout in milliseconds (see McplServerConfig.requestTimeoutMs).
+ *  A live-but-wedged server (accepts requests, never answers, never closes its
+ *  transport) would otherwise freeze the awaiting agent turn forever — no
+ *  endTurn, no further wakes, zero errors anywhere. 60s is generous for real
+ *  tool work while still bounding the hang. */
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
 /** MCP protocol version used in the initialize handshake. */
 const MCP_PROTOCOL_VERSION = '2024-11-05';
 /**
@@ -29,17 +37,28 @@ const MCP_PROTOCOL_VERSION = '2024-11-05';
  * - `'feature-sets-changed'` — Server sent `featureSets/changed`
  * - `'error'`              — Connection-level error
  * - `'close'`              — Connection closed
+ * - `'connect-failed'`     — Initial connect failed; background retry scheduled
+ * - `'reconnect-failed'`   — A background reconnect attempt failed; next retry scheduled
+ * - `'reconnect'`          — Background reconnect succeeded
  */
 export class McplServerConnection extends EventEmitter {
     /** Unique server identifier from config. */
     id;
     /** MCPL capabilities negotiated during the initialize handshake, or null if the server does not support MCPL. */
     capabilities;
-    process;
-    readline;
+    /** The active transport (stdio child or WebSocket). Null for a disconnected
+     *  stub awaiting its first background reconnect. */
+    transport;
+    /** Whether the connection currently has a live transport. False for closed
+     *  connections and disconnected reconnect-stubs awaiting a retry. */
+    get isConnected() {
+        return !this.closed && this.transport !== null;
+    }
     nextRequestId = 1;
     pendingRequests = new Map();
     closed = false;
+    /** Per-request timeout in ms (0 disables). See McplServerConfig.requestTimeoutMs. */
+    requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS;
     // Event buffering: events emitted before ready() are queued, not lost
     readyFlag = false;
     bufferedEvents = [];
@@ -48,22 +67,27 @@ export class McplServerConnection extends EventEmitter {
     hostCapabilities = null;
     reconnectEnabled = false;
     reconnectIntervalMs = 5000;
+    reconnectMaxIntervalMs = 300_000;
     reconnectTimer = null;
-    /** Swaps the line handler on the current child's stderr pipe. Re-bound on reconnect. */
-    rebindStderr = null;
+    /** Consecutive failed connect attempts since the last successful handshake.
+     *  Drives the exponential backoff and is reported on reconnect events. */
+    reconnectAttempts = 0;
+    /** Whether a background reconnect loop will revive this connection after a
+     *  drop. False once close() has been called (explicit close stops retrying). */
+    get willReconnect() {
+        return this.reconnectEnabled;
+    }
     /**
      * Private constructor. Use `McplServerConnection.connect()` instead.
      */
-    constructor(id, capabilities, childProcess, readline) {
+    constructor(id, capabilities, transport) {
         super();
         this.id = id;
         this.capabilities = capabilities;
-        this.process = childProcess;
-        this.readline = readline;
-        // Skip setup for disconnected stubs (process/readline are null)
-        if (childProcess && readline) {
-            this.setupMessageRouting();
-            this.setupLifecycle();
+        this.transport = transport;
+        // Skip setup for disconnected stubs (transport is null).
+        if (transport) {
+            this.wireTransport(transport);
         }
     }
     // ==========================================================================
@@ -97,138 +121,103 @@ export class McplServerConnection extends EventEmitter {
     // Static factory
     // ==========================================================================
     /**
-     * Wire stderr forwarding on a child process. Lines are forwarded to the
-     * supplied callback. The callback can be swapped at any time via `rebind`
-     * (used during reconnect, when we want already-wired pipes to target a new
-     * emitter).
-     */
-    static wireStderrForwarding(child, initialLineHandler) {
-        let onLine = initialLineHandler;
-        let carry = '';
-        child.stderr?.on('data', (chunk) => {
-            const text = carry + chunk.toString('utf8');
-            const lines = text.split('\n');
-            carry = lines.pop() ?? '';
-            for (const line of lines) {
-                if (line.length > 0)
-                    onLine(line);
-            }
-        });
-        return {
-            rebind(next) {
-                onLine = next;
-            },
-        };
-    }
-    /**
-     * Spawn a server process, perform the MCP initialize handshake with MCPL
+     * Open the transport, perform the MCP initialize handshake with MCPL
      * capability negotiation, and return a ready-to-use connection.
      *
-     * Throws if the process cannot be spawned or the handshake times out.
+     * Works over stdio (spawned child) or WebSocket, selected by `config` (see
+     * {@link openTransport}). Throws if the transport can't be opened, the server
+     * closes/errors before the handshake, or the handshake times out.
      */
     static async connect(config, hostCapabilities) {
-        const child = spawn(config.command, config.args ?? [], {
-            stdio: ['pipe', 'pipe', 'pipe'],
-            env: { ...process.env, ...config.env },
-        });
-        // Capture child stderr so it isn't silently dropped. During the handshake
-        // window (before the instance exists) lines are buffered; the buffer is
-        // drained once we have an instance to emit 'stderr' events on.
-        const earlyStderrBuffer = [];
-        const attachStderr = McplServerConnection.wireStderrForwarding(child, (line) => earlyStderrBuffer.push(line));
-        // Fail fast if the process exits before the handshake completes
-        const earlyExitPromise = new Promise((_resolve, reject) => {
-            child.on('error', (err) => {
-                reject(new Error(`Failed to spawn MCPL server "${config.id}": ${err.message}`));
-            });
-            child.on('exit', (code) => {
-                reject(new Error(`MCPL server "${config.id}" exited before handshake (code ${code})`));
-            });
-        });
-        // Set up readline for newline-delimited JSON on stdout
-        const rl = createInterface({ input: child.stdout });
-        // -----------------------------------------------------------------------
-        // Perform initialize handshake
-        // -----------------------------------------------------------------------
-        // Step 1: Send `initialize` request
-        const initId = 0; // use id=0 for the handshake
-        const initRequest = {
-            jsonrpc: '2.0',
-            method: 'initialize',
-            id: initId,
-            params: {
-                protocolVersion: MCP_PROTOCOL_VERSION,
-                capabilities: {
-                    experimental: {
-                        mcpl: hostCapabilities,
-                    },
-                },
-                clientInfo: {
-                    name: 'agent-framework',
-                    version: '1.0.0',
+        const { transport, capabilities } = await McplServerConnection.handshake(config, hostCapabilities);
+        const connection = new McplServerConnection(config.id, capabilities, transport);
+        connection.requestTimeoutMs = config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        // Store config for reconnection
+        if (config.reconnect) {
+            connection.config = config;
+            connection.hostCapabilities = hostCapabilities;
+            connection.reconnectEnabled = true;
+            connection.reconnectIntervalMs = config.reconnectIntervalMs ?? 5000;
+            connection.reconnectMaxIntervalMs = config.reconnectMaxIntervalMs ?? 300_000;
+        }
+        return connection;
+    }
+    /**
+     * Open a fresh transport and run the MCP/MCPL initialize handshake over it,
+     * returning the connected transport plus the negotiated capabilities. Shared
+     * by {@link connect} and {@link attemptReconnect} so both transports handshake
+     * identically. On any failure the transport is closed so a spawned child /
+     * open socket never leaks.
+     */
+    static async handshake(config, hostCapabilities) {
+        const transport = await openTransport(config);
+        try {
+            const initId = 0; // use id=0 for the handshake
+            const initRequest = {
+                jsonrpc: '2.0',
+                method: 'initialize',
+                id: initId,
+                params: {
+                    protocolVersion: MCP_PROTOCOL_VERSION,
+                    capabilities: { experimental: { mcpl: hostCapabilities } },
+                    clientInfo: { name: 'agent-framework', version: '1.0.0' },
                 },
-            },
-        };
-        child.stdin.write(JSON.stringify(initRequest) + '\n');
-        // Step 2: Wait for the initialize response
-        const initResponse = await Promise.race([
-            new Promise((resolve, reject) => {
+            };
+            // Await the initialize response, racing an early transport close/error and
+            // a timeout. All three paths clean up their listeners.
+            const capabilities = await new Promise((resolve, reject) => {
+                const cleanup = () => {
+                    transport.off('line', onLine);
+                    transport.off('close', onClose);
+                    transport.off('error', onError);
+                    clearTimeout(timer);
+                };
                 const onLine = (line) => {
+                    let msg;
                     try {
-                        const msg = JSON.parse(line);
-                        if (msg.id === initId) {
-                            rl.off('line', onLine);
-                            if (msg.error) {
-                                reject(new Error(`MCPL server "${config.id}" initialize error: ${msg.error.message}`));
-                            }
-                            else {
-                                resolve(msg);
-                            }
-                        }
+                        msg = JSON.parse(line);
                     }
                     catch {
-                        // Ignore non-JSON lines (e.g. logback output from Java servers)
+                        return; // Ignore non-JSON lines (e.g. logback output from Java servers)
                     }
+                    if (msg.id !== initId)
+                        return;
+                    cleanup();
+                    if (msg.error) {
+                        reject(new Error(`MCPL server "${config.id}" initialize error: ${msg.error.message}`));
+                        return;
+                    }
+                    const result = msg.result;
+                    const caps = result?.capabilities;
+                    const experimental = caps?.experimental;
+                    resolve(experimental?.mcpl ?? null);
                 };
-                rl.on('line', onLine);
-            }),
-            earlyExitPromise,
-            new Promise((_resolve, reject) => setTimeout(() => {
-                reject(new Error(`MCPL server "${config.id}" initialize handshake timed out`));
-            }, INITIALIZE_TIMEOUT_MS)),
-        ]);
-        // Parse MCPL capabilities from the response
-        const result = initResponse.result;
-        const caps = result?.capabilities;
-        const experimental = caps?.experimental;
-        const mcplCaps = experimental?.mcpl ?? null;
-        // Step 3: Send `initialized` notification (no id)
-        const initializedNotification = {
-            jsonrpc: '2.0',
-            method: 'notifications/initialized',
-        };
-        child.stdin.write(JSON.stringify(initializedNotification) + '\n');
-        // Remove the early-exit listener so normal close handling takes over
-        child.removeAllListeners('exit');
-        child.removeAllListeners('error');
-        const connection = new McplServerConnection(config.id, mcplCaps, child, rl);
-        // Swap the stderr handler to emit events on the instance, then drain
-        // anything that arrived during the handshake window. Keep the rebind
-        // handle on the instance so reconnect can re-target it later.
-        connection.rebindStderr = attachStderr.rebind;
-        attachStderr.rebind((line) => connection.emit('stderr', { line }));
-        for (const line of earlyStderrBuffer) {
-            connection.emit('stderr', { line });
+                const onClose = (info) => {
+                    cleanup();
+                    reject(new Error(`MCPL server "${config.id}" transport closed before handshake completed (${info.reason ?? 'unknown'})`));
+                };
+                const onError = (err) => {
+                    cleanup();
+                    reject(new Error(`MCPL server "${config.id}" transport error during handshake: ${err.message}`));
+                };
+                const timer = setTimeout(() => {
+                    cleanup();
+                    reject(new Error(`MCPL server "${config.id}" initialize handshake timed out`));
+                }, INITIALIZE_TIMEOUT_MS);
+                transport.on('line', onLine);
+                transport.on('close', onClose);
+                transport.on('error', onError);
+                transport.writeLine(JSON.stringify(initRequest));
+            });
+            // Send `initialized` notification (no id)
+            transport.writeLine(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }));
+            return { transport, capabilities };
         }
-        earlyStderrBuffer.length = 0;
-        // Store config for reconnection
-        if (config.reconnect) {
-            connection.config = config;
-            connection.hostCapabilities = hostCapabilities;
-            connection.reconnectEnabled = true;
-            connection.reconnectIntervalMs = config.reconnectIntervalMs ?? 5000;
+        catch (err) {
+            // Never leak the child / socket if the handshake fails.
+            await transport.close().catch(() => { });
+            throw err;
         }
-        return connection;
     }
     /**
      * Connect with reconnect support.
@@ -246,7 +235,12 @@ export class McplServerConnection extends EventEmitter {
             }
             // Non-blocking start: create a disconnected stub that will reconnect in background
             console.error(`MCPL server "${config.id}" initial connect failed, will retry:`, error.message);
-            return McplServerConnection.createDisconnectedStub(config, hostCapabilities);
+            const stub = McplServerConnection.createDisconnectedStub(config, hostCapabilities);
+            // Surface the initial failure. The event is buffered by the emit()
+            // override until the host wires listeners and calls ready(), so it is
+            // not lost in the window before wireMcplEvents runs.
+            stub.emit('connect-failed', { error: error.message, attempt: 0 });
+            return stub;
         }
     }
     /**
@@ -255,28 +249,20 @@ export class McplServerConnection extends EventEmitter {
      * @internal
      */
     static createDisconnectedStub(config, hostCapabilities) {
-        // Use null! for process/readline since the connection is closed
-        const stub = new McplServerConnection(config.id, null, null, null);
+        // Null transport — the stub is closed until its first background reconnect.
+        const stub = new McplServerConnection(config.id, null, null);
         stub.closed = true;
+        stub.requestTimeoutMs = config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
         stub.config = config;
         stub.hostCapabilities = hostCapabilities;
         stub.reconnectEnabled = true;
         stub.reconnectIntervalMs = config.reconnectIntervalMs ?? 5000;
+        stub.reconnectMaxIntervalMs = config.reconnectMaxIntervalMs ?? 300_000;
+        stub.reconnectAttempts = 1; // the initial connect already failed
         // Schedule background reconnect
         stub.scheduleReconnect();
         return stub;
     }
-    /**
-     * Extract internals for transfer during reconnection.
-     * Strips the source connection — caller takes ownership of the process/readline.
-     * @internal Used only by attemptReconnect().
-     */
-    extractInternals() {
-        const result = { process: this.process, readline: this.readline };
-        // Prevent the source connection from killing the transferred process
-        this.closed = true;
-        return result;
-    }
     // ==========================================================================
     // Outbound requests (return Promises)
     // ==========================================================================
@@ -386,80 +372,73 @@ export class McplServerConnection extends EventEmitter {
         this.closed = true;
         // Reject all pending requests
         for (const [id, pending] of this.pendingRequests) {
+            if (pending.timer)
+                clearTimeout(pending.timer);
             pending.reject(new Error(`Connection to MCPL server "${this.id}" closed while awaiting response for ${pending.method} (id=${id})`));
         }
         this.pendingRequests.clear();
-        // Close readline
-        if (this.readline) {
-            this.readline.close();
-        }
-        // Kill the child process
-        if (this.process && !this.process.killed) {
-            this.process.kill();
-        }
-        // Wait for process to actually exit
-        if (this.process) {
-            await new Promise((resolve) => {
-                if (this.process.exitCode !== null || this.process.killed) {
-                    resolve();
-                }
-                else {
-                    this.process.once('exit', () => resolve());
-                }
-            });
+        // Tear down the transport (kills the child / closes the socket). The
+        // transport's own 'close' event is short-circuited by `this.closed` in
+        // setupLifecycle, so this is the single source of the connection 'close'.
+        if (this.transport) {
+            await this.transport.close();
         }
         this.emit('close');
     }
     /**
      * Schedule a background reconnection attempt.
+     *
+     * Delay grows exponentially with consecutive failures (base
+     * `reconnectIntervalMs`, doubling per failure, capped at
+     * `reconnectMaxIntervalMs`) with ±25% jitter so a fleet of servers that
+     * died together doesn't thundering-herd the same instant. The counter
+     * resets on a successful handshake, so a later disconnect starts over at
+     * the base interval.
      */
     scheduleReconnect() {
         if (!this.reconnectEnabled || this.reconnectTimer)
             return;
+        const exponent = Math.max(0, Math.min(this.reconnectAttempts - 1, 30));
+        const uncapped = this.reconnectIntervalMs * 2 ** exponent;
+        const capped = Math.min(uncapped, this.reconnectMaxIntervalMs);
+        const delay = capped * (0.75 + Math.random() * 0.5);
         this.reconnectTimer = setTimeout(() => {
             this.reconnectTimer = null;
             this.attemptReconnect();
-        }, this.reconnectIntervalMs);
+        }, delay);
     }
     /**
-     * Attempt to reconnect by spawning a new process and performing the handshake.
+     * Attempt to reconnect by opening a fresh transport and performing the
+     * handshake, then adopting that transport in place. Unlike the previous
+     * approach this builds no throwaway connection instance, so there are no
+     * leaked listeners on a dead object.
      */
     async attemptReconnect() {
         if (!this.reconnectEnabled || !this.config || !this.hostCapabilities)
             return;
+        // Ordinal of this attempt: 0 was the initial connect, so the Nth retry
+        // reports attempt N (reconnectAttempts counts failures so far).
+        const attempt = Math.max(1, this.reconnectAttempts);
         try {
-            const fresh = await McplServerConnection.connect(this.config, this.hostCapabilities);
-            const internals = fresh.extractInternals();
-            // Transfer state from fresh connection to this instance
-            this.process = internals.process;
-            this.readline = internals.readline;
-            this.capabilities = fresh.capabilities;
+            const { transport, capabilities } = await McplServerConnection.handshake(this.config, this.hostCapabilities);
+            // Adopt the new transport. Listeners were attached to external consumers
+            // on the first wire, so mark ready immediately (re-wire re-binds the
+            // transport-level handlers below).
+            this.transport = transport;
+            this.capabilities = capabilities;
             this.closed = false;
             this.nextRequestId = 1;
             this.pendingRequests.clear();
-            // Re-target stderr forwarding from the throwaway `fresh` instance to `this`.
-            //
-            // Note: this follows the same "transfer internals, leak listeners on the
-            // dead instance" pattern as the message-routing and lifecycle rewiring
-            // below — `fresh`'s own readline 'line' handler and process 'exit'
-            // handler stay registered on the transferred child, short-circuited by
-            // `fresh.closed = true` set in extractInternals(). Rebinding fresh's
-            // stderr listener (rather than removing it) keeps that invariant: if we
-            // ever clean up the message-routing duplication, fresh's stderr data
-            // listener closure-holds onLine and would need the same teardown.
-            if (fresh.rebindStderr) {
-                fresh.rebindStderr((line) => this.emit('stderr', { line }));
-                this.rebindStderr = fresh.rebindStderr;
-            }
-            // Re-wire message routing and lifecycle on the new process
-            this.setupMessageRouting();
-            this.setupLifecycle();
-            this.readyFlag = true; // Listeners already attached from initial wire
+            this.wireTransport(transport);
+            this.readyFlag = true;
             console.error(`MCPL server "${this.id}" reconnected successfully`);
-            this.emit('reconnect');
+            this.reconnectAttempts = 0;
+            this.emit('reconnect', { attempts: attempt });
         }
         catch (error) {
             console.error(`MCPL server "${this.id}" reconnect failed:`, error.message);
+            this.reconnectAttempts = attempt + 1;
+            this.emit('reconnect-failed', { error: error.message, attempt });
             this.scheduleReconnect();
         }
     }
@@ -469,6 +448,13 @@ export class McplServerConnection extends EventEmitter {
     /**
      * Send a JSON-RPC request and return a promise that resolves with the result
      * or rejects with a JSON-RPC error.
+     *
+     * Every request carries a timeout (default 60s, configurable via
+     * McplServerConfig.requestTimeoutMs, 0 disables): a live-but-stuck server
+     * that accepts a request and never answers rejects the pending promise with
+     * a descriptive error instead of freezing the caller forever. For tools/call
+     * the framework maps the rejection to an isError tool_result, so a hung tool
+     * surfaces as a normal tool error and the turn completes.
      */
     sendRequest(method, params) {
         if (this.closed) {
@@ -482,8 +468,22 @@ export class McplServerConnection extends EventEmitter {
             params,
         };
         return new Promise((resolve, reject) => {
-            this.pendingRequests.set(id, { resolve, reject, method });
-            this.process.stdin.write(JSON.stringify(request) + '\n');
+            const pending = { resolve, reject, method };
+            if (this.requestTimeoutMs > 0) {
+                pending.timer = setTimeout(() => {
+                    this.pendingRequests.delete(id);
+                    reject(new Error(`MCPL server "${this.id}" did not respond to ${method} (id=${id}) ` +
+                        `within ${this.requestTimeoutMs}ms — the server may be hung. ` +
+                        `The request was abandoned; the connection remains open. Note the ` +
+                        `tool may still have completed server-side (this is only a response ` +
+                        `timeout, not a cancellation) — verify state before retrying, as a ` +
+                        `blind retry of a stateful/side-effecting tool may duplicate it.`));
+                }, this.requestTimeoutMs);
+                // Don't hold the event loop open for the watchdog alone.
+                pending.timer.unref?.();
+            }
+            this.pendingRequests.set(id, pending);
+            this.transport.writeLine(JSON.stringify(request));
         });
     }
     /**
@@ -498,7 +498,7 @@ export class McplServerConnection extends EventEmitter {
             method,
             params,
         };
-        this.process.stdin.write(JSON.stringify(notification) + '\n');
+        this.transport?.writeLine(JSON.stringify(notification));
     }
     // ==========================================================================
     // Private: inbound message routing
@@ -521,10 +521,22 @@ export class McplServerConnection extends EventEmitter {
         'host/command': 'host-command',
     };
     /**
-     * Wire up readline to route incoming JSON-RPC messages.
+     * Bind all transport-level handlers (inbound routing, lifecycle, stderr) to a
+     * transport. Called from the constructor and again from attemptReconnect when
+     * a new transport is adopted.
+     */
+    wireTransport(transport) {
+        this.setupMessageRouting(transport);
+        this.setupLifecycle(transport);
+        // Surface transport diagnostics (stdio child stderr) as 'stderr' events,
+        // preserving the `{ line }` payload existing consumers expect.
+        transport.on('stderr', (line) => this.emit('stderr', { line }));
+    }
+    /**
+     * Wire up the transport's line stream to route incoming JSON-RPC messages.
      */
-    setupMessageRouting() {
-        this.readline.on('line', (line) => {
+    setupMessageRouting(transport) {
+        transport.on('line', (line) => {
             let msg;
             try {
                 msg = JSON.parse(line);
@@ -564,9 +576,30 @@ export class McplServerConnection extends EventEmitter {
     handleResponse(response) {
         const pending = this.pendingRequests.get(response.id);
         if (!pending) {
+            // Orphaned response — the request already timed out (or was settled) and
+            // was removed from pendingRequests. Stateless late results are harmless to
+            // drop, but a late STATEFUL result carries a `state`/`checkpoint` the
+            // server has already advanced to: dropping it silently diverges the host's
+            // checkpoint tree from the server's, and every subsequent call then sends
+            // stale state. We can't safely re-inject it here (the dispatch context is
+            // gone), but we surface it so the divergence is greppable instead of
+            // invisible.
+            const result = response.result;
+            if (result && typeof result === 'object') {
+                const r = result;
+                if (r.state !== undefined || r.checkpoint !== undefined) {
+                    this.emit('orphaned-response', {
+                        id: response.id,
+                        hadState: r.state !== undefined,
+                        hadCheckpoint: r.checkpoint !== undefined,
+                    });
+                }
+            }
             return; // Orphaned response — ignore
         }
         this.pendingRequests.delete(response.id);
+        if (pending.timer)
+            clearTimeout(pending.timer);
         if (response.error) {
             pending.reject(new Error(`MCPL server "${this.id}" returned error for ${pending.method}: [${response.error.code}] ${response.error.message}`));
         }
@@ -581,7 +614,7 @@ export class McplServerConnection extends EventEmitter {
         if (this.closed)
             return;
         const response = { jsonrpc: '2.0', id, result };
-        this.process.stdin.write(JSON.stringify(response) + '\n');
+        this.transport?.writeLine(JSON.stringify(response));
     }
     /**
      * Send a JSON-RPC error response back to the server.
@@ -594,28 +627,32 @@ export class McplServerConnection extends EventEmitter {
             id,
             error: { code, message, data },
         };
-        this.process.stdin.write(JSON.stringify(response) + '\n');
+        this.transport?.writeLine(JSON.stringify(response));
     }
     // ==========================================================================
     // Private: lifecycle
     // ==========================================================================
     /**
-     * Set up process error/exit handlers.
+     * Set up transport error/close handlers. An unexpected transport close
+     * (child exit or WebSocket drop) rejects in-flight requests, emits 'close',
+     * and — when enabled — schedules a background reconnect.
      */
-    setupLifecycle() {
-        this.process.on('error', (err) => {
-            this.emit('error', new Error(`MCPL server "${this.id}" process error: ${err.message}`));
+    setupLifecycle(transport) {
+        transport.on('error', (err) => {
+            this.emit('error', new Error(`MCPL server "${this.id}" transport error: ${err.message}`));
         });
-        this.process.on('exit', (code, signal) => {
+        transport.on('close', (info) => {
             if (!this.closed) {
                 this.closed = true;
                 // Reject all pending requests
                 for (const [id, pending] of this.pendingRequests) {
-                    pending.reject(new Error(`MCPL server "${this.id}" exited unexpectedly (code=${code}, signal=${signal}) while awaiting ${pending.method} (id=${id})`));
+                    if (pending.timer)
+                        clearTimeout(pending.timer);
+                    pending.reject(new Error(`MCPL server "${this.id}" disconnected unexpectedly (code=${info.code ?? 'n/a'}, signal=${info.signal ?? 'n/a'}, reason=${info.reason ?? 'unknown'}) while awaiting ${pending.method} (id=${id})`));
                 }
                 this.pendingRequests.clear();
-                this.emit('close', code, signal);
-                // Schedule reconnect if enabled (unexpected exit triggers auto-reconnect)
+                this.emit('close', info.code ?? null, info.signal ?? null);
+                // Schedule reconnect if enabled (unexpected disconnect triggers auto-reconnect)
                 if (this.reconnectEnabled) {
                     this.scheduleReconnect();
                 }