@animalabs/agent-framework 0.5.7 → 0.6.2

package/dist/src/mcpl/server-connection.d.ts

@@ -1,12 +1,13 @@
 /**
  * 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 { type ChildProcess } from 'node:child_process';
-import { type Interface as ReadlineInterface } from 'node:readline';
 import { EventEmitter } from 'node:events';
 import type { McplServerConfig, McplCapabilities, McplHostCapabilities, BeforeInferenceParams, BeforeInferenceResult, AfterInferenceParams, AfterInferenceResult, FeatureSetsUpdateParams, InferenceChunkParams, StateRollbackParams, StateRollbackResult, ChannelsOpenParams, ChannelsOpenResult, ChannelsCloseParams, ChannelsCloseResult, ChannelsListResult, ChannelsPublishParams, ChannelsPublishResult, ChannelsOutgoingChunkParams, ChannelsOutgoingCompleteParams, McpToolDefinition, McpToolCallResult } from './types.js';
 /**
@@ -24,26 +25,40 @@ import type { McplServerConfig, McplCapabilities, McplHostCapabilities, BeforeIn
  * - `'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 declare class McplServerConnection extends EventEmitter {
     /** Unique server identifier from config. */
     readonly id: string;
     /** MCPL capabilities negotiated during the initialize handshake, or null if the server does not support MCPL. */
     capabilities: McplCapabilities | null;
-    private process;
-    private readline;
+    /** The active transport (stdio child or WebSocket). Null for a disconnected
+     *  stub awaiting its first background reconnect. */
+    private transport;
+    /** Whether the connection currently has a live transport. False for closed
+     *  connections and disconnected reconnect-stubs awaiting a retry. */
+    get isConnected(): boolean;
     private nextRequestId;
     private pendingRequests;
     private closed;
+    /** Per-request timeout in ms (0 disables). See McplServerConfig.requestTimeoutMs. */
+    private requestTimeoutMs;
     private readyFlag;
     private bufferedEvents;
     private config;
     private hostCapabilities;
     private reconnectEnabled;
     private reconnectIntervalMs;
+    private reconnectMaxIntervalMs;
     private reconnectTimer;
-    /** Swaps the line handler on the current child's stderr pipe. Re-bound on reconnect. */
-    private rebindStderr;
+    /** Consecutive failed connect attempts since the last successful handshake.
+     *  Drives the exponential backoff and is reported on reconnect events. */
+    private reconnectAttempts;
+    /** 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;
     /**
      * Private constructor. Use `McplServerConnection.connect()` instead.
      */
@@ -60,19 +75,22 @@ export declare class McplServerConnection extends EventEmitter {
      */
     emit(event: string | symbol, ...args: unknown[]): boolean;
     /**
-     * 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;
-    /**
-     * 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 connect(config: McplServerConfig, hostCapabilities: McplHostCapabilities): Promise<McplServerConnection>;
+    /**
+     * 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 handshake;
     /**
      * Connect with reconnect support.
      * When `config.reconnect` is true and the initial connection fails,
@@ -86,15 +104,6 @@ export declare class McplServerConnection extends EventEmitter {
      * @internal
      */
     private static createDisconnectedStub;
-    /**
-     * 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;
-    };
     /** Send `context/beforeInference` and await result. */
     sendBeforeInference(params: BeforeInferenceParams): Promise<BeforeInferenceResult>;
     /**
@@ -146,15 +155,32 @@ export declare class McplServerConnection extends EventEmitter {
     close(): Promise<void>;
     /**
      * 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;
     /**
-     * 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 attemptReconnect;
     /**
      * 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;
     /**
@@ -166,7 +192,13 @@ export declare class McplServerConnection extends EventEmitter {
      */
     private static readonly METHOD_TO_EVENT;
     /**
-     * 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;
+    /**
+     * Wire up the transport's line stream to route incoming JSON-RPC messages.
      */
     private setupMessageRouting;
     /**
@@ -182,7 +214,9 @@ export declare class McplServerConnection extends EventEmitter {
      */
     private sendErrorResponse;
     /**
-     * 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;
 }

package/dist/src/mcpl/server-connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-connection.d.ts","sourceRoot":"","sources":["../../../src/mcpl/server-connection.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAmB,KAAK,SAAS,IAAI,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACrF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EAGpB,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,uBAAuB,EACvB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,EACrB,2BAA2B,EAC3B,8BAA8B,EAC9B,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAoBpB;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;IACpD,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,iHAAiH;IACjH,YAAY,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAEtC,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,QAAQ,CAAoB;IACpC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,eAAe,CAA8C;IACrE,OAAO,CAAC,MAAM,CAAS;IAGvB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,cAAc,CAAiD;IAGvE,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,gBAAgB,CAAqC;IAC7D,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,mBAAmB,CAAQ;IACnC,OAAO,CAAC,cAAc,CAA8C;IAEpE,wFAAwF;IACxF,OAAO,CAAC,YAAY,CAAyD;IAE7E;;OAEG;IACH,OAAO;IAuBP;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAQb;;;OAGG;IACM,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO;IAalE;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAqBnC;;;;;OAKG;WACU,OAAO,CAClB,MAAM,EAAE,gBAAgB,EACxB,gBAAgB,EAAE,oBAAoB,GACrC,OAAO,CAAC,oBAAoB,CAAC;IAwHhC;;;;;OAKG;WACU,oBAAoB,CAC/B,MAAM,EAAE,gBAAgB,EACxB,gBAAgB,EAAE,oBAAoB,GACrC,OAAO,CAAC,oBAAoB,CAAC;IAchC;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAkBrC;;;;OAIG;IACH,gBAAgB,IAAI;QAAE,OAAO,EAAE,YAAY,CAAC;QAAC,QAAQ,EAAE,iBAAiB,CAAA;KAAE;IAW1E,uDAAuD;IACvD,mBAAmB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAIlF;;;;OAIG;IACH,kBAAkB,CAAC,MAAM,EAAE,oBAAoB,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAQ1G,8CAA8C;IAC9C,qBAAqB,CAAC,MAAM,EAAE,uBAAuB,GAAG,IAAI;IAI5D,2CAA2C;IAC3C,kBAAkB,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI;IAItD,sDAAsD;IACtD,iBAAiB,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAI5E,qDAAqD;IACrD,gBAAgB,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAIzE,sDAAsD;IACtD,iBAAiB,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAI5E,qDAAqD;IACrD,gBAAgB,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAI/C;;;;OAIG;IACH,mBAAmB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC;IAQzF,mDAAmD;IACnD,yBAAyB,CAAC,MAAM,EAAE,2BAA2B,GAAG,IAAI;IAIpE,sDAAsD;IACtD,4BAA4B,CAAC,MAAM,EAAE,8BAA8B,GAAG,IAAI;IAI1E;;;;;;uEAMmE;IACnE,kBAAkB,CAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,EAAE,GAAE,OAAO,GAAG,MAAgB,GAC7B,IAAI;IAUP,kEAAkE;IAClE,aAAa,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,iBAAiB,EAAE,CAAA;KAAE,CAAC;IAIxD,wGAAwG;IACxG,aAAa,CACX,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,WAAW,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GACrD,OAAO,CAAC,iBAAiB,CAAC;IAW7B,+FAA+F;IACzF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA2C5B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IASzB;;OAEG;YACW,gBAAgB;IA+C9B;;;OAGG;IACH,OAAO,CAAC,WAAW;IAmBnB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAiBxB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAarC;IAEF;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAsC3B;;OAEG;IACH,OAAO,CAAC,cAAc;IAiBtB;;OAEG;IACH,OAAO,CAAC,YAAY;IAMpB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAczB;;OAEG;IACH,OAAO,CAAC,cAAc;CA4BvB"}
+{"version":3,"file":"server-connection.d.ts","sourceRoot":"","sources":["../../../src/mcpl/server-connection.ts"],"names":[],"mappings":"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"}