@animalabs/agent-framework 0.1.0

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

@@ -0,0 +1,174 @@
+/**
+ * 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.
+ */
+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';
+/**
+ * McplServerConnection manages a single JSON-RPC 2.0 connection to an
+ * MCPL server over stdio. Use the static `connect()` factory to create
+ * and initialize a connection.
+ *
+ * Events emitted:
+ * - `'push-event'`        — Server sent `push/event`
+ * - `'inference-request'`  — Server sent `inference/request`
+ * - `'scope-elevate'`      — Server sent `scope/elevate`
+ * - `'channels-register'`  — Server sent `channels/register`
+ * - `'channels-changed'`   — Server sent `channels/changed`
+ * - `'channels-incoming'`  — Server sent `channels/incoming`
+ * - `'feature-sets-changed'` — Server sent `featureSets/changed`
+ * - `'error'`              — Connection-level error
+ * - `'close'`              — Connection closed
+ */
+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;
+    private nextRequestId;
+    private pendingRequests;
+    private closed;
+    private readyFlag;
+    private bufferedEvents;
+    private config;
+    private hostCapabilities;
+    private reconnectEnabled;
+    private reconnectIntervalMs;
+    private reconnectTimer;
+    /**
+     * Private constructor. Use `McplServerConnection.connect()` instead.
+     */
+    private constructor();
+    /**
+     * Mark the connection as ready — flushes any events that arrived between
+     * construction (when setupMessageRouting starts emitting) and now (when
+     * the caller has attached listeners via wireMcplEvents).
+     */
+    ready(): void;
+    /**
+     * Override emit to buffer server→host events until ready() is called.
+     * Lifecycle events ('close', 'error', 'reconnect') always pass through.
+     */
+    emit(event: string | symbol, ...args: unknown[]): boolean;
+    /**
+     * Spawn a server process, 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.
+     */
+    static connect(config: McplServerConfig, hostCapabilities: McplHostCapabilities): Promise<McplServerConnection>;
+    /**
+     * Connect with reconnect support.
+     * When `config.reconnect` is true and the initial connection fails,
+     * resolves immediately with null capabilities and retries in the background.
+     * Adapted from Anarchid/agent-framework@mcpl-module-proto.
+     */
+    static connectWithReconnect(config: McplServerConfig, hostCapabilities: McplHostCapabilities): Promise<McplServerConnection>;
+    /**
+     * Create a disconnected stub connection that will reconnect in the background.
+     * Used when initial connect fails and reconnect is enabled.
+     * @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>;
+    /**
+     * Send `context/afterInference`.
+     * When `blocking` is true, sends as a request and awaits the result.
+     * When `blocking` is false (or omitted), sends as a notification.
+     */
+    sendAfterInference(params: AfterInferenceParams, blocking?: boolean): Promise<AfterInferenceResult | void>;
+    /** Send `featureSets/update` notification. */
+    sendFeatureSetsUpdate(params: FeatureSetsUpdateParams): void;
+    /** Send `inference/chunk` notification. */
+    sendInferenceChunk(params: InferenceChunkParams): void;
+    /** Send `state/rollback` request and await result. */
+    sendStateRollback(params: StateRollbackParams): Promise<StateRollbackResult>;
+    /** Send `channels/open` request and await result. */
+    sendChannelsOpen(params: ChannelsOpenParams): Promise<ChannelsOpenResult>;
+    /** Send `channels/close` request and await result. */
+    sendChannelsClose(params: ChannelsCloseParams): Promise<ChannelsCloseResult>;
+    /** Send `channels/list` request and await result. */
+    sendChannelsList(): Promise<ChannelsListResult>;
+    /**
+     * Send `channels/publish`.
+     * May be sent as a request (if an ACK is desired) or notification.
+     * When `params.stream` is true, sends as a notification (no ACK).
+     */
+    sendChannelsPublish(params: ChannelsPublishParams): Promise<ChannelsPublishResult | void>;
+    /** Send `channels/outgoing/chunk` notification. */
+    sendChannelsOutgoingChunk(params: ChannelsOutgoingChunkParams): void;
+    /** Send `channels/outgoing/complete` notification. */
+    sendChannelsOutgoingComplete(params: ChannelsOutgoingCompleteParams): void;
+    /** Send `channels/typing` notification (best-effort). */
+    sendChannelsTyping(channelId: string): void;
+    /** Send `tools/list` and return the server's tool definitions. */
+    sendToolsList(): Promise<{
+        tools: McpToolDefinition[];
+    }>;
+    /** Send `tools/call` and return the result. Optionally includes state/checkpoint for stateful tools. */
+    sendToolsCall(name: string, args: Record<string, unknown>, stateParams?: {
+        state?: unknown;
+        checkpoint?: string;
+    }): Promise<McpToolCallResult>;
+    /** Close the connection: disable reconnect, kill the child process, and clean up resources. */
+    close(): Promise<void>;
+    /**
+     * Schedule a background reconnection attempt.
+     */
+    private scheduleReconnect;
+    /**
+     * Attempt to reconnect by spawning a new process and performing the handshake.
+     */
+    private attemptReconnect;
+    /**
+     * Send a JSON-RPC request and return a promise that resolves with the result
+     * or rejects with a JSON-RPC error.
+     */
+    private sendRequest;
+    /**
+     * Send a JSON-RPC notification (no `id`, no response expected).
+     */
+    private sendNotification;
+    /**
+     * Map from JSON-RPC method name to the EventEmitter event name.
+     */
+    private static readonly METHOD_TO_EVENT;
+    /**
+     * Wire up readline to route incoming JSON-RPC messages.
+     */
+    private setupMessageRouting;
+    /**
+     * Handle a JSON-RPC response by resolving/rejecting the corresponding pending request.
+     */
+    private handleResponse;
+    /**
+     * Send a successful JSON-RPC response back to the server.
+     */
+    private sendResponse;
+    /**
+     * Send a JSON-RPC error response back to the server.
+     */
+    private sendErrorResponse;
+    /**
+     * Set up process error/exit handlers.
+     */
+    private setupLifecycle;
+}
+//# sourceMappingURL=server-connection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server-connection.d.ts","sourceRoot":"","sources":["../../../src/mcpl/server-connection.ts"],"names":[],"mappings":"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"}