/** * Escalation Pipeline for PraisonAI Agents. * * Python parity: praisonaiagents/escalation/pipeline.py. Implements * progressive escalation from direct response to full autonomous mode. */ import { DoomLoopConfig, DoomLoopConfigOptions, DoomLoopDetector } from './doom-loop'; import { ObservabilityHooks } from './observability'; import { EscalationTrigger } from './triggers'; import { EscalationConfig, EscalationConfigOptions, EscalationResult, EscalationSignal, EscalationStage, StageContext } from './types'; /** Anything with a `chat(prompt)` (the TS `Agent` qualifies). */ export interface EscalationAgent { chat(prompt: string): unknown; tools?: unknown[]; } /** Shape of the checkpoint service consulted before autonomous execution (pipeline.py:418). */ export interface CheckpointServiceLike { save(description: string): Promise<{ success: boolean; checkpoint?: { id: string; }; }> | { success: boolean; checkpoint?: { id: string; }; }; } /** Result of one stage execution (pipeline.py:265 `Dict[str, Any]`). */ export interface StageExecutionResult { response: string; success: boolean; } /** * Injectable runner for the autonomous stage. Receives the raw prompt and * the live {@link StageContext}; returns the response text. The coordinator * may wire `src/cli/features/autonomy-mode.ts` here. */ export type AutonomousRunner = (prompt: string, context: StageContext) => Promise | string; /** Callback for stage transitions (pipeline.py:50 `on_stage_change`). */ export type StageChangeCallback = (oldStage: EscalationStage, newStage: EscalationStage) => void; /** Constructor options for {@link EscalationPipeline} (pipeline.py:44-50). */ export interface EscalationPipelineOptions { /** Pipeline configuration (default null -> `EscalationConfig()`). */ config?: EscalationConfig | EscalationConfigOptions | null; /** Agent instance for execution (default null). */ agent?: EscalationAgent | null; /** Available tools (default null -> []). */ tools?: unknown[] | null; /** Service for checkpoints (default null). */ checkpointService?: CheckpointServiceLike | null; /** Callback for stage transitions (default null). */ onStageChange?: StageChangeCallback | null; /** TypeScript-only: runner for the AUTONOMOUS stage; falls back to `agent.chat` with the autonomous prompt. */ autonomousRunner?: AutonomousRunner | null; /** TypeScript-only: opt-in observability hooks that receive stage/loop/budget events. */ observability?: ObservabilityHooks | null; /** TypeScript-only: configuration for the built-in {@link DoomLoopDetector}. */ doomLoopConfig?: DoomLoopConfig | DoomLoopConfigOptions | null; } /** * Progressive escalation pipeline for agent execution. * * - Stage 0 (DIRECT): Immediate response without tools * - Stage 1 (HEURISTIC): Tool selection based on local signals * - Stage 2 (PLANNED): Lightweight planning with single LLM call * - Stage 3 (AUTONOMOUS): Full autonomous loop with verification * * Python parity: escalation/pipeline.py:23 `EscalationPipeline`. * * @example * const pipeline = new EscalationPipeline({ agent }); * const result = await pipeline.execute('Refactor the auth module'); * // Or analyze first, then execute * const stage = pipeline.analyze('Simple question'); * const result2 = await pipeline.executeAtStage('Simple question', stage); */ export declare class EscalationPipeline { config: EscalationConfig; agent: EscalationAgent | null; tools: unknown[]; checkpointService: CheckpointServiceLike | null; onStageChange: StageChangeCallback | null; autonomousRunner: AutonomousRunner | null; observability: ObservabilityHooks | null; trigger: EscalationTrigger; doomDetector: DoomLoopDetector; private currentContext; constructor(options?: EscalationPipelineOptions); /** * Analyze prompt and recommend initial stage. * * Python parity: pipeline.py:75 `analyze(prompt, context=None)`. */ analyze(prompt: string, context?: Record | null): EscalationStage; /** * Execute prompt with automatic escalation. * * Python parity: pipeline.py:93 `execute(prompt, context=None, session_id=None)`. */ execute(prompt: string, context?: Record | null, sessionId?: string | null): Promise; /** * Execute prompt at a specific stage. * * Python parity: pipeline.py:122 * `execute_at_stage(prompt, stage, signals=None, context=None, session_id=None)`. */ executeAtStage(prompt: string, stage: EscalationStage, signals?: Set | EscalationSignal[] | null, context?: Record | null, sessionId?: string | null): Promise; /** Python parity: pipeline.py:261 `_execute_stage(stage, prompt)`. */ protected executeStage(stage: EscalationStage, prompt: string): Promise; /** * Execute direct response (Stage 0): no tools, no planning. * * Python parity: pipeline.py:287 `_execute_direct`. */ protected executeDirect(prompt: string): Promise; /** * Execute with heuristic tool selection (Stage 1): local signals pick the * tools, no extra LLM call. * * Python parity: pipeline.py:319 `_execute_heuristic`. */ protected executeHeuristic(prompt: string): Promise; /** * Execute with lightweight planning (Stage 2): a single LLM call creates a * constrained plan, then executes. * * Python parity: pipeline.py:365 `_execute_planned`. */ protected executePlanned(prompt: string): Promise; /** * Execute the full autonomous loop (Stage 3): tools + planning + * verification + checkpoints. Uses the injected {@link AutonomousRunner} * when one was given, else `agent.chat` with the autonomous prompt. * * Python parity: pipeline.py:402 `_execute_autonomous`. */ protected executeAutonomous(prompt: string): Promise; /** * Select tools based on detected signals. * * Python parity: pipeline.py:451 `_select_tools_heuristically`. */ protected selectToolsHeuristically(): unknown[]; /** Python parity: pipeline.py:492 `_notify_stage_change(old_stage, new_stage)`. */ protected notifyStageChange(oldStage: EscalationStage, newStage: EscalationStage): void; /** Python parity: pipeline.py:506 `get_current_stage`. */ getCurrentStage(): EscalationStage | null; /** Python parity: pipeline.py:512 `get_context`. */ getContext(): StageContext | null; /** `agent.chat` may be sync or async and may return a non-string. */ private chat; }