@apnex/network-adapter 0.1.0

package/dist/wire/mcp-transport.js

@@ -0,0 +1,447 @@
+/**
+ * McpTransport — first `ITransport` implementation, backed by the MCP
+ * SDK's `Client` + `StreamableHTTPClientTransport`.
+ *
+ * Phase 2 of the L4/L7 refactor: extracted alongside the existing
+ * `McpConnectionManager`, which stays intact for the rest of the
+ * migration. Nothing in the current runtime uses this file yet — it
+ * exists so the Phase-2 gap tests can exercise the L4 surface in
+ * isolation and prove the split holds before Phase 3 relocates the
+ * session FSM.
+ *
+ * ## What this class owns (L4)
+ *
+ *   - The MCP wire: SDK `Client` + `StreamableHTTPClientTransport`.
+ *   - SSE liveness: first-keepalive deadline, mid-stream watchdog,
+ *     heartbeat POST loop.
+ *   - Wire-level reconnection: on SSE death or heartbeat failure it
+ *     tears down the SDK client and rebuilds a fresh one. Callers see
+ *     only `reconnecting` + `reconnected` wire events.
+ *   - Untyped `request(method, params)` over MCP `callTool`.
+ *   - `listMethods()` via MCP `listTools`.
+ *
+ * ## What this class deliberately does NOT own
+ *
+ *   - `register_role`. The bare register_role call that the legacy
+ *     `McpConnectionManager` fires during `connect()` is a session
+ *     concern — it binds the MCP session to an engineer role on the
+ *     Hub. `McpTransport.connect()` returns once the MCP wire is
+ *     initialized, *without* calling register_role. The caller
+ *     (future `IAgentClient`) issues the role call via
+ *     `transport.request("register_role", {role})` itself.
+ *   - Session FSM. No synchronizing / streaming vocabulary, no
+ *     sync buffer, no `completeSync()`.
+ *   - `session_invalid` classification and retry. Callers see the
+ *     raw error from `request()` and reconnect at the session layer.
+ *
+ * ## Hub-event push delivery
+ *
+ * SSE notifications land on the MCP client's `LoggingMessageNotification`
+ * handler. This class splits them into two streams:
+ *
+ *   - `logger === "keepalive"` frames feed the SSE watchdog and are
+ *     NOT forwarded to subscribers — they are wire noise.
+ *   - `logger === "hub-event"` frames are emitted as
+ *     `{ type: "push", method: "hub-event", payload }` via the
+ *     `onWireEvent` stream. Classification, dedup, and routing happen
+ *     above this layer.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { LoggingMessageNotificationSchema } from "@modelcontextprotocol/sdk/types.js";
+import { normalizeToILogger } from "../logger.js";
+/**
+ * Wire-level reconnect backoff curve. Pure function so the invariant
+ * (start at `baseDelay`, double each consecutive failure, clamp at
+ * `maxDelay`) is unit-testable without spinning a real wire.
+ *
+ * The cap on the exponent (`6`) matches the legacy manager: after six
+ * consecutive failures we're pegged at 60s and further failures don't
+ * push the delay higher — they just sit at the cap until a keepalive
+ * arrives and resets `consecutiveReconnects` to zero.
+ */
+export function computeReconnectBackoff(consecutiveReconnects, baseDelay, maxDelay = 60_000) {
+    const exp = Math.min(Math.max(consecutiveReconnects, 0), 6);
+    return Math.min(baseDelay * Math.pow(2, exp), maxDelay);
+}
+export class McpTransport {
+    cfg;
+    log;
+    client = null;
+    sdkTransport = null;
+    _wireState = "disconnected";
+    handlers = [];
+    // SSE liveness
+    lastKeepaliveAt = 0;
+    sseVerified = false;
+    // Timers
+    heartbeatTimer = null;
+    sseWatchdogTimer = null;
+    firstKeepaliveTimer = null;
+    reconnectTimer = null;
+    // Metrics
+    totalReconnects = 0;
+    consecutiveReconnects = 0;
+    lastReconnectCause;
+    requestsInFlight = 0;
+    // Re-entrancy guard: prevents overlapping reconnects.
+    reconnecting = false;
+    // True once `close()` was called — suppresses further reconnect attempts.
+    closed = false;
+    constructor(config) {
+        this.cfg = {
+            url: config.url,
+            token: config.token,
+            heartbeatInterval: config.heartbeatInterval ?? 30_000,
+            sseKeepaliveTimeout: config.sseKeepaliveTimeout ?? 90_000,
+            firstKeepaliveDeadline: config.firstKeepaliveDeadline ?? 60_000,
+            sseWatchdogInterval: config.sseWatchdogInterval ?? 30_000,
+            reconnectDelay: config.reconnectDelay ?? 5_000,
+            getLastEventId: config.getLastEventId,
+        };
+        this.log = normalizeToILogger(config.logger, "McpTransport");
+    }
+    // ── ITransport: public surface ──────────────────────────────────────
+    get wireState() {
+        return this._wireState;
+    }
+    async connect() {
+        if (this._wireState === "connected" || this._wireState === "connecting") {
+            this.log.log("transport.connect.ignored", { wireState: this._wireState }, `connect() ignored in wireState=${this._wireState}`);
+            return;
+        }
+        this.closed = false;
+        this.transition("connecting");
+        try {
+            await this.createWire();
+            this.transition("connected");
+            this.startHeartbeat();
+            this.startSseWatchdog();
+            this.startFirstKeepaliveDeadline();
+        }
+        catch (err) {
+            this.log.log("transport.connect.failed", { error: String(err) }, `connect failed: ${err}`);
+            this.transition("disconnected");
+            throw err;
+        }
+    }
+    async close() {
+        this.closed = true;
+        this.cancelReconnectTimer();
+        this.stopHeartbeat();
+        this.stopSseWatchdog();
+        this.cancelFirstKeepaliveDeadline();
+        const wasConnected = this._wireState !== "disconnected";
+        this.transition("disconnected");
+        await this.teardownWire();
+        if (wasConnected) {
+            this.emit({ type: "closed", reason: "caller-closed" });
+        }
+    }
+    async request(method, params) {
+        if (this._wireState !== "connected" || !this.client) {
+            throw new Error(`McpTransport.request: wire is ${this._wireState}`);
+        }
+        this.requestsInFlight++;
+        try {
+            const result = await this.client.callTool({
+                name: method,
+                arguments: params,
+            });
+            const content = result.content;
+            if (content?.[0]?.text) {
+                try {
+                    return JSON.parse(content[0].text);
+                }
+                catch {
+                    return content[0].text;
+                }
+            }
+            return null;
+        }
+        finally {
+            this.requestsInFlight--;
+        }
+    }
+    async listMethods() {
+        if (this._wireState !== "connected" || !this.client)
+            return [];
+        try {
+            const { tools } = await this.client.listTools();
+            return tools.map((t) => t.name);
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Escape hatch for shims that need full MCP tool definitions
+     * (name + inputSchema + description), not just method names.
+     * Consumed by proxy shims that re-advertise the Hub's tool surface
+     * to another MCP client (e.g. Claude Code stdio proxy).
+     */
+    async listToolsRaw() {
+        if (this._wireState !== "connected" || !this.client)
+            return [];
+        try {
+            const { tools } = await this.client.listTools();
+            return tools;
+        }
+        catch {
+            return [];
+        }
+    }
+    onWireEvent(handler) {
+        this.handlers.push(handler);
+    }
+    getMetrics() {
+        return {
+            wireState: this._wireState,
+            totalReconnects: this.totalReconnects,
+            consecutiveReconnects: this.consecutiveReconnects,
+            lastReconnectCause: this.lastReconnectCause,
+            lastKeepaliveAt: this.lastKeepaliveAt || undefined,
+            requestsInFlight: this.requestsInFlight,
+        };
+    }
+    /**
+     * Test-only helper. Session IDs are an MCP-specific concept exposed
+     * here so Phase-2 integration tests can assert that a wire reconnect
+     * rebuilds the session. Not part of `ITransport`.
+     */
+    getSessionId() {
+        return this.sdkTransport?.sessionId ?? undefined;
+    }
+    // ── Internal: wire lifecycle ────────────────────────────────────────
+    async createWire() {
+        const headers = {
+            "Content-Type": "application/json",
+            Accept: "application/json, text/event-stream",
+        };
+        if (this.cfg.token) {
+            headers["Authorization"] = `Bearer ${this.cfg.token}`;
+        }
+        // Mission-56 W2.2: attach `Last-Event-ID` when the layer above
+        // (McpAgentClient) has observed at least one Hub event. The Hub's
+        // W1b wrapper backfills Messages with id > lastEventId before
+        // resuming live emit. Cold-start (provider returns undefined or no
+        // provider configured) falls through to the stream-all-with-soft-cap
+        // path on the Hub side.
+        const lastEventId = this.cfg.getLastEventId?.();
+        if (lastEventId !== undefined && lastEventId !== "") {
+            headers["Last-Event-ID"] = lastEventId;
+        }
+        // Same rationale as McpConnectionManager: disable the SDK's
+        // internal SSE reconnection so our watchdog is the single authority
+        // for liveness. A split-brain where the SDK reopens the stream
+        // internally would leave our notification handler wired to the
+        // dead one.
+        this.sdkTransport = new StreamableHTTPClientTransport(new URL(this.cfg.url), {
+            requestInit: { headers },
+            reconnectionOptions: {
+                initialReconnectionDelay: 1000,
+                maxReconnectionDelay: 30_000,
+                reconnectionDelayGrowFactor: 1.5,
+                maxRetries: 0,
+            },
+        });
+        this.client = new Client({ name: "ois-mcp-transport", version: "1.0.0" }, { capabilities: {} });
+        this.sseVerified = false;
+        this.lastKeepaliveAt = 0;
+        this.client.setNotificationHandler(LoggingMessageNotificationSchema, (notification) => {
+            const params = notification.params;
+            if (!params)
+                return;
+            if (params.logger === "keepalive") {
+                this.lastKeepaliveAt = Date.now();
+                if (!this.sseVerified) {
+                    this.sseVerified = true;
+                    this.cancelFirstKeepaliveDeadline();
+                    this.log.log("transport.sse.verified", undefined, "SSE verified (first keepalive received)");
+                }
+                return;
+            }
+            if (params.logger === "hub-event" && params.data) {
+                this.emit({
+                    type: "push",
+                    method: "hub-event",
+                    payload: params.data,
+                });
+            }
+        });
+        this.sdkTransport.onclose = () => {
+            this.log.log("transport.sdk.onclose", undefined, "SDK transport onclose fired");
+            if (this._wireState === "connected") {
+                void this.reconnectWire("peer_closed");
+            }
+        };
+        this.sdkTransport.onerror = (err) => {
+            this.log.log("transport.sdk.onerror", { error: err?.message || String(err) }, `SDK transport onerror: ${err?.message || err}`);
+            if (this._wireState === "connected") {
+                void this.reconnectWire("wire_error");
+            }
+        };
+        this.client.onerror = (err) => {
+            this.log.log("transport.client.onerror", { error: err?.message || String(err) }, `SDK client onerror: ${err?.message || err}`);
+        };
+        await this.client.connect(this.sdkTransport);
+        this.log.log("transport.wire.initialized", undefined, "MCP wire initialized");
+    }
+    async teardownWire() {
+        const oldClient = this.client;
+        this.client = null;
+        this.sdkTransport = null;
+        this.stopHeartbeat();
+        this.stopSseWatchdog();
+        this.cancelFirstKeepaliveDeadline();
+        if (oldClient) {
+            try {
+                await oldClient.close();
+            }
+            catch {
+                // expected on dead wires
+            }
+        }
+        // Let any in-flight SSE callbacks settle before the next wire opens.
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+    /**
+     * Wire-level reconnect loop. Entered on any wire-death signal
+     * (SSE drop, heartbeat failure, transport error). Emits
+     * `reconnecting` + (on success) `reconnected` wire events so the
+     * AgentClient above can re-run its L7 handshake.
+     */
+    async reconnectWire(cause) {
+        if (this.reconnecting || this.closed)
+            return;
+        this.reconnecting = true;
+        this.totalReconnects++;
+        this.consecutiveReconnects++;
+        this.lastReconnectCause = cause;
+        this.log.log("transport.reconnect.start", { cause, consecutive: this.consecutiveReconnects }, `reconnectWire: cause=${cause}, consecutive=${this.consecutiveReconnects}`);
+        this.emit({ type: "reconnecting", cause });
+        this.transition("connecting");
+        await this.teardownWire();
+        try {
+            await this.createWire();
+            if (this.closed) {
+                // close() called mid-reconnect — bail out.
+                await this.teardownWire();
+                this.transition("disconnected");
+                return;
+            }
+            this.transition("connected");
+            this.startHeartbeat();
+            this.startSseWatchdog();
+            this.startFirstKeepaliveDeadline();
+            this.emit({ type: "reconnected" });
+        }
+        catch (err) {
+            this.log.log("transport.reconnect.failed", { cause, error: String(err) }, `reconnectWire failed: ${err}`);
+            this.transition("disconnected");
+            this.scheduleReconnectTimer(cause);
+        }
+        finally {
+            this.reconnecting = false;
+        }
+    }
+    scheduleReconnectTimer(cause) {
+        if (this.closed)
+            return;
+        this.cancelReconnectTimer();
+        const backoff = computeReconnectBackoff(this.consecutiveReconnects, this.cfg.reconnectDelay);
+        this.log.log("transport.reconnect.retry_scheduled", { cause, backoffMs: backoff }, `scheduling retry in ${backoff}ms`);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            void this.reconnectWire(cause);
+        }, backoff);
+    }
+    cancelReconnectTimer() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+    // ── Internal: liveness timers ───────────────────────────────────────
+    startHeartbeat() {
+        this.stopHeartbeat();
+        this.heartbeatTimer = setInterval(async () => {
+            if (this._wireState !== "connected" || !this.client)
+                return;
+            try {
+                await this.client.listTools();
+            }
+            catch {
+                this.log.log("transport.heartbeat.failed", undefined, "heartbeat failed, triggering wire reconnect");
+                void this.reconnectWire("heartbeat_failed");
+            }
+        }, this.cfg.heartbeatInterval);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    startSseWatchdog() {
+        this.stopSseWatchdog();
+        this.sseWatchdogTimer = setInterval(() => {
+            if (this._wireState !== "connected")
+                return;
+            if (!this.sseVerified)
+                return;
+            const gap = Date.now() - this.lastKeepaliveAt;
+            if (gap > this.cfg.sseKeepaliveTimeout) {
+                this.log.log("transport.sse.watchdog.fired", { gapMs: gap, thresholdMs: this.cfg.sseKeepaliveTimeout }, `SSE watchdog: ${Math.round(gap / 1000)}s without keepalive (threshold ${this.cfg.sseKeepaliveTimeout / 1000}s)`);
+                void this.reconnectWire("sse_watchdog");
+            }
+        }, this.cfg.sseWatchdogInterval);
+    }
+    stopSseWatchdog() {
+        if (this.sseWatchdogTimer) {
+            clearInterval(this.sseWatchdogTimer);
+            this.sseWatchdogTimer = null;
+        }
+    }
+    startFirstKeepaliveDeadline() {
+        this.cancelFirstKeepaliveDeadline();
+        this.firstKeepaliveTimer = setTimeout(() => {
+            this.firstKeepaliveTimer = null;
+            if (this._wireState !== "connected")
+                return;
+            if (this.sseVerified)
+                return;
+            this.log.log("transport.sse.never_opened", { deadlineMs: this.cfg.firstKeepaliveDeadline }, `first keepalive deadline: ${this.cfg.firstKeepaliveDeadline}ms elapsed without SSE`);
+            void this.reconnectWire("sse_never_opened");
+        }, this.cfg.firstKeepaliveDeadline);
+    }
+    cancelFirstKeepaliveDeadline() {
+        if (this.firstKeepaliveTimer) {
+            clearTimeout(this.firstKeepaliveTimer);
+            this.firstKeepaliveTimer = null;
+        }
+    }
+    // ── Internal: state + event emission ────────────────────────────────
+    transition(to) {
+        if (this._wireState === to)
+            return;
+        const from = this._wireState;
+        this._wireState = to;
+        if (to === "connected") {
+            this.consecutiveReconnects = 0;
+        }
+        this.log.log("transport.wire.state", { from, to }, `wire ${from} → ${to}`);
+        this.emit({ type: "state", from, to });
+    }
+    emit(event) {
+        for (const h of this.handlers) {
+            try {
+                h(event);
+            }
+            catch (err) {
+                this.log.log("transport.handler.error", { error: String(err) }, `wire-event handler error: ${err}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=mcp-transport.js.map

package/dist/wire/mcp-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-transport.js","sourceRoot":"","sources":["../../src/wire/mcp-transport.ts"],"names":[],"mappings":"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"}

package/dist/wire/transport.d.ts

@@ -0,0 +1,174 @@
+/**
+ * ITransport — Layer-4 wire surface for the network-adapter package.
+ *
+ * Phase 1: types only. Zero runtime change. The real implementation
+ * (`McpTransport`) lands in Phase 2, extracted out of the current
+ * `McpConnectionManager`.
+ *
+ * ## Responsibility boundary
+ *
+ * A Transport owns exactly one logical wire to a Hub. It is responsible
+ * for:
+ *
+ *   1. Opening and closing that wire.
+ *   2. Shipping untyped request/response pairs over it (`request`).
+ *   3. Enumerating what method names the remote peer advertises
+ *      (`listMethods` — used by the adapter for discovery translation).
+ *   4. Surfacing liveness: a coarse 3-value `wireState` and a stream of
+ *      `WireEvent`s (connected, disconnected, peer-closed, etc.).
+ *   5. Wire-level reconnect policy: it transparently reconnects the
+ *      underlying socket/HTTP/SSE stream on transient failure. It does
+ *      NOT know about sessions, roles, handshakes, or FSM.
+ *
+ * It is NOT responsible for:
+ *
+ *   - Session lifecycle (bind/rebind/teardown). That lives on the
+ *     `IAgentClient` above it.
+ *   - Authentication and handshake semantics (register_role, enriched handshake).
+ *   - Event classification, dedup, or state sync.
+ *   - Retry-on-session-invalid (that policy is above the wire).
+ *
+ * ## Why untyped `request(method, params)`
+ *
+ * The adapter and shim above must be transport-agnostic. By keeping the
+ * request surface a plain string-keyed call, the same adapter code can
+ * run against a future gRPC or QUIC transport without leaking protocol
+ * detail. MCP-specific encodings (tool calls, list_tools, etc.) are
+ * translated inside `McpTransport`, not exposed here.
+ *
+ * The trade-off: type safety on the wire is the transport's problem.
+ * Callers (the adapter) validate response shapes at the L7 seam.
+ */
+import type { ILogger, LegacyStringLogger } from "../logger.js";
+/**
+ * Coarse-grained wire state.
+ *
+ * Deliberately only three values — the transport does NOT model a
+ * session FSM. "connected" means "the wire is up right now"; anything
+ * stronger (handshake done, session bound, streaming) lives on the
+ * AgentClient layer.
+ */
+export type WireState = "disconnected" | "connecting" | "connected";
+/**
+ * Why the wire reconnected. A narrower vocabulary than
+ * `SessionReconnectReason` (in `agent-client.ts`), because the
+ * transport doesn't classify session-level failures.
+ */
+export type WireReconnectCause = "sse_watchdog" | "sse_never_opened" | "heartbeat_failed" | "peer_closed" | "wire_error";
+/**
+ * Stream of wire-level events the AgentClient subscribes to. The
+ * transport emits these; the AgentClient uses them to drive its
+ * session FSM. Intentionally narrow — this is the entire L4→L7 event
+ * protocol.
+ */
+export type WireEvent = {
+    type: "state";
+    from: WireState;
+    to: WireState;
+} | {
+    type: "reconnecting";
+    cause: WireReconnectCause;
+} | {
+    type: "reconnected";
+} | {
+    type: "closed";
+    reason?: string;
+} | {
+    /**
+     * Unsolicited inbound message from the remote (push notification,
+     * server-sent event). The transport delivers the raw body and
+     * the method name; the adapter decides what to do with it.
+     */
+    type: "push";
+    method: string;
+    payload: unknown;
+};
+export type WireEventHandler = (event: WireEvent) => void;
+/**
+ * Transport configuration — minimal. Anything session- or role-related
+ * belongs in `IAgentClient` config, not here.
+ */
+export interface TransportConfig {
+    url: string;
+    token?: string;
+    heartbeatInterval?: number;
+    sseKeepaliveTimeout?: number;
+    firstKeepaliveDeadline?: number;
+    sseWatchdogInterval?: number;
+    reconnectDelay?: number;
+    /**
+     * Logger injection. Preferred is `ILogger`; the string variant is a
+     * Phase-2 migration aid so existing string-logger call sites can
+     * wire up a transport without being rewritten first.
+     */
+    logger?: ILogger | LegacyStringLogger;
+    /**
+     * Mission-56 W2.2: optional provider for the most-recent Hub event id
+     * the layer above has observed. The transport reads this at
+     * (re)connect time and, when a value is returned, attaches it as the
+     * canonical SSE `Last-Event-ID` header on the inbound stream. The
+     * Hub-side W1b wrapper consumes the header to backfill missed
+     * Messages before resuming live emit. Returning `undefined` (no
+     * value yet) means cold-start — Hub falls through to the
+     * stream-all-with-soft-cap path.
+     */
+    getLastEventId?: () => string | undefined;
+}
+/**
+ * Pull-style telemetry on a Transport. Deliberately a point-in-time
+ * snapshot — the log stream is the authoritative event record. These
+ * counters exist so an AgentClient (or operator) can report
+ * "how is this wire doing right now" without subscribing.
+ */
+export interface TransportMetrics {
+    readonly wireState: WireState;
+    readonly totalReconnects: number;
+    readonly consecutiveReconnects: number;
+    readonly lastReconnectCause?: WireReconnectCause;
+    readonly lastKeepaliveAt?: number;
+    readonly requestsInFlight: number;
+}
+export interface ITransport {
+    /** Current coarse wire state. */
+    readonly wireState: WireState;
+    /**
+     * Open the wire. Resolves when `wireState === "connected"`. Idempotent:
+     * calling `connect()` on an already-connected transport is a no-op.
+     */
+    connect(): Promise<void>;
+    /**
+     * Close the wire cleanly. After this resolves, `wireState === "disconnected"`
+     * and no further `WireEvent`s will be delivered except a final
+     * `{type:"state", to:"disconnected"}` if one hasn't fired yet.
+     */
+    close(): Promise<void>;
+    /**
+     * Ship an untyped request/response pair over the wire.
+     *
+     * Protocol framing is the transport's problem. Session-invalid
+     * classification is NOT — callers receive the raw error and decide
+     * whether to reconnect at the session layer.
+     */
+    request(method: string, params: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Enumerate the method names currently advertised by the remote peer.
+     * Used by the AgentClient for discovery translation: it rewrites this
+     * list into an `IAgentClient`-shaped descriptor set exposed to shims.
+     *
+     * The return shape is intentionally `string[]` rather than full
+     * JSON-schema descriptors — richer discovery, if needed, is a
+     * future extension via an optional second method. Keeping the minimum
+     * here means every transport can satisfy it cheaply.
+     */
+    listMethods(): Promise<string[]>;
+    /** Subscribe to the wire-event stream. Multiple subscribers allowed. */
+    onWireEvent(handler: WireEventHandler): void;
+    /** Point-in-time snapshot of wire-level telemetry. */
+    getMetrics(): TransportMetrics;
+    /**
+     * Current wire-level session id, if any. For MCP this is the
+     * StreamableHTTP session id issued by the server; for a loopback
+     * transport it's a synthetic handle. Undefined before first `connect()`.
+     */
+    getSessionId(): string | undefined;
+}