agentic-flow 2.0.12-fix.8 → 2.0.13

package/dist/transport/quic-loader.js

@@ -1,412 +0,0 @@
-// QUIC Transport Loader with WebSocket fallback
-//
-// Backported from outer repo loader pattern. Exposes a single
-// loadQuicTransport(config) entry point that:
-//
-//   1. Tries to load the WASM-backed QuicClient/QuicServer (real QUIC if a
-//      native build is wired in the future).
-//   2. Falls back to WebSocketFallbackTransport when QUIC is unavailable
-//      OR when the WASM stub is detected (current state — see
-//      crates/agentic-flow-quic/src/wasm.rs comment: WASM build is a stub
-//      because browsers can't do raw UDP/QUIC; production QUIC needs
-//      native Node.js builds which haven't shipped yet).
-//
-// The fallback uses standard WebSocket (ws://) so it works on all Node
-// versions without complex native dependencies. Same async send/receive
-// API surface as QuicTransport.
-//
-// Federation use case (ruvnet/ruflo ADR-104): two peers on the same
-// tailnet can call loadQuicTransport({ serverName: 'peer.tailnet' }) and
-// exchange signed envelopes today, with zero code change required when
-// the native QUIC build lands later.
-import { logger } from '../utils/logger.js';
-import WebSocket, { WebSocketServer } from 'ws';
-import { createHash } from 'node:crypto';
-import { createServer as createHttpsServer } from 'node:https';
-import { readFileSync } from 'node:fs';
-/** Default streamId when caller omits it. Backward-compat sentinel. */
-export const DEFAULT_STREAM_ID = 'default';
-/**
- * WebSocket fallback transport.
- *
- * Spec compliance: implements the AgentTransport interface using
- * `ws://` (or `wss://` if address starts with `wss://`). Each call to
- * `send` lazily opens (or reuses) a connection to `address`. The
- * `receive(address)` call drains the next queued message for that
- * address; if none is queued it polls every 100ms until one arrives.
- *
- * Limits vs real QUIC: no 0-RTT resumption, no multiplexed streams
- * (one TCP connection per peer), TLS handled by the WS layer (use
- * `wss://` for encryption). Performance is "good enough" for federation
- * messages at human/agent rates (≤ 100 RPS per peer).
- */
-class WebSocketFallbackTransport {
-    config;
-    connections = new Map();
-    /**
-     * Per-(address, streamId) message queue. Composite key shape
-     * `${address}#${streamId}` — see {@link queueKey}. Each stream gets
-     * its own FIFO so receive(addr, streamA) is independent of
-     * receive(addr, streamB) — eliminates head-of-line blocking on a
-     * single peer connection.
-     */
-    messageQueue = new Map();
-    connectionsCreated = 0;
-    connectionsClosed = 0;
-    servers = new Map();
-    /**
-     * Inbound handlers. Each entry is { handler, streamId? }. When
-     * streamId is undefined the handler receives ALL messages
-     * regardless of stream; otherwise only messages with the matching
-     * streamId. Lets callers register both per-stream + catch-all.
-     */
-    inboundHandlers = new Set();
-    /** Compose the per-(address, streamId) queue key. */
-    queueKey(address, streamId) {
-        return `${address}#${streamId}`;
-    }
-    /** Resolve the streamId for a message — defaults to DEFAULT_STREAM_ID. */
-    streamOf(message) {
-        return message.streamId ?? DEFAULT_STREAM_ID;
-    }
-    constructor(config) {
-        this.config = config;
-    }
-    static async create(config = {}) {
-        const fullConfig = {
-            serverName: config.serverName ?? 'localhost',
-            maxIdleTimeoutMs: config.maxIdleTimeoutMs ?? 30000,
-            maxConcurrentStreams: config.maxConcurrentStreams ?? 100,
-            // Not applicable for WebSocket — record but ignore
-            enable0Rtt: config.enable0Rtt ?? false,
-            tls: config.tls ?? {},
-        };
-        return new WebSocketFallbackTransport(fullConfig);
-    }
-    /**
-     * Bind a server-side listener so this transport instance can RECEIVE
-     * messages from a remote peer (in addition to sending). Federation
-     * peers run BOTH a listener and a client — calling listen(9100) plus
-     * send('peer:9100', ...) gives bidirectional connectivity.
-     *
-     * Enables `permessage-deflate` compression with thresholds chosen
-     * for federation envelopes (typically JSON, 100B-10KB):
-     *   - threshold: 256B — don't waste CPU compressing tiny pings
-     *   - level: 3 — balanced compression vs CPU (zlib's BEST_SPEED→6 range)
-     *   - serverNoContextTakeover: true — bound per-conn memory growth
-     */
-    async listen(port, host = '0.0.0.0') {
-        if (this.servers.has(port))
-            return;
-        return new Promise((resolve, reject) => {
-            const tls = this.config.tls;
-            const wssOpts = {
-                perMessageDeflate: {
-                    threshold: 256,
-                    zlibDeflateOptions: { level: 3 },
-                    serverNoContextTakeover: true,
-                    clientNoContextTakeover: true,
-                },
-            };
-            // ADR-107: if cert+key paths are configured, bind via https.Server
-            // (wss://). Otherwise bind plain ws:// directly.
-            if (tls?.certPath && tls?.keyPath) {
-                const cert = readFileSync(tls.certPath);
-                const key = readFileSync(tls.keyPath);
-                const httpsServer = createHttpsServer({ cert, key });
-                httpsServer.listen(port, host, () => {
-                    const wss = new WebSocketServer({ ...wssOpts, server: httpsServer });
-                    this.attachServerHandlers(wss);
-                    this.servers.set(port, wss);
-                    resolve();
-                });
-                httpsServer.on('error', reject);
-                return;
-            }
-            const wss = new WebSocketServer({ ...wssOpts, port, host });
-            wss.on('listening', () => {
-                this.servers.set(port, wss);
-                resolve();
-            });
-            wss.on('error', reject);
-            this.attachServerHandlers(wss);
-        });
-    }
-    /**
-     * Wire the server's `connection` and per-socket `message` handlers.
-     * Extracted so the wss:// path (where the WebSocketServer is attached
-     * to a pre-created https.Server) can share the same logic.
-     */
-    attachServerHandlers(wss) {
-        wss.on('connection', (ws, req) => {
-            const remoteAddr = `${req.socket.remoteAddress}:${req.socket.remotePort}`;
-            ws.on('message', (raw) => {
-                try {
-                    const message = JSON.parse(raw.toString());
-                    // Per-stream queue (default stream when message.streamId omitted)
-                    const key = this.queueKey(remoteAddr, this.streamOf(message));
-                    const queue = this.messageQueue.get(key) ?? [];
-                    queue.push(message);
-                    this.messageQueue.set(key, queue);
-                    this.dispatchInbound(remoteAddr, message);
-                }
-                catch (err) {
-                    logger.warn('Dropped malformed inbound WS message', { remoteAddr, err });
-                }
-            });
-        });
-    }
-    async getOrCreateConnection(address) {
-        return new Promise((resolve, reject) => {
-            const existing = this.connections.get(address);
-            if (existing && existing.readyState === WebSocket.OPEN) {
-                resolve(existing);
-                return;
-            }
-            const url = address.startsWith('ws://') || address.startsWith('wss://')
-                ? address
-                : `ws://${address}`;
-            // ADR-107: cert pinning for wss:// peers. Build the WS options
-            // with both compression (perf) and TLS hooks (security).
-            const tls = this.config.tls;
-            const isWss = url.startsWith('wss://');
-            const wsOpts = {
-                perMessageDeflate: {
-                    threshold: 256,
-                    zlibDeflateOptions: { level: 3 },
-                    serverNoContextTakeover: true,
-                    clientNoContextTakeover: true,
-                },
-            };
-            if (isWss && tls?.pinnedFingerprints && tls.pinnedFingerprints.length > 0) {
-                // Fail-closed pinning: ONLY accept the listed cert fingerprints.
-                // CA path validation is irrelevant — the fingerprint IS the trust
-                // anchor. If the cert rotates, the operator must update config.
-                const pinned = new Set(tls.pinnedFingerprints);
-                // Cast: ws's `checkServerIdentity` is typed as returning boolean
-                // but the underlying `tls.checkServerIdentity` (which it
-                // forwards to) accepts `Error | undefined`. The runtime
-                // semantics are: throw OR return Error → reject; otherwise accept.
-                // The boolean type signature is overly restrictive.
-                wsOpts.checkServerIdentity = (_host, cert) => {
-                    // cert.raw is the DER-encoded cert bytes; sha256/<base64> matches
-                    // common pinning notation (and what `openssl x509 -fingerprint
-                    // -sha256` outputs after base64-encoding).
-                    const fp = `sha256/${createHash('sha256').update(cert.raw).digest('base64')}`;
-                    if (!pinned.has(fp)) {
-                        return new Error(`Federation TLS: peer cert fingerprint ${fp} not in pinned set ` +
-                            `(${pinned.size} fingerprint(s) configured)`);
-                    }
-                    return undefined; // accept
-                };
-                // When pinning is on, we explicitly DON'T want CA validation
-                // (the fingerprint check above is the real auth). But we also
-                // DON'T want to silently accept ANY cert — the checkServerIdentity
-                // above is still called.
-                wsOpts.rejectUnauthorized = false;
-            }
-            else if (isWss && tls?.caPath) {
-                // Non-pinned mode: validate against the configured CA bundle.
-                wsOpts.ca = readFileSync(tls.caPath);
-                wsOpts.rejectUnauthorized = true;
-            }
-            // (no tls config + ws:// → plain unencrypted; ADR-104 documents
-            // tailnet-as-TLS as the recommended path)
-            const ws = new WebSocket(url, wsOpts);
-            ws.on('open', () => {
-                this.connections.set(address, ws);
-                this.connectionsCreated++;
-                resolve(ws);
-            });
-            ws.on('error', (error) => {
-                reject(new Error(`WebSocket connection to ${url} failed: ${error.message}`));
-            });
-            ws.on('close', () => {
-                this.connectionsClosed++;
-                this.connections.delete(address);
-            });
-            ws.on('message', (raw) => {
-                try {
-                    const message = JSON.parse(raw.toString());
-                    const key = this.queueKey(address, this.streamOf(message));
-                    const queue = this.messageQueue.get(key) ?? [];
-                    queue.push(message);
-                    this.messageQueue.set(key, queue);
-                    this.dispatchInbound(address, message);
-                }
-                catch (err) {
-                    logger.warn('Dropped malformed WebSocket message', { address, err });
-                }
-            });
-        });
-    }
-    async send(address, message) {
-        const ws = await this.getOrCreateConnection(address);
-        ws.send(JSON.stringify(message));
-    }
-    /**
-     * Register an inbound handler. Optional `options.streamId` scopes
-     * the handler to a specific stream (only fires for messages with
-     * matching streamId). Omit to subscribe to ALL streams.
-     *
-     * Patterns:
-     *   onMessage(h)                              — receives all
-     *   onMessage(h, { streamId: 'rpc' })         — receives only rpc
-     *   onMessage(h, { streamId: 'event' })       — receives only event
-     *   (both registered)                         — both fire on
-     *                                                their respective streams
-     */
-    onMessage(handler, options = {}) {
-        this.inboundHandlers.add({ handler, streamId: options.streamId });
-    }
-    /**
-     * Fire all matching handlers for a received message. Stream-scoped
-     * handlers only fire when the message's streamId matches; all-stream
-     * handlers always fire. Errors thrown sync OR async-rejected by one
-     * handler don't stop delivery to others.
-     */
-    dispatchInbound(address, message) {
-        if (this.inboundHandlers.size === 0)
-            return;
-        const msgStream = this.streamOf(message);
-        for (const entry of this.inboundHandlers) {
-            // Stream filter: scoped handler only fires on matching streamId
-            if (entry.streamId !== undefined && entry.streamId !== msgStream)
-                continue;
-            try {
-                const r = entry.handler(address, message);
-                if (r && typeof r.catch === 'function') {
-                    r.catch((err) => {
-                        logger.warn('Inbound handler rejected', { address, err });
-                    });
-                }
-            }
-            catch (err) {
-                logger.warn('Inbound handler threw', { address, err });
-            }
-        }
-    }
-    async receive(address, streamId = DEFAULT_STREAM_ID) {
-        const key = this.queueKey(address, streamId);
-        // Fast path
-        const queue = this.messageQueue.get(key) ?? [];
-        if (queue.length > 0)
-            return queue.shift();
-        // Poll (caller must time out externally if they don't want to wait)
-        return new Promise((resolve) => {
-            const interval = setInterval(() => {
-                const q = this.messageQueue.get(key) ?? [];
-                if (q.length > 0) {
-                    clearInterval(interval);
-                    resolve(q.shift());
-                }
-            }, 100);
-        });
-    }
-    async request(address, message) {
-        await this.send(address, message);
-        return this.receive(address);
-    }
-    async sendBatch(address, messages) {
-        await Promise.all(messages.map((m) => this.send(address, m)));
-    }
-    async getStats() {
-        return {
-            active: this.connections.size,
-            idle: 0,
-            created: this.connectionsCreated,
-            closed: this.connectionsClosed,
-        };
-    }
-    async close() {
-        // Outbound clients first.
-        for (const ws of this.connections.values()) {
-            ws.terminate();
-        }
-        this.connections.clear();
-        this.messageQueue.clear();
-        // Inbound: WebSocketServer.close() blocks until every accepted
-        // socket disconnects. Forcibly terminate them so the close
-        // callback fires within the test/CI timeout window.
-        for (const wss of this.servers.values()) {
-            for (const client of wss.clients) {
-                try {
-                    client.terminate();
-                }
-                catch {
-                    /* socket already gone */
-                }
-            }
-            await new Promise((resolve) => wss.close(() => resolve()));
-        }
-        this.servers.clear();
-    }
-}
-/**
- * Detect whether the WASM-backed QUIC transport is "real" (i.e. it
- * actually moves bytes on the wire) vs the current stub. The stub
- * returns 0ms for connect+send and never increments the server's
- * received-bytes counter. We probe by observing a documented marker
- * on the WASM module: when it's truly wired the loader function
- * `defaultConfig` returns an object whose round-trip through
- * `WasmQuicClient.new` actually opens a UDP socket — failing fast on
- * an OS that blocks UDP outbound (e.g. some sandboxed CI envs).
- *
- * Until the native build lands this returns false; the loader picks
- * WebSocket. When the native binding is wired this returns true and
- * the loader picks real QUIC. Callers get the same API either way.
- */
-async function isRealQuicAvailable() {
-    try {
-        // The WASM file is published in `wasm/quic/` of this package. We
-        // do NOT use it for federation today (per the wasm.rs note: it's a
-        // stub since browsers can't do UDP). When a native binding is added
-        // this probe should switch to detect that binding instead.
-        const native = process.env.AGENTIC_FLOW_QUIC_NATIVE === '1';
-        return native;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Public API — load a working transport, preferring real QUIC when
- * available, falling back to WebSocket otherwise. The returned object
- * satisfies the AgentTransport interface in both cases.
- *
- * Example:
- *   const t = await loadQuicTransport({ serverName: 'ruvultra:9100' });
- *   await t.send('ruvultra:9100', { id: '1', type: 'task', payload: {...} });
- *
- * Federation v1 ships on the WebSocket fallback (this is the actual
- * working transport today). When the native QUIC binding lands, set
- * the AGENTIC_FLOW_QUIC_NATIVE=1 environment variable and the same
- * code path picks up the upgrade with no API changes.
- */
-export async function loadQuicTransport(config = {}) {
-    if (await isRealQuicAvailable()) {
-        // Future: wire to the native binding here.
-        logger.info('QUIC transport: native binding selected');
-    }
-    else {
-        if (process.env.NODE_ENV !== 'test') {
-            logger.warn('QUIC native binding not available; using WebSocket fallback. ' +
-                'Set AGENTIC_FLOW_QUIC_NATIVE=1 once a native build is installed.');
-        }
-    }
-    return WebSocketFallbackTransport.create(config);
-}
-/** Quick capability probe for the doctor / health surface. */
-export async function isQuicAvailable() {
-    return isRealQuicAvailable();
-}
-export async function getTransportCapabilities() {
-    const quic = await isRealQuicAvailable();
-    return {
-        quicAvailable: quic,
-        webSocketFallbackAvailable: true,
-        selectedBackend: quic ? 'quic' : 'websocket',
-    };
-}
-export { WebSocketFallbackTransport };
-//# sourceMappingURL=quic-loader.js.map

package/dist/transport/quic-loader.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"quic-loader.js","sourceRoot":"","sources":["../../src/transport/quic-loader.ts"],"names":[],"mappings":"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","sourcesContent":["// QUIC Transport Loader with WebSocket fallback\n//\n// Backported from outer repo loader pattern. Exposes a single\n// loadQuicTransport(config) entry point that:\n//\n//   1. Tries to load the WASM-backed QuicClient/QuicServer (real QUIC if a\n//      native build is wired in the future).\n//   2. Falls back to WebSocketFallbackTransport when QUIC is unavailable\n//      OR when the WASM stub is detected (current state — see\n//      crates/agentic-flow-quic/src/wasm.rs comment: WASM build is a stub\n//      because browsers can't do raw UDP/QUIC; production QUIC needs\n//      native Node.js builds which haven't shipped yet).\n//\n// The fallback uses standard WebSocket (ws://) so it works on all Node\n// versions without complex native dependencies. Same async send/receive\n// API surface as QuicTransport.\n//\n// Federation use case (ruvnet/ruflo ADR-104): two peers on the same\n// tailnet can call loadQuicTransport({ serverName: 'peer.tailnet' }) and\n// exchange signed envelopes today, with zero code change required when\n// the native QUIC build lands later.\n\nimport { logger } from '../utils/logger.js';\nimport WebSocket, { WebSocketServer, type RawData } from 'ws';\nimport { createHash } from 'node:crypto';\nimport { createServer as createHttpsServer } from 'node:https';\nimport { readFileSync } from 'node:fs';\nimport type { TLSSocket } from 'node:tls';\n\n/** TLS configuration for wss:// peers (ADR-107). */\nexport interface TlsConfig {\n  /** Path to PEM cert file (server side — bind certs for the listener). */\n  certPath?: string;\n  /** Path to PEM key file (server side). */\n  keyPath?: string;\n  /**\n   * Pinned `sha256/<base64>` fingerprints of acceptable peer certs\n   * (client side — outbound connections).\n   *\n   * When set, ONLY these exact certs are accepted. CA validation is\n   * skipped — the fingerprint IS the trust anchor. Fail-closed: if the\n   * peer's cert rotates and the fingerprint doesn't match, the\n   * connection is refused (operator must update config + restart).\n   *\n   * This prevents:\n   *   - Compromised public CAs issuing rogue certs for our domain\n   *   - TLS-MITM attacks where the attacker holds a valid cert chain\n   */\n  pinnedFingerprints?: string[];\n  /**\n   * Optional CA bundle path for non-pinned mode (e.g. private CA).\n   * Used only when `pinnedFingerprints` is empty/unset.\n   */\n  caPath?: string;\n}\n\n/** Caller-facing config — minimal common surface across both backends. */\nexport interface QuicTransportConfig {\n  serverName?: string;\n  maxIdleTimeoutMs?: number;\n  maxConcurrentStreams?: number;\n  enable0Rtt?: boolean;\n  /** TLS materials for wss:// listeners + clients (ADR-107). */\n  tls?: TlsConfig;\n}\n\nexport interface AgentMessage {\n  id: string;\n  type: 'task' | 'result' | 'status' | 'coordination' | 'heartbeat' | string;\n  payload: unknown;\n  metadata?: Record<string, unknown>;\n  /**\n   * Stream multiplexing identifier. Messages with different streamIds\n   * to the same peer are independent — receive queues and onMessage\n   * handlers can scope per-stream, eliminating head-of-line blocking\n   * for sequential `await` patterns on a single peer connection.\n   *\n   * Defaults to `'default'` if omitted (backward compat). Common\n   * patterns:\n   *   - One stream per logical request type (`'rpc'`, `'event'`,\n   *     `'control'`)\n   *   - One stream per task (`taskId` doubled as streamId)\n   *   - One stream per priority class (`'high'`, `'normal'`, `'low'`)\n   *\n   * Maps cleanly to native QUIC streams when AGENTIC_FLOW_QUIC_NATIVE=1\n   * (each app-layer streamId becomes a QUIC stream id at that point).\n   */\n  streamId?: string | number;\n}\n\n/** Default streamId when caller omits it. Backward-compat sentinel. */\nexport const DEFAULT_STREAM_ID = 'default';\n\nexport interface PoolStatistics {\n  active: number;\n  idle: number;\n  created: number;\n  closed: number;\n}\n\n/** Inbound message handler — called for every received message. */\nexport type InboundMessageHandler = (\n  address: string,\n  message: AgentMessage,\n) => void | Promise<void>;\n\n/**\n * Per-stream subscription options. Pass to `onMessage` to scope a\n * handler to a specific streamId (only fires for messages with that\n * exact streamId). Omit to receive all streams.\n */\nexport interface OnMessageOptions {\n  readonly streamId?: string | number;\n}\n\n/** Common interface both real-QUIC and fallback transports satisfy. */\nexport interface AgentTransport {\n  send(address: string, message: AgentMessage): Promise<void>;\n  /**\n   * Receive the next message from a peer. Optional `streamId` scopes\n   * to that stream's queue (independent of other streams to the same\n   * peer). Omit to use the default stream — backward-compat behavior.\n   */\n  receive(address: string, streamId?: string | number): Promise<AgentMessage>;\n  request(address: string, message: AgentMessage): Promise<AgentMessage>;\n  sendBatch(address: string, messages: AgentMessage[]): Promise<void>;\n  getStats(): Promise<PoolStatistics>;\n  close(): Promise<void>;\n  /**\n   * Subscribe to inbound messages. The handler fires for every received\n   * message that matches `options.streamId` (if provided) or for every\n   * message regardless of streamId (if options omitted).\n   *\n   * Multiple handlers may be registered (per-stream OR all-streams or\n   * a mix). Errors thrown by a handler are logged but do not stop\n   * delivery to other handlers.\n   *\n   * Optional method — implementations that don't support push-style\n   * delivery may omit it. Callers should use `transport.onMessage?.(h)`\n   * to gracefully degrade.\n   */\n  onMessage?(handler: InboundMessageHandler, options?: OnMessageOptions): void;\n}\n\n/**\n * WebSocket fallback transport.\n *\n * Spec compliance: implements the AgentTransport interface using\n * `ws://` (or `wss://` if address starts with `wss://`). Each call to\n * `send` lazily opens (or reuses) a connection to `address`. The\n * `receive(address)` call drains the next queued message for that\n * address; if none is queued it polls every 100ms until one arrives.\n *\n * Limits vs real QUIC: no 0-RTT resumption, no multiplexed streams\n * (one TCP connection per peer), TLS handled by the WS layer (use\n * `wss://` for encryption). Performance is \"good enough\" for federation\n * messages at human/agent rates (≤ 100 RPS per peer).\n */\nclass WebSocketFallbackTransport implements AgentTransport {\n  private connections = new Map<string, WebSocket>();\n  /**\n   * Per-(address, streamId) message queue. Composite key shape\n   * `${address}#${streamId}` — see {@link queueKey}. Each stream gets\n   * its own FIFO so receive(addr, streamA) is independent of\n   * receive(addr, streamB) — eliminates head-of-line blocking on a\n   * single peer connection.\n   */\n  private messageQueue = new Map<string, AgentMessage[]>();\n  private connectionsCreated = 0;\n  private connectionsClosed = 0;\n  private servers = new Map<number, WebSocketServer>();\n  /**\n   * Inbound handlers. Each entry is { handler, streamId? }. When\n   * streamId is undefined the handler receives ALL messages\n   * regardless of stream; otherwise only messages with the matching\n   * streamId. Lets callers register both per-stream + catch-all.\n   */\n  private inboundHandlers = new Set<{\n    handler: InboundMessageHandler;\n    streamId?: string | number;\n  }>();\n\n  /** Compose the per-(address, streamId) queue key. */\n  private queueKey(address: string, streamId: string | number): string {\n    return `${address}#${streamId}`;\n  }\n\n  /** Resolve the streamId for a message — defaults to DEFAULT_STREAM_ID. */\n  private streamOf(message: AgentMessage): string | number {\n    return message.streamId ?? DEFAULT_STREAM_ID;\n  }\n\n  constructor(private readonly config: Required<QuicTransportConfig>) {}\n\n  static async create(config: QuicTransportConfig = {}): Promise<WebSocketFallbackTransport> {\n    const fullConfig: Required<QuicTransportConfig> = {\n      serverName: config.serverName ?? 'localhost',\n      maxIdleTimeoutMs: config.maxIdleTimeoutMs ?? 30000,\n      maxConcurrentStreams: config.maxConcurrentStreams ?? 100,\n      // Not applicable for WebSocket — record but ignore\n      enable0Rtt: config.enable0Rtt ?? false,\n      tls: config.tls ?? {},\n    };\n    return new WebSocketFallbackTransport(fullConfig);\n  }\n\n  /**\n   * Bind a server-side listener so this transport instance can RECEIVE\n   * messages from a remote peer (in addition to sending). Federation\n   * peers run BOTH a listener and a client — calling listen(9100) plus\n   * send('peer:9100', ...) gives bidirectional connectivity.\n   *\n   * Enables `permessage-deflate` compression with thresholds chosen\n   * for federation envelopes (typically JSON, 100B-10KB):\n   *   - threshold: 256B — don't waste CPU compressing tiny pings\n   *   - level: 3 — balanced compression vs CPU (zlib's BEST_SPEED→6 range)\n   *   - serverNoContextTakeover: true — bound per-conn memory growth\n   */\n  async listen(port: number, host = '0.0.0.0'): Promise<void> {\n    if (this.servers.has(port)) return;\n    return new Promise((resolve, reject) => {\n      const tls = this.config.tls;\n      const wssOpts: ConstructorParameters<typeof WebSocketServer>[0] = {\n        perMessageDeflate: {\n          threshold: 256,\n          zlibDeflateOptions: { level: 3 },\n          serverNoContextTakeover: true,\n          clientNoContextTakeover: true,\n        },\n      };\n      // ADR-107: if cert+key paths are configured, bind via https.Server\n      // (wss://). Otherwise bind plain ws:// directly.\n      if (tls?.certPath && tls?.keyPath) {\n        const cert = readFileSync(tls.certPath);\n        const key = readFileSync(tls.keyPath);\n        const httpsServer = createHttpsServer({ cert, key });\n        httpsServer.listen(port, host, () => {\n          const wss = new WebSocketServer({ ...wssOpts, server: httpsServer });\n          this.attachServerHandlers(wss);\n          this.servers.set(port, wss);\n          resolve();\n        });\n        httpsServer.on('error', reject);\n        return;\n      }\n      const wss = new WebSocketServer({ ...wssOpts, port, host });\n      wss.on('listening', () => {\n        this.servers.set(port, wss);\n        resolve();\n      });\n      wss.on('error', reject);\n      this.attachServerHandlers(wss);\n    });\n  }\n\n  /**\n   * Wire the server's `connection` and per-socket `message` handlers.\n   * Extracted so the wss:// path (where the WebSocketServer is attached\n   * to a pre-created https.Server) can share the same logic.\n   */\n  private attachServerHandlers(wss: WebSocketServer): void {\n    wss.on('connection', (ws, req) => {\n      const remoteAddr = `${req.socket.remoteAddress}:${req.socket.remotePort}`;\n      ws.on('message', (raw: RawData) => {\n        try {\n          const message = JSON.parse(raw.toString()) as AgentMessage;\n          // Per-stream queue (default stream when message.streamId omitted)\n          const key = this.queueKey(remoteAddr, this.streamOf(message));\n          const queue = this.messageQueue.get(key) ?? [];\n          queue.push(message);\n          this.messageQueue.set(key, queue);\n          this.dispatchInbound(remoteAddr, message);\n        } catch (err) {\n          logger.warn('Dropped malformed inbound WS message', { remoteAddr, err });\n        }\n      });\n    });\n  }\n\n  private async getOrCreateConnection(address: string): Promise<WebSocket> {\n    return new Promise((resolve, reject) => {\n      const existing = this.connections.get(address);\n      if (existing && existing.readyState === WebSocket.OPEN) {\n        resolve(existing);\n        return;\n      }\n\n      const url = address.startsWith('ws://') || address.startsWith('wss://')\n        ? address\n        : `ws://${address}`;\n\n      // ADR-107: cert pinning for wss:// peers. Build the WS options\n      // with both compression (perf) and TLS hooks (security).\n      const tls = this.config.tls;\n      const isWss = url.startsWith('wss://');\n      const wsOpts: WebSocket.ClientOptions = {\n        perMessageDeflate: {\n          threshold: 256,\n          zlibDeflateOptions: { level: 3 },\n          serverNoContextTakeover: true,\n          clientNoContextTakeover: true,\n        },\n      };\n\n      if (isWss && tls?.pinnedFingerprints && tls.pinnedFingerprints.length > 0) {\n        // Fail-closed pinning: ONLY accept the listed cert fingerprints.\n        // CA path validation is irrelevant — the fingerprint IS the trust\n        // anchor. If the cert rotates, the operator must update config.\n        const pinned = new Set(tls.pinnedFingerprints);\n        // Cast: ws's `checkServerIdentity` is typed as returning boolean\n        // but the underlying `tls.checkServerIdentity` (which it\n        // forwards to) accepts `Error | undefined`. The runtime\n        // semantics are: throw OR return Error → reject; otherwise accept.\n        // The boolean type signature is overly restrictive.\n        (wsOpts as unknown as { checkServerIdentity: unknown }).checkServerIdentity = (\n          _host: string,\n          cert: { raw: Buffer },\n        ): Error | undefined => {\n          // cert.raw is the DER-encoded cert bytes; sha256/<base64> matches\n          // common pinning notation (and what `openssl x509 -fingerprint\n          // -sha256` outputs after base64-encoding).\n          const fp = `sha256/${createHash('sha256').update(cert.raw).digest('base64')}`;\n          if (!pinned.has(fp)) {\n            return new Error(\n              `Federation TLS: peer cert fingerprint ${fp} not in pinned set ` +\n                `(${pinned.size} fingerprint(s) configured)`,\n            );\n          }\n          return undefined; // accept\n        };\n        // When pinning is on, we explicitly DON'T want CA validation\n        // (the fingerprint check above is the real auth). But we also\n        // DON'T want to silently accept ANY cert — the checkServerIdentity\n        // above is still called.\n        wsOpts.rejectUnauthorized = false;\n      } else if (isWss && tls?.caPath) {\n        // Non-pinned mode: validate against the configured CA bundle.\n        wsOpts.ca = readFileSync(tls.caPath);\n        wsOpts.rejectUnauthorized = true;\n      }\n      // (no tls config + ws:// → plain unencrypted; ADR-104 documents\n      // tailnet-as-TLS as the recommended path)\n\n      const ws = new WebSocket(url, wsOpts);\n\n      ws.on('open', () => {\n        this.connections.set(address, ws);\n        this.connectionsCreated++;\n        resolve(ws);\n      });\n\n      ws.on('error', (error: Error) => {\n        reject(new Error(`WebSocket connection to ${url} failed: ${error.message}`));\n      });\n\n      ws.on('close', () => {\n        this.connectionsClosed++;\n        this.connections.delete(address);\n      });\n\n      ws.on('message', (raw: RawData) => {\n        try {\n          const message = JSON.parse(raw.toString()) as AgentMessage;\n          const key = this.queueKey(address, this.streamOf(message));\n          const queue = this.messageQueue.get(key) ?? [];\n          queue.push(message);\n          this.messageQueue.set(key, queue);\n          this.dispatchInbound(address, message);\n        } catch (err) {\n          logger.warn('Dropped malformed WebSocket message', { address, err });\n        }\n      });\n    });\n  }\n\n  async send(address: string, message: AgentMessage): Promise<void> {\n    const ws = await this.getOrCreateConnection(address);\n    ws.send(JSON.stringify(message));\n  }\n\n  /**\n   * Register an inbound handler. Optional `options.streamId` scopes\n   * the handler to a specific stream (only fires for messages with\n   * matching streamId). Omit to subscribe to ALL streams.\n   *\n   * Patterns:\n   *   onMessage(h)                              — receives all\n   *   onMessage(h, { streamId: 'rpc' })         — receives only rpc\n   *   onMessage(h, { streamId: 'event' })       — receives only event\n   *   (both registered)                         — both fire on\n   *                                                their respective streams\n   */\n  onMessage(handler: InboundMessageHandler, options: OnMessageOptions = {}): void {\n    this.inboundHandlers.add({ handler, streamId: options.streamId });\n  }\n\n  /**\n   * Fire all matching handlers for a received message. Stream-scoped\n   * handlers only fire when the message's streamId matches; all-stream\n   * handlers always fire. Errors thrown sync OR async-rejected by one\n   * handler don't stop delivery to others.\n   */\n  private dispatchInbound(address: string, message: AgentMessage): void {\n    if (this.inboundHandlers.size === 0) return;\n    const msgStream = this.streamOf(message);\n    for (const entry of this.inboundHandlers) {\n      // Stream filter: scoped handler only fires on matching streamId\n      if (entry.streamId !== undefined && entry.streamId !== msgStream) continue;\n      try {\n        const r = entry.handler(address, message);\n        if (r && typeof (r as Promise<void>).catch === 'function') {\n          (r as Promise<void>).catch((err) => {\n            logger.warn('Inbound handler rejected', { address, err });\n          });\n        }\n      } catch (err) {\n        logger.warn('Inbound handler threw', { address, err });\n      }\n    }\n  }\n\n  async receive(address: string, streamId: string | number = DEFAULT_STREAM_ID): Promise<AgentMessage> {\n    const key = this.queueKey(address, streamId);\n    // Fast path\n    const queue = this.messageQueue.get(key) ?? [];\n    if (queue.length > 0) return queue.shift()!;\n\n    // Poll (caller must time out externally if they don't want to wait)\n    return new Promise((resolve) => {\n      const interval = setInterval(() => {\n        const q = this.messageQueue.get(key) ?? [];\n        if (q.length > 0) {\n          clearInterval(interval);\n          resolve(q.shift()!);\n        }\n      }, 100);\n    });\n  }\n\n  async request(address: string, message: AgentMessage): Promise<AgentMessage> {\n    await this.send(address, message);\n    return this.receive(address);\n  }\n\n  async sendBatch(address: string, messages: AgentMessage[]): Promise<void> {\n    await Promise.all(messages.map((m) => this.send(address, m)));\n  }\n\n  async getStats(): Promise<PoolStatistics> {\n    return {\n      active: this.connections.size,\n      idle: 0,\n      created: this.connectionsCreated,\n      closed: this.connectionsClosed,\n    };\n  }\n\n  async close(): Promise<void> {\n    // Outbound clients first.\n    for (const ws of this.connections.values()) {\n      ws.terminate();\n    }\n    this.connections.clear();\n    this.messageQueue.clear();\n\n    // Inbound: WebSocketServer.close() blocks until every accepted\n    // socket disconnects. Forcibly terminate them so the close\n    // callback fires within the test/CI timeout window.\n    for (const wss of this.servers.values()) {\n      for (const client of wss.clients) {\n        try {\n          client.terminate();\n        } catch {\n          /* socket already gone */\n        }\n      }\n      await new Promise<void>((resolve) => wss.close(() => resolve()));\n    }\n    this.servers.clear();\n  }\n}\n\n/**\n * Detect whether the WASM-backed QUIC transport is \"real\" (i.e. it\n * actually moves bytes on the wire) vs the current stub. The stub\n * returns 0ms for connect+send and never increments the server's\n * received-bytes counter. We probe by observing a documented marker\n * on the WASM module: when it's truly wired the loader function\n * `defaultConfig` returns an object whose round-trip through\n * `WasmQuicClient.new` actually opens a UDP socket — failing fast on\n * an OS that blocks UDP outbound (e.g. some sandboxed CI envs).\n *\n * Until the native build lands this returns false; the loader picks\n * WebSocket. When the native binding is wired this returns true and\n * the loader picks real QUIC. Callers get the same API either way.\n */\nasync function isRealQuicAvailable(): Promise<boolean> {\n  try {\n    // The WASM file is published in `wasm/quic/` of this package. We\n    // do NOT use it for federation today (per the wasm.rs note: it's a\n    // stub since browsers can't do UDP). When a native binding is added\n    // this probe should switch to detect that binding instead.\n    const native = process.env.AGENTIC_FLOW_QUIC_NATIVE === '1';\n    return native;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Public API — load a working transport, preferring real QUIC when\n * available, falling back to WebSocket otherwise. The returned object\n * satisfies the AgentTransport interface in both cases.\n *\n * Example:\n *   const t = await loadQuicTransport({ serverName: 'ruvultra:9100' });\n *   await t.send('ruvultra:9100', { id: '1', type: 'task', payload: {...} });\n *\n * Federation v1 ships on the WebSocket fallback (this is the actual\n * working transport today). When the native QUIC binding lands, set\n * the AGENTIC_FLOW_QUIC_NATIVE=1 environment variable and the same\n * code path picks up the upgrade with no API changes.\n */\nexport async function loadQuicTransport(\n  config: QuicTransportConfig = {},\n): Promise<AgentTransport> {\n  if (await isRealQuicAvailable()) {\n    // Future: wire to the native binding here.\n    logger.info('QUIC transport: native binding selected');\n  } else {\n    if (process.env.NODE_ENV !== 'test') {\n      logger.warn(\n        'QUIC native binding not available; using WebSocket fallback. ' +\n          'Set AGENTIC_FLOW_QUIC_NATIVE=1 once a native build is installed.',\n      );\n    }\n  }\n  return WebSocketFallbackTransport.create(config);\n}\n\n/** Quick capability probe for the doctor / health surface. */\nexport async function isQuicAvailable(): Promise<boolean> {\n  return isRealQuicAvailable();\n}\n\nexport interface TransportCapabilities {\n  quicAvailable: boolean;\n  webSocketFallbackAvailable: true;\n  selectedBackend: 'quic' | 'websocket';\n}\n\nexport async function getTransportCapabilities(): Promise<TransportCapabilities> {\n  const quic = await isRealQuicAvailable();\n  return {\n    quicAvailable: quic,\n    webSocketFallbackAvailable: true,\n    selectedBackend: quic ? 'quic' : 'websocket',\n  };\n}\n\nexport { WebSocketFallbackTransport };\n"]}