v3.8.0 — Phase 5 Part 6: Federated Budget Tracking

[Jovancoding]

v3.8.0 — Phase 5 Part 6: Federated Budget Tracking

## Phase 5 Part 6: Federated Budget Tracking

Token spending tracked and enforced across distributed agent swarms.

### New: `FederatedBudget`

```typescript
import { FederatedBudget } from 'network-ai';

const budget = new FederatedBudget({ ceiling: 10_000, perAgentCeiling: 3_000 });

budget.spend('agent-1', 2500); // { allowed: true,  remaining: 7500 }
budget.spend('agent-2', 8000); // { allowed: false, remaining: 7500, deniedReason: 'global_ceiling' }

budget.getSpendLog();         // { 'agent-1': 2500 }
budget.getTotalSpent();       // 2500
budget.remaining();           // 7500

Features

• Global ceiling — no agent can push cumulative spend past the configured limit
• Per-agent ceiling — optional individual cap per agent, enforced independently
• deniedReason — 'global_ceiling' or 'per_agent_ceiling' tells you exactly which limit was hit
• getSpendLog() — per-agent totals as a plain object
• getTransactionLog() — ordered list of every approved spend with agentId, tokens, and ISO timestamp
• reset() — clears all counters; preserves ceiling
• setCeiling(n) — adjust the global ceiling at runtime (safe to call below current spend)
• Blackboard persistence — pass any BlackboardBackend to sync budget state across nodes automatically
• loadFromBlackboard() — restore accumulated spend after node restart

Distributed sync example

import { CrdtBackend, FederatedBudget } from 'network-ai';

const nodeA = new CrdtBackend('node-a');
const budget = new FederatedBudget({ ceiling: 50_000, blackboard: nodeA });

budget.spend('agent-1', 1000);
// Snapshot written to nodeA — sync nodeA to other CrdtBackend nodes
// for automatic budget propagation with no extra config.

Exports

import {
  FederatedBudget,
  type FederatedBudgetOptions,
  type SpendResult,
  type SpendLogEntry,
} from 'network-ai';

Stats

• 127 new tests in test-phase5f.ts
• 974 tests passing (0 failing)
• No breaking changes

---

This discussion was created from the release v3.8.0 — Phase 5 Part 6: Federated Budget Tracking.

[UrRhb]

Nice -- budget enforcement across distributed agents is something most people ignore until they get a scary bill. One thing that could pair well with FederatedBudget: actually knowing the real cost of each agent's calls rather than estimating. We built burn0 for this -- it's a one-import Node.js library that intercepts HTTP calls, identifies the API from the hostname, and extracts exact token counts from response metadata. So instead of manually passing token counts to budget.spend(), you could potentially feed real cost data from burn0 into FederatedBudget automatically. Cool to see someone thinking about this problem at the swarm level.