/** * The error base: kinds, context protocol and `PraisonAIError`. * * Split out of `errors.ts` so a module that only throws (agent/handoff.ts, the * tool registry) does not drag the whole error module onto the agent's graph. * praisonai/mobile bundles that graph against a lazy-size budget, and the * subclasses plus the failover helpers are 11kB nothing there ever calls. * `errors.ts` re-exports everything here, so imports from it are unchanged. * * Python parity: praisonaiagents/errors.py. */ /** * Closed error taxonomy for typed failure classification. * Python parity: praisonaiagents/errors.py:18-22 (`AgentErrorKind`) */ export declare const AGENT_ERROR_KINDS: readonly ["auth", "auth_permanent", "rate_limit", "overloaded", "context_overflow", "idle_timeout", "billing", "model_not_found", "empty_response", "format_error", "unknown"]; /** Python parity: praisonaiagents/errors.py:18 (`AgentErrorKind` Literal). */ export type AgentErrorKind = (typeof AGENT_ERROR_KINDS)[number]; /** * Legacy error categories still accepted (with a deprecation warning) and * mapped onto the closed taxonomy. * Python parity: praisonaiagents/errors.py:25-32 (`LEGACY_ERROR_CATEGORY_MAP`) */ export declare const LEGACY_ERROR_CATEGORY_MAP: Readonly>; /** A legacy category name accepted by `resolveErrorCategory`. */ export type LegacyErrorCategory = keyof typeof LEGACY_ERROR_CATEGORY_MAP; /** Runtime check that a string is one of the closed `AgentErrorKind` values. */ export declare function isAgentErrorKind(value: unknown): value is AgentErrorKind; /** * Resolve a user-supplied error category to the closed taxonomy. * * Mirrors the branch in `PraisonAIError.__init__` * (praisonaiagents/errors.py:101-116): `undefined`/`null` -> "unknown", a * known kind passes through, a legacy name is mapped with a deprecation * warning, anything else throws. */ export declare function resolveErrorCategory(errorCategory?: string | null): AgentErrorKind; /** * Structured error context propagated by every PraisonAI error. * Python parity: praisonaiagents/errors.py:69-76 (`ErrorContextProtocol`) */ export interface ErrorContextProtocol { agentId: string; runId: string; isRetryable: boolean; errorCategory: AgentErrorKind; } /** * Structural check mirroring Python's `@runtime_checkable` protocol test * (`isinstance(obj, ErrorContextProtocol)`). */ export declare function isErrorContext(value: unknown): value is ErrorContextProtocol; /** * Keyword options of `PraisonAIError`. * Python parity: praisonaiagents/errors.py:87-95 (`PraisonAIError.__init__`) */ export interface PraisonAIErrorOptions { /** Identifier of the agent that raised the error. Default `"unknown"`. */ agentId?: string; /** Run identifier; a fresh UUID4 is generated when omitted. */ runId?: string; /** Closed taxonomy kind, or a legacy name (mapped with a warning). Default `"unknown"`. */ errorCategory?: AgentErrorKind | LegacyErrorCategory | string; /** Whether a retry may succeed. Default `false`. */ isRetryable?: boolean; /** Arbitrary structured metadata (snake_case keys, as in Python). */ context?: Record; } /** * Base error class with structured context for the PraisonAI SDK. * * All PraisonAI errors inherit from this to ensure uniform error handling, * context propagation and observability hooks. * Python parity: praisonaiagents/errors.py:79-122 (`PraisonAIError`) */ export declare class PraisonAIError extends Error implements ErrorContextProtocol { readonly agentId: string; readonly runId: string; readonly errorCategory: AgentErrorKind; readonly isRetryable: boolean; readonly context: Record; constructor(message: string, options?: PraisonAIErrorOptions); /** * Python parity: `PraisonAIError.__str__` * (`[category] message (agent: x, run: y)`). `message` itself stays raw. */ toString(): string; /** * Serialise the structured context. Keys are snake_case to match the * attribute names on the Python side. */ toDict(): Record; }