/** * Doom Loop Detection for PraisonAI Agents. * * Python parity: praisonaiagents/escalation/doom_loop.py. Detects and * prevents infinite loops, repeated failures, and stuck states, and provides * recovery strategies when loops are detected. * * Hashing note: Python uses `hashlib.sha256(...)[:16]`. This port uses a * non-cryptographic FNV-1a digest of the same width so the module stays free * of a static `crypto` import (see src/utils/uuid.ts for why that matters in * webviews). The hashes are only ever compared for equality. */ /** Python parity: escalation/doom_loop.py:17 `DoomLoopType(Enum)`. */ export declare enum DoomLoopType { /** Same action repeated. */ REPEATED_ACTION = "repeated_action", /** Same failure repeated. */ REPEATED_FAILURE = "repeated_failure", /** No meaningful progress. */ NO_PROGRESS = "no_progress", /** Plan loops back to start. */ CIRCULAR_PLAN = "circular_plan", /** Budget exceeded. */ RESOURCE_EXHAUSTION = "resource_exhaustion", /** Same output text repeated (content chanting). */ REPEATED_OUTPUT = "repeated_output" } /** Python parity: escalation/doom_loop.py:26 `RecoveryAction(Enum)`. */ export declare enum RecoveryAction { /** Continue execution. */ CONTINUE = "continue", /** Retry with different approach. */ RETRY_DIFFERENT = "retry_different", /** Try stronger model. */ ESCALATE_MODEL = "escalate_model", /** Ask user for clarification. */ REQUEST_HELP = "request_help", /** Stop execution safely. */ ABORT = "abort" } /** Constructor options for {@link DoomLoopConfig} (escalation/doom_loop.py:35-66). */ export interface DoomLoopConfigOptions { /** Max identical consecutive actions (default 3). */ maxIdenticalActions?: number; /** Max similar actions (fuzzy match) (default 5). */ maxSimilarActions?: number; /** Max failures before intervention (default 3). */ maxConsecutiveFailures?: number; /** Max steps without progress (default 5). */ maxNoProgressSteps?: number; /** Retained for backward compatibility only; not consulted by the detectors (default 0.85). */ similarityThreshold?: number; /** Max seconds per action (default 60.0). */ maxTimePerAction?: number; /** Max total execution time, seconds (default 300.0). */ maxTotalTime?: number; /** Auto-attempt recovery (default true). */ enableAutoRecovery?: boolean; /** Max recovery attempts (default 2). */ maxRecoveryAttempts?: number; /** Escalate model on loop detection (default true). */ escalateOnLoop?: boolean; /** Initial backoff in seconds (default 1.0). */ initialBackoff?: number; /** Backoff multiplier (default 2.0). */ backoffMultiplier?: number; /** Maximum backoff, seconds (default 30.0). */ maxBackoff?: number; /** Max identical output chunks before flagging (default 8). */ maxRepeatedChunks?: number; /** Sliding window chunk size, chars (default 50). */ contentChunkSize?: number; } /** * Configuration for doom loop detection. * * Python parity: escalation/doom_loop.py:35 `DoomLoopConfig`. */ export declare class DoomLoopConfig { maxIdenticalActions: number; maxSimilarActions: number; maxConsecutiveFailures: number; maxNoProgressSteps: number; similarityThreshold: number; maxTimePerAction: number; maxTotalTime: number; enableAutoRecovery: boolean; maxRecoveryAttempts: number; escalateOnLoop: boolean; initialBackoff: number; backoffMultiplier: number; maxBackoff: number; maxRepeatedChunks: number; contentChunkSize: number; constructor(options?: DoomLoopConfigOptions); } /** Accept either a built config or its options (TS convenience). */ export declare function toDoomLoopConfig(config: DoomLoopConfig | DoomLoopConfigOptions | null | undefined): DoomLoopConfig; /** Constructor options for {@link DoomLoopEvent} (escalation/doom_loop.py:69-76). */ export interface DoomLoopEventOptions { loopType: DoomLoopType; description: string; actionHistory: string[]; recoveryAction: RecoveryAction; /** Seconds since the epoch (default: now). */ timestamp?: number; /** (default {}) */ metadata?: Record; } /** * Event representing a doom loop detection. * * Python parity: escalation/doom_loop.py:69 `DoomLoopEvent`. */ export declare class DoomLoopEvent { loopType: DoomLoopType; description: string; actionHistory: string[]; recoveryAction: RecoveryAction; timestamp: number; metadata: Record; constructor(options: DoomLoopEventOptions); } /** * Record of an action for loop detection. * * Python parity: escalation/doom_loop.py:79 `ActionRecord`. */ export interface ActionRecord { actionType: string; actionHash: string; argsHash: string; resultHash: string | null; success: boolean; /** Seconds since the epoch. */ timestamp: number; /** Seconds. */ duration: number; metadata: Record; } /** Python parity: escalation/doom_loop.py:310 `get_stats` return shape. */ export interface DoomLoopStats { totalActions: number; successfulActions: number; failedActions: number; loopEvents: number; recoveryAttempts: number; progressMarkers: number; /** Seconds. */ elapsedTime: number; /** Seconds. */ currentBackoff: number; } /** * Detects and prevents doom loops in agent execution. * * Monitors action history for patterns that indicate stuck states: * repeated identical actions, repeated similar actions, consecutive * failures, no meaningful progress. * * Python parity: escalation/doom_loop.py:90 `DoomLoopDetector`. * * @example * const detector = new DoomLoopDetector(); * detector.recordAction('read_file', { path: 'foo.py' }, 'content', true); * detector.recordAction('read_file', { path: 'foo.py' }, 'content', true); * if (detector.isDoomLoop()) { * const event = detector.getLoopEvent(); * const recovery = detector.getRecoveryAction(); * } */ export declare class DoomLoopDetector { config: DoomLoopConfig; private actions; private loopEvents; private recoveryAttempts; private startTime; private progressMarkers; private currentBackoff; /** hash -> count */ private contentChunkCounts; /** Python parity: escalation/doom_loop.py:113 `__init__(config=None)`. */ constructor(config?: DoomLoopConfig | DoomLoopConfigOptions | null); /** Start a new detection session. Python parity: doom_loop.py:124 `start_session`. */ startSession(): void; /** * Record an action for loop detection. * * Python parity: doom_loop.py:134 * `record_action(action_type, args, result, success, duration=0.0, metadata=None)`. * * @param actionType - Type of action (e.g. "read_file", "edit") * @param args - Action arguments * @param result - Action result * @param success - Whether the action succeeded * @param duration - Action duration in seconds * @param metadata - Optional metadata */ recordAction(actionType: string, args: Record, result: unknown, success: boolean, duration?: number, metadata?: Record | null): void; /** * Record model response text for content streaming loop detection. * Hashes sliding window chunks and tracks repetition counts. * * Python parity: doom_loop.py:170 `record_response(text)`. */ recordResponse(text: string): void; /** * Mark meaningful progress (file modified, test passed, goal partially achieved). * * Python parity: doom_loop.py:189 `mark_progress(marker)`. */ markProgress(marker: string): void; /** * Check if the current state indicates a doom loop. * * Python parity: doom_loop.py:198 `is_doom_loop`. */ isDoomLoop(): boolean; /** Python parity: doom_loop.py:238 `get_loop_type`. */ getLoopType(): DoomLoopType | null; /** Python parity: doom_loop.py:254 `get_loop_event`. */ getLoopEvent(): DoomLoopEvent | null; /** Python parity: doom_loop.py:271 `get_recovery_action`. */ getRecoveryAction(): RecoveryAction; /** * Apply the backoff delay and return the delay used (seconds). * * Python parity: doom_loop.py:284 `apply_backoff` (which blocks with * `time.sleep`; this port awaits a timer instead). */ applyBackoff(): Promise; /** Python parity: doom_loop.py:296 `reset_backoff`. */ resetBackoff(): void; /** * Increment the recovery attempt counter; true if more attempts are allowed. * * Python parity: doom_loop.py:300 `increment_recovery`. */ incrementRecovery(): boolean; /** Python parity: doom_loop.py:310 `get_stats`. */ getStats(): DoomLoopStats; /** Loop events recorded by {@link recordAction} (Python `_loop_events`). */ getLoopEvents(): DoomLoopEvent[]; /** Python parity: doom_loop.py:329 `_hash_action`. */ private hashAction; /** Python parity: doom_loop.py:334 `_hash_dict` (keys sorted for stability). */ private hashDict; /** Python parity: doom_loop.py:340 `_hash_result` (first 1000 chars). */ private hashResult; /** Python parity: doom_loop.py:345 `_check_repeated_identical`. */ private checkRepeatedIdentical; /** Python parity: doom_loop.py:355 `_check_repeated_similar`. */ private checkRepeatedSimilar; /** Python parity: doom_loop.py:369 `_check_consecutive_failures`. */ private checkConsecutiveFailures; /** * Python parity: doom_loop.py:377 `_check_no_progress`. Only progress * markers within the current no-progress window count; the boundary is the * completion timestamp of the action immediately preceding the window (or * 0 if the window is the whole history) so a marker recorded during the * window's first action is still counted. */ private checkNoProgress; /** Python parity: doom_loop.py:409 `_check_resource_exhaustion`. */ private checkResourceExhaustion; /** Python parity: doom_loop.py:417 `_check_content_loop`. */ private checkContentLoop; /** Python parity: doom_loop.py:430 `_determine_recovery_action`. */ private determineRecoveryAction; /** Python parity: doom_loop.py:451 `_get_loop_description`. */ private getLoopDescription; /** Python parity: doom_loop.py:473 `_handle_loop_detection`. */ private handleLoopDetection; } /** * 16-hex-char digest built from two 32-bit FNV-1a passes with different * offset bases. Stable across runs; equality-only use. */ export declare function stableHash(content: string): string;