cost-federation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

ADR-097第三阶段指定了一个

federation_spend

事件总线，每次

federation_send

完成时发布一个事件：

{peerId, taskId, tokensUsed, usdSpent, ts}

。Cost-tracker是指定的消费端——它聚合基于节点的滚动窗口（1小时/24小时/7天）数据，联邦断路器会查询该聚合数据，以暂停超过配置阈值的节点。

第三阶段尚未合并到上游代码库。 本Skill是消费端的适配逻辑；一旦上游开始向

federation-spend

命名空间发布事件，它就会激活。在此之前，它会清晰返回“未找到事件”的提示。

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.

在向新节点开放联邦流量之前——建立基准数据。
定期执行（例如
```
/loop 5m
```
）——监控各节点在不同窗口内的支出情况。
ADR-097第二/三阶段落地后——验证断路器暂停节点的依据。

Steps

操作步骤

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)

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

运行脚本：
bash
```
node plugins/ruflo-cost-tracker/scripts/federation.mjs
```
可选环境变量：
- ```
FED_FORMAT=json
```
  —— 输出JSON格式而非Markdown
- ```
FED_NAMESPACE=federation-spend
```
  —— 覆盖目标命名空间
- ```
FED_SUSPEND_THRESHOLD_USD=5.0
```
  —— 断路器阈值（ADR-097默认值）
查看结果——各节点1小时/24小时/7天窗口内的事件数量+美元支出数据，以及一个“暂停阈值检查”模块，标记超出断路器阈值的节点。

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.

当第三阶段落地后，事件应持久化到

federation-spend

命名空间，键前缀为

fed-spend-

，JSON值格式如下：

json

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

脚本会读取所有匹配该前缀的记录，无论上游如何生成这些记录。同一节点的多个事件会被干净地累积到滚动窗口的总和中。

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)

ADR-097: 联邦预算断路器 —— 完整规范
```
cost-report
```
—— 相同数据，不同视角（cost-report聚焦本地Agent支出；本Skill聚焦各节点的联邦支出）
```
ruflo-federation
```
插件 —— 生产端逻辑（第三阶段落地后）