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

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, 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, 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:

// 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:

// 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) supplies the token and USD metrics consumed by these evaluations, while 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, 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 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 gathers fresh inputs from each agent's telemetry stream before invoking breaker.tick().

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}