/** * Structured run outcome types for agent execution results. * * Python parity: * - praisonaiagents/run_outcome.py (`RunStatus`, `TerminationReason`, * `termination_to_run_status`, `AgentRunOutcome`, `validate_decision_string`) * - praisonaiagents/agent/run_outcome.py (`TerminalReason`, `RunOutcome`, * `classify_finish_reason`, `PROVIDER_BLOCK_REASONS`) * * Note on naming: Python's `run_outcome.RunStatus` is exported here as * `AgentRunStatus`. The existing `RunStatus` in `src/session/index.ts` * (`'pending' | 'running' | 'completed' | 'failed'`) describes a session run's * lifecycle, not a terminal outcome, so its values are incompatible and it is * not reused. */ /** * Closed status vocabulary for agent run outcomes. * Python parity: praisonaiagents/run_outcome.py:17-23 (`RunStatus`) */ export declare const AGENT_RUN_STATUSES: readonly ["success", "failure", "timeout", "cancelled", "invalid_output"]; /** Python parity: praisonaiagents/run_outcome.py:17 (`RunStatus` Literal). */ export type AgentRunStatus = (typeof AGENT_RUN_STATUSES)[number]; /** * Typed terminal reasons for an autonomous run. * * String values are identical to the free strings historically emitted by * `run_autonomous` so string-matching callers keep working * (`TerminationReason.GOAL_MET === 'goal'`). * Python parity: praisonaiagents/run_outcome.py:26-48 (`TerminationReason`) */ export declare enum TerminationReason { GOAL_MET = "goal", TOOL_COMPLETION = "tool_completion", PROMISE = "promise", NO_TOOL_CALLS = "no_tool_calls", MAX_ITERATIONS = "max_iterations", TIMEOUT = "timeout", BUDGET_EXHAUSTED = "budget_exhausted", DOOM_LOOP = "doom_loop", NEEDS_HELP = "needs_help", INTERRUPTED = "interrupted", CANCELLED = "cancelled", ERROR = "error" } /** * Map from `TerminationReason` value to the closed `AgentRunStatus` * vocabulary so autonomous runs and task validation share one terminal * terminology. * Python parity: praisonaiagents/run_outcome.py:53-66 (`_TERMINATION_TO_RUN_STATUS`) */ export declare const TERMINATION_TO_RUN_STATUS: Readonly>; /** * Map a `TerminationReason` (or its string value) to an `AgentRunStatus`. * Unknown reasons fall back to `"failure"`. * Python parity: praisonaiagents/run_outcome.py:69-75 (`termination_to_run_status`) */ export declare function terminationToRunStatus(reason: TerminationReason | string | unknown): AgentRunStatus; /** * Constructor fields of `AgentRunOutcome`. Only `status` is required. * Python parity: praisonaiagents/run_outcome.py:105-128 (dataclass fields) */ export interface AgentRunOutcomeInit { /** Typed status discriminant - exhaustively matchable. */ status: AgentRunStatus; /** Successful execution output or partial result. */ output?: string; /** Error message for non-successful outcomes. */ error?: string; /** Error category from `PraisonAIError.errorCategory` if applicable. */ errorCategory?: string; /** Execution duration in seconds. Default `0`. */ elapsedS?: number; /** Name of the agent that produced this outcome. */ agentName?: string; /** Unique identifier for this execution run. */ runId?: string; /** Additional structured metadata. */ context?: Record; } /** * Common keyword options shared by the `AgentRunOutcome` factories. * Python parity: praisonaiagents/run_outcome.py:165-268 (classmethod kwargs) */ export interface AgentRunOutcomeOptions { /** Execution duration in seconds. Default `0`. */ elapsedS?: number; agentName?: string; runId?: string; context?: Record; } /** `AgentRunOutcome.failure` additionally accepts an error category. */ export interface AgentRunOutcomeFailureOptions extends AgentRunOutcomeOptions { errorCategory?: string; } /** * Structured outcome for agent execution, validation and handoff operations. * * Replaces freeform string parsing with typed status values that callers can * match exhaustively, plus structured metadata for debugging and retry * policies. * Python parity: praisonaiagents/run_outcome.py:78-268 (`AgentRunOutcome`) */ export declare class AgentRunOutcome { readonly status: AgentRunStatus; readonly output?: string; readonly error?: string; readonly errorCategory?: string; readonly elapsedS: number; readonly agentName?: string; readonly runId?: string; readonly context?: Record; constructor(init: AgentRunOutcomeInit); /** Check if the outcome represents successful completion. */ isSuccess(): boolean; /** Check if the outcome represents any kind of failure. */ isFailure(): boolean; /** * Check if this outcome represents a potentially retryable failure: * `timeout` and `invalid_output` are; `failure` and `cancelled` are not. */ isRetryable(): boolean; /** * Convert to a plain object for serialisation or logging. Keys are * snake_case to match Python's `to_dict()`; absent optionals are `null`. */ toDict(): Record; /** Create a successful outcome. Python parity: `AgentRunOutcome.success`. */ static success(output: string, options?: AgentRunOutcomeOptions): AgentRunOutcome; /** Create a general failure outcome. Python parity: `AgentRunOutcome.failure`. */ static failure(error: string, options?: AgentRunOutcomeFailureOptions): AgentRunOutcome; /** Create a timeout outcome. Python parity: `AgentRunOutcome.timeout`. */ static timeout(error?: string, options?: AgentRunOutcomeOptions): AgentRunOutcome; /** Create a cancelled outcome. Python parity: `AgentRunOutcome.cancelled`. */ static cancelled(error?: string, options?: AgentRunOutcomeOptions): AgentRunOutcome; /** Create an invalid-output outcome. Python parity: `AgentRunOutcome.invalid_output`. */ static invalidOutput(error: string, options?: AgentRunOutcomeOptions): AgentRunOutcome; } /** * Convert a legacy validation decision string to a typed `AgentRunStatus`. * * `null`/`undefined` -> `"failure"`; a non-string throws a `TypeError`; * matching is case-insensitive after trimming; unknown strings are treated as * a general `"failure"`. * Python parity: praisonaiagents/run_outcome.py:275-316 (`validate_decision_string`) */ export declare function validateDecisionString(decisionStr: string | null | undefined): AgentRunStatus; /** * Closed description of how an agent run ended. * Python parity: praisonaiagents/agent/run_outcome.py:20-29 (`TerminalReason`) */ export type TerminalReason = 'completed' | 'hard_timeout' | 'cancelled' | 'aborted' | 'failed' | 'content_filtered' | 'refused' | 'length_truncated'; /** * Provider-side terminal reasons derived from the LLM `finish_reason`/refusal * signal. * Python parity: praisonaiagents/agent/run_outcome.py:36 (`PROVIDER_BLOCK_REASONS`) */ export declare const PROVIDER_BLOCK_REASONS: readonly TerminalReason[]; /** * Precedence of terminal reasons: higher wins and is sticky (a hard timeout * is never downgraded by later cleanup). * Python parity: praisonaiagents/agent/run_outcome.py:42-51 (`_REASON_PRECEDENCE`) */ export declare const TERMINAL_REASON_PRECEDENCE: Readonly>; /** * Constructor fields of `RunOutcome`. * Python parity: praisonaiagents/agent/run_outcome.py:65-67 */ export interface RunOutcomeInit { reason: TerminalReason; /** Partial or final text, if any. */ output?: string; /** Redacted message when `reason === "failed"`. */ error?: string; } /** * Closed, canonical description of how an agent run ended. Instances are * frozen (Python: `@dataclass(frozen=True)`). * Python parity: praisonaiagents/agent/run_outcome.py:55-117 (`RunOutcome`) */ export declare class RunOutcome { readonly reason: TerminalReason; readonly output?: string; readonly error?: string; constructor(init: RunOutcomeInit); /** True only when the run completed normally. */ get succeeded(): boolean; /** Python parity: `RunOutcome.completed`. */ static completed(output?: string): RunOutcome; /** * Normalise a thrown value into a canonical terminal outcome. * * Maps well-known error types (by class/`name` substring) to their terminal * reason; anything unrecognised is `"failed"` with the error's message. * `AbortError` (the JS analogue of `asyncio.CancelledError`) is * `"cancelled"`. * Python parity: praisonaiagents/agent/run_outcome.py:86-117 (`RunOutcome.from_exception`) */ static fromException(exc: unknown, output?: string): RunOutcome; } /** * Map a provider `finish_reason`/refusal signal to a terminal reason. * * Returns `content_filtered | refused | length_truncated` when the provider * blocked/refused/truncated the turn, or `undefined` for a normal stop * (`undefined`/`"stop"`) or any unrecognised value. * Python parity: praisonaiagents/agent/run_outcome.py:125-146 (`classify_finish_reason`) */ export declare function classifyFinishReason(finishReason: string | null | undefined, refusal?: unknown): TerminalReason | undefined; /** * How a run ended, in order of increasing attribution strength. `merge` may * only refine toward a stronger kind; it never downgrades. * Python parity: praisonaiagents/run_outcome.py:335 (`TerminalKind`) */ export type TerminalKind = 'ok' | 'failed' | 'timeout' | 'aborted'; /** * What observed the run ending. * Python parity: praisonaiagents/run_outcome.py:338-345 (`TerminalSource`) */ export type TerminalSource = 'completion' | 'idle' | 'run_budget' | 'external' | 'provider' | 'superseded'; /** * Constructor fields of `RunTerminal`. * Python parity: praisonaiagents/run_outcome.py:380-382 (dataclass fields) */ export interface RunTerminalInit { kind: TerminalKind; source: TerminalSource; detail?: string; } /** * One authoritative way a run ended — a closed discriminated union. * * `kind` is the collapsed terminal category; `source` records which observer * produced it (used to decide stickiness). Instances are frozen so a recorded * outcome is immutable — refinement happens by producing a new instance via * {@link mergeRunTerminal}, never by mutation (Python: `@dataclass(frozen=True)`). * Python parity: praisonaiagents/run_outcome.py:370-395 (`RunTerminal`) */ export declare class RunTerminal { readonly kind: TerminalKind; readonly source: TerminalSource; readonly detail?: string; constructor(init: RunTerminalInit); /** * Serialise to a plain object (JSON friendly, round-trippable). Keys match * Python's `to_dict()`; an absent `detail` is `null`. */ toDict(): { kind: TerminalKind; source: TerminalSource; detail: string | null; }; /** Rehydrate from a plain object produced by {@link toDict}. */ static fromDict(data: { kind: TerminalKind; source: TerminalSource; detail?: string | null; }): RunTerminal; } /** * Whether `outcome` can never be overwritten by a later observation. * * Deliberate cancellations (`external`), hard run-budget timeouts * (`run_budget`), and supersedes (`superseded`) are intentional terminals: * once recorded they are authoritative. * Python parity: praisonaiagents/run_outcome.py:398-405 (`is_sticky`) */ export declare function isSticky(outcome: RunTerminal): boolean; /** * Fold a newly-observed terminal into the current one (refine-only). * * Pure, deterministic and order-independent: folding the same set of * observations always yields the same authoritative outcome regardless of the * sequence in which they arrive. A later, weaker observation never overwrites * a stronger one, and a sticky terminal always wins over an equally-ranked * non-sticky one no matter which was observed first. * Python parity: praisonaiagents/run_outcome.py:408-444 (`merge_run_terminal`) */ export declare function mergeRunTerminal(current: RunTerminal | null | undefined, observed: RunTerminal): RunTerminal; /** * Project a `RunTerminal` onto the existing `AgentRunStatus` vocabulary. * * Collapses to exactly one of `success`/`timeout`/`cancelled`/`failure` for * all downstream consumers. * Python parity: praisonaiagents/run_outcome.py:447-453 (`collapse`) */ export declare function collapse(outcome: RunTerminal): AgentRunStatus;