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

feat(federation): ADR-097 Phase 1 — budget envelope + hop counter (#1723)

Reuven7e1cc06dfdc7
diff --git a/v3/@claude-flow/plugin-agent-federation/__tests__/unit/federation-budget.test.ts b/v3/@claude-flow/plugin-agent-federation/__tests__/unit/federation-budget.test.ts
new file mode 100644
index 0000000000..16703d8d12
--- /dev/null
+++ b/v3/@claude-flow/plugin-agent-federation/__tests__/unit/federation-budget.test.ts
@@ -0,0 +1,290 @@
+/**
+ * Tests for ADR-097 Phase 1 — federation budget validator + enforcer.
+ *
+ * Pins the security invariants the reviewer called out (audit_1776853149979
+ * follow-up):
+ * 1. validateBudget rejects NaN, ±Infinity, negatives, non-integer hops
+ * 2. enforceBudget is atomic (synchronous, no awaits) — pinned by
+ * checking that two concurrent calls cannot both pass a single-hop
+ * budget when the caller passes the same hopCount=0 in.
+ * 3. Errors are constant strings — no remaining-budget echo on failure
+ * 4. Backward compat: omitted budget → unbounded with default maxHops=8
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+ DEFAULT_MAX_HOPS,
+ enforceBudget,
+ validateBudget,
+} from '../../src/domain/value-objects/federation-budget.js';
+
+describe('validateBudget (ADR-097 Phase 1)', () => {
+ describe('happy path', () => {
+ it('accepts undefined → unbounded budget with default maxHops', () => {
+ const r = validateBudget(undefined);
+ expect(r.ok).toBe(true);
+ if (!r.ok) return;
+ expect(r.budget.maxHops).toBe(DEFAULT_MAX_HOPS);
+ expect(r.budget.maxTokens).toBe(Number.POSITIVE_INFINITY);
+ expect(r.budget.maxUsd).toBe(Number.POSITIVE_INFINITY);
+ });
+
+ it('accepts null → unbounded with default maxHops', () => {
+ const r = validateBudget(null);
+ expect(r.ok).toBe(true);
+ });
+
+ it('accepts a fully-specified budget', () => {
+ const r = validateBudget({ maxTokens: 1000, maxUsd: 0.5, maxHops: 4 });
+ expect(r.ok).toBe(true);
+ if (!r.ok) return;
+ expect(r.budget).toEqual({ maxTokens: 1000, maxUsd: 0.5, maxHops: 4 });
+ });
+
+ it('accepts maxHops=0 (no remote delegation allowed)', () => {
+ const r = validateBudget({ maxHops: 0 });
+ expect(r.ok).toBe(true);
+ if (!r.ok) return;
+ expect(r.budget.maxHops).toBe(0);
+ });
+
+ it('overrideMaxHops takes precedence over the budget object value', () => {
+ const r = validateBudget({ maxHops: 5 }, 2);
+ expect(r.ok).toBe(true);
+ if (!r.ok) return;
+ expect(r.budget.maxHops).toBe(2);
+ });
+
+ it('overrideMaxHops alone (no budget object) yields a hop-only budget', () => {
+ const r = validateBudget(undefined, 0);
+ expect(r.ok).toBe(true);
+ if (!r.ok) return;
+ expect(r.budget.maxHops).toBe(0);
+ });
+ });
+
+ describe('rejection: malformed types', () => {
+ it.each([
+ ['string', 'budget must be an object'],
+ [42, 'budget must be an object'],
+ [[1, 2], 'budget must be an object'],
+ ])('rejects raw=%s', (raw, expected) => {
+ const r = validateBudget(raw as unknown);
+ expect(r.ok).toBe(false);
+ if (r.ok) return;
+ expect(r.error).toContain(expected);
+ });
+ });
+
+ describe('rejection: hop validation', () => {
+ it.each([
+ [Number.NaN, 'finite integer'],
+ [Number.POSITIVE_INFINITY, 'finite integer'],
+ [Number.NEGATIVE_INFINITY, 'finite integer'],
+ [1.5, 'finite integer'],
+ [-1, '>= 0'],
+ [65, 'ceiling'],
+ [Number.MAX_SAFE_INTEGER, 'ceiling'],
+ ['8' as unknown as number, 'finite integer'],
+ ])('rejects maxHops=%s', (val, expected) => {
+ const r = validateBudget({ maxHops: val });
+ expect(r.ok).toBe(false);
+ if (r.ok) return;
+ expect(r.error).toContain(expected);
+ });
+ });
+
+ describe('rejection: token validation', () => {
+ it.each([
+ [Number.NaN, 'finite number'],
+ [Number.POSITIVE_INFINITY, 'finite number'],
+ [-1, '>= 0'],
+ [1.5, 'integer'],
+ [1_000_000_001, 'ceiling'],
+ ])('rejects maxTokens=%s', (val, expected) => {
+ const r = validateBudget({ maxTokens: val });
+ expect(r.ok).toBe(false);
+ if (r.ok) return;
+ expect(r.error).toContain(expected);
+ });
+ });
+
+ describe('rejection: usd validation', () => {
+ it.each([
+ [Number.NaN, 'finite number'],
+ [Number.POSITIVE_INFINITY, 'finite number'],
+ [-0.01, '>= 0'],
+ [1_000_001, 'ceiling'],
+ ])('rejects maxUsd=%s', (val, expected) => {
+ const r = validateBudget({ maxUsd: val });
+ expect(r.ok).toBe(false);
+ if (r.ok) return;
+ expect(r.error).toContain(expected);
+ });
+
+ it('accepts maxUsd as a non-integer (e.g. 0.001)', () => {
+ const r = validateBudget({ maxUsd: 0.001 });
+ expect(r.ok).toBe(true);
+ });
+ });
+});
+
+describe('enforceBudget (ADR-097 Phase 1)', () => {
+ function bud(p: Partial<{ maxHops: number; maxTokens: number; maxUsd: number }> = {}) {
+ const r = validateBudget(p);
+ if (!r.ok) throw new Error(r.error);
+ return r.budget;
+ }
+
+ describe('hop counter', () => {
+ it('passes when nextHopCount <= maxHops', () => {
+ const r = enforceBudget(bud({ maxHops: 3 }), 0);
+ expect(r.ok).toBe(true);
+ if (!r.ok) return;
+ expect(r.nextHopCount).toBe(1);
+ });
+
+ it('refuses with HOP_LIMIT_EXCEEDED when nextHopCount > maxHops', () => {
+ const r = enforceBudget(bud({ maxHops: 2 }), 2);
+ expect(r.ok).toBe(false);
+ if (r.ok) return;
+ expect(r.reason).toBe('HOP_LIMIT_EXCEEDED');
+ });
+
+ it('maxHops=0 refuses to forward at all (originator → first hop blocked)', () => {
+ const r = enforceBudget(bud({ maxHops: 0 }), 0);
+ expect(r.ok).toBe(false);
+ if (r.ok) return;
+ expect(r.reason).toBe('HOP_LIMIT_EXCEEDED');
+ });
+
+ it('terminates a synthetic recursive ring at the configured maxHops', () => {
+ const budget = bud({ maxHops: 3 });
+ // Simulate hops A → B → A → B → … incrementing hopCount each step
+ let hops = 0;
+ let lastResult: ReturnType<typeof enforceBudget> | null = null;
+ for (let i = 0; i < 10; i++) {
+ lastResult = enforceBudget(budget, hops);
+ if (!lastResult.ok) break;
+ hops = lastResult.nextHopCount;
+ }
+ expect(lastResult).not.toBeNull();
+ expect(lastResult!.ok).toBe(false);
+ expect(hops).toBe(3); // exactly maxHops legs ran
+ if (!lastResult!.ok) {
+ expect(lastResult!.reason).toBe('HOP_LIMIT_EXCEEDED');
+ }
+ });
+ });
+
+ describe('budget axes', () => {
+ it('passes when cumulative tokens still within cap', () => {
+ const r = enforceBudget(bud({ maxTokens: 100, maxHops: 5 }), 0, {
+ tokens: 30,
+ usd: 0,
+ });
+ expect(r.ok).toBe(true);
+ });
+
+ it('refuses with BUDGET_EXCEEDED when tokens overshoot', () => {
+ const r = enforceBudget(bud({ maxTokens: 50, maxHops: 5 }), 0, {
+ tokens: 60,
+ usd: 0,
+ });
+ expect(r.ok).toBe(false);
+ if (r.ok) return;
+ expect(r.reason).toBe('BUDGET_EXCEEDED');
+ });
+
+ it('refuses with BUDGET_EXCEEDED when USD overshoots', () => {
+ const r = enforceBudget(bud({ maxUsd: 0.5, maxHops: 5 }), 0, {
+ tokens: 0,
+ usd: 0.6,
+ });
+ expect(r.ok).toBe(false);
+ if (r.ok) return;
+ expect(r.reason).toBe('BUDGET_EXCEEDED');
+ });
+
+ it('hop limit takes priority over budget exhaust (deterministic order)', () => {
+ const r = enforceBudget(bud({ maxHops: 0, maxTokens: 0 }), 0, {
+ tokens: 100,
+ usd: 0,
+ });
+ expect(r.ok).toBe(false);
+ if (r.ok) return;
+ expect(r.reason).toBe('HOP_LIMIT_EXCEEDED');
+ });
+ });
+
+ describe('downstream propagation', () => {
+ it('returns remaining budget for the downstream peer', () => {
+ const r = enforceBudget(bud({ maxTokens: 100, maxUsd: 1, maxHops: 5 }), 0, {
+ tokens: 30,
+ usd: 0.25,
+ });
+ expect(r.ok).toBe(true);
+ if (!r.ok) return;
+ expect(r.remaining.maxTokens).toBe(70);
+ expect(r.remaining.maxUsd).toBe(0.75);
+ expect(r.remaining.maxHops).toBe(5); // hop ceiling itself unchanged
+ });
+ });
+
+ describe('anti-malice: negative spend cannot inflate remaining', () => {
+ it('treats negative tokens as 0 (no refund / inflation)', () => {
+ const r = enforceBudget(bud({ maxTokens: 100, maxHops: 5 }), 0, {
+ tokens: -50,
+ usd: 0,
+ });
+ expect(r.ok).toBe(true);
+ if (!r.ok) return;
+ expect(r.remaining.maxTokens).toBe(100);
+ });
+
+ it('treats negative usd as 0', () => {
+ const r = enforceBudget(bud({ maxUsd: 1, maxHops: 5 }), 0, {
+ tokens: 0,
+ usd: -2,
+ });
+ expect(r.ok).toBe(true);
+ if (!r.ok) return;
+ expect(r.remaining.maxUsd).toBe(1);
+ });
+ });
+
+ describe('atomic check (no internal awaits)', () => {
+ it('is purely synchronous — return value type is not a Promise', () => {
+ const r = enforceBudget(bud({ maxHops: 1 }), 0);
+ // The return type is the discriminated union, not a Promise. This
+ // pins the no-internal-await contract: a future refactor that adds
+ // an await would change the function to async and break this assertion.
+ expect(r).not.toBeInstanceOf(Promise);
+ expect(typeof (r as object as { then?: unknown }).then).toBe('undefined');
+ });
+ });
+
+ describe('error info leak (anti-oracle)', () => {
+ it('failure result carries no remaining-budget data', () => {
+ const r = enforceBudget(bud({ maxHops: 0 }), 0);
+ expect(r.ok).toBe(false);
+ if (r.ok) return;
+ // Reason is the only public field on the failure case — no budget
+ // numbers, no remaining counts, nothing a caller can probe with.
+ expect(Object.keys(r).sort()).toEqual(['ok', 'reason']);
+ });
+
+ it('uses constant strings (HOP_LIMIT_EXCEEDED / BUDGET_EXCEEDED only)', () => {
+ const r1 = enforceBudget(bud({ maxHops: 0 }), 0);
+ const r2 = enforceBudget(bud({ maxTokens: 0, maxHops: 5 }), 0, {
+ tokens: 1,
+ usd: 0,
+ });
+ expect(r1.ok).toBe(false);
+ expect(r2.ok).toBe(false);
+ if (r1.ok || r2.ok) return;
+ expect(['HOP_LIMIT_EXCEEDED', 'BUDGET_EXCEEDED']).toContain(r1.reason);
+ expect(['HOP_LIMIT_EXCEEDED', 'BUDGET_EXCEEDED']).toContain(r2.reason);
+ });
+ });
+});
diff --git a/v3/@claude-flow/plugin-agent-federation/src/application/federation-coordinator.ts b/v3/@claude-flow/plugin-agent-federation/src/application/federation-coordinator.ts
index 051b802a44..157143ef06 100644
--- a/v3/@claude-flow/plugin-agent-federation/src/application/federation-coordinator.ts
+++ b/v3/@claude-flow/plugin-agent-federation/src/application/federation-coordinator.ts
@@ -9,6 +9,31 @@ import { AuditService } from '../domain/services/audit-service.js';
import { PIIPipelineService } from '../domain/services/pii-pipeline-service.js';
import { TrustEvaluator, type ImmediateDowngradeReason } from './trust-evaluator.js';
import { PolicyEngine } from './policy-engine.js';
+import {
+ type Budget,
+ type BudgetEnforcement,
+ enforceBudget,
+ validateBudget,
+} from '../domain/value-objects/federation-budget.js';
+
+/**
+ * Optional per-call budget controls (ADR-097 Phase 1). All fields are
+ * optional; omitted means "no limit on that axis" (the default unbounded
+ * budget still has maxHops = 8 to defang recursive delegation loops).
+ */
+export interface SendOptions {
+ readonly budget?: { maxTokens?: number; maxUsd?: number };
+ readonly maxHops?: number;
+ /**
+ * How many hops this message has already traveled (0 on the originator).
+ * Phase 1 enforces at the send side because there is no inbound dispatcher
+ * yet; callers re-forwarding a received message should pass the original
+ * envelope's hopCount here.
+ */
+ readonly hopCount?: number;
+ /** Caller-reported usage from the previous leg, for cumulative checks. */
+ readonly spent?: { tokens?: number; usd?: number };
+}
export interface FederationCoordinatorConfig {
readonly nodeId: string;
@@ -119,6 +144,7 @@ export class FederationCoordinator {
targetNodeId: string,
messageType: FederationMessageType,
payload: T,
+ options: SendOptions = {},
): Promise<RoutingResult> {
this.ensureInitialized();
@@ -155,18 +181,72 @@ export class FederationCoordinator {
};
}
+ // ADR-097 Phase 1: validate caller-supplied budget + enforce hop limit
+ // and cumulative spend BEFORE outbound dispatch. Synchronous & atomic —
+ // no awaits between validate and enforce, so concurrent sends cannot
+ // both pass a single-hop budget. Errors are constant strings so a
+ // malicious caller cannot use the response as a budget oracle.
+ const budgetResult = validateBudget(options.budget, options.maxHops);
+ if (!budgetResult.ok) {
+ await this.audit.log('message_rejected', {
+ targetNodeId,
+ sessionId: session.sessionId,
+ metadata: { reason: 'INVALID_BUDGET', detail: budgetResult.error },
+ });
+ return {
+ success: false,
+ mode: 'direct',
+ envelopeId: '',
+ targetNodeIds: [targetNodeId],
+ error: 'INVALID_BUDGET',
+ };
+ }
+ const enforcement: BudgetEnforcement = enforceBudget(
+ budgetResult.budget,
+ options.hopCount ?? 0,
+ {
+ tokens: options.spent?.tokens ?? 0,
+ usd: options.spent?.usd ?? 0,
+ },
+ );
+ if (!enforcement.ok) {
+ await this.audit.log('message_rejected', {
+ targetNodeId,
+ sessionId: session.sessionId,
+ metadata: { reason: enforcement.reason },
+ });
+ return {
+ success: false,
+ mode: 'direct',
+ envelopeId: '',
+ targetNodeIds: [targetNodeId],
+ error: enforcement.reason, // constant string — no oracle leak
+ };
+ }
+
const result = await this.routing.send(session, messageType, payload);
await this.audit.log(result.success ? 'message_sent' : 'message_rejected', {
targetNodeId,
sessionId: session.sessionId,
latencyMs: result.latencyMs,
- metadata: { messageType, mode: result.mode },
+ metadata: {
+ messageType,
+ mode: result.mode,
+ hopCount: enforcement.nextHopCount,
+ },
});
return result;
}
+ /**
+ * Re-export the budget primitives so external callers (e.g. follow-up
+ * iterations adding receive-side decrement) can reuse them without
+ * dipping into domain/value-objects directly.
+ */
+ static readonly budget = { validate: validateBudget, enforce: enforceBudget };
+
async broadcastMessage<T>(
messageType: FederationMessageType,
payload: T,
diff --git a/v3/@claude-flow/plugin-agent-federation/src/domain/value-objects/federation-budget.ts b/v3/@claude-flow/plugin-agent-federation/src/domain/value-objects/federation-budget.ts
new file mode 100644
index 0000000000..68ffe5a314
--- /dev/null
+++ b/v3/@claude-flow/plugin-agent-federation/src/domain/value-objects/federation-budget.ts
@@ -0,0 +1,211 @@
+/**
+ * Federation budget + hop counter (ADR-097 Phase 1).
+ *
+ * Carried in {@link FederationEnvelope} alongside the existing
+ * sourceNodeId/targetNodeId/payload. Sender supplies the original limits;
+ * each outbound hop increments hopCount and decrements remaining budget.
+ *
+ * Phase 1 enforces at the *send* side because there is no inbound
+ * dispatcher today (sendToNode is a stub — see researcher report).
+ * Phase 2 will move the decrement to receive once the inbound path lands.
+ *
+ * Security invariants pinned by the reviewer (audit_1776853149979 follow-up):
+ *
+ * 1. validateBudget rejects NaN, ±Infinity, negative numbers, and
+ * non-integer hop counts. Returns a discriminated result so callers
+ * cannot accidentally use a bad budget unchecked.
+ * 2. enforceBudget runs check-then-decrement in a single synchronous
+ * function with no awaits inside — two concurrent send calls cannot
+ * both pass the pre-check.
+ * 3. Errors return constant strings ("HOP_LIMIT_EXCEEDED" /
+ * "BUDGET_EXCEEDED") with no remaining-budget echo so a caller can't
+ * use the error response as an oracle for the threshold.
+ */
+
+/** Maximum hops a federation message may travel before the breaker opens. */
+export const DEFAULT_MAX_HOPS = 8;
+/** Hard ceiling on caller-supplied maxUsd to prevent absurd integer math. */
+const MAX_USD_CEILING = 1_000_000;
+/** Hard ceiling on caller-supplied maxTokens. 1B tokens is more than any real session. */
+const MAX_TOKENS_CEILING = 1_000_000_000;
+/** Hard ceiling on hop count. */
+const MAX_HOPS_CEILING = 64;
+
+/**
+ * Caller-supplied budget. All fields are optional; omitted fields are
+ * treated as Infinity for the corresponding axis. Created via validateBudget;
+ * never construct directly.
+ */
+export interface Budget {
+ readonly maxHops: number;
+ readonly maxTokens: number; // Infinity allowed
+ readonly maxUsd: number; // Infinity allowed
+}
+
+/** Discriminated result of validating raw user input into a Budget. */
+export type BudgetValidationResult =
+ | { ok: true; budget: Budget }
+ | { ok: false; error: string };
+
+/**
+ * Validate a raw budget object. Pure, no side effects. Caller obtains either
+ * a guaranteed-safe Budget or a structured error suitable for logging.
+ *
+ * Accepts undefined/null and returns a default unbounded budget (maxHops =
+ * DEFAULT_MAX_HOPS, tokens/usd = Infinity). This preserves backward
+ * compatibility for callers that don't pass a budget at all.
+ */
+export function validateBudget(
+ raw: unknown,
+ overrideMaxHops?: unknown,
+): BudgetValidationResult {
+ // Default unbounded budget when caller passes nothing.
+ if (raw == null && overrideMaxHops == null) {
+ return {
+ ok: true,
+ budget: {
+ maxHops: DEFAULT_MAX_HOPS,
+ maxTokens: Number.POSITIVE_INFINITY,
+ maxUsd: Number.POSITIVE_INFINITY,
+ },
+ };
+ }
+
+ // Caller passed a bare maxHops without a budget object — accept it as a
+ // hop-only budget. Useful for "no remote delegation allowed" via
+ // maxHops: 0.
+ if (raw == null && overrideMaxHops != null) {
+ const hopCheck = checkHops(overrideMaxHops);
+ if (!hopCheck.ok) return hopCheck;
+ return {
+ ok: true,
+ budget: {
+ maxHops: hopCheck.value,
+ maxTokens: Number.POSITIVE_INFINITY,
+ maxUsd: Number.POSITIVE_INFINITY,
+ },
+ };
+ }
+
+ if (typeof raw !== 'object' || Array.isArray(raw)) {
+ return { ok: false, error: 'budget must be an object' };
+ }
+ const obj = raw as Record<string, unknown>;
+
+ const hopsRaw = overrideMaxHops ?? obj.maxHops;
+ const hopCheck =
+ hopsRaw == null
+ ? { ok: true as const, value: DEFAULT_MAX_HOPS }
+ : checkHops(hopsRaw);
+ if (!hopCheck.ok) return hopCheck;
+
+ const tokensCheck =
+ obj.maxTokens == null
+ ? { ok: true as const, value: Number.POSITIVE_INFINITY }
+ : checkBound(obj.maxTokens, MAX_TOKENS_CEILING, 'maxTokens', true);
+ if (!tokensCheck.ok) return tokensCheck;
+
+ const usdCheck =
+ obj.maxUsd == null
+ ? { ok: true as const, value: Number.POSITIVE_INFINITY }
+ : checkBound(obj.maxUsd, MAX_USD_CEILING, 'maxUsd', false);
+ if (!usdCheck.ok) return usdCheck;
+
+ return {
+ ok: true,
+ budget: {
+ maxHops: hopCheck.value,
+ maxTokens: tokensCheck.value,
+ maxUsd: usdCheck.value,
+ },
+ };
+}
+
+function checkHops(
+ v: unknown,
+): { ok: true; value: number } | { ok: false; error: string } {
+ if (typeof v !== 'number' || !Number.isFinite(v) || !Number.isInteger(v)) {
+ return { ok: false, error: 'maxHops must be a finite integer' };
+ }
+ if (v < 0) return { ok: false, error: 'maxHops must be >= 0' };
+ if (v > MAX_HOPS_CEILING) {
+ return { ok: false, error: `maxHops exceeds ceiling (${MAX_HOPS_CEILING})` };
+ }
+ return { ok: true, value: v };
+}
+
+function checkBound(
+ v: unknown,
+ ceiling: number,
+ label: string,
+ requireInteger: boolean,
+): { ok: true; value: number } | { ok: false; error: string } {
+ if (typeof v !== 'number' || !Number.isFinite(v)) {
+ return { ok: false, error: `${label} must be a finite number` };
+ }
+ if (requireInteger && !Number.isInteger(v)) {
+ return { ok: false, error: `${label} must be an integer` };
+ }
+ if (v < 0) return { ok: false, error: `${label} must be >= 0` };
+ if (v > ceiling) {
+ return { ok: false, error: `${label} exceeds ceiling (${ceiling})` };
+ }
+ return { ok: true, value: v };
+}
+
+/**
+ * Enforcement decision returned by enforceBudget. Discriminated so the
+ * caller can map directly to a constant-string error — no remaining-budget
+ * echo on the failure side (anti-oracle).
+ */
+export type BudgetEnforcement =
+ | { ok: true; nextHopCount: number; remaining: Budget }
+ | { ok: false; reason: 'HOP_LIMIT_EXCEEDED' | 'BUDGET_EXCEEDED' };
+
+/**
+ * Atomic (single synchronous function, no internal awaits) hop check.
+ *
+ * Returns the hopCount value the OUTBOUND envelope should carry plus the
+ * remaining budget that downstream peers will see. Callers must use the
+ * returned values; mutating the input Budget is forbidden (it's readonly).
+ *
+ * Contract:
+ * - hopCount represents how many hops the message has already taken.
+ * - The next outbound hop increments it: nextHopCount = hopCount + 1.
+ * - The check fires AFTER increment: nextHopCount must be <= maxHops.
+ * - This means maxHops=0 refuses to forward at all, which matches the
+ * ADR's "no remote delegation allowed" semantic.
+ *
+ * tokensSpent / usdSpent are caller-reported actuals from the immediately
+ * preceding leg (or 0 on the originator). The check fires on the
+ * *post-spend* totals so a leg that overshoots is caught before the next
+ * outbound dispatch.
+ */
+export function enforceBudget(
+ budget: Budget,
+ hopCount: number,
+ spent: { tokens: number; usd: number } = { tokens: 0, usd: 0 },
+): BudgetEnforcement {
+ const nextHopCount = hopCount + 1;
+ if (nextHopCount > budget.maxHops) {
+ return { ok: false, reason: 'HOP_LIMIT_EXCEEDED' };
+ }
+ // Negative spend is a programming error; treat as 0 rather than refunding
+ // the budget (which would let a malicious caller inflate remaining).
+ const ts = Math.max(0, spent.tokens);
+ const us = Math.max(0, spent.usd);
+ const remainingTokens = budget.maxTokens - ts;
+ const remainingUsd = budget.maxUsd - us;
+ if (remainingTokens < 0 || remainingUsd < 0) {
+ return { ok: false, reason: 'BUDGET_EXCEEDED' };
+ }
+ return {
+ ok: true,
+ nextHopCount,
+ remaining: {
+ maxHops: budget.maxHops,
+ maxTokens: remainingTokens,
+ maxUsd: remainingUsd,
+ },
+ };
+}
diff --git a/v3/@claude-flow/plugin-agent-federation/src/mcp-tools.ts b/v3/@claude-flow/plugin-agent-federation/src/mcp-tools.ts
index 31a780ad53..c01e22e1f3 100644
--- a/v3/@claude-flow/plugin-agent-federation/src/mcp-tools.ts
+++ b/v3/@claude-flow/plugin-agent-federation/src/mcp-tools.ts
@@ -89,7 +89,7 @@ export function createMcpTools(
},
{
name: 'federation_send',
- description: 'Send a message to a federated peer through the PII pipeline and security gates',
+ description: 'Send a message to a federated peer through the PII pipeline and security gates. Optional budget controls (ADR-097): maxHops defaults to 8 to prevent recursive delegation; maxTokens/maxUsd cap cumulative spend across the hop chain.',
pluginName: '@claude-flow/plugin-agent-federation',
version: '1.0.0-alpha.1',
inputSchema: {
@@ -98,6 +98,33 @@ export function createMcpTools(
targetNodeId: { type: 'string', description: 'Target node ID' },
messageType: { type: 'string', description: 'Message type (task-assignment, memory-query, context-share, etc.)' },
payload: { type: 'object', description: 'Message payload' },
+ // ADR-097 Phase 1: optional budget envelope. Backward compatible —
+ // omitting these preserves the legacy unbounded-tokens/USD path,
+ // with maxHops still defaulting to 8 to defang recursion loops.
+ budget: {
+ type: 'object',
+ description: 'Optional cumulative spend budget for this delegation chain',
+ properties: {
+ maxTokens: { type: 'number', description: 'Hard cap on Σ tokens across hops' },
+ maxUsd: { type: 'number', description: 'Hard cap on Σ USD spent' },
+ },
+ },
+ maxHops: {
+ type: 'number',
+ description: 'Maximum hops this message may travel (default 8, 0 disallows remote delegation)',
+ },
+ hopCount: {
+ type: 'number',
+ description: 'How many hops this message has already taken (0 on the originator)',
+ },
+ spent: {
+ type: 'object',
+ description: 'Caller-reported usage from previous legs (cumulative)',
+ properties: {
+ tokens: { type: 'number' },
+ usd: { type: 'number' },
+ },
+ },
},
required: ['targetNodeId', 'messageType', 'payload'],
},
@@ -107,6 +134,12 @@ export function createMcpTools(
params['targetNodeId'] as string,
params['messageType'] as FederationMessageType,
params['payload'],
+ {
+ budget: params['budget'] as { maxTokens?: number; maxUsd?: number } | undefined,
+ maxHops: params['maxHops'] as number | undefined,
+ hopCount: params['hopCount'] as number | undefined,
+ spent: params['spent'] as { tokens?: number; usd?: number } | undefined,
+ },
);
return textResult(JSON.stringify(result, null, 2), !result.success);
},