#Sentinel Circuit Breaker (@xtnd/vantage-sentinel)

Package: @xtnd/vantage-sentinel
Source Directory: xtnd-vantage/packages/sentinel/

#1. Overview

Autonomous AI agents and complex tool-calling workflows introduce unprecedented operational risks: infinite recursion loops, recursive API retries, and runaway token spending.

@xtnd/vantage-sentinel provides dynamic circuit breakers that actively monitor execution health, error density, agent steps, and dollar burn velocity, tripping instantly when safety guardrails are breached.

#2. Circuit Breaker Configuration (CircuitBreakerConfig)

export interface CircuitBreakerConfig {
  /** Maximum consecutive failures before opening the circuit (default: 5) */
  maxConsecutiveErrors?: number;

  /** Maximum recursive tool/planning steps an agent can execute per session (default: 25) */
  maxAgentSteps?: number;

  /** Maximum dollar threshold an agent session can consume (default: $5.00) */
  maxCostPerSessionUsd?: number;
}

#3. Circuit States & Transitions

stateDiagram-v2
    [*] --> CLOSED: Initial Healthy State
    CLOSED --> OPEN: Max Errors / Runaway Steps / Budget Overrun
    OPEN --> HALF_OPEN: Administrative Reset / Probe Check
    HALF_OPEN --> CLOSED: recordSuccess()
    HALF_OPEN --> OPEN: Failure on Probe

• CLOSED: All systems operational. Executions proceed normally (canExecute() === true).
• OPEN: Safety threshold breached. All executions are immediately halted (canExecute() === false).
• HALF_OPEN: Canary state. Allows a single test request through; if successful, restores to CLOSED.

#4. Protection Guardrails & Trip Triggers

#4.1 Runaway Agent Loop Breaker (RUNAWAY_AGENT_LOOP)

Autonomous agents can become trapped in reasoning cycles (e.g., repeatedly calling a tool that returns ambiguous data).

• Sentinel monitors agent step increments via recordAgentStep(stepNumber, costUsd).
• If stepNumber >= maxAgentSteps (default: 25 steps), the circuit trips immediately.

#4.2 Session Cost Cap Breaker (SESSION_COST_LIMIT_EXCEEDED)

Multi-turn agent chains using expensive models (such as o1 or claude-3-opus) can burn dozens of dollars in minutes.

• Sentinel accumulates total spend across turns.
• If sessionCost >= maxCostPerSessionUsd (default: $5.00), the circuit trips immediately.

#4.3 Consecutive Error Spike (CONSECUTIVE_ERRORS_EXCEEDED)

• If upstream AI providers experience rate limits (HTTP 429) or gateway failures (HTTP 503), consecutive errors accumulate.
• At 5 consecutive failures, the breaker opens, protecting downstream systems from hammering degraded endpoints.

#5. Event-Driven P0 Trip Notification

When the circuit trips:

1. state shifts to OPEN.
2. A P0_CRITICAL event (circuit:trip) is written to local storage.
3. StorageManager dispatches the emergency signal out-of-band to api.vantage.xgi.io/v1/events/urgent, triggering alerts and command center kill-switch visualizers.

this.storageManager.writeEvent(
  'circuit:trip',
  {
    reason: 'RUNAWAY_AGENT_LOOP',
    details: { steps: 25, maxSteps: 25 },
    isCritical: true,
  },
  { forcedPriority: 'P0_CRITICAL' }
);

#6. Usage Example

import { VantageCircuitBreaker } from '@xtnd/vantage-sentinel';

const breaker = new VantageCircuitBreaker(storageManager, {
  maxAgentSteps: 15,
  maxCostPerSessionUsd: 2.50,
  maxConsecutiveErrors: 3
});

// Guarding an autonomous agent step:
if (!breaker.canExecute()) {
  throw new Error('Agent execution blocked by Vantage Sentinel Circuit Breaker');
}

try {
  const result = await runAgentStep(stepCount);
  breaker.recordSuccess();
  breaker.recordAgentStep(stepCount, result.stepCostUsd);
} catch (err) {
  breaker.recordError(err);
  throw err;
}