/**
 * Self-healing and retry logic for the Agent dimension.
 *
 * Provides configurable retry policies with exponential backoff + jitter,
 * and recovery mechanisms for crashed agents. Error classification
 * determines whether a retry is appropriate.
 *
 * @module agents/retry
 */
/** Configuration for retry behavior. */
export interface RetryPolicy {
    /** Maximum number of retry attempts. Default: 3. */
    maxRetries: number;
    /** Base delay in milliseconds before first retry. Default: 1000. */
    baseDelayMs: number;
    /** Maximum delay in milliseconds between retries. Default: 30000. */
    maxDelayMs: number;
    /** Multiplier for exponential backoff. Default: 2. */
    backoffMultiplier: number;
    /** Whether to add random jitter to delays. Default: true. */
    jitter: boolean;
    /** Whether to retry on 'unknown' error classification. Default: true. */
    retryOnUnknown: boolean;
}
/** Default retry policy matching the BRAIN specification. */
export declare const DEFAULT_RETRY_POLICY: Readonly<RetryPolicy>;
/**
 * Create a retry policy by merging overrides with the default policy.
 *
 * @remarks
 * Unspecified fields fall back to {@link DEFAULT_RETRY_POLICY}.
 *
 * @param overrides - Partial policy to merge with defaults
 * @returns A complete RetryPolicy
 *
 * @example
 * ```ts
 * const policy = createRetryPolicy({ maxRetries: 5 });
 * ```
 */
export declare function createRetryPolicy(overrides?: Partial<RetryPolicy>): RetryPolicy;
/**
 * Calculate the delay for a given retry attempt using exponential backoff.
 *
 * @remarks
 * Formula: `min(baseDelay * multiplier^attempt, maxDelay) + jitter`.
 * Jitter adds 0-25% randomness to prevent thundering herd.
 *
 * @param attempt - Zero-based attempt index
 * @param policy - Retry policy with delay configuration
 * @returns Delay in milliseconds before the next attempt
 *
 * @example
 * ```ts
 * const delay = calculateDelay(1, createRetryPolicy());
 * // => ~2000ms (with jitter)
 * ```
 */
export declare function calculateDelay(attempt: number, policy: RetryPolicy): number;
/**
 * Determine whether an error should be retried based on its classification
 * and the retry policy.
 *
 * @remarks
 * Permanent errors are never retried. Retriable errors are always retried
 * (within attempt limits). Unknown errors defer to `policy.retryOnUnknown`.
 *
 * @param error - The caught error to classify
 * @param attempt - Current attempt number (0-based)
 * @param policy - Retry policy with limits and classification rules
 * @returns True if the error should be retried
 *
 * @example
 * ```ts
 * if (shouldRetry(err, attempt, policy)) { /* retry *\/ }
 * ```
 */
export declare function shouldRetry(error: unknown, attempt: number, policy: RetryPolicy): boolean;
/** Result of a retried operation. */
export interface RetryResult<T> {
    success: boolean;
    value?: T;
    error?: Error;
    attempts: number;
    totalDelayMs: number;
}
/**
 * Wrap an async function with retry logic using configurable exponential backoff.
 *
 * @remarks
 * Agent-specific variant that integrates with error classification from the
 * agent registry. For a dependency-free generic retry, use `lib/retry.ts`.
 *
 * @typeParam T - The resolved type of the async function
 * @param fn - The async function to execute with retries
 * @param policy - Retry policy (uses DEFAULT_RETRY_POLICY if not provided)
 * @returns The result of the operation with retry metadata
 *
 * @example
 * ```ts
 * const result = await withRetry(() => fetchAgentTask(agentId));
 * if (!result.success) console.error(result.error);
 * ```
 */
export declare function withRetry<T>(fn: () => Promise<T>, policy?: Partial<RetryPolicy>): Promise<RetryResult<T>>;
/** Result of a recovery attempt for a single agent. */
export interface AgentRecoveryResult {
    agentId: string;
    recovered: boolean;
    action: 'restarted' | 'abandoned' | 'skipped';
    reason: string;
}
/**
 * Attempt to recover crashed agents.
 *
 * Finds all agents with status 'crashed' and determines if they can be
 * restarted based on their error history. Agents whose last error was
 * classified as 'permanent' are abandoned. Agents with retriable errors
 * are reset to 'starting' for the orchestration layer to re-assign.
 *
 * @remarks
 * Two-phase process: first detects stale agents via heartbeat threshold,
 * then evaluates each crashed agent's error history for recoverability.
 *
 * @param thresholdMs - Heartbeat threshold for crash detection (default: 30000)
 * @param cwd - Working directory
 * @returns Recovery results for each crashed agent
 *
 * @example
 * ```ts
 * const results = await recoverCrashedAgents(60_000);
 * results.filter(r => r.recovered).forEach(r => console.log(r.agentId));
 * ```
 */
export declare function recoverCrashedAgents(thresholdMs?: number, cwd?: string): Promise<AgentRecoveryResult[]>;
//# sourceMappingURL=retry.d.ts.map