@claude-flow/cli 3.39.3 → 3.41.0

package/.claude/helpers/helpers.manifest.json

@@ -1,6 +1,6 @@
 {
   "manifest": {
-    "version": "3.39.3",
+    "version": "3.41.0",
     "files": {
       "auto-memory-hook.mjs": "85fe05c757421c52137c0bc8545a0896bab6b4714538c2a11d1d0835bfcc8c1c",
       "hook-handler.cjs": "209d9fafe10e17d1be0866727f6f9cf9ac66f9a0793f1c793a4f58319e8e4583",
@@ -8,6 +8,6 @@
       "statusline.cjs": "4a48353b4f1566fa4379b00fd0321b6676a22b6cc91fbbd8380ac5183d619468"
     }
   },
-  "signature": "rJ2JGAqKGTyEQH0zJfJEUHMUC+KV5FdSPiprkhc9gf620sZQO0r9/YksOolXgQOJLpg9EF05oFc+XSBaA772AA==",
+  "signature": "lJIU7TlbDO4FdWAceZ1eddxBvAn8zCSnrN+SNhhSpbeDv4jFgUWHFkYj27+O1DGRRDoebonbSRLrzbcWP9hHCQ==",
   "algorithm": "ed25519"
 }

package/catalog-manifest.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "generation": 6,
-  "generatedAt": "2026-09-09T20:16:38.603Z",
-  "gitSha": "07f1cf3a",
+  "generatedAt": "2026-09-10T11:59:15.567Z",
+  "gitSha": "cb10bf61",
   "catalog": {
     "agents": 167,
-    "tools": 397,
+    "tools": 418,
     "skills": 34
   },
   "benchmark": null

package/dist/src/commands/federation.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `ruflo federation` — open swarm federation via x.ruv.io (Nostr, signed,
+ * membership-gated). Thin CLI over the x_federation_* MCP tools so the same
+ * behaviour is available in-process and from any MCP client.
+ */
+import type { Command } from '../types.js';
+export declare const federationCommand: Command;
+//# sourceMappingURL=federation.d.ts.map

package/dist/src/commands/federation.js

@@ -0,0 +1,98 @@
+import { output } from '../output.js';
+import { callMCPTool } from '../mcp-client.js';
+function printJsonOrTable(ctx, data, title) {
+    if (ctx.flags.format === 'json') {
+        output.printJson(data);
+        return;
+    }
+    output.printInfo(title);
+    output.writeln(JSON.stringify(data, null, 2));
+}
+async function run(ctx, tool, args, title) {
+    try {
+        // CLI flag --gateway takes precedence over the RUFLO_X_GATEWAY_URL env var (ADR-125).
+        const data = await callMCPTool(tool, { gatewayUrl: ctx.flags.gateway, ...args });
+        printJsonOrTable(ctx, data, title);
+        return { success: true, data };
+    }
+    catch (e) {
+        output.printError(`${title} failed: ${e.message}`);
+        return { success: false, exitCode: 1 };
+    }
+}
+export const federationCommand = {
+    name: 'federation',
+    description: 'Open swarm federation via x.ruv.io — sync messages, roster, claims, registry, invites (Nostr, signed, membership-gated)',
+    options: [
+        { name: 'format', short: 'f', description: 'Output format (json|text)', type: 'string', default: 'text' },
+        { name: 'gateway', description: 'Gateway base URL (takes precedence over RUFLO_X_GATEWAY_URL; default https://x.ruv.io)', type: 'string' },
+    ],
+    subcommands: [
+        { name: 'join', description: 'Join the open swarm with YOUR OWN key using an invite code (generates ~/.ruflo/nostr.key if absent, claims via NIP-98, verifies via NIP-42)',
+            options: [{ name: 'code', description: 'Invite code (v2.…) — a bearer secret, keep it private', type: 'string', required: true }],
+            action: (ctx) => run(ctx, 'x_federation_join', { code: ctx.flags.code }, 'Join federation') },
+        { name: 'sync', description: 'Fetch recent verified swarm messages',
+            options: [{ name: 'since', description: 'Look-back seconds (default 3600)', type: 'number' }, { name: 'limit', description: 'Max messages', type: 'number' }, { name: 'type', description: 'Filter by message type', type: 'string' }],
+            action: (ctx) => run(ctx, 'x_federation_sync', { sinceSeconds: ctx.flags.since, limit: ctx.flags.limit, type: ctx.flags.type }, 'Federation sync') },
+        { name: 'roster', description: 'Nodes currently announcing on the open swarm', action: (ctx) => run(ctx, 'x_federation_roster', {}, 'Swarm roster') },
+        { name: 'claims', description: 'Current owner-per-resource claims ledger', action: (ctx) => run(ctx, 'x_federation_claims', {}, 'Claims board') },
+        { name: 'registry', description: 'Relay, canonical NIP-42 relay tag, gateway pubkey and self-join steps', action: (ctx) => run(ctx, 'x_federation_registry', {}, 'Federation registry') },
+        { name: 'invite', description: 'Mint a self-join invite code (admin; needs RUFLO_X_ADMIN_TOKEN). The code is a bearer secret — share privately.',
+            options: [{ name: 'ttl', description: 'Validity seconds (default 7d)', type: 'number' }, { name: 'uses', description: 'Max redemptions (default 25)', type: 'number' }],
+            action: (ctx) => run(ctx, 'x_federation_invite_mint', { ttlSecs: ctx.flags.ttl, maxUses: ctx.flags.uses }, 'Invite minted') },
+        { name: 'admit', description: 'Admit a 64-hex Nostr pubkey as relay member (admin; needs RUFLO_X_ADMIN_TOKEN)',
+            options: [{ name: 'pubkey', description: '64-hex pubkey', type: 'string', required: true }, { name: 'role', description: 'member|admin', type: 'string' }],
+            action: (ctx) => run(ctx, 'x_federation_admit', { pubkey: ctx.flags.pubkey, role: ctx.flags.role }, 'Admit member') },
+        { name: 'publish', description: 'Publish a message AS THE GATEWAY (admin; needs RUFLO_X_ADMIN_TOKEN). Nodes should publish with their own key instead.',
+            options: [{ name: 'type', description: 'Message type (Status|Task|Result|…)', type: 'string', required: true }, { name: 'payload', description: 'JSON payload', type: 'string', required: true }],
+            action: (ctx) => {
+                let payload;
+                try {
+                    payload = JSON.parse(String(ctx.flags.payload));
+                }
+                catch {
+                    output.printError('--payload must be JSON');
+                    return Promise.resolve({ success: false, exitCode: 1 });
+                }
+                return run(ctx, 'x_federation_publish', { msgType: ctx.flags.type, payload }, 'Published');
+            } },
+        { name: 'channel', description: 'Public and private swarm channels (ADR-386). Private channels are encrypted with a key only this machine holds.',
+            options: [
+                { name: 'action', description: 'create|grant|accept|publish|read|list', type: 'string', required: true },
+                { name: 'name', description: 'Channel name (create)', type: 'string' },
+                { name: 'visibility', description: 'public|private (create)', type: 'string' },
+                { name: 'channel', description: 'Channel id: pub:<name> or prv:<16 hex>', type: 'string' },
+                { name: 'pubkey', description: '64-hex member pubkey (grant)', type: 'string' },
+                { name: 'type', description: 'Message type (publish)', type: 'string' },
+                { name: 'payload', description: 'JSON payload (publish)', type: 'string' },
+                { name: 'since', description: 'Look-back seconds (read|accept)', type: 'number' },
+                { name: 'limit', description: 'Max messages (read)', type: 'number' },
+            ],
+            action: (ctx) => {
+                const a = String(ctx.flags.action);
+                switch (a) {
+                    case 'create': return run(ctx, 'x_federation_channel_create', { name: ctx.flags.name, visibility: ctx.flags.visibility ?? 'public' }, 'Channel created');
+                    case 'grant': return run(ctx, 'x_federation_channel_grant', { channel: ctx.flags.channel, pubkey: ctx.flags.pubkey }, 'Channel granted');
+                    case 'accept': return run(ctx, 'x_federation_channel_accept', { sinceSeconds: ctx.flags.since }, 'Grants accepted');
+                    case 'read': return run(ctx, 'x_federation_channel_read', { channel: ctx.flags.channel, sinceSeconds: ctx.flags.since, limit: ctx.flags.limit }, 'Channel messages');
+                    case 'list': return run(ctx, 'x_federation_channel_list', {}, 'Channel keys held');
+                    case 'publish': {
+                        let payload;
+                        try {
+                            payload = JSON.parse(String(ctx.flags.payload));
+                        }
+                        catch {
+                            output.printError('--payload must be JSON');
+                            return Promise.resolve({ success: false, exitCode: 1 });
+                        }
+                        return run(ctx, 'x_federation_channel_publish', { channel: ctx.flags.channel, msgType: ctx.flags.type, payload }, 'Published to channel');
+                    }
+                    default:
+                        output.printError('--action must be create|grant|accept|publish|read|list');
+                        return Promise.resolve({ success: false, exitCode: 1 });
+                }
+            } },
+    ],
+    action: async (ctx) => { output.printInfo('Usage: ruflo federation <join|sync|roster|claims|registry|invite|admit|publish|channel>'); void ctx; return { success: true }; },
+};
+//# sourceMappingURL=federation.js.map

package/dist/src/commands/index.d.ts

@@ -17,6 +17,7 @@ export { sessionCommand } from './session.js';
 export { agentCommand } from './agent.js';
 export { swarmCommand } from './swarm.js';
 export { memoryCommand } from './memory.js';
+export { federationCommand } from './federation.js';
 export { mcpCommand } from './mcp.js';
 export { hooksCommand } from './hooks.js';
 export declare function getConfigCommand(): Promise<Command | undefined>;

package/dist/src/commands/index.js

@@ -138,6 +138,7 @@ import { sessionCommand } from './session.js';
 import { agentCommand } from './agent.js';
 import { swarmCommand } from './swarm.js';
 import { memoryCommand } from './memory.js';
+import { federationCommand } from './federation.js';
 import { mcpCommand } from './mcp.js';
 import { hooksCommand } from './hooks.js';
 // Pre-populate cache with core commands only
@@ -149,6 +150,7 @@ loadedCommands.set('session', sessionCommand);
 loadedCommands.set('agent', agentCommand);
 loadedCommands.set('swarm', swarmCommand);
 loadedCommands.set('memory', memoryCommand);
+loadedCommands.set('federation', federationCommand);
 loadedCommands.set('mcp', mcpCommand);
 loadedCommands.set('hooks', hooksCommand);
 // =============================================================================
@@ -163,6 +165,7 @@ export { sessionCommand } from './session.js';
 export { agentCommand } from './agent.js';
 export { swarmCommand } from './swarm.js';
 export { memoryCommand } from './memory.js';
+export { federationCommand } from './federation.js';
 export { mcpCommand } from './mcp.js';
 export { hooksCommand } from './hooks.js';
 // Lazy-loaded command re-exports (for backwards compatibility, but async-only)
@@ -207,6 +210,7 @@ export const commands = [
     agentCommand,
     swarmCommand,
     memoryCommand,
+    federationCommand,
     mcpCommand,
     hooksCommand,
 ];

package/dist/src/commands/memory.js

@@ -352,7 +352,14 @@ const searchCommand = {
             name: 'threshold',
             description: 'Similarity threshold (0-1)',
             type: 'number',
-            default: 0.7
+            // MUST stay <= 0.4. The recall fusion in bridgeSearchEntries scores a
+            // full-coverage exact-keyword hit as 0.6*max(0,semantic) + 0.4*lexical,
+            // so when the semantic cosine is <= 0 (routine for a one-word query) a
+            // perfect keyword match tops out at exactly 0.40. #2790 raised this
+            // default to 0.7, which silently re-broke #2558: `memory search` matched
+            // content word-for-word and still returned nothing. Regression guard:
+            // __tests__/memory-search-recall-2558.test.ts.
+            default: 0.3
         },
         {
             name: 'type',
@@ -421,7 +428,7 @@ const searchCommand = {
         // coalescing preserves an explicit zero. Fallback aligned with the
         // option's declared `default: 0.7` (was `0.3` — the two disagreed
         // and --help advertised a default the code did not honor).
-        const threshold = ctx.flags.threshold ?? 0.7;
+        const threshold = ctx.flags.threshold ?? 0.3;
         const searchType = ctx.flags.type || 'semantic';
         const buildHnsw = (ctx.flags['build-hnsw'] || ctx.flags.buildHnsw);
         const requestedIntent = ctx.flags.intent || 'mixed';

package/dist/src/mcp-client.js

@@ -62,6 +62,10 @@ import { agenticowSpeculateTools } from './mcp-tools/agenticow-speculate-tools.j
 // ADR-164 — AgentBBS federated business-domain BBS rooms (Phase 1).
 // Optional runtime dep, every handler returns `{degraded: true}` when missing.
 import { agentbbsTools } from './mcp-tools/agentbbs-tools.js';
+import { xFederationTools } from './mcp-tools/x-federation-tools.js';
+import { seraphinaTools } from './mcp-tools/seraphina-tools.js';
+import { xFederationJoinTools } from './mcp-tools/x-federation-join.js';
+import { xFederationChannelTools } from './mcp-tools/x-federation-channels.js';
 // ADR-164 Phase 2 — Business-pod template validation (pure local, no optional deps).
 import { businessPodTools } from './mcp-tools/business-pod-tools.js';
 // ADR-164 Phase 4 §5.1.8 — http_fetch MCP tool (secure-by-default HTTP probe
@@ -167,6 +171,10 @@ registerTools([
     ...agenticowSpeculateTools,
     // ADR-164 — AgentBBS federated business-domain BBS rooms (4 tools, Phase 1, graceful-degraded)
     ...agentbbsTools,
+    ...xFederationTools,
+    ...seraphinaTools,
+    ...xFederationJoinTools,
+    ...xFederationChannelTools,
     // ADR-164 Phase 2 + Phase 3 — business_pod_validate + business_pod_route_backend
     // (2 tools, no optional dep — schema validator + §3.4 domain-affinity router)
     ...businessPodTools,

package/dist/src/mcp-tools/agentbbs-federation.d.ts

@@ -0,0 +1,178 @@
+/**
+ * agentbbs Phase 2 — cross-host federation.
+ *
+ * Phase 1 (`agentbbs-tools.ts`) gives every host an append-only room log at
+ * `<basePath>/room-<roomId>.jsonl`, and derives `roomId` deterministically from
+ * the room label. Two independent hosts that register `#sales` therefore
+ * compute the *same* roomId without ever talking to each other. That is the
+ * property this module builds on.
+ *
+ * ## Why a signed union-merge, and not a consensus protocol
+ *
+ * A room log is an append-only set of immutable envelopes. Two hosts that each
+ * append locally hold two subsets of the same logical set, so reconciling them
+ * is a set union — there is no conflicting write to arbitrate, and therefore
+ * nothing for a consensus round to decide. Union is commutative, associative
+ * and idempotent, which makes sync order-independent and safe to retry: pulling
+ * the same peer twice, or pulling A-then-B versus B-then-A, converges on the
+ * same log. That is a CRDT (a grow-only set keyed by `envelopeId`), and it is
+ * strictly cheaper and less failure-prone than the Byzantine agreement the
+ * plugin README gestures at.
+ *
+ * What union does *not* give you is authenticity. If any peer can inject an
+ * envelope, the merge faithfully replicates forgeries. So every envelope is
+ * Ed25519-signed by its originating node, and a receiver verifies the signature
+ * against the *pinned* public key it recorded when the peer was added — not
+ * against a key carried in the envelope, which would let an attacker sign with
+ * their own key and claim any origin. Trust is pinned at peer-add time; the
+ * wire is treated as hostile.
+ *
+ * ## Transport
+ *
+ * Pull-based HTTP. A node serves `GET /agentbbs/v1/rooms/:roomId/envelopes?since=N`
+ * and peers poll it. Pull is deliberate: it needs no inbound connectivity from
+ * the peer's side, survives a node being offline (it just catches up later),
+ * and gives the *receiver* control over how much it ingests. Push would invert
+ * that and make every node an unauthenticated write target.
+ *
+ * Designed for a private overlay (Tailscale/WireGuard) where the network
+ * already authenticates the host. Signatures mean a compromised or hostile peer
+ * still cannot forge another node's envelopes. See `bindHost` on serve() — it
+ * binds loopback by default, and binding a routable interface is an explicit
+ * operator choice.
+ *
+ * ## Bounds
+ *
+ * Every ingest path is bounded: envelope count per sync, byte size per envelope,
+ * total bytes per response, peer count, and hop count. An unbounded merge from
+ * an untrusted peer is a memory-exhaustion primitive, so limits are enforced on
+ * the *receiving* side where they cannot be negotiated away by the sender.
+ *
+ * @module @claude-flow/cli/mcp-tools/agentbbs-federation
+ */
+import { type Server } from 'node:http';
+/** Max envelopes accepted from one peer in one sync. */
+export declare const MAX_ENVELOPES_PER_SYNC = 5000;
+/** Max serialized bytes for a single envelope. */
+export declare const MAX_ENVELOPE_BYTES: number;
+/** Max total bytes read from one peer response. */
+export declare const MAX_SYNC_RESPONSE_BYTES: number;
+/** Max peers in the registry. */
+export declare const MAX_PEERS = 256;
+/** Max federation hops before an envelope stops propagating. */
+export declare const MAX_HOPS = 8;
+/** Per-request timeout when pulling from a peer. */
+export declare const SYNC_TIMEOUT_MS = 15000;
+export interface NodeIdentity {
+    nodeId: string;
+    publicKey: string;
+    privateKey: string;
+    createdAt: string;
+}
+export interface FederationPeer {
+    nodeId: string;
+    url: string;
+    publicKey: string;
+    label?: string;
+    addedAt: string;
+    lastSyncedAt?: string;
+    lastSeq?: Record<string, number>;
+}
+export interface SignedEnvelope {
+    envelopeId: string;
+    roomId: string;
+    seq: number;
+    msgType: string;
+    payload: unknown;
+    timestamp: string;
+    origin?: string;
+    hops?: number;
+    signature?: string;
+}
+/**
+ * Deterministic byte string an envelope's signature covers.
+ *
+ * Field order is fixed here rather than relying on `JSON.stringify` key order,
+ * because a receiver must reconstruct byte-identical input from a payload that
+ * survived a JSON round trip. `payload` is canonicalized recursively with
+ * sorted keys for the same reason: `{a:1,b:2}` and `{b:2,a:1}` are the same
+ * value and must not produce different signatures.
+ *
+ * `hops` is deliberately excluded — it is mutated in transit by design, so
+ * including it would invalidate the signature at the first relay.
+ */
+export declare function canonicalEnvelopeBytes(env: SignedEnvelope): Uint8Array;
+/**
+ * Load or create this host's long-lived Ed25519 identity.
+ *
+ * Phase 1 minted an ephemeral key per process, which is fine for local token
+ * signing but useless across hosts: a peer cannot pin a key that changes on
+ * every restart. This persists one, 0600, and derives a stable nodeId from the
+ * public key so identity is verifiable rather than self-asserted.
+ */
+export declare function getNodeIdentity(basePath: string): Promise<NodeIdentity>;
+export declare function signEnvelope(basePath: string, env: SignedEnvelope): Promise<SignedEnvelope>;
+/**
+ * Verify an envelope against a public key the caller already trusts.
+ *
+ * The key is passed in rather than read from the envelope on purpose: an
+ * envelope-carried key proves only that the sender holds *a* key, not that they
+ * are who the `origin` field claims. Callers pass the key pinned at peer-add.
+ */
+export declare function verifyEnvelope(env: SignedEnvelope, publicKeyHex: string): Promise<boolean>;
+export declare function readPeers(basePath: string): FederationPeer[];
+/**
+ * Reject anything that is not a plain http(s) URL to a host.
+ *
+ * Blocks credentials-in-URL (they would be logged), and non-http schemes such
+ * as `file:` which would turn a peer entry into a local file read.
+ */
+export declare function validatePeerUrl(raw: string): string;
+export declare function addPeer(basePath: string, input: {
+    nodeId: string;
+    url: string;
+    publicKey: string;
+    label?: string;
+}): FederationPeer;
+export declare function removePeer(basePath: string, nodeId: string): boolean;
+export declare function readEnvelopes(basePath: string, roomId: string): SignedEnvelope[];
+export declare function validateRoomId(roomId: string): string;
+export interface MergeResult {
+    merged: number;
+    skippedDuplicate: number;
+    skippedUnverified: number;
+    skippedOversize: number;
+    skippedHopLimit: number;
+}
+/**
+ * Union-merge verified envelopes from a peer into the local room log.
+ *
+ * Idempotent: `envelopeId` is the merge key, so replaying the same batch is a
+ * no-op. Anything that fails verification is dropped and counted rather than
+ * quarantined — a receiver has no use for an envelope it cannot attribute.
+ */
+export declare function mergeEnvelopes(basePath: string, roomId: string, incoming: SignedEnvelope[], peerPublicKey: string): Promise<MergeResult>;
+/** Pull one room from one peer and merge what verifies. */
+export declare function syncRoomFromPeer(basePath: string, peer: FederationPeer, roomId: string, fetchImpl?: typeof fetch): Promise<MergeResult & {
+    peerNodeId: string;
+    roomId: string;
+}>;
+/**
+ * Serve this node's room logs for peers to pull.
+ *
+ * Binds loopback unless the caller explicitly asks otherwise, so starting a
+ * server never silently exposes room contents on a routable interface. Read
+ * only by construction: there is no route that mutates state, which removes the
+ * whole class of unauthenticated-write attacks that a push design would open.
+ */
+export declare function serveFederation(basePath: string, opts?: {
+    port?: number;
+    bindHost?: string;
+}): Promise<{
+    server: Server;
+    port: number;
+    host: string;
+}>;
+/** Constant-time compare for any future shared-secret paths. */
+export declare function safeEqual(a: string, b: string): boolean;
+//# sourceMappingURL=agentbbs-federation.d.ts.map