mcpField
C
cost-federation

cost-federation

github.com/ruvnetAgent workflows80.0k683 installsUpdated today
Repository

About cost-federation

cost-federation reads federation spend events and summarizes peer spending across rolling time windows. It is intended for monitoring federation costs and checking whether peers exceed a suspension threshold; upstream event publishing is not yet available.

Key features

  1. 01Per-peer 1h, 24h, and 7d totals
  2. 02Event counts and USD spending
  3. 03Suspension-threshold checks
  4. 04Markdown or JSON output
  5. 05Configurable event namespace

Use cases

  1. 01Establish a new peer's spending baseline
  2. 02Monitor federation costs periodically
  3. 03Review breaker decisions after ADR-097 updates

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/ruvnet/ruflo --skill cost-federation

After installing, type/cost-federationin Claude Code to confirm it loaded.

Details

From the project README

Cost Federation

ADR-097 Phase 3 specifies a federation_spend event bus that publishes one event per federation_send completion: {peerId, taskId, tokensUsed, usdSpent, ts}. Cost-tracker is the declared consumer — it aggregates per-peer rolling windows (1h / 24h / 7d) and the federation breaker queries that aggregate to suspend peers exceeding the configured threshold.

Phase 3 isn't landed upstream yet. This skill is the consumer-side wiring; it activates the moment upstream publishes events to the federation-spend namespace. Until then it reports cleanly with a "no events found" notice.

When to use

  • Before opening federation traffic to a new peer — establish baseline.
  • Periodically (e.g. /loop 5m) to monitor per-peer spend across windows.
  • After ADR-097 Phase 2/3 lands — to verify breaker suspension reasoning.

Steps

  1. Run the script:

    node plugins/ruflo-cost-tracker/scripts/federation.mjs

    Optional env:

    • FED_FORMAT=json — JSON instead of markdown
    • FED_NAMESPACE=federation-spend — override target namespace
    • FED_SUSPEND_THRESHOLD_USD=5.0 — breaker threshold (ADR-097 default)

  2. Inspect — per-peer 1h/24h/7d windows of count + USD spent, plus a "Suspension threshold check" block flagging peers over the breaker line.

Storage contract (consumer side)

When Phase 3 lands, events should be persisted to namespace federation-spend with key prefix fed-spend- and JSON value matching:

{
  "peerId": "<peer-uuid>",
  "taskId": "<task-uuid>",
  "tokensUsed": 12345,
  "usdSpent": 0.0287,
  "ts": "2026-05-05T..."
}

The script reads any record matching that prefix, regardless of how upstream produces them. Multiple events per peer accumulate cleanly into the rolling-window sums.

Cross-references

  • ADR-097: Federation budget circuit breaker — the complete spec
  • cost-report — same data, different lens (cost-report focuses on local agent spend; this skill on per-peer federated spend)
  • ruflo-federation plugin — the producer side (when Phase 3 lands)

Comments

Markdown supported