plugins/ruflo-federation/README.md
The comms layer for multi-agent AI. Cross-installation agent federation with zero-trust security, PII-gated data flow, and compliance-grade audit trails.
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-federation@ruflo
maxHops (default 8), optional maxTokens / maxUsd caps, and constant-string HOP_LIMIT_EXCEEDED / BUDGET_EXCEEDED errors that defang recursive delegation loops and runaway cost cascades/federation send accepts optional cumulative-spend caps so a single delegation cannot spawn an unbounded fan-out:
/federation send <node-id> task-assignment '{"task":"…"}' \
--max-hops 4 \
--max-tokens 50000 \
--max-usd 0.25
| Field | Default when omitted | Notes |
|---|---|---|
maxHops | 8 | 0 disallows remote delegation entirely. Hard ceiling 64. |
maxTokens | unbounded | Σ tokens across the whole hop chain. Hard ceiling 1B. |
maxUsd | unbounded | Σ USD across hops. Hard ceiling $1M. |
hopCount | 0 | Pass-through for messages being re-forwarded. |
spent.{tokens,usd} | 0 | Caller-reported usage from previous legs. Negatives clamped to 0. |
Validation rejects NaN, ±Infinity, negative numbers, and non-integer hop counts up front. Errors surface as constant strings with no remaining-budget echo, so a malicious caller cannot use response codes as an oracle to probe configured thresholds.
Phase 1 enforces at the send side. Phase 2 (peer state machine: ACTIVE / SUSPENDED / EVICTED) and Phase 3 (ruflo-cost-tracker integration for unified spend reporting) ship in follow-up releases.
| Command | Description |
|---|---|
/federation-init | Generate keypair and initialize federation on this node |
/federation-status | Show peers, sessions, trust levels, and health |
/federation-audit | Query structured audit logs with compliance filtering |
| Agent | Description |
|---|---|
federation-coordinator | Orchestrates discovery, handshake, trust evaluation, and secure message routing |
ruflo-core plugin (provides MCP server)@claude-flow/security (cryptographic primitives)@claude-flow/cli v3.6 major+minor.@claude-flow/plugin-agent-federation (resolved via npx -y -p).bash plugins/ruflo-federation/scripts/smoke.sh is the contract.Federation's "PII Pipeline" feature is a richer specialization of the canonical 3-gate pattern owned by ruflo-aidefence ADR-0001. The mapping:
| Canonical gate | Federation specialization |
|---|---|
Pre-storage PII (aidefence_has_pii) | 14-type PII detection with per-trust-level policies (BLOCK / REDACT / HASH / PASS) |
Sanitization (aidefence_scan) | Outbound HMAC-signed envelope + dual AI Defence gates |
Prompt-injection (aidefence_is_safe) | Inbound message verification before delivery to local agents |
Federation extends the canonical gates with adaptive confidence calibration and trust-level-aware policies, but the gate ordering and intent are identical. New federated content paths should reference the canonical 3-gate pattern by name.
This plugin owns the federation AgentDB namespace. This is the documented exception to the kebab-case <plugin-stem>-<intent> rule: when a plugin's name is the intent, the namespace can match the plugin stem. See ruflo-agentdb ADR-0001 §"Namespace convention". Reserved namespaces (pattern, claude-memories, default) MUST NOT be shadowed.
federation is accessed via memory_* tools (namespace-routed). Used for: peer registry, trust score history, audit log indices, message envelope receipts.
bash plugins/ruflo-federation/scripts/smoke.sh
# Expected: "10 passed, 0 failed"