π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
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.mjsindex 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.tsnew file mode 100644index 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.tsindex 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.jsimport { 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.tsnew file mode 100644index 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,+ };+}