# How Per-Agent Token Caps and Floor-Wide Budgets Are Enforced by the Breaker Tick Evaluation

> Discover how the breaker tick evaluation enforces per-agent token caps and floor-wide budgets to protect system resources while identifying violating agents.

- Repository: [Chaitanya Giri/munder-difflin](https://github.com/chaitanyagiri/munder-difflin)
- Tags: internals
- Published: 2026-08-29

---

**The `CircuitBreaker` class evaluates per-agent token caps individually and floor-wide budgets collectively during each heartbeat tick, escalating only specific agents that violate limits while protecting overall system resources.**

In the `chaitanyagiri/munder-difflin` repository, the circuit breaker implementation ensures that autonomous agents operate within strictly defined resource boundaries. The breaker tick evaluation serves as the central enforcement mechanism that monitors both individual agent consumption and aggregate floor-wide spending, applying a "blame-the-biggest-spender" policy when collective budgets are breached.

## Breaker Tick Evaluation Architecture

The core enforcement logic resides in [`src/main/breaker.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/breaker.ts), specifically within the `tick()` method. This method executes once per heartbeat cycle, receiving an array of `BreakerInput` objects—each containing an agent's latest usage sample, filesystem progress status, and operational signals.

During each evaluation cycle, the breaker performs three distinct budget validations sequentially. These checks determine whether to escalate an agent's breaker state (from `healthy` → `steering` → `constrained` → `stopped`) or allow recovery toward healthy status.

## Per-Agent Token Cap Enforcement

### Individual Agent Monitoring

Per-agent limits are configured through the `agentTokenCaps` mapping in `CircuitBreakerConfig`. Each agent ID maps to a maximum allowable token count. During the tick evaluation at lines 3023-3025 of [`src/main/breaker.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/breaker.ts), the breaker extracts cumulative token usage via `tokensOf(input.sample)` and compares it against the configured cap for that specific agent.

When an agent exceeds its individual allocation, the breaker immediately returns a tripping decision with the reason "token limit … over the agent cap." This creates a hard boundary that prevents any single agent from monopolizing resources regardless of floor-wide availability.

### Cap Violation Detection

The enforcement occurs before floor-wide aggregation, ensuring that individual violations are caught even when the overall system remains under budget. The check uses strict inequality comparisons against the `agentTokenCaps` configuration values, allowing precise control over high-cost or experimental agents.

## Floor-Wide Budget Enforcement

### USD Cost Cap Aggregation

For collective cost control, the breaker implements a two-phase aggregation at lines 00270-00278. First, it iterates through the entire `inputs` array to sum `usd` values from each sample while tracking the highest-spending participant (`topSpender`). 

If the total floor cost exceeds `costCapUsd`, the enforcement logic at lines 00308-00309 triggers a trip action targeting exclusively the `topSpender`. This design maintains floor operations by constraining only the worst offender rather than halting all agents.

### Token Budget Aggregation

Similarly, token budgets are evaluated at lines 00280-00288 through aggregation of `tokensOf(i.sample)` across all agents. The breaker identifies the `topTokenSpender` during this summation. When the cumulative total exceeds `costCapTokens`, lines 00311-00312 execute a trip decision against the highest consumer, again preserving floor functionality while enforcing the collective limit.

### Blame-the-Biggest-Spender Policy

Both floor-wide checks implement a selective enforcement strategy. By targeting only the agent contributing most significantly to the budget overrun, the system achieves **graceful degradation** rather than total floor shutdown. This approach aligns with the repository's goal of maximizing productive agent uptime while preventing runaway costs.

## Escalation and Recovery Logic

After budget validation, the breaker applies a state transition ladder defined at lines 00264-00268. The logic evaluates whether any check returned `tripping: true`:

- If tripped: Increment the agent's breaker level (capped by the `hardStop` configuration)
- If healthy: Decrement the level toward `healthy` status

The resulting `BreakerDecision` includes the new `BreakerState`, the corresponding action (`steer`, `constrain`, or `stop`), and a `changed` flag indicating whether this tick modified the agent's status.

## Configuration and Implementation

Implementing these guards requires configuring the `CircuitBreaker` with appropriate caps and thresholds:

```typescript
// src/main/config.ts usage example
import { CircuitBreakerConfig } from './config';

const cfg: CircuitBreakerConfig = {
  enabled: true,
  hardStop: false,           // Allow constrained state before stopping
  costCapUsd: 50,            // Floor-wide $50 limit
  costCapTokens: 1_000_000, // Floor-wide 1M token limit
  agentTokenCaps: {
    'agent-alpha': 250_000,
    'agent-beta': 150_000
  }
};

const breaker = new CircuitBreaker(() => cfg);

```

Invoke the enforcement cycle in your heartbeat loop:

```typescript
// src/main/index.ts pattern
const decisions = breaker.tick(agentInputs, Date.now());

decisions.forEach(decision => {
  if (decision.changed) {
    console.log(`Agent ${decision.agentId}: ${decision.action}`);
    // Apply steering constraints or stop commands
  }
});

```

The `BreakerInput` type (defined in [`src/main/usage.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/usage.ts)) supplies the token and USD metrics consumed by these evaluations, while [`src/renderer/src/hooks/useTelemetry.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/renderer/src/hooks/useTelemetry.ts) consumes the resulting states for UI visualization.

## Summary

- **Per-agent enforcement** occurs at lines 3023-3025 of [`src/main/breaker.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/breaker.ts), comparing individual `tokensOf()` samples against `agentTokenCaps` configurations.
- **Floor-wide USD caps** aggregate total spending at lines 00270-00278, triggering at lines 00308-00309 when exceeding `costCapUsd`.
- **Floor-wide token budgets** sum collective usage at lines 00280-00288, with trip logic at lines 00311-00312 when exceeding `costCapTokens`.
- **Selective targeting** ensures only the highest-spending agent receives enforcement actions during collective budget violations.
- **State transitions** are managed at lines 00264-00268, supporting four levels from `healthy` to `stopped` based on `hardStop` configuration.

## Frequently Asked Questions

### What happens when both per-agent and floor-wide caps are exceeded simultaneously?

The breaker evaluates per-agent limits before floor-wide aggregations. If an agent violates its individual cap, it receives an immediate trip action regardless of floor status. Floor-wide checks only execute for agents surviving individual scrutiny, creating a layered defense where individual limits act as a first line of protection.

### How does the breaker determine which agent to constrain during a floor-wide budget breach?

The implementation tracks `topSpender` (for USD) and `topTokenSpender` (for tokens) during the aggregation loops. These variables hold the agent ID with the maximum contribution to the overrun. When a floor cap triggers, only these specific agents receive escalation actions, leaving other agents operational.

### Can an agent recover from a stopped state automatically?

Yes, if `hardStop` is disabled (set to `false`). Each tick without violations decrements the agent's breaker level toward `healthy` according to the recovery logic at lines 00264-00268. However, if `hardStop` is enabled, the agent remains in `stopped` state until manual intervention or configuration changes occur.

### Where are the usage metrics sourced for these budget calculations?

The `BreakerInput` type defined in [`src/main/usage.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/usage.ts) provides the `sample` field containing `usd` and token metrics. The `tokensOf()` utility function extracts cumulative counts from these samples, while the heartbeat loop in [`src/main/index.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/index.ts) gathers fresh inputs from each agent's telemetry stream before invoking `breaker.tick()`.