Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

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.json
index 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.md
index 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.
## Commands
diff --git a/plugins/ruflo-federation/agents/federation-coordinator.md b/plugins/ruflo-federation/agents/federation-coordinator.md
index 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 transmission
5. **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 Downgrade
diff --git a/plugins/ruflo-federation/commands/federation.md b/plugins/ruflo-federation/commands/federation.md
index 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`