PraisonAI 4.6.83__tar.gz → 4.6.95__tar.gz

{praisonai-4.6.83 → praisonai-4.6.95}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PraisonAI
-Version: 4.6.83
+Version: 4.6.95
 Summary: PraisonAI is an AI Agents Framework with Self Reflection. PraisonAI application combines PraisonAI Agents, AutoGen, and CrewAI into a low-code solution for building and managing multi-agent LLM systems, focusing on simplicity, customisation, and efficient human-agent collaboration.
 Author: Mervin Praison
 License: MIT
@@ -11,7 +11,7 @@ Description-Content-Type: text/markdown
 Requires-Dist: rich>=13.7
 Requires-Dist: markdown>=3.5
 Requires-Dist: pyparsing>=3.0.0
-Requires-Dist: praisonaiagents>=1.6.90
+Requires-Dist: praisonaiagents>=1.6.95
 Requires-Dist: python-dotenv>=0.19.0
 Requires-Dist: litellm<2,>=1.83.14
 Requires-Dist: PyYAML>=6.0
@@ -93,6 +93,15 @@ Requires-Dist: autogen-ext[openai]>=0.4.0; extra == "autogen-v4"
 Requires-Dist: autogen-core>=0.4.0; extra == "autogen-v4"
 Requires-Dist: praisonai-tools>=0.1.0; extra == "autogen-v4"
 Requires-Dist: crewai; extra == "autogen-v4"
+Provides-Extra: langgraph
+Requires-Dist: langgraph<2,>=0.2.0; extra == "langgraph"
+Requires-Dist: langgraph-prebuilt<2,>=0.2.0; extra == "langgraph"
+Requires-Dist: langchain-core<2,>=0.3.0; extra == "langgraph"
+Requires-Dist: langchain-openai<2,>=0.2.0; extra == "langgraph"
+Requires-Dist: praisonai-tools>=0.1.0; extra == "langgraph"
+Provides-Extra: openai-agents
+Requires-Dist: praisonai-frameworks[openai-agents]>=0.1.3; extra == "openai-agents"
+Requires-Dist: praisonai-tools>=0.1.0; extra == "openai-agents"
 Provides-Extra: acp
 Requires-Dist: agent-client-protocol>=0.7.0; extra == "acp"
 Provides-Extra: flow

{praisonai-4.6.83 → praisonai-4.6.95}/PraisonAI.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PraisonAI
-Version: 4.6.83
+Version: 4.6.95
 Summary: PraisonAI is an AI Agents Framework with Self Reflection. PraisonAI application combines PraisonAI Agents, AutoGen, and CrewAI into a low-code solution for building and managing multi-agent LLM systems, focusing on simplicity, customisation, and efficient human-agent collaboration.
 Author: Mervin Praison
 License: MIT
@@ -11,7 +11,7 @@ Description-Content-Type: text/markdown
 Requires-Dist: rich>=13.7
 Requires-Dist: markdown>=3.5
 Requires-Dist: pyparsing>=3.0.0
-Requires-Dist: praisonaiagents>=1.6.90
+Requires-Dist: praisonaiagents>=1.6.95
 Requires-Dist: python-dotenv>=0.19.0
 Requires-Dist: litellm<2,>=1.83.14
 Requires-Dist: PyYAML>=6.0
@@ -93,6 +93,15 @@ Requires-Dist: autogen-ext[openai]>=0.4.0; extra == "autogen-v4"
 Requires-Dist: autogen-core>=0.4.0; extra == "autogen-v4"
 Requires-Dist: praisonai-tools>=0.1.0; extra == "autogen-v4"
 Requires-Dist: crewai; extra == "autogen-v4"
+Provides-Extra: langgraph
+Requires-Dist: langgraph<2,>=0.2.0; extra == "langgraph"
+Requires-Dist: langgraph-prebuilt<2,>=0.2.0; extra == "langgraph"
+Requires-Dist: langchain-core<2,>=0.3.0; extra == "langgraph"
+Requires-Dist: langchain-openai<2,>=0.2.0; extra == "langgraph"
+Requires-Dist: praisonai-tools>=0.1.0; extra == "langgraph"
+Provides-Extra: openai-agents
+Requires-Dist: praisonai-frameworks[openai-agents]>=0.1.3; extra == "openai-agents"
+Requires-Dist: praisonai-tools>=0.1.0; extra == "openai-agents"
 Provides-Extra: acp
 Requires-Dist: agent-client-protocol>=0.7.0; extra == "acp"
 Provides-Extra: flow

{praisonai-4.6.83 → praisonai-4.6.95}/PraisonAI.egg-info/SOURCES.txt

@@ -65,11 +65,11 @@ praisonai/bots/_admission.py
 praisonai/bots/_approval.py
 praisonai/bots/_approval_base.py
 praisonai/bots/_approval_store.py
-praisonai/bots/_auth.py
 praisonai/bots/_chunk.py
 praisonai/bots/_commands.py
 praisonai/bots/_config_schema.py
 praisonai/bots/_correlation.py
+praisonai/bots/_dead_targets.py
 praisonai/bots/_debounce.py
 praisonai/bots/_defaults.py
 praisonai/bots/_delivery.py
@@ -89,10 +89,12 @@ praisonai/bots/_outbound_resilience.py
 praisonai/bots/_outbox.py
 praisonai/bots/_pairing_ui.py
 praisonai/bots/_presentation_approval.py
+praisonai/bots/_presentation_approval_backend.py
 praisonai/bots/_presentation_renderer.py
 praisonai/bots/_protocol_mixin.py
 praisonai/bots/_rate_limit.py
 praisonai/bots/_registry.py
+praisonai/bots/_relay_adapter.py
 praisonai/bots/_reset_policy.py
 praisonai/bots/_resilience.py
 praisonai/bots/_run_control.py
@@ -548,6 +550,7 @@ praisonai/flow/components/__init__.py
 praisonai/flow/components/PraisonAI/praisonai_agent.py
 praisonai/flow/components/PraisonAI/praisonai_agents.py
 praisonai/framework_adapters/__init__.py
+praisonai/framework_adapters/_config_builder.py
 praisonai/framework_adapters/autogen_adapter.py
 praisonai/framework_adapters/base.py
 praisonai/framework_adapters/crewai_adapter.py

{praisonai-4.6.83 → praisonai-4.6.95}/PraisonAI.egg-info/requires.txt

@@ -1,7 +1,7 @@
 rich>=13.7
 markdown>=3.5
 pyparsing>=3.0.0
-praisonaiagents>=1.6.90
+praisonaiagents>=1.6.95
 python-dotenv>=0.19.0
 litellm<2,>=1.83.14
 PyYAML>=6.0
@@ -156,6 +156,13 @@ langextract>=1.0.0
 [langfuse]
 langfuse>=3.0.0
 
+[langgraph]
+langgraph<2,>=0.2.0
+langgraph-prebuilt<2,>=0.2.0
+langchain-core<2,>=0.3.0
+langchain-openai<2,>=0.2.0
+praisonai-tools>=0.1.0
+
 [lite]
 
 [modal]
@@ -173,6 +180,10 @@ psycopg2-binary>=2.9.0
 [observability]
 langfuse>=3.0.0
 
+[openai-agents]
+praisonai-frameworks[openai-agents]>=0.1.3
+praisonai-tools>=0.1.0
+
 [os]
 fastapi>=0.115.0
 uvicorn>=0.34.0

{praisonai-4.6.83 → praisonai-4.6.95}/praisonai/_framework_availability.py

@@ -20,6 +20,29 @@ def _autogen_v4_probe() -> bool:
     return (importlib.util.find_spec("autogen_agentchat") is not None
             and importlib.util.find_spec("autogen_ext") is not None)
 
+def _langgraph_probe() -> bool:
+    # find_spec on a submodule imports the parent package; guard against
+    # import-time errors in langgraph/its deps crashing the availability check.
+    try:
+        if importlib.util.find_spec("langgraph") is None:
+            return False
+        return importlib.util.find_spec("langgraph.prebuilt") is not None
+    except Exception:
+        return False
+
+def _openai_agents_probe() -> bool:
+    try:
+        importlib.metadata.distribution("openai-agents")
+    except importlib.metadata.PackageNotFoundError:
+        return False
+    if importlib.util.find_spec("agents") is None:
+        return False
+    try:
+        from agents import Runner  # noqa: F401
+        return True
+    except ImportError:
+        return False
+
 _PROBES: dict[str, Callable[[], bool]] = {
     "crewai":            lambda: importlib.util.find_spec("crewai") is not None,
     "autogen":           lambda: importlib.util.find_spec("autogen") is not None,
@@ -40,6 +63,8 @@ _PROBES: dict[str, Callable[[], bool]] = {
     "pinecone":          lambda: importlib.util.find_spec("pinecone") is not None,
     "qdrant_client":     lambda: importlib.util.find_spec("qdrant_client") is not None,
     "weaviate":          lambda: importlib.util.find_spec("weaviate") is not None,
+    "langgraph":         _langgraph_probe,
+    "openai_agents":     _openai_agents_probe,
 }
 
 def is_available(name: str) -> bool:

{praisonai-4.6.83 → praisonai-4.6.95}/praisonai/agents_generator.py

@@ -80,10 +80,6 @@ def __dir__():
 
 
 
-_TOOL_TIMEOUT_EXECUTOR = None
-# Eagerly initialised so concurrent first-callers always share one lock (and
-# therefore one executor); a lazily-created lock would itself race.
-_TOOL_TIMEOUT_EXECUTOR_LOCK = threading.Lock()
 _DEFAULT_TOOL_TIMEOUT_WORKERS = 32
 
 
@@ -113,33 +109,15 @@ def _resolve_tool_timeout_workers():
     return workers
 
 
-def _get_tool_timeout_executor():
-    """Lazily create a bounded, observable thread pool for sync tool timeouts.
-
-    Using a bounded pool (instead of unbounded bare daemon threads) means any
-    background work left running after a timeout is at least capped and named,
-    so operators can enumerate it rather than accumulating phantom threads.
-    """
-    global _TOOL_TIMEOUT_EXECUTOR
-    import concurrent.futures
-
-    with _TOOL_TIMEOUT_EXECUTOR_LOCK:
-        if _TOOL_TIMEOUT_EXECUTOR is None:
-            _TOOL_TIMEOUT_EXECUTOR = concurrent.futures.ThreadPoolExecutor(
-                max_workers=_resolve_tool_timeout_workers(),
-                thread_name_prefix="praisonai-tool-timeout",
-            )
-    return _TOOL_TIMEOUT_EXECUTOR
-
-
-def _wrap_with_timeout(tool, timeout_seconds: float):
+def _wrap_with_timeout(tool, timeout_seconds: float, executor_factory):
     """Enforce a per-call timeout on a tool, sync or async.
 
     For async tools the underlying task is cancelled on timeout. For sync tools
-    the call runs in a bounded thread pool; on timeout we best-effort cancel the
-    future and log a warning. Note: a synchronous call that has already started
-    cannot be forcibly interrupted, so background work may continue executing —
-    the returned payload flags this with ``background_work_may_continue``.
+    the call runs in an instance-owned bounded thread pool obtained from
+    ``executor_factory``; on timeout we best-effort cancel the future and log a
+    warning. Note: a synchronous call that has already started cannot be forcibly
+    interrupted, so background work may continue executing — the returned payload
+    flags this with ``background_work_may_continue``.
     """
     if timeout_seconds is None or timeout_seconds <= 0 or not callable(tool):
         return tool
@@ -165,7 +143,7 @@ def _wrap_with_timeout(tool, timeout_seconds: float):
 
     @functools.wraps(tool)
     def _sync_wrapped(*args, **kwargs):
-        executor = _get_tool_timeout_executor()
+        executor = executor_factory()
         future = executor.submit(tool, *args, **kwargs)
         try:
             return future.result(timeout=timeout_seconds)
@@ -235,7 +213,7 @@ def _resolve_yaml_cli_backend(cli_backend_config, logger):
 
 
 class AgentsGenerator:
-    def __init__(self, agent_file, framework, config_list, log_level=None, agent_callback=None, task_callback=None, agent_yaml=None, tools=None, cli_config=None, adapter_registry=None):
+    def __init__(self, agent_file, framework, config_list, log_level=None, agent_callback=None, task_callback=None, agent_yaml=None, tools=None, cli_config=None, adapter_registry=None, tool_timeout_executor=None):
         """
         Initialize the AgentsGenerator object.
 
@@ -289,11 +267,56 @@ class AgentsGenerator:
         # DI-friendly: tests/multi-tenant runtimes pass their own registry;
         # CLI users get the process default.
         self._adapter_registry = adapter_registry or _get_default_adapter_registry()
+
+        # Instance-owned tool-timeout executor so multi-tenant runtimes can scope
+        # it per session (no process-wide singleton). Created lazily on first use
+        # to avoid spawning threads for generators that never time a sync tool.
+        # A caller-supplied executor is treated as borrowed and never shut down.
+        self._tool_timeout_executor = tool_timeout_executor
+        self._owns_tool_timeout_executor = tool_timeout_executor is None
+        self._tool_timeout_executor_lock = threading.Lock()
         
         # Defer framework adapter creation until YAML is loaded
         # This fixes the issue where empty framework string fails before YAML framework is read
         self.framework_adapter = None
 
+    def _get_tool_timeout_executor(self):
+        """Lazily create this generator's bounded sync-tool-timeout thread pool.
+
+        The pool is owned by the instance (not a module global), so concurrent
+        sessions / tenants never share workers and a stuck tool in one session
+        cannot starve another.
+        """
+        import concurrent.futures
+
+        with self._tool_timeout_executor_lock:
+            if self._tool_timeout_executor is None:
+                self._tool_timeout_executor = concurrent.futures.ThreadPoolExecutor(
+                    max_workers=_resolve_tool_timeout_workers(),
+                    thread_name_prefix=f"praisonai-tool-timeout-{id(self):x}",
+                )
+            # Capture the reference inside the lock so a concurrent close() can
+            # never null the attribute out between the check and the return.
+            return self._tool_timeout_executor
+
+    def _wrap_tool_with_timeout(self, tool, timeout_seconds):
+        """Wrap a tool with this generator's instance-owned timeout executor."""
+        return _wrap_with_timeout(tool, timeout_seconds, self._get_tool_timeout_executor)
+
+    def close(self):
+        """Release the owned tool-timeout executor; safe to call repeatedly."""
+        with self._tool_timeout_executor_lock:
+            if self._owns_tool_timeout_executor and self._tool_timeout_executor is not None:
+                self._tool_timeout_executor.shutdown(wait=False, cancel_futures=True)
+                self._tool_timeout_executor = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self.close()
+        return False
+
     def _get_framework_adapter(self, framework: str) -> FrameworkAdapter:
         """
         Get the appropriate framework adapter for the given framework.
@@ -339,6 +362,21 @@ class AgentsGenerator:
         # Handle agent-level overrides using unified approach
         agent_level_fields = ['tool_timeout', 'tool_retry_policy', 'planning_tools', 'autonomy', 'planning', 'web', 'web_fetch']
         agent_overrides = {k: v for k, v in cli_config.items() if k in agent_level_fields}
+
+        if "tool_retry_policy" in agent_overrides:
+            policy = agent_overrides["tool_retry_policy"]
+            try:
+                from praisonaiagents.tools.retry import RetryPolicy
+
+                if isinstance(policy, RetryPolicy):
+                    agent_overrides["tool_retry_policy"] = {
+                        "max_attempts": policy.max_attempts,
+                        "delay": policy.initial_delay_ms / 1000.0,
+                        "backoff_factor": policy.backoff_factor,
+                        "max_delay": policy.max_delay_ms / 1000.0,
+                    }
+            except (ImportError, AttributeError, TypeError):
+                pass
         
         # Handle handoff configuration - convert CLI flags into handoff dict
         handoff_fields = ['handoff', 'handoff_policy', 'handoff_timeout', 'handoff_max_depth', 'handoff_max_concurrent', 'handoff_detect_cycles']

{praisonai-4.6.83 → praisonai-4.6.95}/praisonai/bots/__init__.py

@@ -20,12 +20,14 @@ if TYPE_CHECKING:
     from ._session import BotSessionManager
     from ._identity import StoreBackedIdentityResolver
     from ._dlq import InboundDLQ, DLQEntry
+    from ._dead_targets import DeadTargetRegistry, DeadTarget
     from ._ingress import InboundJournal, JournalEntry
     from ._slack_approval import SlackApproval
     from ._telegram_approval import TelegramApproval
     from ._discord_approval import DiscordApproval
     from ._webhook_approval import WebhookApproval
     from ._http_approval import HTTPApproval
+    from ._presentation_approval_backend import PresentationApprovalBackend
     from ._streaming import StreamingConfig, StreamingMode, DraftStreamer
     from ._outbox import OutboundQueue, OutboundEntry
     from ._approval_store import ApprovalStore
@@ -85,6 +87,9 @@ def __getattr__(name: str):
     if name == "HTTPApproval":
         from ._http_approval import HTTPApproval
         return HTTPApproval
+    if name == "PresentationApprovalBackend":
+        from ._presentation_approval_backend import PresentationApprovalBackend
+        return PresentationApprovalBackend
     # W1 — cross-platform mirror + identity
     if name == "mirror_to_session":
         from ._mirror import mirror_to_session
@@ -102,6 +107,13 @@ def __getattr__(name: str):
     if name == "DLQEntry":
         from ._dlq import DLQEntry
         return DLQEntry
+    # Self-healing dead-target registry (issue #2486)
+    if name == "DeadTargetRegistry":
+        from ._dead_targets import DeadTargetRegistry
+        return DeadTargetRegistry
+    if name == "DeadTarget":
+        from ._dead_targets import DeadTarget
+        return DeadTarget
     # Inbound message journal for durable processing
     if name == "InboundJournal":
         from ._ingress import InboundJournal
@@ -172,6 +184,7 @@ __all__ = [
     "BotSessionManager",
     "StoreBackedIdentityResolver",
     "InboundDLQ", "DLQEntry",
+    "DeadTargetRegistry", "DeadTarget",
     "InboundJournal", "JournalEntry",
     "OutboundQueue", "OutboundEntry",
     "ApprovalStore",
@@ -184,6 +197,7 @@ __all__ = [
     "use_correlation_id", "GatewayMetrics",
     "SlackApproval", "TelegramApproval", "DiscordApproval",
     "WebhookApproval", "HTTPApproval",
+    "PresentationApprovalBackend",
     # Streaming
     "StreamingConfig", "StreamingMode", "DraftStreamer",
     # W1

praisonai-4.6.95/praisonai/bots/_dead_targets.py

@@ -0,0 +1,274 @@
+"""
+Self-healing dead-target registry for outbound delivery (issue #2486).
+
+When a gateway delivers to a channel that has become *permanently* unreachable
+— the bot was kicked/blocked, the group was deleted, the chat no longer exists
+— there is otherwise no memory of that. Every subsequent proactive, scheduled
+or broadcast send re-attempts the dead target from scratch: a fresh API call, a
+fresh failure, and a fresh stack of log lines. For a long-lived gateway pushing
+periodic updates to many channels this quietly burns rate-limit budget, slows
+fan-out (every cycle waits on doomed calls), and floods logs with noise.
+
+This module provides a small, bounded, **self-healing** registry:
+  - record a ``(platform, channel_id)`` as dead only on a *confirmed permanent*
+    failure (e.g. ``403 Forbidden``, ``404``/"chat not found"),
+  - short-circuit future sends to it (consulted by ``DeliveryRouter.deliver``),
+  - **automatically clear** the flag the moment any send to that target
+    succeeds again (user re-adds the bot, group is restored).
+
+Design constraints (per PraisonAI principles):
+  - Wrapper-only — heavy code stays out of the core SDK.
+  - Lazy/stdlib only — JSON + atomic file replace, no extra dependency.
+  - Default OFF — ``DeliveryRouter`` works exactly as before unless a registry
+    is constructed and attached.
+  - Bounded: ``max_size`` + ``ttl_seconds`` prevent unbounded growth/staleness.
+  - Thread-safe: a per-instance ``threading.Lock`` guards mutation + persistence.
+  - Persistence is best-effort: failures are logged, never raised.
+
+Public API:
+  - ``DeadTargetRegistry(persist_path=None, *, max_size=10_000, ttl_seconds=...)``
+  - ``is_dead(platform, channel_id) -> bool``
+  - ``should_reprobe(platform, channel_id) -> bool``  (periodic self-heal probe)
+  - ``mark_dead(platform, channel_id, reason) -> None``
+  - ``clear(platform, channel_id) -> None``  (called on every success)
+  - ``list_dead() -> list[DeadTarget]``
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+# 30 days default — a kicked bot is rarely re-added within seconds, but we still
+# want the registry to forget very old entries so a target that was dead long
+# ago is re-probed eventually even if no traffic ever cleared it.
+_DEFAULT_TTL_SECONDS = 30 * 86400
+_DEFAULT_MAX_SIZE = 10_000
+# How long to fully suppress a dead target before allowing a single re-probe.
+# A kicked bot is rarely re-added within seconds, but waiting the full 30-day
+# TTL to retry a *recovered* target is far too long. Letting one send through
+# roughly once an hour bounds self-heal latency to ~1h while still suppressing
+# the overwhelming majority of doomed cycles.
+_DEFAULT_REPROBE_SECONDS = 3600
+
+
+@dataclass(frozen=True)
+class DeadTarget:
+    """A single target confirmed permanently unreachable."""
+
+    platform: str
+    channel_id: str
+    reason: str
+    ts: float
+
+
+class DeadTargetRegistry:
+    """Persistent, bounded, self-healing registry of dead delivery targets.
+
+    Args:
+        persist_path: JSON file path for durability. Defaults to
+            ``~/.praisonai/state/dead_targets.json``. Pass ``None`` explicitly
+            via ``persist=False`` semantics is not supported; use a temp path
+            for ephemeral instances in tests.
+        max_size: Maximum dead entries kept; oldest evicted when exceeded.
+        ttl_seconds: Entries older than this are dropped on the next access so
+            a long-dead target is eventually re-probed.
+
+    Example::
+
+        from praisonai.bots import DeadTargetRegistry
+
+        reg = DeadTargetRegistry()
+        if reg.is_dead("telegram", "-1001234"):
+            ...  # short-circuit
+        reg.mark_dead("telegram", "-1001234", reason="403 Forbidden: bot kicked")
+        reg.clear("telegram", "-1001234")  # on next successful send
+    """
+
+    def __init__(
+        self,
+        persist_path: Optional[Path] = None,
+        *,
+        max_size: int = _DEFAULT_MAX_SIZE,
+        ttl_seconds: int = _DEFAULT_TTL_SECONDS,
+        reprobe_seconds: int = _DEFAULT_REPROBE_SECONDS,
+    ) -> None:
+        state_dir = Path.home() / ".praisonai" / "state"
+        self._persist_path = Path(
+            persist_path or (state_dir / "dead_targets.json")
+        ).expanduser()
+        self.max_size = int(max_size)
+        self.ttl_seconds = int(ttl_seconds)
+        self.reprobe_seconds = int(reprobe_seconds)
+        self._lock = threading.Lock()
+        # (platform, channel_id) -> DeadTarget
+        self._dead: Dict[Tuple[str, str], DeadTarget] = {}
+        self._load()
+
+    # ── Helpers ─────────────────────────────────────────────────────
+    @staticmethod
+    def _key(platform: str, channel_id: str) -> Tuple[str, str]:
+        return (str(platform).lower(), str(channel_id))
+
+    def _evict_expired_locked(self) -> bool:
+        """Drop expired entries. Caller must hold the lock. Returns True if changed."""
+        if self.ttl_seconds <= 0:
+            return False
+        cutoff = time.time() - self.ttl_seconds
+        stale = [k for k, v in self._dead.items() if v.ts < cutoff]
+        for k in stale:
+            self._dead.pop(k, None)
+        return bool(stale)
+
+    def _enforce_bound_locked(self) -> None:
+        """Evict oldest entries beyond ``max_size``. Caller must hold the lock."""
+        if self.max_size <= 0 or len(self._dead) <= self.max_size:
+            return
+        # Oldest first by timestamp.
+        ordered = sorted(self._dead.items(), key=lambda kv: kv[1].ts)
+        overflow = len(self._dead) - self.max_size
+        for k, _ in ordered[:overflow]:
+            self._dead.pop(k, None)
+
+    # ── Persistence (best-effort, atomic) ───────────────────────────
+    def _load(self) -> None:
+        if not self._persist_path.exists():
+            return
+        try:
+            with open(self._persist_path, "r") as f:
+                data = json.load(f)
+        except Exception as e:
+            logger.warning("DeadTargetRegistry: failed to load %s: %s", self._persist_path, e)
+            return
+        entries = data.get("dead", []) if isinstance(data, dict) else []
+        if not isinstance(entries, list):
+            return
+        for item in entries:
+            try:
+                platform = str(item["platform"]).lower()
+                channel_id = str(item["channel_id"])
+                reason = str(item.get("reason", ""))
+                ts = float(item.get("ts", time.time()))
+            except (KeyError, TypeError, ValueError):
+                continue
+            self._dead[(platform, channel_id)] = DeadTarget(
+                platform=platform, channel_id=channel_id, reason=reason, ts=ts
+            )
+        # Prune anything already expired/over-bound on load.
+        self._evict_expired_locked()
+        self._enforce_bound_locked()
+        logger.info(
+            "DeadTargetRegistry: loaded %d dead target(s) from %s",
+            len(self._dead),
+            self._persist_path,
+        )
+
+    def _save_locked(self) -> None:
+        """Persist current state. Caller must hold the lock."""
+        try:
+            data = {
+                "dead": [
+                    {
+                        "platform": v.platform,
+                        "channel_id": v.channel_id,
+                        "reason": v.reason,
+                        "ts": v.ts,
+                    }
+                    for v in self._dead.values()
+                ]
+            }
+            self._persist_path.parent.mkdir(parents=True, exist_ok=True)
+            tmp_path = self._persist_path.with_suffix(self._persist_path.suffix + ".tmp")
+            with open(tmp_path, "w") as f:
+                json.dump(data, f, indent=2)
+            os.replace(tmp_path, self._persist_path)
+        except Exception as e:
+            logger.error("DeadTargetRegistry: failed to save %s: %s", self._persist_path, e)
+
+    # ── Public API ──────────────────────────────────────────────────
+    def is_dead(self, platform: str, channel_id: str) -> bool:
+        """Return True if the target is currently suppressed as dead."""
+        key = self._key(platform, channel_id)
+        with self._lock:
+            entry = self._dead.get(key)
+            if entry is None:
+                return False
+            # Honour TTL lazily so a long-dead target re-enters circulation.
+            if self.ttl_seconds > 0 and entry.ts < time.time() - self.ttl_seconds:
+                self._dead.pop(key, None)
+                self._save_locked()
+                return False
+            return True
+
+    def should_reprobe(self, platform: str, channel_id: str) -> bool:
+        """Return True if a dead target is due for a single self-healing re-probe.
+
+        A suppressed target can only prove it has recovered by being sent to, but
+        ``is_dead`` would otherwise block every send until the (long) TTL expires.
+        To bound self-heal latency, once ``reprobe_seconds`` has elapsed since the
+        target was last marked dead we allow *one* send through. If it succeeds,
+        :meth:`clear` un-suppresses it; if it fails permanently again,
+        :meth:`mark_dead` resets the clock for another ``reprobe_seconds`` window.
+        """
+        if self.reprobe_seconds <= 0:
+            return False
+        key = self._key(platform, channel_id)
+        with self._lock:
+            entry = self._dead.get(key)
+            if entry is None:
+                return False
+            return entry.ts < time.time() - self.reprobe_seconds
+
+    def mark_dead(self, platform: str, channel_id: str, reason: str) -> None:
+        """Record a confirmed-permanent failure, suppressing future sends."""
+        key = self._key(platform, channel_id)
+        with self._lock:
+            already = key in self._dead
+            self._dead[key] = DeadTarget(
+                platform=key[0], channel_id=key[1], reason=str(reason), ts=time.time()
+            )
+            self._enforce_bound_locked()
+            self._save_locked()
+        if not already:
+            logger.warning(
+                "DeadTargetRegistry: suppressing dead target %s:%s (%s)",
+                key[0],
+                key[1],
+                reason,
+            )
+
+    def clear(self, platform: str, channel_id: str) -> None:
+        """Un-suppress a target. Called on every successful send (self-healing)."""
+        key = self._key(platform, channel_id)
+        with self._lock:
+            if key not in self._dead:
+                return
+            self._dead.pop(key, None)
+            self._save_locked()
+        logger.info(
+            "DeadTargetRegistry: target %s:%s recovered — suppression cleared",
+            key[0],
+            key[1],
+        )
+
+    def list_dead(self) -> List[DeadTarget]:
+        """Return a snapshot of currently-dead targets (expired ones pruned)."""
+        with self._lock:
+            if self._evict_expired_locked():
+                self._save_locked()
+            return sorted(self._dead.values(), key=lambda d: d.ts)
+
+    def size(self) -> int:
+        """Number of currently-suppressed targets (expired ones pruned)."""
+        with self._lock:
+            if self._evict_expired_locked():
+                self._save_locked()
+            return len(self._dead)