@claude-flow/plugin-agent-federation 1.0.0-alpha.14 → 1.0.0-alpha.16

package/dist/transport/midstream-aware-loader.js

@@ -0,0 +1,167 @@
+/**
+ * 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.
+ */
+/**
+ * Lazy loader for agentic-flow's `loadQuicTransport`. Returns `null`
+ * when `agentic-flow` is not installed — callers must then fall back
+ * to the midstream-first path or surface a clear error.
+ *
+ * Per ADR-120 + issue #1949, `agentic-flow` is now an **optional**
+ * peer dependency. Operators who only want the midstream-native
+ * transport (via `MIDSTREAMER_QUIC_NATIVE=1`) can omit it to avoid
+ * the deep `koa-router` → `cookies@0.9.1` transitive chain that
+ * hardened npm registries reject.
+ */
+async function loadAgenticFlowQuicTransport(config) {
+    // Direct dynamic `import()` (not the `new Function` trick) so
+    // test frameworks like vitest can intercept via `vi.mock`. The
+    // try/catch makes the module-not-found case a clean `null` so the
+    // caller falls back gracefully — agentic-flow is now an optional
+    // peer dependency.
+    let mod;
+    try {
+        mod = (await import('agentic-flow/transport/loader'));
+    }
+    catch {
+        return null;
+    }
+    const fn = typeof mod.loadQuicTransport === 'function'
+        ? mod.loadQuicTransport
+        : mod.default?.loadQuicTransport;
+    if (typeof fn !== 'function') {
+        return null;
+    }
+    try {
+        return await fn(config);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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) {
+    if (process.env.MIDSTREAMER_QUIC_NATIVE !== '1') {
+        return null;
+    }
+    let mod;
+    try {
+        // Lazy + indirect so bundlers don't try to resolve at compile time.
+        // Prefer the `midstreamer/quic` sub-path (added in midstreamer@0.3.1
+        // per upstream ruvnet/midstream#81) which exposes
+        // `loadQuicTransport` directly without WASM init. Fall back to the
+        // root `midstreamer` package for older versions that put the QUIC
+        // surface on the default export.
+        const dynamicImport = new Function('s', 'return import(s)');
+        try {
+            mod = await dynamicImport('midstreamer/quic');
+        }
+        catch {
+            mod = await dynamicImport('midstreamer');
+        }
+    }
+    catch {
+        return null;
+    }
+    const candidate = mod;
+    // CommonJS sub-path exposes its API via `module.exports = {...};
+    // module.exports.default = module.exports;` — so we also accept the
+    // `.default` form. ESM imports flatten the named exports directly.
+    const surface = (typeof candidate.loadQuicTransport === 'function'
+        ? candidate
+        : candidate.default);
+    if (!surface) {
+        return null;
+    }
+    // Refuse to use the WASM stub. ADR-119 documented the previous
+    // QuicMultistream as a counter-tracking stub with no real UDP, TLS,
+    // or protocol — using it would silently downgrade the federation
+    // path. midstreamer@0.3.1+ ships a real QUIC transport via
+    // `midstreamer/quic` (ADR-120, Step 1 — upstream PR ruvnet/midstream#81)
+    // and reports `isNative() === true`. Older versions either expose
+    // `isStub()` returning true or omit both probes.
+    if (typeof surface.isStub === 'function' && surface.isStub()) {
+        return { transport: null, reason: 'midstreamer module reports isStub() === true; refusing to bind a stub QUIC backend (ADR-119)' };
+    }
+    if (typeof surface.loadQuicTransport !== 'function') {
+        return null;
+    }
+    if (typeof surface.isNative === 'function' && !surface.isNative()) {
+        return null;
+    }
+    try {
+        const transport = await surface.loadQuicTransport(config);
+        return { transport };
+    }
+    catch (err) {
+        return {
+            transport: null,
+            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) {
+    const probe = await probeMidstreamerTransport(config);
+    if (probe && probe.transport) {
+        return { transport: probe.transport, source: 'midstreamer-native' };
+    }
+    const transport = await loadAgenticFlowQuicTransport(config);
+    if (!transport) {
+        throw new Error('No federation transport available. Install `agentic-flow` ' +
+            '(default) or `midstreamer` and set `MIDSTREAMER_QUIC_NATIVE=1` ' +
+            '(per ADR-120). Both are now optional peer dependencies — at ' +
+            'least one must be present at runtime.');
+    }
+    return {
+        transport,
+        source: 'agentic-flow-loader',
+        fallbackReason: probe?.reason,
+    };
+}
+//# sourceMappingURL=midstream-aware-loader.js.map

package/dist/transport/midstream-aware-loader.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/plugin-agent-federation",
-  "version": "1.0.0-alpha.14",
+  "version": "1.0.0-alpha.16",
   "description": "Cross-installation agent federation with zero-trust security, PII-gated data flow, and compliance-grade audit trails.",
   "homepage": "https://github.com/ruvnet/ruflo",
   "type": "module",
@@ -21,12 +21,24 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@noble/ed25519": "^2.0.0",
-    "agentic-flow": "2.0.12-fix.8"
+    "@noble/ed25519": "^2.0.0"
+  },
+  "peerDependencies": {
+    "agentic-flow": ">=2.0.12-fix.8",
+    "midstreamer": ">=0.3.1"
+  },
+  "peerDependenciesMeta": {
+    "agentic-flow": {
+      "optional": true
+    },
+    "midstreamer": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@claude-flow/shared": "workspace:*",
     "@claude-flow/security": "workspace:*",
+    "agentic-flow": "2.0.12-fix.8",
     "typescript": "^5.4.0",
     "vitest": "^4.0.16"
   },