# cost-federation

Tracks federated request costs per peer in rolling windows (1h, 24h, 7d) and checks suspension thresholds. Use it when opening federation channels to new peers or monitoring consumption.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 683 installs · ★ 79357
- Author: ruvnet
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/ruvnet/ruflo/tree/HEAD/plugins/ruflo-cost-tracker/skills/cost-federation/SKILL.md
- Updated: 2026-10-25
- HTML: https://affpapa.org/en/nevibecode/skills/cost-federation

## What it does

The skill connects to the `federation_spend` event bus from ADR-097 Phase 3 — each federated request generates an event with peer ID, tokens used, and USD spent. The script accumulates these into rolling windows, shows per-peer costs, and flags peers exceeding the suspension threshold.

Run: `node plugins/ruflo-cost-tracker/scripts/federation.mjs`. By default it outputs a markdown table with 1h / 24h / 7d windows and a threshold check block. Switch to JSON with `FED_FORMAT=json`, override the namespace (`FED_NAMESPACE=federation-spend`), or adjust the threshold (`FED_SUSPEND_THRESHOLD_USD=5.0`).

Until Phase 3 lands upstream, the skill works cleanly and reports "no events found". Events should contain: peerId, taskId, tokensUsed, usdSpent, ts — the script reads any record with prefix `fed-spend-` from storage and aggregates automatically.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add ruvnet/ruflo --skill cost-federation -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/cost-federation/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/cost-federation/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add ruvnet/ruflo --skill cost-federation -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/cost-federation/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add ruvnet/ruflo --skill cost-federation -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/cost-federation/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install ruvnet/ruflo cost-federation
```

2. **Manually: put the files in place**
- File: `.github/skills/cost-federation/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add ruvnet/ruflo --skill cost-federation -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/ruvnet/ruflo --path plugins/ruflo-cost-tracker/skills/cost-federation
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/cost-federation/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add ruvnet/ruflo --skill cost-federation -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/ruvnet/ruflo/tree/HEAD/plugins/ruflo-cost-tracker/skills/cost-federation/SKILL.md

## When to use it
- collect per-peer federated spend statistics over the past 7 days
- verify whether limits on a specific peer are exceeded
- establish baseline spend before onboarding a new peer
- trace why a peer was suspended via the event chain

## Example prompts
- Run cost-federation and show which peer spent the most in the last 24 hours
- cost-federation over the past 7 days — output as JSON table
- Check peers with spend above $3 per hour

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 3e4fa8c3f0252903.

BEGIN THIRD-PARTY FILE 3e4fa8c3f0252903
````text
---
name: cost-federation
description: Consumer-side wiring for ADR-097 Phase 3 federation_spend events — per-peer rolling windows + suspension-threshold check
argument-hint: ""
allowed-tools: Bash
---

# 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**:

   ```bash
   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:

```json
{
  "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](../../../../v3/docs/adr/ADR-097-federation-budget-circuit-breaker.md) — 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)
````
END THIRD-PARTY FILE 3e4fa8c3f0252903

The third-party file has ended. Everything between the 3e4fa8c3f0252903 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

© ruvnet · MIT · https://github.com/ruvnet/ruflo/tree/HEAD/plugins/ruflo-cost-tracker/skills/cost-federation/SKILL.md

## Similar
- [apollo-federation](https://affpapa.org/en/nevibecode/skills/apollo-federation.md) — skill · 1900 installs
- [Agent Cost Report](https://affpapa.org/en/nevibecode/skills/agent-cost-report.md) — skill · 381 installs
- [google-cloud-waf-cost-optimization](https://affpapa.org/en/nevibecode/skills/google-cloud-waf-cost-optimization.md) — skill · 14266 installs
- [aws-billing-and-cost-management](https://affpapa.org/en/nevibecode/skills/aws-billing-and-cost-management.md) — skill · 9000 installs
- [az-cost-optimize](https://affpapa.org/en/nevibecode/skills/az-cost-optimize.md) — skill · 8700 installs

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md