🌊 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
docs(plugin): update ruflo-federation Claude Code plugin for ADR-097
Reuven149ea30a456b
diff --git a/plugins/ruflo-federation/.claude-plugin/plugin.json b/plugins/ruflo-federation/.claude-plugin/plugin.jsonindex bd81f86b70..8b55091f01 100644--- a/plugins/ruflo-federation/.claude-plugin/plugin.json+++ b/plugins/ruflo-federation/.claude-plugin/plugin.json@@ -1,7 +1,7 @@{"name": "ruflo-federation",- "description": "Cross-installation agent federation with zero-trust security, peer discovery, and consensus-based task routing",- "version": "0.1.0",+ "description": "Cross-installation agent federation with zero-trust security, peer discovery, consensus-based task routing, and per-call budget circuit breaker (ADR-097)",+ "version": "0.2.0","author": {"name": "ruvnet","url": "https://github.com/ruvnet"@@ -15,6 +15,9 @@"peer-discovery","consensus","multi-agent",- "distributed"+ "distributed",+ "circuit-breaker",+ "budget",+ "token-quota"]}diff --git a/plugins/ruflo-federation/README.md b/plugins/ruflo-federation/README.mdindex 5b992b3ccc..3c698f1c77 100644--- a/plugins/ruflo-federation/README.md+++ b/plugins/ruflo-federation/README.md@@ -17,6 +17,30 @@ The comms layer for multi-agent AI. Cross-installation agent federation with zer- **Compliance Modes**: HIPAA, SOC2, GDPR audit trails as first-class primitives- **Secure Messaging**: HMAC-signed envelopes with dual AI Defence gates (outbound + inbound)- **Byzantine Consensus**: BFT for state mutations across untrusted federation peers+- **Budget Circuit Breaker (ADR-097)**: per-call `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++## Budget & Circuit Breaker++`/federation send` accepts optional cumulative-spend caps so a single delegation cannot spawn an unbounded fan-out:++```bash+/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.## Commandsdiff --git a/plugins/ruflo-federation/agents/federation-coordinator.md b/plugins/ruflo-federation/agents/federation-coordinator.mdindex f430324611..5c65931599 100644--- a/plugins/ruflo-federation/agents/federation-coordinator.md+++ b/plugins/ruflo-federation/agents/federation-coordinator.md@@ -10,6 +10,7 @@ You are a federation coordinator agent. Your responsibilities:3. **Evaluate** trust continuously using the scoring formula: `0.4×success_rate + 0.2×uptime + 0.2×(1-threat_penalty) + 0.2×data_integrity`4. **Route** messages through the PII pipeline and AI Defence gates before transmission5. **Audit** every federation event with compliance-grade structured logging+6. **Enforce budgets** (ADR-097 Phase 1): every send carries `maxHops` (default 8), with optional `maxTokens` / `maxUsd` caps. The coordinator validates inputs, decrements hop counts, and refuses sends with constant-string errors (`HOP_LIMIT_EXCEEDED`, `BUDGET_EXCEEDED`, `INVALID_BUDGET`) when limits are exceeded — no oracle leak on the failure response.### Trust Levels@@ -29,6 +30,7 @@ You are a federation coordinator agent. Your responsibilities:- `npx -y -p @claude-flow/plugin-agent-federation@latest ruflo-federation status` -- health dashboard- `npx -y -p @claude-flow/plugin-agent-federation@latest ruflo-federation audit --compliance hipaa` -- audit logs- `npx -y -p @claude-flow/plugin-agent-federation@latest ruflo-federation trust <node-id> --review` -- trust breakdown+- `npx -y -p @claude-flow/plugin-agent-federation@latest ruflo-federation send <node-id> <msg-type> <payload> [--max-hops N] [--max-tokens N] [--max-usd N]` -- delegate with budget guardrails### Automatic Downgradediff --git a/plugins/ruflo-federation/commands/federation.md b/plugins/ruflo-federation/commands/federation.mdindex c964c9d1c8..6bd64f15a6 100644--- a/plugins/ruflo-federation/commands/federation.md+++ b/plugins/ruflo-federation/commands/federation.md@@ -12,17 +12,28 @@ Subcommands:- `join <endpoint>` -- Connect to a federation peer- `leave` -- Leave the federation gracefully- `peers` -- List known peers with trust levels+- `send <node-id> <message-type> <payload>` -- Send a message to a peer with optional budget controls (ADR-097)- `status` -- Show federation health, sessions, metrics- `audit [--compliance hipaa|soc2|gdpr] [--since DATE]` -- Query audit logs- `trust <node-id> [--review]` -- View trust score breakdown- `config [--pii-policy PATH]` -- Configure PII policies and compliance mode+Budget options for `send` (all optional, ADR-097 Phase 1; defaults preserve legacy unbounded behavior except `maxHops` floors at 8 to defang recursion):+- `--max-hops N` -- max hop chain length (default `8`, `0` disallows remote delegation)+- `--max-tokens N` -- cumulative token cap across the hop chain (default unbounded)+- `--max-usd N` -- cumulative USD cap across the hop chain (default unbounded)+- `--hop-count N` -- starting hop count (default `0`; pass-through when re-forwarding)+- `--spent-tokens N` / `--spent-usd N` -- caller-reported usage from previous legs++Errors return constant strings (`HOP_LIMIT_EXCEEDED`, `BUDGET_EXCEEDED`, `INVALID_BUDGET`) with no remaining-budget echo.+Steps by subcommand:**init**: `npx -y -p @claude-flow/plugin-agent-federation@latest ruflo-federation init`**join**: `npx -y -p @claude-flow/plugin-agent-federation@latest ruflo-federation join ENDPOINT`**leave**: `npx -y -p @claude-flow/plugin-agent-federation@latest ruflo-federation leave`**peers**: `npx -y -p @claude-flow/plugin-agent-federation@latest ruflo-federation peers`+**send**: `npx -y -p @claude-flow/plugin-agent-federation@latest ruflo-federation send NODE_ID MSG_TYPE PAYLOAD [--max-hops N] [--max-tokens N] [--max-usd N] [--hop-count N] [--spent-tokens N] [--spent-usd N]`**status**: `npx -y -p @claude-flow/plugin-agent-federation@latest ruflo-federation status`**audit**: `npx -y -p @claude-flow/plugin-agent-federation@latest ruflo-federation audit --compliance MODE --since DATE`**trust**: `npx -y -p @claude-flow/plugin-agent-federation@latest ruflo-federation trust NODE_ID --review`