@animalabs/agent-framework 0.5.7 → 0.6.2

package/src/mcpl/server-connection.ts

@@ -1,15 +1,18 @@
 /**
  * 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, type ChildProcess } from 'node:child_process';
-import { createInterface, type Interface as ReadlineInterface } from 'node:readline';
 import { EventEmitter } from 'node:events';
 
+import { openTransport, type McplTransport, type TransportCloseInfo } from './transport.js';
+
 import type {
   McplServerConfig,
   McplCapabilities,
@@ -43,6 +46,13 @@ import { McplMethod } from './types.js';
  *  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';
 
@@ -53,6 +63,8 @@ interface PendingRequest {
   resolve: (result: unknown) => void;
   reject: (error: Error) => void;
   method: string;
+  /** Per-request timeout timer; cleared on response/close/timeout. */
+  timer?: ReturnType<typeof setTimeout>;
 }
 
 /**
@@ -70,6 +82,9 @@ interface PendingRequest {
  * - `'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. */
@@ -78,12 +93,23 @@ export class McplServerConnection extends EventEmitter {
   /** MCPL capabilities negotiated during the initialize handshake, or null if the server does not support MCPL. */
   capabilities: McplCapabilities | null;
 
-  private process: ChildProcess;
-  private readline: ReadlineInterface;
+  /** The active transport (stdio child or WebSocket). Null for a disconnected
+   *  stub awaiting its first background reconnect. */
+  private transport: McplTransport | null;
+
+  /** Whether the connection currently has a live transport. False for closed
+   *  connections and disconnected reconnect-stubs awaiting a retry. */
+  get isConnected(): boolean {
+    return !this.closed && this.transport !== null;
+  }
+
   private nextRequestId = 1;
   private pendingRequests = new Map<string | number, PendingRequest>();
   private closed = false;
 
+  /** Per-request timeout in ms (0 disables). See McplServerConfig.requestTimeoutMs. */
+  private requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS;
+
   // Event buffering: events emitted before ready() are queued, not lost
   private readyFlag = false;
   private bufferedEvents: Array<{ event: string; args: unknown[] }> = [];
@@ -93,10 +119,17 @@ export class McplServerConnection extends EventEmitter {
   private hostCapabilities: McplHostCapabilities | null = null;
   private reconnectEnabled = false;
   private reconnectIntervalMs = 5000;
+  private reconnectMaxIntervalMs = 300_000;
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  /** Consecutive failed connect attempts since the last successful handshake.
+   *  Drives the exponential backoff and is reported on reconnect events. */
+  private reconnectAttempts = 0;
 
-  /** Swaps the line handler on the current child's stderr pipe. Re-bound on reconnect. */
-  private rebindStderr: ((next: (line: string) => void) => void) | null = null;
+  /** Whether a background reconnect loop will revive this connection after a
+   *  drop. False once close() has been called (explicit close stops retrying). */
+  get willReconnect(): boolean {
+    return this.reconnectEnabled;
+  }
 
   /**
    * Private constructor. Use `McplServerConnection.connect()` instead.
@@ -104,19 +137,16 @@ export class McplServerConnection extends EventEmitter {
   private constructor(
     id: string,
     capabilities: McplCapabilities | null,
-    childProcess: ChildProcess,
-    readline: ReadlineInterface,
+    transport: McplTransport | null,
   ) {
     super();
     this.id = id;
     this.capabilities = capabilities;
-    this.process = childProcess;
-    this.readline = readline;
+    this.transport = transport;
 
-    // Skip setup for disconnected stubs (process/readline are null)
-    if (childProcess && readline) {
-      this.setupMessageRouting();
-      this.setupLifecycle();
+    // Skip setup for disconnected stubs (transport is null).
+    if (transport) {
+      this.wireTransport(transport);
     }
   }
 
@@ -155,159 +185,115 @@ export class McplServerConnection extends EventEmitter {
   // ==========================================================================
 
   /**
-   * 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).
-   */
-  private static wireStderrForwarding(
-    child: ChildProcess,
-    initialLineHandler: (line: string) => void,
-  ): { rebind: (next: (line: string) => void) => void } {
-    let onLine = initialLineHandler;
-    let carry = '';
-    child.stderr?.on('data', (chunk: Buffer) => {
-      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: McplServerConfig,
     hostCapabilities: McplHostCapabilities,
   ): Promise<McplServerConnection> {
-    const child = spawn(config.command, config.args ?? [], {
-      stdio: ['pipe', 'pipe', 'pipe'],
-      env: { ...process.env, ...config.env },
-    });
+    const { transport, capabilities } = await McplServerConnection.handshake(config, hostCapabilities);
 
-    // 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: string[] = [];
-    const attachStderr = McplServerConnection.wireStderrForwarding(child, (line) =>
-      earlyStderrBuffer.push(line),
-    );
-
-    // Fail fast if the process exits before the handshake completes
-    const earlyExitPromise = new Promise<never>((_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})`));
-      });
-    });
+    const connection = new McplServerConnection(config.id, capabilities, transport);
+    connection.requestTimeoutMs = config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
 
-    // Set up readline for newline-delimited JSON on stdout
-    const rl = createInterface({ input: child.stdout! });
+    // 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;
+    }
 
-    // -----------------------------------------------------------------------
-    // Perform initialize handshake
-    // -----------------------------------------------------------------------
+    return connection;
+  }
 
-    // Step 1: Send `initialize` request
-    const initId = 0; // use id=0 for the handshake
-    const initRequest: JsonRpcRequest = {
-      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');
+  /**
+   * 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.
+   */
+  private static async handshake(
+    config: McplServerConfig,
+    hostCapabilities: McplHostCapabilities,
+  ): Promise<{ transport: McplTransport; capabilities: McplCapabilities | null }> {
+    const transport = await openTransport(config);
 
-    // Step 2: Wait for the initialize response
-    const initResponse = await Promise.race([
-      new Promise<JsonRpcResponse>((resolve, reject) => {
+    try {
+      const initId = 0; // use id=0 for the handshake
+      const initRequest: JsonRpcRequest = {
+        jsonrpc: '2.0',
+        method: 'initialize',
+        id: initId,
+        params: {
+          protocolVersion: MCP_PROTOCOL_VERSION,
+          capabilities: { experimental: { mcpl: hostCapabilities } },
+          clientInfo: { name: 'agent-framework', version: '1.0.0' },
+        },
+      };
+
+      // 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<McplCapabilities | null>((resolve, reject) => {
+        const cleanup = () => {
+          transport.off('line', onLine);
+          transport.off('close', onClose);
+          transport.off('error', onError);
+          clearTimeout(timer);
+        };
         const onLine = (line: string) => {
+          let msg: JsonRpcResponse;
           try {
-            const msg = JSON.parse(line) as JsonRpcResponse;
-            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) as JsonRpcResponse;
           } 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 as Record<string, unknown> | undefined;
+          const caps = result?.capabilities as Record<string, unknown> | undefined;
+          const experimental = caps?.experimental as Record<string, unknown> | undefined;
+          resolve((experimental?.mcpl as McplCapabilities) ?? null);
+        };
+        const onClose = (info: TransportCloseInfo) => {
+          cleanup();
+          reject(new Error(`MCPL server "${config.id}" transport closed before handshake completed (${info.reason ?? 'unknown'})`));
+        };
+        const onError = (err: Error) => {
+          cleanup();
+          reject(new Error(`MCPL server "${config.id}" transport error during handshake: ${err.message}`));
         };
-        rl.on('line', onLine);
-      }),
-      earlyExitPromise,
-      new Promise<never>((_resolve, reject) =>
-        setTimeout(() => {
+        const timer = setTimeout(() => {
+          cleanup();
           reject(new Error(`MCPL server "${config.id}" initialize handshake timed out`));
-        }, INITIALIZE_TIMEOUT_MS),
-      ),
-    ]);
-
-    // Parse MCPL capabilities from the response
-    const result = initResponse.result as Record<string, unknown> | undefined;
-    const caps = result?.capabilities as Record<string, unknown> | undefined;
-    const experimental = caps?.experimental as Record<string, unknown> | undefined;
-    const mcplCaps = (experimental?.mcpl as McplCapabilities) ?? null;
-
-    // Step 3: Send `initialized` notification (no id)
-    const initializedNotification: JsonRpcRequest = {
-      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');
+        }, INITIALIZE_TIMEOUT_MS);
 
-    const connection = new McplServerConnection(config.id, mcplCaps, child, rl);
+        transport.on('line', onLine);
+        transport.on('close', onClose);
+        transport.on('error', onError);
+        transport.writeLine(JSON.stringify(initRequest));
+      });
 
-    // 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: string) => connection.emit('stderr', { line }));
-    for (const line of earlyStderrBuffer) {
-      connection.emit('stderr', { line });
-    }
-    earlyStderrBuffer.length = 0;
+      // Send `initialized` notification (no id)
+      transport.writeLine(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }));
 
-    // Store config for reconnection
-    if (config.reconnect) {
-      connection.config = config;
-      connection.hostCapabilities = hostCapabilities;
-      connection.reconnectEnabled = true;
-      connection.reconnectIntervalMs = config.reconnectIntervalMs ?? 5000;
+      return { transport, capabilities };
+    } catch (err) {
+      // Never leak the child / socket if the handshake fails.
+      await transport.close().catch(() => { /* best effort */ });
+      throw err;
     }
-
-    return connection;
   }
 
   /**
@@ -329,7 +315,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 as 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 as Error).message, attempt: 0 });
+      return stub;
     }
   }
 
@@ -342,13 +333,16 @@ export class McplServerConnection extends EventEmitter {
     config: McplServerConfig,
     hostCapabilities: McplHostCapabilities,
   ): McplServerConnection {
-    // Use null! for process/readline since the connection is closed
-    const stub = new McplServerConnection(config.id, null, null! as ChildProcess, null! as ReadlineInterface);
+    // 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();
@@ -356,18 +350,6 @@ export class McplServerConnection extends EventEmitter {
     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(): { process: ChildProcess; readline: ReadlineInterface } {
-    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)
   // ==========================================================================
@@ -501,29 +483,16 @@ export class McplServerConnection extends EventEmitter {
 
     // 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<void>((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');
@@ -531,58 +500,65 @@ export class McplServerConnection extends EventEmitter {
 
   /**
    * 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.
    */
   private scheduleReconnect(): void {
     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.
    */
   private async attemptReconnect(): Promise<void> {
     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();
+      const { transport, capabilities } = await McplServerConnection.handshake(
+        this.config,
+        this.hostCapabilities,
+      );
 
-      // Transfer state from fresh connection to this instance
-      this.process = internals.process;
-      this.readline = internals.readline;
-      this.capabilities = fresh.capabilities;
+      // 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: string) => 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 as Error).message);
+      this.reconnectAttempts = attempt + 1;
+      this.emit('reconnect-failed', { error: (error as Error).message, attempt });
       this.scheduleReconnect();
     }
   }
@@ -594,6 +570,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.
    */
   private sendRequest(method: string, params: Record<string, unknown>): Promise<unknown> {
     if (this.closed) {
@@ -609,8 +592,24 @@ export class McplServerConnection extends EventEmitter {
     };
 
     return new Promise((resolve, reject) => {
-      this.pendingRequests.set(id, { resolve, reject, method });
-      this.process.stdin!.write(JSON.stringify(request) + '\n');
+      const pending: PendingRequest = { 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));
     });
   }
 
@@ -627,7 +626,7 @@ export class McplServerConnection extends EventEmitter {
       method,
       params,
     };
-    this.process.stdin!.write(JSON.stringify(notification) + '\n');
+    this.transport?.writeLine(JSON.stringify(notification));
   }
 
   // ==========================================================================
@@ -653,10 +652,23 @@ export class McplServerConnection extends EventEmitter {
   };
 
   /**
-   * 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.
+   */
+  private wireTransport(transport: McplTransport): void {
+    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: string) => this.emit('stderr', { line }));
+  }
+
+  /**
+   * Wire up the transport's line stream to route incoming JSON-RPC messages.
    */
-  private setupMessageRouting(): void {
-    this.readline.on('line', (line) => {
+  private setupMessageRouting(transport: McplTransport): void {
+    transport.on('line', (line: string) => {
       let msg: JsonRpcRequest | JsonRpcResponse;
       try {
         msg = JSON.parse(line);
@@ -699,10 +711,30 @@ export class McplServerConnection extends EventEmitter {
   private handleResponse(response: JsonRpcResponse): void {
     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 as { state?: unknown; checkpoint?: unknown };
+        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(
@@ -719,7 +751,7 @@ export class McplServerConnection extends EventEmitter {
   private sendResponse(id: string | number, result: unknown): void {
     if (this.closed) return;
     const response: JsonRpcResponse = { jsonrpc: '2.0', id, result };
-    this.process.stdin!.write(JSON.stringify(response) + '\n');
+    this.transport?.writeLine(JSON.stringify(response));
   }
 
   /**
@@ -732,7 +764,7 @@ export class McplServerConnection extends EventEmitter {
       id,
       error: { code, message, data },
     };
-    this.process.stdin!.write(JSON.stringify(response) + '\n');
+    this.transport?.writeLine(JSON.stringify(response));
   }
 
   // ==========================================================================
@@ -740,30 +772,33 @@ export class McplServerConnection extends EventEmitter {
   // ==========================================================================
 
   /**
-   * 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.
    */
-  private setupLifecycle(): void {
-    this.process.on('error', (err) => {
-      this.emit('error', new Error(`MCPL server "${this.id}" process error: ${err.message}`));
+  private setupLifecycle(transport: McplTransport): void {
+    transport.on('error', (err: Error) => {
+      this.emit('error', new Error(`MCPL server "${this.id}" transport error: ${err.message}`));
     });
 
-    this.process.on('exit', (code, signal) => {
+    transport.on('close', (info: TransportCloseInfo) => {
       if (!this.closed) {
         this.closed = true;
 
         // Reject all pending requests
         for (const [id, pending] of this.pendingRequests) {
+          if (pending.timer) clearTimeout(pending.timer);
           pending.reject(
             new Error(
-              `MCPL server "${this.id}" exited unexpectedly (code=${code}, signal=${signal}) while awaiting ${pending.method} (id=${id})`,
+              `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);
+        this.emit('close', info.code ?? null, info.signal ?? null);
 
-        // Schedule reconnect if enabled (unexpected exit triggers auto-reconnect)
+        // Schedule reconnect if enabled (unexpected disconnect triggers auto-reconnect)
         if (this.reconnectEnabled) {
           this.scheduleReconnect();
         }