@dollhousemcp/mcp-server/dist/elements/agents/resilienceEvaluator.d.ts

DollhouseMCP - A Model Context Protocol (MCP) server that enables dynamic AI persona management from markdown files, allowing Claude and other compatible AI assistants to activate and switch between different behavioral personas.

/**
 * Resilience Evaluator for Agent Execution
 *
 * Pure functions that evaluate resilience policies to determine recovery actions
 * when agents hit step limits or encounter execution failures.
 *
 * Design: All functions are pure (no side effects, no I/O). The MCPAQLHandler
 * is responsible for acting on the returned ResilienceAction.
 *
 * The CircuitBreakerState class is the one exception to purity — it holds
 * singleton state that tracks agents whose resilience limits were recently
 * exhausted.  When an agent trips the breaker and is re-executed within the
 * cooldown window, the evaluator forces an immediate pause instead of allowing
 * further auto-continuation or retry loops.
 *
 * @since v2.1.0 - Agent Execution Resilience (Issue #526)
 */
import type { AgentResiliencePolicy, ResilienceAction } from './types.js';
/** Default resilience policy — all 'pause', matching pre-#526 behavior */
export declare const DEFAULT_RESILIENCE_POLICY: Required<AgentResiliencePolicy>;
/** Base delay for backoff calculations (milliseconds) */
export declare const BACKOFF_BASE_MS = 1000;
/** Maximum backoff delay cap (milliseconds) — 30 seconds */
export declare const BACKOFF_MAX_MS = 30000;
/** Exponential base used in backoff calculations */
export declare const EXPONENTIAL_BASE = 2;
/** Cooldown window for the circuit breaker (milliseconds) — 5 minutes */
export declare const CIRCUIT_BREAKER_COOLDOWN_MS: number;
/**
 * Tracks agents that have recently exhausted their resilience limits.
 *
 * When an agent hits maxContinuations or maxRetries and is forced to pause,
 * the circuit breaker records a "trip". If the same agent is re-executed and
 * triggers resilience evaluation again within the cooldown window, the breaker
 * fires and forces an immediate pause — preventing tight re-execution loops
 * of broken agents.
 */
export declare class CircuitBreakerState {
    private trips;
    /**
     * Record that an agent exhausted its resilience limits.
     * Increments the trip count and updates the timestamp.
     */
    trip(agentName: string): void;
    /**
     * Check whether an agent's circuit breaker is currently tripped.
     *
     * Returns true if the agent was tripped within the given cooldown window,
     * meaning it should be immediately paused rather than allowed to retry/continue.
     */
    isTripped(agentName: string, cooldownMs: number): boolean;
    /**
     * Clear circuit breaker state for a specific agent.
     * Call this when an agent completes successfully to reset its breaker.
     */
    reset(agentName: string): void;
    /**
     * Clear all circuit breaker state. Primarily for testing.
     */
    resetAll(): void;
    /**
     * Get the trip record for an agent (read-only, for diagnostics).
     * Returns undefined if the agent has no trip history.
     */
    getState(agentName: string): {
        tripCount: number;
        lastTrippedAt: number;
    } | undefined;
}
/** Singleton circuit breaker instance shared across all resilience evaluations */
export declare const circuitBreaker: CircuitBreakerState;
/**
 * Context needed to evaluate a resilience decision.
 * Kept minimal — only what the evaluator needs.
 */
export interface ResilienceContext {
    /** What triggered the evaluation */
    trigger: 'step_limit' | 'execution_failure';
    /** Current continuation count for this execution chain */
    continuationCount: number;
    /** Current retry count for this specific step */
    retryCount: number;
    /** Step outcome that triggered the evaluation (for failure triggers) */
    stepOutcome?: 'success' | 'failure' | 'partial';
    /** Agent name for circuit breaker tracking (optional for backward compatibility) */
    agentName?: string;
}
/**
 * Evaluate a resilience policy given the trigger context.
 *
 * Returns a ResilienceAction describing what recovery action to take.
 * The action 'pause' means "do nothing special" (legacy behavior).
 */
export declare function evaluateResiliencePolicy(policy: AgentResiliencePolicy | undefined, context: ResilienceContext): ResilienceAction;
/**
 * Merge a partial policy with defaults to get a fully resolved policy.
 */
export declare function resolvePolicy(policy: AgentResiliencePolicy | undefined): Required<AgentResiliencePolicy>;
/**
 * Calculate backoff delay in milliseconds for a given retry count and strategy.
 *
 * @param strategy - The backoff strategy: 'none' (0ms), 'linear', or 'exponential'
 * @param retryCount - The current retry attempt number (0-based)
 * @param jitter - When true, multiplies the delay by a random factor between 0.5
 *   and 1.5 to decorrelate concurrent retries. The jittered result is still
 *   capped at BACKOFF_MAX_MS. Default: false.
 * @returns Backoff delay in milliseconds
 */
export declare function calculateBackoff(strategy: 'none' | 'linear' | 'exponential', retryCount: number, jitter?: boolean): number;
//# sourceMappingURL=resilienceEvaluator.d.ts.map