Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat(federation): ADR-120 Step 2 β€” midstream-aware transport loader (#2007)

rUv8f5934dea586
diff --git a/scripts/audit-fix-invariants.mjs b/scripts/audit-fix-invariants.mjs
index 57f1226b50..9d68ee64b5 100755
--- a/scripts/audit-fix-invariants.mjs
+++ b/scripts/audit-fix-invariants.mjs
@@ -219,6 +219,24 @@ const INVARIANTS = [
regex: /try\s*\{[\s\S]{0,200}agent\.executeTask\(task\)/,
why: 'executeTask wraps agent.executeTask in try/catch so a thrown error becomes a structured TaskResult{status:"failed", error} instead of crashing the swarm.',
},
+
+ // ADR-120 Step 2 β€” midstream-aware federation loader prefers
+ // midstreamer's real QUIC build when MIDSTREAMER_QUIC_NATIVE=1,
+ // falls back to agentic-flow's loader otherwise. Without this
+ // invariant, a refactor could silently re-introduce the bare
+ // loadQuicTransport import that bypasses the midstream preference.
+ {
+ issue: 'ADR-120',
+ file: 'v3/@claude-flow/plugin-agent-federation/src/transport/midstream-aware-loader.ts',
+ substring: 'MIDSTREAMER_QUIC_NATIVE',
+ why: 'midstream-aware loader probes MIDSTREAMER_QUIC_NATIVE first; without this env flag check, the federation transport silently stays on agentic-flow even after [email protected] ships real QUIC.',
+ },
+ {
+ issue: 'ADR-120',
+ file: 'v3/@claude-flow/plugin-agent-federation/src/plugin.ts',
+ substring: 'loadFederationTransport',
+ why: 'plugin.ts dispatches through the midstream-aware loader. Reverting to the bare loadQuicTransport import bypasses the ADR-120 preference layer entirely.',
+ },
];
const offenders = [];
diff --git a/v3/@claude-flow/plugin-agent-federation/__tests__/unit/midstream-aware-loader.test.ts b/v3/@claude-flow/plugin-agent-federation/__tests__/unit/midstream-aware-loader.test.ts
new file mode 100644
index 0000000000..2bb7d559b5
--- /dev/null
+++ b/v3/@claude-flow/plugin-agent-federation/__tests__/unit/midstream-aware-loader.test.ts
@@ -0,0 +1,108 @@
+/**
+ * Unit tests for the midstream-aware federation transport loader
+ * (ADR-120, Step 2).
+ *
+ * The loader's job is narrow: when MIDSTREAMER_QUIC_NATIVE=1 AND a
+ * real (non-stub) midstreamer module is importable, return it.
+ * Otherwise, fall through to the agentic-flow loader. These tests
+ * verify both branches by stubbing the dynamic import / mocking the
+ * agentic-flow loader where needed.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+
+import {
+ loadFederationTransport,
+} from '../../src/transport/midstream-aware-loader.js';
+
+// We don't want the real agentic-flow loader to fire UDP / WebSocket
+// listeners in tests. Mock the underlying transport so every test
+// gets a deterministic transport stub.
+vi.mock('agentic-flow/transport/loader', async () => {
+ return {
+ loadQuicTransport: vi.fn(async () => ({
+ send: vi.fn(),
+ receive: vi.fn(),
+ request: vi.fn(),
+ sendBatch: vi.fn(),
+ getStats: vi.fn(),
+ close: vi.fn(),
+ // Marker so we can assert which branch resolved
+ __mockSource: 'agentic-flow-mock',
+ })),
+ };
+});
+
+describe('loadFederationTransport β€” ADR-120 Step 2', () => {
+ const originalEnv = process.env.MIDSTREAMER_QUIC_NATIVE;
+
+ beforeEach(() => {
+ delete process.env.MIDSTREAMER_QUIC_NATIVE;
+ });
+
+ afterEach(() => {
+ if (originalEnv === undefined) {
+ delete process.env.MIDSTREAMER_QUIC_NATIVE;
+ } else {
+ process.env.MIDSTREAMER_QUIC_NATIVE = originalEnv;
+ }
+ });
+
+ it('defers to agentic-flow when MIDSTREAMER_QUIC_NATIVE is unset', async () => {
+ const loaded = await loadFederationTransport();
+ expect(loaded.source).toBe('agentic-flow-loader');
+ expect(loaded.transport).toBeDefined();
+ expect((loaded.transport as unknown as { __mockSource: string }).__mockSource).toBe(
+ 'agentic-flow-mock',
+ );
+ });
+
+ it('defers to agentic-flow when MIDSTREAMER_QUIC_NATIVE is "0"', async () => {
+ process.env.MIDSTREAMER_QUIC_NATIVE = '0';
+ const loaded = await loadFederationTransport();
+ expect(loaded.source).toBe('agentic-flow-loader');
+ });
+
+ it('defers to agentic-flow with no error noise when midstreamer is not installed', async () => {
+ process.env.MIDSTREAMER_QUIC_NATIVE = '1';
+ // No need to mock 'midstreamer' β€” the dynamic import will throw
+ // MODULE_NOT_FOUND and the loader is supposed to fall through.
+ const loaded = await loadFederationTransport();
+ expect(loaded.source).toBe('agentic-flow-loader');
+ // `fallbackReason` is only set when a probe ran to completion and
+ // produced a diagnostic; a clean miss leaves it unset.
+ expect(loaded.fallbackReason).toBeUndefined();
+ });
+
+ it('passes config through to the underlying loader', async () => {
+ const mod = await import('agentic-flow/transport/loader');
+ const loaderFn = (mod as unknown as { loadQuicTransport: ReturnType<typeof vi.fn> })
+ .loadQuicTransport;
+ loaderFn.mockClear();
+
+ await loadFederationTransport({
+ serverName: 'test-node',
+ maxIdleTimeoutMs: 12_345,
+ maxConcurrentStreams: 42,
+ enable0Rtt: false,
+ });
+
+ expect(loaderFn).toHaveBeenCalledWith(
+ expect.objectContaining({
+ serverName: 'test-node',
+ maxIdleTimeoutMs: 12_345,
+ maxConcurrentStreams: 42,
+ enable0Rtt: false,
+ }),
+ );
+ });
+
+ it('returned envelope has the documented LoadedFederationTransport shape', async () => {
+ const loaded = await loadFederationTransport();
+ expect(Object.keys(loaded).sort()).toEqual(
+ expect.arrayContaining(['transport', 'source']),
+ );
+ // `source` must be one of the two documented values.
+ expect(['midstreamer-native', 'agentic-flow-loader']).toContain(loaded.source);
+ });
+});
diff --git a/v3/@claude-flow/plugin-agent-federation/src/plugin.ts b/v3/@claude-flow/plugin-agent-federation/src/plugin.ts
index 6a5be33fca..fb7f067c3f 100644
--- a/v3/@claude-flow/plugin-agent-federation/src/plugin.ts
+++ b/v3/@claude-flow/plugin-agent-federation/src/plugin.ts
@@ -30,18 +30,24 @@ import { TrustLevel, getTrustLevelLabel } from './domain/entities/trust-level.js
import { type FederationMessageType } from './domain/entities/federation-envelope.js';
// ADR-104: real wire transport via agentic-flow loader pattern.
-// Today this resolves to WebSocketFallbackTransport (real ws networking);
-// when ruvnet/agentic-flow ships a native QUIC binding the same import
-// auto-upgrades with no plugin changes (set AGENTIC_FLOW_QUIC_NATIVE=1).
-type LoadedTransport = Awaited<ReturnType<typeof loadQuicTransport>> & {
+// ADR-120: midstream-aware loader wraps the agentic-flow loader so
+// when `midstreamer` (ruvnet/midstream) ships its production QUIC
+// build (Step 1 of ADR-120) and operators opt in with
+// MIDSTREAMER_QUIC_NATIVE=1, the federation transport auto-upgrades.
+// Until then, the wrapper transparently defers to the agentic-flow
+// loader β€” which itself resolves to WebSocketFallbackTransport
+// today, or native QUIC when AGENTIC_FLOW_QUIC_NATIVE=1.
+import {
+ loadFederationTransport,
+ type AgentMessage,
+ type AgentTransport,
+} from './transport/midstream-aware-loader.js';
+
+type LoadedTransport = AgentTransport & {
/** WebSocketFallbackTransport adds listen(); the loader's interface
* doesn't include it, so we cast at the call site. */
listen?: (port: number, host?: string) => Promise<void>;
};
-import {
- loadQuicTransport,
- type AgentMessage,
-} from 'agentic-flow/transport/loader';
import { dispatchInbound, canonicalizeEnvelopeForVerify } from './application/inbound-dispatcher.js';
import { createMcpTools } from './mcp-tools.js';
import { createCliCommands } from './cli-commands.js';
@@ -216,20 +222,28 @@ export class AgentFederationPlugin implements ClaudeFlowPlugin {
const sessions: Map<string, import('./domain/entities/federation-session.js').FederationSession> = new Map();
- // ADR-104: load wire transport. WebSocket fallback by default; native
- // QUIC when AGENTIC_FLOW_QUIC_NATIVE=1 + binding installed. Failures
- // here downgrade to in-process noop (logged), preserving backward
- // compat for tests/environments without ws available.
+ // ADR-104 + ADR-120: load wire transport. WebSocket fallback by
+ // default; native QUIC when AGENTIC_FLOW_QUIC_NATIVE=1 (ADR-108) or
+ // MIDSTREAMER_QUIC_NATIVE=1 (ADR-120 Step 1, when [email protected]
+ // ships its real QUIC build). The midstream-aware loader picks the
+ // best available transport transparently. Failures downgrade to
+ // in-process noop (logged), preserving backward compat for
+ // tests/environments without ws available.
let transport: LoadedTransport | null = null;
try {
- transport = await loadQuicTransport({
+ const loaded = await loadFederationTransport({
serverName: nodeId,
maxIdleTimeoutMs: 30_000,
maxConcurrentStreams: 100,
enable0Rtt: true,
- }) as LoadedTransport;
+ });
+ transport = loaded.transport as LoadedTransport;
this.transport = transport;
- context.logger.info(`Federation transport loaded: ${nodeId}`);
+ context.logger.info(
+ `Federation transport loaded: ${nodeId} (source=${loaded.source}${
+ loaded.fallbackReason ? `, note=${loaded.fallbackReason}` : ''
+ })`,
+ );
} catch (err) {
context.logger.warn(
`Federation transport unavailable (${err instanceof Error ? err.message : err}); ` +
diff --git a/v3/@claude-flow/plugin-agent-federation/src/transport/midstream-aware-loader.ts b/v3/@claude-flow/plugin-agent-federation/src/transport/midstream-aware-loader.ts
new file mode 100644
index 0000000000..d755857255
--- /dev/null
+++ b/v3/@claude-flow/plugin-agent-federation/src/transport/midstream-aware-loader.ts
@@ -0,0 +1,142 @@
+/**
+ * Midstream-aware federation transport loader (ADR-120, Step 2).
+ *
+ * Extends the agentic-flow `loadQuicTransport` loader pattern with a
+ * preferred branch that probes `midstreamer` first. When `midstreamer`
+ * ships real QUIC (currently the WASM build is a counter-tracking
+ * stub per ADR-119), this loader picks it up automatically without
+ * any change to consumer plugins.
+ *
+ * Resolution order:
+ *
+ * 1. If `MIDSTREAMER_QUIC_NATIVE=1` AND the `midstreamer` module
+ * exposes a real `QuicMultistream`-derived `AgentTransport`,
+ * use it. (Today: probes fail closed and we fall through.)
+ *
+ * 2. Otherwise: defer to agentic-flow's existing loader, which
+ * itself respects `AGENTIC_FLOW_QUIC_NATIVE=1` (ADR-108) and
+ * falls back to WebSocket (ADR-104) otherwise.
+ *
+ * The loader is opt-in: callers must explicitly invoke
+ * `loadFederationTransport()` instead of `loadQuicTransport()`.
+ * Behavior is identical to `loadQuicTransport()` until upstream
+ * `midstreamer` ships its real QUIC build AND the operator sets the
+ * env flag β€” so this change is safe to land before any of that
+ * happens.
+ *
+ * Re-exports the `AgentTransport` / `AgentMessage` / `QuicTransportConfig`
+ * surface from agentic-flow so consumers only import from one place.
+ */
+
+import {
+ loadQuicTransport,
+ type AgentTransport,
+ type AgentMessage,
+ type QuicTransportConfig,
+} from 'agentic-flow/transport/loader';
+
+export type { AgentTransport, AgentMessage, QuicTransportConfig };
+
+/** Result envelope describing which backend the loader picked. */
+export interface LoadedFederationTransport {
+ /** The live transport. Send/receive against this. */
+ transport: AgentTransport;
+ /** Which loader branch resolved. Useful for logs/metrics. */
+ source: 'midstreamer-native' | 'agentic-flow-loader';
+ /** Free-form note when a probe failed (helps explain a fallback). */
+ fallbackReason?: string;
+}
+
+/**
+ * Probe the `midstreamer` npm package for a real QUIC transport.
+ * Returns `null` when the env flag is off, when the package isn't
+ * installed, when the import surface doesn't match expectations, or
+ * when the loaded module is detectably the WASM stub (per ADR-119
+ * the current shipped build is a counter-tracking stub β€” `isNative()`
+ * or `isStub()` probes are checked when available).
+ *
+ * The function never throws β€” any failure becomes `null` so the
+ * outer `loadFederationTransport` can transparently fall back.
+ */
+async function probeMidstreamerTransport(
+ config?: QuicTransportConfig,
+): Promise<{ transport: AgentTransport; reason?: string } | null> {
+ if (process.env.MIDSTREAMER_QUIC_NATIVE !== '1') {
+ return null;
+ }
+
+ let mod: unknown;
+ try {
+ // Lazy + indirect so bundlers don't try to resolve at compile time.
+ // The `'midstreamer'` package name is what `ruvnet/midstream`
+ // publishes (the README calls it `@midstream/wasm` but that's a
+ // packaging desync; install name wins β€” see ADR-119).
+ const dynamicImport: (s: string) => Promise<unknown> = new Function(
+ 's',
+ 'return import(s)',
+ ) as (s: string) => Promise<unknown>;
+ mod = await dynamicImport('midstreamer');
+ } catch {
+ return null;
+ }
+
+ const candidate = mod as {
+ loadQuicTransport?: (c?: QuicTransportConfig) => Promise<AgentTransport>;
+ isNative?: () => boolean;
+ isStub?: () => boolean;
+ };
+
+ // Refuse to use the WASM stub. ADR-119 documented the current shipped
+ // QuicMultistream as a counter-tracking stub with no real UDP, TLS,
+ // or protocol β€” using it would silently downgrade the federation
+ // path. When [email protected] ships real QUIC (ADR-120, Step 1),
+ // either `isNative()` returns true OR `isStub()` is absent.
+ if (typeof candidate.isStub === 'function' && candidate.isStub()) {
+ return { transport: null as unknown as AgentTransport, reason: 'midstreamer module reports isStub() === true; refusing to bind a stub QUIC backend (ADR-119)' };
+ }
+
+ if (typeof candidate.loadQuicTransport !== 'function') {
+ return null;
+ }
+
+ if (typeof candidate.isNative === 'function' && !candidate.isNative()) {
+ return null;
+ }
+
+ try {
+ const transport = await candidate.loadQuicTransport(config);
+ return { transport };
+ } catch (err) {
+ return {
+ transport: null as unknown as AgentTransport,
+ reason: `midstreamer.loadQuicTransport failed: ${err instanceof Error ? err.message : String(err)}`,
+ };
+ }
+}
+
+/**
+ * Top-level loader for federation transport. Identical signature to
+ * agentic-flow's `loadQuicTransport`, but with the midstreamer-first
+ * preference. Use this from `plugins/ruflo-federation` in place of
+ * the bare `loadQuicTransport`.
+ *
+ * Failure mode: if midstreamer is requested but rejects (stub, init
+ * error, missing package), this function falls through to the
+ * agentic-flow loader silently β€” the federation peer always gets a
+ * transport (WebSocket fallback in the worst case, per ADR-104).
+ */
+export async function loadFederationTransport(
+ config?: QuicTransportConfig,
+): Promise<LoadedFederationTransport> {
+ const probe = await probeMidstreamerTransport(config);
+ if (probe && probe.transport) {
+ return { transport: probe.transport, source: 'midstreamer-native' };
+ }
+
+ const transport = await loadQuicTransport(config);
+ return {
+ transport,
+ source: 'agentic-flow-loader',
+ fallbackReason: probe?.reason,
+ };
+}