agentic-flow 3.0.0-alpha.2 → 3.0.0

package/dist/transport/index.js

@@ -1,3 +1,4 @@
 // Transport Layer Exports
 export * from './quic.js';
+export { loadQuicTransport, isQuicAvailable, getTransportCapabilities, WebSocketFallbackTransport, DEFAULT_STREAM_ID, } from './quic-loader.js';
 //# sourceMappingURL=index.js.map

package/dist/transport/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/transport/index.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAC1B,cAAc,WAAW,CAAC","sourcesContent":["// Transport Layer Exports\nexport * from './quic.js';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/transport/index.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAC1B,cAAc,WAAW,CAAC;AAC1B,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,wBAAwB,EACxB,0BAA0B,EAC1B,iBAAiB,GASlB,MAAM,kBAAkB,CAAC","sourcesContent":["// Transport Layer Exports\nexport * from './quic.js';\nexport {\n  loadQuicTransport,\n  isQuicAvailable,\n  getTransportCapabilities,\n  WebSocketFallbackTransport,\n  DEFAULT_STREAM_ID,\n  type AgentTransport,\n  type AgentMessage,\n  type InboundMessageHandler,\n  type OnMessageOptions,\n  type PoolStatistics,\n  type TransportCapabilities,\n  type QuicTransportConfig as LoaderQuicTransportConfig,\n  type TlsConfig,\n} from './quic-loader.js';\n"]}

package/dist/transport/quic-loader.d.ts

@@ -0,0 +1,266 @@
+/** TLS configuration for wss:// peers (ADR-107). */
+export interface TlsConfig {
+    /** Path to PEM cert file (server side — bind certs for the listener). */
+    certPath?: string;
+    /** Path to PEM key file (server side). */
+    keyPath?: string;
+    /**
+     * Pinned `sha256/<base64>` fingerprints of acceptable peer certs
+     * (client side — outbound connections).
+     *
+     * When set, ONLY these exact certs are accepted. CA validation is
+     * skipped — the fingerprint IS the trust anchor. Fail-closed: if the
+     * peer's cert rotates and the fingerprint doesn't match, the
+     * connection is refused (operator must update config + restart).
+     *
+     * This prevents:
+     *   - Compromised public CAs issuing rogue certs for our domain
+     *   - TLS-MITM attacks where the attacker holds a valid cert chain
+     */
+    pinnedFingerprints?: string[];
+    /**
+     * Optional CA bundle path for non-pinned mode (e.g. private CA).
+     * Used only when `pinnedFingerprints` is empty/unset.
+     */
+    caPath?: string;
+}
+/** Caller-facing config — minimal common surface across both backends. */
+export interface QuicTransportConfig {
+    serverName?: string;
+    maxIdleTimeoutMs?: number;
+    maxConcurrentStreams?: number;
+    enable0Rtt?: boolean;
+    /** TLS materials for wss:// listeners + clients (ADR-107). */
+    tls?: TlsConfig;
+}
+export interface AgentMessage {
+    id: string;
+    type: 'task' | 'result' | 'status' | 'coordination' | 'heartbeat' | string;
+    payload: unknown;
+    metadata?: Record<string, unknown>;
+    /**
+     * Stream multiplexing identifier. Messages with different streamIds
+     * to the same peer are independent — receive queues and onMessage
+     * handlers can scope per-stream, eliminating head-of-line blocking
+     * for sequential `await` patterns on a single peer connection.
+     *
+     * Defaults to `'default'` if omitted (backward compat). Common
+     * patterns:
+     *   - One stream per logical request type (`'rpc'`, `'event'`,
+     *     `'control'`)
+     *   - One stream per task (`taskId` doubled as streamId)
+     *   - One stream per priority class (`'high'`, `'normal'`, `'low'`)
+     *
+     * Maps cleanly to native QUIC streams when AGENTIC_FLOW_QUIC_NATIVE=1
+     * (each app-layer streamId becomes a QUIC stream id at that point).
+     */
+    streamId?: string | number;
+}
+/** Default streamId when caller omits it. Backward-compat sentinel. */
+export declare const DEFAULT_STREAM_ID = "default";
+/** Largest WebSocket frame accepted from a peer (federation envelopes are ~100B-10KB). */
+export declare const MAX_WS_PAYLOAD_BYTES: number;
+/** Unconsumed messages kept per (peer, stream) for receive(); oldest dropped beyond this. */
+export declare const MAX_QUEUED_PER_STREAM = 1000;
+/** Distinct (peer, stream) queues kept; messages for further new streams are dropped. */
+export declare const MAX_QUEUE_STREAMS = 1024;
+export interface PoolStatistics {
+    active: number;
+    idle: number;
+    created: number;
+    closed: number;
+}
+/** Inbound message handler — called for every received message. */
+export type InboundMessageHandler = (address: string, message: AgentMessage) => void | Promise<void>;
+/**
+ * Per-stream subscription options. Pass to `onMessage` to scope a
+ * handler to a specific streamId (only fires for messages with that
+ * exact streamId). Omit to receive all streams.
+ */
+export interface OnMessageOptions {
+    readonly streamId?: string | number;
+}
+/** Common interface both real-QUIC and fallback transports satisfy. */
+export interface AgentTransport {
+    send(address: string, message: AgentMessage): Promise<void>;
+    /**
+     * Receive the next message from a peer. Optional `streamId` scopes
+     * to that stream's queue (independent of other streams to the same
+     * peer). Omit to use the default stream — backward-compat behavior.
+     */
+    receive(address: string, streamId?: string | number): Promise<AgentMessage>;
+    request(address: string, message: AgentMessage): Promise<AgentMessage>;
+    sendBatch(address: string, messages: AgentMessage[]): Promise<void>;
+    getStats(): Promise<PoolStatistics>;
+    close(): Promise<void>;
+    /**
+     * Subscribe to inbound messages. The handler fires for every received
+     * message that matches `options.streamId` (if provided) or for every
+     * message regardless of streamId (if options omitted).
+     *
+     * Multiple handlers may be registered (per-stream OR all-streams or
+     * a mix). Errors thrown by a handler are logged but do not stop
+     * delivery to other handlers.
+     *
+     * Optional method — implementations that don't support push-style
+     * delivery may omit it. Callers should use `transport.onMessage?.(h)`
+     * to gracefully degrade.
+     */
+    onMessage?(handler: InboundMessageHandler, options?: OnMessageOptions): void;
+}
+/**
+ * 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).
+ */
+declare class WebSocketFallbackTransport implements AgentTransport {
+    private readonly config;
+    private connections;
+    /**
+     * 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.
+     */
+    private messageQueue;
+    private connectionsCreated;
+    private connectionsClosed;
+    private servers;
+    /**
+     * 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.
+     */
+    private inboundHandlers;
+    /**
+     * Server-accepted (inbound) sockets indexed by peer host (#162). A
+     * peer that already dialed us has a live, full-duplex socket here;
+     * {@link getOrCreateConnection} reuses it for replies instead of
+     * opening a fresh outbound connection — which, on a direct
+     * point-to-point link, can hit a per-process stale scoped route
+     * (`EHOSTUNREACH`) even while the inbound direction is healthy.
+     */
+    private inboundByHost;
+    /** Active liveness-probe intervals, cleared on close (#162). */
+    private heartbeats;
+    /**
+     * Liveness ping cadence, derived from `maxIdleTimeoutMs` (#162 — this
+     * config was previously accepted but never used). Pings at 1/6 of the
+     * idle timeout so a dead socket is caught within ~1/3 of it. Default
+     * 30000ms → 5000ms.
+     */
+    private get pingIntervalMs();
+    /**
+     * Normalize an address or socket `remoteAddress` to a bare host key
+     * for {@link inboundByHost} lookups. Strips `ws(s)://` scheme, an
+     * IPv6-mapped IPv4 prefix (`::ffff:`), bracketed IPv6 (`[::1]:port`),
+     * and a trailing `:port` on plain `host:port` forms. Bare IPv6
+     * (multiple colons, no brackets) is returned unchanged.
+     */
+    private hostOf;
+    /**
+     * Liveness probe for a socket (#162). Pings on {@link pingIntervalMs};
+     * a socket that misses a ping/pong window is terminated so a stale
+     * connection can't silently black-hole sends. The interval is unref'd
+     * (never keeps the process alive on its own) and cleared on close/error.
+     */
+    private startHeartbeat;
+    /** Compose the per-(address, streamId) queue key. */
+    private queueKey;
+    /** Resolve the streamId for a message — defaults to DEFAULT_STREAM_ID. */
+    private streamOf;
+    constructor(config: Required<QuicTransportConfig>);
+    static create(config?: QuicTransportConfig): Promise<WebSocketFallbackTransport>;
+    /**
+     * 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
+     */
+    listen(port: number, host?: string): Promise<void>;
+    /**
+     * 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.
+     */
+    private attachServerHandlers;
+    private getOrCreateConnection;
+    send(address: string, message: AgentMessage): Promise<void>;
+    /**
+     * 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: InboundMessageHandler, options?: OnMessageOptions): void;
+    /**
+     * 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.
+     */
+    private dispatchInbound;
+    /**
+     * Hand an inbound message to the matching onMessage handlers. Only a
+     * message no handler consumed is queued for receive(), and the queues are
+     * bounded so a peer cannot grow memory without limit.
+     */
+    private deliverInbound;
+    /** Shift the head of a queue, dropping the queue once empty so stream keys don't accumulate. */
+    private takeFrom;
+    /** Messages waiting for receive(), across all peers and streams. */
+    queuedMessageCount(): number;
+    receive(address: string, streamId?: string | number): Promise<AgentMessage>;
+    request(address: string, message: AgentMessage): Promise<AgentMessage>;
+    sendBatch(address: string, messages: AgentMessage[]): Promise<void>;
+    getStats(): Promise<PoolStatistics>;
+    close(): Promise<void>;
+}
+/**
+ * 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 declare function loadQuicTransport(config?: QuicTransportConfig): Promise<AgentTransport>;
+/** Quick capability probe for the doctor / health surface. */
+export declare function isQuicAvailable(): Promise<boolean>;
+export interface TransportCapabilities {
+    quicAvailable: boolean;
+    webSocketFallbackAvailable: true;
+    selectedBackend: 'quic' | 'websocket';
+}
+export declare function getTransportCapabilities(): Promise<TransportCapabilities>;
+export { WebSocketFallbackTransport };
+//# sourceMappingURL=quic-loader.d.ts.map

package/dist/transport/quic-loader.d.ts.map

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