/** * Observability Hooks for the Escalation Pipeline. * * Python parity: praisonaiagents/escalation/observability.py. Lightweight * tracing and metrics collection for escalation execution. Opt-in only - no * overhead when not enabled. */ import { EscalationStage } from './types'; /** * Types of observable events. * * Python parity: escalation/observability.py:18 `EventType(Enum)`. Exported * as `ObservabilityEventType` so it does not clash with `src/trace`'s * `EventType`. */ export declare enum ObservabilityEventType { STAGE_ENTER = "stage_enter", STAGE_EXIT = "stage_exit", STAGE_ESCALATE = "stage_escalate", STAGE_DEESCALATE = "stage_deescalate", EXECUTION_START = "execution_start", EXECUTION_END = "execution_end", STEP_START = "step_start", STEP_END = "step_end", TOOL_CALL_START = "tool_call_start", TOOL_CALL_END = "tool_call_end", TOOL_CALL_ERROR = "tool_call_error", CHECKPOINT_CREATE = "checkpoint_create", CHECKPOINT_RESTORE = "checkpoint_restore", DOOM_LOOP_DETECTED = "doom_loop_detected", RECOVERY_ATTEMPT = "recovery_attempt", BUDGET_WARNING = "budget_warning", BUDGET_EXCEEDED = "budget_exceeded" } /** Constructor options for {@link ObservabilityEvent} (observability.py:50-62). */ export interface ObservabilityEventOptions { eventType: ObservabilityEventType; /** Seconds since the epoch. */ timestamp: number; /** (default {}) */ data?: Record; /** (default null) */ sessionId?: string | null; /** (default null) */ stage?: EscalationStage | null; /** (default 0) */ stepNumber?: number; /** (default null) */ durationMs?: number | null; } /** * An observable event from the escalation pipeline. * * Python parity: escalation/observability.py:50 `ObservabilityEvent`. */ export declare class ObservabilityEvent { eventType: ObservabilityEventType; timestamp: number; data: Record; sessionId: string | null; stage: EscalationStage | null; stepNumber: number; durationMs: number | null; constructor(options: ObservabilityEventOptions); /** Python parity: observability.py:64 `to_dict` (snake_case keys for wire compatibility). */ toDict(): Record; } /** Constructor options for {@link ExecutionMetrics} (observability.py:77-98). */ export interface ExecutionMetricsOptions { /** (default 0.0) */ totalDurationMs?: number; /** (default {}) */ stageDurationsMs?: Record; /** (default 0) */ totalSteps?: number; /** (default 0) */ toolCalls?: number; /** (default 0) */ toolErrors?: number; /** (default 0) */ escalations?: number; /** (default 0) */ deescalations?: number; /** (default 0) */ tokensUsed?: number; /** (default 0) */ checkpointsCreated?: number; /** (default 0) */ doomLoopsDetected?: number; /** (default 0) */ recoveryAttempts?: number; } /** * Metrics collected during execution. * * Python parity: escalation/observability.py:77 `ExecutionMetrics`. */ export declare class ExecutionMetrics { totalDurationMs: number; stageDurationsMs: Record; totalSteps: number; toolCalls: number; toolErrors: number; escalations: number; deescalations: number; tokensUsed: number; checkpointsCreated: number; doomLoopsDetected: number; recoveryAttempts: number; constructor(options?: ExecutionMetricsOptions); /** Python parity: observability.py:100 `to_dict` (snake_case keys for wire compatibility). */ toDict(): Record; } /** Handler signature for {@link ObservabilityHooks.on}. */ export type ObservabilityHandler = (event: ObservabilityEvent) => void; /** Constructor options for {@link ObservabilityHooks} (observability.py:136). */ export interface ObservabilityHooksOptions { /** Whether observability is enabled (default true). */ enabled?: boolean; } /** * Observability hooks for the escalation pipeline: event emission, metrics * collection, custom handler registration, tracing support. * * Python parity: escalation/observability.py:116 `ObservabilityHooks`. * Observability is per-agent/per-pipeline (multi-agent safety): each * pipeline gets its own instance. * * @example * const hooks = new ObservabilityHooks(); * hooks.on(ObservabilityEventType.STAGE_ESCALATE, (e) => console.log(`Escalated to ${e.stage}`)); * const pipeline = new EscalationPipeline({ observability: hooks }); */ export declare class ObservabilityHooks { enabled: boolean; private handlers; private events; private metrics; private sessionId; private currentStage; private stepNumber; /** stage name -> seconds since the epoch */ private stageStartTimes; /** Python parity: observability.py:136 `__init__(enabled=True)`. */ constructor(options?: ObservabilityHooksOptions); /** Register an event handler. Python parity: observability.py:154 `on(event_type, handler)`. */ on(eventType: ObservabilityEventType, handler: ObservabilityHandler): void; /** Unregister an event handler. Python parity: observability.py:164 `off(event_type, handler)`. */ off(eventType: ObservabilityEventType, handler: ObservabilityHandler): void; /** * Emit an event. * * Python parity: observability.py:175 `emit(event_type, data=None, duration_ms=None)`. */ emit(eventType: ObservabilityEventType, data?: Record | null, durationMs?: number | null): void; /** Python parity: observability.py:207 `_update_metrics`. */ private updateMetrics; /** Python parity: observability.py:226 `set_session(session_id)`. */ setSession(sessionId: string): void; /** Python parity: observability.py:230 `set_stage(stage)` (tracks per-stage timing). */ setStage(stage: EscalationStage): void; /** Python parity: observability.py:247 `increment_step`. */ incrementStep(): void; /** Python parity: observability.py:251 `add_tokens(count)`. */ addTokens(count: number): void; /** Python parity: observability.py:255 `get_events` (a copy). */ getEvents(): ObservabilityEvent[]; /** Python parity: observability.py:259 `get_metrics`. */ getMetrics(): ExecutionMetrics; /** Python parity: observability.py:263 `reset`. */ reset(): void; /** Python parity: observability.py:272 `start_execution(session_id=None)`. */ startExecution(sessionId?: string | null): void; /** Python parity: observability.py:279 `end_execution(duration_ms)`. */ endExecution(durationMs: number): void; /** Python parity: observability.py:284 `get_summary`. */ getSummary(): Record; private handlersFor; }