"""
InsAIts SDK - Persistence Engine (Phase 3.6-3.11)
===================================================
Intelligent escalation when agents surrender, loop, or go NPC.

This is a facade: full implementation lives in premium/_persistence_core.py.
Open-source stub always returns level=0 (no escalation).

Author: InsAIts SDK
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import Dict, Optional, Set, Tuple

# ---------------------------------------------------------------------------
# Public constants (always available, not premium-gated)
# ---------------------------------------------------------------------------

LEVEL_NUDGE = 1
LEVEL_REDIRECT = 2
LEVEL_DECOMPOSE = 3
LEVEL_ESCALATE = 4
LEVEL_CIRCUIT_BREAK = 5

MAX_LEVEL = LEVEL_CIRCUIT_BREAK

RESET_TIMEOUT_SECONDS = 600  # 10 minutes
TOOLS_TRIED_BACKOFF_THRESHOLD = 3
STEALTH_VISIBLE_THRESHOLD = LEVEL_ESCALATE  # level 4+


# ---------------------------------------------------------------------------
# Public data class (always available, not premium-gated)
# ---------------------------------------------------------------------------

@dataclass(frozen=True)
class EscalationAction:
    """Result of a persistence engine escalation decision.

    Attributes:
        level: Escalation level 1-5.
        message: Intervention text for the agent.
        should_output: Whether to write to stdout (stealth-aware).
        should_log: Whether to write to the audit log (always True).
        should_circuit_break: True only at level 5.
    """

    level: int
    message: str
    should_output: bool
    should_log: bool
    should_circuit_break: bool


# ---------------------------------------------------------------------------
# PersistenceEngine: premium or stub
# ---------------------------------------------------------------------------

try:
    from insa_its.premium._persistence_core import PersistenceEngine  # noqa: F401
except ImportError:

    class PersistenceEngine:  # type: ignore[no-redef]
        """Open-source stub: always returns level=0 (no escalation).

        Same interface as the premium PersistenceEngine but performs
        no tracking or escalation logic.
        """

        def __init__(self, stealth: bool = False) -> None:
            self._stealth = stealth

        def record_failure(
            self,
            agent_id: str,
            task_context: str,
            error_type: Optional[str] = None,
            tool_name: Optional[str] = None,
        ) -> EscalationAction:
            """Stub: returns level 0, no escalation."""
            return EscalationAction(
                level=0,
                message="",
                should_output=False,
                should_log=False,
                should_circuit_break=False,
            )

        def get_escalation_level(
            self, agent_id: str, task_context: str,
        ) -> int:
            """Stub: always returns 0."""
            return 0

        def get_intervention_message(
            self, level: int, task_context: Optional[str] = None,
        ) -> str:
            """Stub: returns empty string."""
            return ""

        def reset(
            self, agent_id: str, task_context: Optional[str] = None,
        ) -> None:
            """Stub: no-op."""
            pass

        def should_back_off(
            self, agent_id: str, task_context: str,
        ) -> bool:
            """Stub: always returns False."""
            return False


__all__ = [
    "LEVEL_NUDGE",
    "LEVEL_REDIRECT",
    "LEVEL_DECOMPOSE",
    "LEVEL_ESCALATE",
    "LEVEL_CIRCUIT_BREAK",
    "MAX_LEVEL",
    "RESET_TIMEOUT_SECONDS",
    "TOOLS_TRIED_BACKOFF_THRESHOLD",
    "STEALTH_VISIBLE_THRESHOLD",
    "EscalationAction",
    "PersistenceEngine",
]
