PraisonAI 4.6.55__tar.gz → 4.6.57__tar.gz

{praisonai-4.6.55 → praisonai-4.6.57}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PraisonAI
-Version: 4.6.55
+Version: 4.6.57
 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.55
+Requires-Dist: praisonaiagents>=1.6.57
 Requires-Dist: python-dotenv>=0.19.0
 Requires-Dist: litellm<2,>=1.83.14
 Requires-Dist: PyYAML>=6.0

{praisonai-4.6.55 → praisonai-4.6.57}/PraisonAI.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PraisonAI
-Version: 4.6.55
+Version: 4.6.57
 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.55
+Requires-Dist: praisonaiagents>=1.6.57
 Requires-Dist: python-dotenv>=0.19.0
 Requires-Dist: litellm<2,>=1.83.14
 Requires-Dist: PyYAML>=6.0

{praisonai-4.6.55 → praisonai-4.6.57}/PraisonAI.egg-info/SOURCES.txt

@@ -20,7 +20,6 @@ praisonai/agent_scheduler.py
 praisonai/agents_generator.py
 praisonai/async_agent_scheduler.py
 praisonai/auto.py
-praisonai/deploy.py
 praisonai/profiler.py
 praisonai/setup.py
 praisonai/test.py
@@ -73,6 +72,7 @@ praisonai/bots/_discord_approval.py
 praisonai/bots/_dlq.py
 praisonai/bots/_email_utils.py
 praisonai/bots/_http_approval.py
+praisonai/bots/_ingress.py
 praisonai/bots/_mirror.py
 praisonai/bots/_pairing_ui.py
 praisonai/bots/_protocol_mixin.py
@@ -81,6 +81,7 @@ praisonai/bots/_registry.py
 praisonai/bots/_resilience.py
 praisonai/bots/_session.py
 praisonai/bots/_slack_approval.py
+praisonai/bots/_streaming.py
 praisonai/bots/_telegram_approval.py
 praisonai/bots/_typing_indicator.py
 praisonai/bots/_unknown_user.py
@@ -519,6 +520,7 @@ praisonai/gateway/push_presence.py
 praisonai/gateway/rate_limiter.py
 praisonai/gateway/redis_pubsub.py
 praisonai/gateway/server.py
+praisonai/gateway/supervisor.py
 praisonai/gateway/unicode_utils.py
 praisonai/inbuilt_tools/__init__.py
 praisonai/inbuilt_tools/autogen_tools.py

{praisonai-4.6.55 → praisonai-4.6.57}/PraisonAI.egg-info/requires.txt

@@ -1,7 +1,7 @@
 rich>=13.7
 markdown>=3.5
 pyparsing>=3.0.0
-praisonaiagents>=1.6.55
+praisonaiagents>=1.6.57
 python-dotenv>=0.19.0
 litellm<2,>=1.83.14
 PyYAML>=6.0

{praisonai-4.6.55 → praisonai-4.6.57}/praisonai/agents_generator.py

@@ -632,6 +632,37 @@ class AgentsGenerator:
         return tools_dict
 
 
+    def _load_config(self):
+        """Load configuration from agent file or agent_yaml."""
+        if self.agent_yaml:
+            config = yaml.safe_load(self.agent_yaml)
+        else:
+            if self.agent_file in ('/app/api:app', 'api:app'):
+                self.agent_file = 'agents.yaml'
+            try:
+                with open(self.agent_file, 'r') as f:
+                    config = yaml.safe_load(f)
+            except FileNotFoundError:
+                print(f"File not found: {self.agent_file}")
+                return None
+        
+        # Apply CLI config overrides to both paths (agent_yaml and agent_file)
+        if self.cli_config:
+            self._merge_cli_config(config, self.cli_config)
+        return config
+
+    def _is_workflow_yaml(self, config):
+        """Check if configuration is workflow mode YAML."""
+        process_type = config.get('process', 'sequential')
+        has_steps = 'steps' in config
+        has_workflow_config = 'workflow' in config
+        workflow_type = config.get('type')
+        return (
+            process_type == 'workflow'
+            or (has_steps and has_workflow_config)
+            or workflow_type in {'job', 'hybrid'}
+        )
+
     def generate_crew_and_kickoff(self):
         """
         Generates a crew of agents and initiates tasks based on the provided configuration.
@@ -649,30 +680,10 @@ class AgentsGenerator:
 
         This function first loads the agent configuration from the specified file. It then initializes the tools required for the agents based on the specified framework. If the specified framework is "autogen", it loads the LLM configuration dynamically and creates an AssistantAgent for each role in the configuration. It then adds tools to the agents if specified in the configuration. Finally, it prepares tasks for the agents based on the configuration and initiates the tasks using the crew of agents. If the specified framework is not "autogen", it creates a crew of agents and initiates tasks based on the configuration.
         """
-        if self.agent_yaml:
-            config = yaml.safe_load(self.agent_yaml)
-        else:
-            if self.agent_file == '/app/api:app' or self.agent_file == 'api:app':
-                self.agent_file = 'agents.yaml'
-            try:
-                with open(self.agent_file, 'r') as f:
-                    config = yaml.safe_load(f)
-            except FileNotFoundError:
-                print(f"File not found: {self.agent_file}")
-                return
-
-        # Apply CLI configuration overrides to YAML config
-        if self.cli_config:
-            # Merge CLI configuration with YAML config
-            self._merge_cli_config(config, self.cli_config)
-
-        # Check if this is a workflow-mode YAML (process: workflow or has steps section)
-        process_type = config.get('process', 'sequential')
-        has_steps = 'steps' in config
-        has_workflow_config = 'workflow' in config
-        
-        if process_type == 'workflow' or (has_steps and has_workflow_config):
-            # Route to YAMLWorkflowParser for advanced workflow patterns
+        config = self._load_config()
+        if config is None:
+            return
+        if self._is_workflow_yaml(config):
             return self._run_yaml_workflow(config)
 
         # Use shared preparation logic
@@ -694,35 +705,12 @@ class AgentsGenerator:
         Async version of generate_crew_and_kickoff.
         Generates a crew of agents and initiates tasks based on the provided configuration.
         """
-        if self.agent_yaml:
-            config = yaml.safe_load(self.agent_yaml)
-        else:
-            if self.agent_file == '/app/api:app' or self.agent_file == 'api:app':
-                self.agent_file = 'agents.yaml'
-            try:
-                with open(self.agent_file, 'r') as f:
-                    config = yaml.safe_load(f)
-            except FileNotFoundError:
-                print(f"File not found: {self.agent_file}")
-                return
-
-        # Apply CLI configuration overrides to YAML config
-        if self.cli_config:
-            # Merge CLI configuration with YAML config
-            self._merge_cli_config(config, self.cli_config)
-
-        # Check if this is a workflow-mode YAML (process: workflow or has steps section)
-        process_type = config.get('process', 'sequential')
-        has_steps = 'steps' in config
-        has_workflow_config = 'workflow' in config
-        
-        if process_type == 'workflow' or (has_steps and has_workflow_config):
+        config = self._load_config()
+        if config is None:
+            return
+        if self._is_workflow_yaml(config):
             return await self._arun_yaml_workflow(config)
-        else:
-            return await self._arun_framework(config)
 
-    async def _arun_framework(self, config):
-        """Async version of _run_framework with shared preparation logic."""
         # Use shared preparation logic
         prep = self._prepare_for_run(config)
         
@@ -737,6 +725,7 @@ class AgentsGenerator:
             cli_config=getattr(self, 'cli_config', None),
         )
 
+
     async def _arun_yaml_workflow(self, config):
         """
         Async version of _run_yaml_workflow using YAMLWorkflowParser.

{praisonai-4.6.55 → praisonai-4.6.57}/praisonai/bots/__init__.py

@@ -19,11 +19,13 @@ if TYPE_CHECKING:
     from .botos import BotOS
     from ._session import BotSessionManager
     from ._dlq import InboundDLQ, DLQEntry
+    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 ._streaming import StreamingConfig, StreamingMode, DraftStreamer
 
 def __getattr__(name: str):
     """Lazy loading of bot components."""
@@ -83,6 +85,23 @@ def __getattr__(name: str):
     if name == "DLQEntry":
         from ._dlq import DLQEntry
         return DLQEntry
+    # Inbound message journal for durable processing
+    if name == "InboundJournal":
+        from ._ingress import InboundJournal
+        return InboundJournal
+    if name == "JournalEntry":
+        from ._ingress import JournalEntry
+        return JournalEntry
+    # Streaming components
+    if name == "StreamingConfig":
+        from ._streaming import StreamingConfig
+        return StreamingConfig
+    if name == "StreamingMode":
+        from ._streaming import StreamingMode
+        return StreamingMode
+    if name == "DraftStreamer":
+        from ._streaming import DraftStreamer
+        return DraftStreamer
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 __all__ = [
@@ -90,8 +109,11 @@ __all__ = [
     "Bot", "BotOS",
     "BotSessionManager",
     "InboundDLQ", "DLQEntry",
+    "InboundJournal", "JournalEntry",
     "SlackApproval", "TelegramApproval", "DiscordApproval",
     "WebhookApproval", "HTTPApproval",
+    # Streaming
+    "StreamingConfig", "StreamingMode", "DraftStreamer",
     # W1
     "mirror_to_session", "BotSessionManager",
 ]

{praisonai-4.6.55 → praisonai-4.6.57}/praisonai/bots/_config_schema.py

@@ -21,6 +21,39 @@ class AgentConfigSchema(BaseModel):
     tools: List[str] = Field(default_factory=list)
 
 
+class StreamingConfigSchema(BaseModel):
+    """Schema for streaming reply configuration."""
+    mode: str = "off"  # off | draft | progress
+    min_interval: float = 1.5  # Minimum seconds between edits
+    min_delta: int = 120  # Minimum character delta before edit
+    placeholder_text: str = "🤔 Thinking..."
+    progress_prefix: str = "🤔 "
+    
+    @field_validator("mode")
+    @classmethod
+    def validate_streaming_mode(cls, v: str) -> str:
+        allowed = {"off", "draft", "progress"}
+        if v not in allowed:
+            raise ValueError(
+                f"Invalid streaming mode '{v}'. Must be one of: {', '.join(sorted(allowed))}"
+            )
+        return v
+    
+    @field_validator("min_interval")
+    @classmethod
+    def validate_min_interval(cls, v: float) -> float:
+        if v < 0.1:
+            raise ValueError("min_interval must be at least 0.1 seconds")
+        return v
+    
+    @field_validator("min_delta")
+    @classmethod
+    def validate_min_delta(cls, v: int) -> int:
+        if v < 1:
+            raise ValueError("min_delta must be at least 1 character")
+        return v
+
+
 class ChannelConfigSchema(BaseModel):
     """Schema for a single channel configuration."""
     platform: Optional[str] = None
@@ -33,6 +66,7 @@ class ChannelConfigSchema(BaseModel):
     routes: Dict[str, str] = Field(default_factory=dict)
     webhook_url: Optional[str] = None
     webhook_port: int = 8080
+    streaming: Optional[StreamingConfigSchema] = None
     
     @field_validator("mode")
     @classmethod

praisonai-4.6.57/praisonai/bots/_ingress.py

@@ -0,0 +1,382 @@
+"""
+Inbound Message Journal for PraisonAI bot adapters.
+
+Provides durable inbound message processing with deduplication, persistent
+ingress journal, and idempotent replay to prevent duplicate agent runs and
+silent message loss during crashes or webhook redeliveries.
+
+Design constraints (per PraisonAI principles):
+  - Wrapper-only — heavy implementation stays out of core SDK
+  - Lazy: sqlite3 is stdlib so no extra dependency  
+  - Optional: BotSessionManager works exactly as before unless journal is provided
+  - Bounded: TTL + max_size prevent unbounded disk growth
+  - Thread-safe: per-instance threading.Lock guards SQLite writes
+  - Atomic: claim/complete mechanism ensures at-least-once with effective exactly-once
+
+Storage schema::
+
+    ingress_journal(
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        ts REAL,
+        platform TEXT, 
+        account TEXT,
+        channel_id TEXT, 
+        message_id TEXT,
+        payload TEXT,
+        status TEXT,  -- 'pending', 'claimed', 'completed'
+        claimed_at REAL,
+        completed_at REAL,
+        attempts INTEGER DEFAULT 0,
+        UNIQUE(platform, account, channel_id, message_id)
+    )
+
+Public API:
+  - InboundJournal(path, *, max_size=50_000, ttl_seconds=30*86400, claim_timeout=300)
+  - receive(platform, account, channel_id, message_id, payload) -> Optional[str]
+  - claim(key) -> ClaimContext  
+  - complete(key)
+  - replay() -> int
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sqlite3
+import threading
+import time
+from contextlib import asynccontextmanager, contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+logger = logging.getLogger(__name__)
+
+# 30 days default — long enough for ops to investigate, short enough not to blow up disk
+_DEFAULT_TTL_SECONDS = 30 * 86400
+_DEFAULT_MAX_SIZE = 50_000
+_DEFAULT_CLAIM_TIMEOUT = 300  # 5 minutes
+
+
+@dataclass(frozen=True)
+class JournalEntry:
+    """A journaled inbound message."""
+    
+    id: int
+    ts: float
+    platform: str
+    account: str  
+    channel_id: str
+    message_id: str
+    payload: str
+    status: str
+    claimed_at: Optional[float]
+    completed_at: Optional[float]  
+    attempts: int
+
+
+class ClaimContext:
+    """Context manager for claiming/releasing journal entries."""
+    
+    def __init__(self, journal: "InboundJournal", key: str):
+        self._journal = journal
+        self._key = key
+        
+    def __enter__(self):
+        return self
+        
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        # No longer needed - release is handled by the outer context managers
+        pass
+        
+    async def __aenter__(self):
+        return self
+        
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        # No longer needed - release is handled by the outer context managers
+        pass
+
+
+class InboundJournal:
+    """SQLite-backed inbound message journal for durable bot processing.
+    
+    Args:
+        path: SQLite file path. Created if missing; parent dirs created.
+        max_size: Maximum entries kept; oldest completed entries evicted when exceeded.
+        ttl_seconds: Completed entries older than this are evicted.
+        claim_timeout: Claimed entries older than this are considered stale for replay.
+    
+    Example::
+    
+        from praisonai.bots import InboundJournal, BotSessionManager
+        
+        journal = InboundJournal(path="~/.praisonai/state/ingress.sqlite")
+        session_mgr = BotSessionManager(platform="telegram", ingress_journal=journal)
+        
+        # In message handler:
+        key = journal.receive("telegram", "bot123", chat_id, update.message.message_id, payload)
+        if key is None:
+            return  # duplicate redelivery
+        async with journal.claim(key):
+            response = await session_mgr.chat(agent, user_id, text)
+        journal.complete(key)
+    """
+    
+    def __init__(
+        self,
+        path: Union[str, Path],
+        *,
+        max_size: int = _DEFAULT_MAX_SIZE,
+        ttl_seconds: int = _DEFAULT_TTL_SECONDS,
+        claim_timeout: int = _DEFAULT_CLAIM_TIMEOUT,
+    ) -> None:
+        self.path = Path(path).expanduser()
+        self.max_size = int(max_size)
+        self.ttl_seconds = int(ttl_seconds)
+        self.claim_timeout = int(claim_timeout)
+        self._lock = threading.Lock()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._init_schema()
+    
+    # ── Schema ──────────────────────────────────────────────────────
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(str(self.path))
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("PRAGMA synchronous=NORMAL")
+        return conn
+    
+    def _init_schema(self) -> None:
+        with self._lock, self._connect() as conn:
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS ingress_journal (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    ts REAL NOT NULL,
+                    platform TEXT NOT NULL,
+                    account TEXT NOT NULL,
+                    channel_id TEXT NOT NULL,
+                    message_id TEXT NOT NULL, 
+                    payload TEXT NOT NULL DEFAULT '',
+                    status TEXT NOT NULL DEFAULT 'pending',
+                    claimed_at REAL,
+                    completed_at REAL,
+                    attempts INTEGER DEFAULT 0,
+                    UNIQUE(platform, account, channel_id, message_id)
+                )
+            """)
+            conn.execute("CREATE INDEX IF NOT EXISTS idx_status ON ingress_journal(status)")
+            conn.execute("CREATE INDEX IF NOT EXISTS idx_ts ON ingress_journal(ts)")
+            conn.execute("CREATE INDEX IF NOT EXISTS idx_claimed_at ON ingress_journal(claimed_at)")
+    
+    # ── Core API ────────────────────────────────────────────────────
+    def receive(
+        self,
+        platform: str,
+        account: str,  
+        channel_id: str,
+        message_id: str,
+        payload: Dict[str, Any] = None
+    ) -> Optional[str]:
+        """Journal an inbound message for durable processing.
+        
+        Args:
+            platform: Bot platform ("telegram", "discord", "slack", etc.)
+            account: Bot account/instance identifier  
+            channel_id: Platform channel/chat identifier
+            message_id: Platform message identifier
+            payload: Message data to store (will be JSON-serialized)
+            
+        Returns:
+            str: Unique key for claim/complete, or None if duplicate
+        """
+        if payload is None:
+            payload = {}
+            
+        with self._lock, self._connect() as conn:
+            try:
+                conn.execute("BEGIN IMMEDIATE")
+                self._evict_expired_locked(conn)
+                
+                # Try to insert - will fail on duplicate (platform, account, channel_id, message_id)
+                cur = conn.execute("""
+                    INSERT INTO ingress_journal(ts, platform, account, channel_id, 
+                                               message_id, payload, status)
+                    VALUES (?, ?, ?, ?, ?, ?, 'pending')
+                """, (
+                    time.time(), platform, account, channel_id, 
+                    message_id, json.dumps(payload)
+                ))
+                
+                entry_id = cur.lastrowid
+                self._evict_overflow_locked(conn)
+                conn.commit()
+                
+                # Return a key for claim/complete operations
+                return f"{platform}:{account}:{channel_id}:{message_id}:{entry_id}"
+                
+            except sqlite3.IntegrityError:
+                # Duplicate message - this is expected for webhook redeliveries
+                conn.rollback()
+                return None
+            except Exception:
+                conn.rollback() 
+                raise
+    
+    @contextmanager
+    def claim(self, key: str):
+        """Claim a journal entry for processing."""
+        self._claim_entry(key)
+        try:
+            yield ClaimContext(self, key)
+        finally:
+            # Release claim if not completed
+            self._release_claim(key)
+    
+    @asynccontextmanager  
+    async def aclaim(self, key: str):
+        """Async claim a journal entry for processing."""
+        self._claim_entry(key)
+        try:
+            yield ClaimContext(self, key)
+        finally:
+            # Release claim if not completed
+            self._release_claim(key)
+    
+    def complete(self, key: str) -> None:
+        """Mark a journal entry as completed."""
+        entry_id = self._extract_id_from_key(key)
+        
+        with self._lock, self._connect() as conn:
+            conn.execute("""
+                UPDATE ingress_journal 
+                SET status = 'completed', completed_at = ?
+                WHERE id = ?
+            """, (time.time(), entry_id))
+    
+    # ── Internal Implementation ────────────────────────────────────
+    def _claim_entry(self, key: str) -> None:
+        """Mark entry as claimed for processing."""
+        entry_id = self._extract_id_from_key(key)
+        
+        with self._lock, self._connect() as conn:
+            conn.execute("""
+                UPDATE ingress_journal
+                SET status = 'claimed', claimed_at = ?, attempts = attempts + 1
+                WHERE id = ? AND status IN ('pending', 'claimed')
+            """, (time.time(), entry_id))
+    
+    def _release_claim(self, key: str) -> None:
+        """Release claim without completing (for crash recovery)."""
+        entry_id = self._extract_id_from_key(key)
+        
+        with self._lock, self._connect() as conn:
+            conn.execute("""
+                UPDATE ingress_journal
+                SET status = 'pending', claimed_at = NULL
+                WHERE id = ? AND status = 'claimed'
+            """, (entry_id,))
+    
+    def _extract_id_from_key(self, key: str) -> int:
+        """Extract entry ID from journal key."""
+        try:
+            return int(key.split(":")[-1])
+        except (ValueError, IndexError):
+            raise ValueError(f"Invalid journal key format: {key}")
+    
+    # ── Maintenance ─────────────────────────────────────────────────
+    def _evict_expired_locked(self, conn: sqlite3.Connection) -> int:
+        """Remove completed entries older than ttl_seconds."""
+        cutoff = time.time() - self.ttl_seconds
+        cur = conn.execute("""
+            DELETE FROM ingress_journal 
+            WHERE status = 'completed' AND completed_at <= ?
+        """, (cutoff,))
+        return int(cur.rowcount or 0)
+    
+    def _evict_overflow_locked(self, conn: sqlite3.Connection) -> int:
+        """Remove oldest entries if over max_size. Prefers completed, then oldest pending."""
+        n = conn.execute("SELECT COUNT(*) FROM ingress_journal").fetchone()[0]
+        if n <= self.max_size:
+            return 0
+            
+        excess = n - self.max_size
+        
+        # First try to delete completed entries
+        completed_cur = conn.execute("""
+            DELETE FROM ingress_journal WHERE id IN (
+                SELECT id FROM ingress_journal 
+                WHERE status = 'completed'
+                ORDER BY completed_at ASC 
+                LIMIT ?
+            )
+        """, (excess,))
+        deleted = int(completed_cur.rowcount or 0)
+        
+        # If we still have excess after deleting completed entries, delete oldest pending
+        remaining_excess = excess - deleted
+        if remaining_excess > 0:
+            pending_cur = conn.execute("""
+                DELETE FROM ingress_journal WHERE id IN (
+                    SELECT id FROM ingress_journal 
+                    WHERE status = 'pending'
+                    ORDER BY ts ASC 
+                    LIMIT ?
+                )
+            """, (remaining_excess,))
+            deleted += int(pending_cur.rowcount or 0)
+            
+        return deleted
+    
+    def replay(self) -> int:
+        """Find and replay stale claimed entries. Returns count replayed."""
+        stale_cutoff = time.time() - self.claim_timeout
+        
+        with self._lock, self._connect() as conn:
+            # Find stale claimed entries  
+            cur = conn.execute("""
+                SELECT id FROM ingress_journal
+                WHERE status = 'claimed' AND claimed_at <= ?
+            """, (stale_cutoff,))
+            
+            stale_ids = [row[0] for row in cur.fetchall()]
+            
+            if stale_ids:
+                # Reset them to pending for replay
+                placeholders = ",".join("?" * len(stale_ids))
+                conn.execute(f"""
+                    UPDATE ingress_journal
+                    SET status = 'pending', claimed_at = NULL
+                    WHERE id IN ({placeholders})
+                """, stale_ids)
+                
+                logger.info(f"InboundJournal: reset {len(stale_ids)} stale claimed entries for replay")
+                
+        return len(stale_ids)
+    
+    def size(self) -> int:
+        """Return total number of entries."""
+        with self._lock, self._connect() as conn:
+            return int(conn.execute("SELECT COUNT(*) FROM ingress_journal").fetchone()[0])
+    
+    def pending_count(self) -> int:
+        """Return number of pending entries."""  
+        with self._lock, self._connect() as conn:
+            return int(conn.execute(
+                "SELECT COUNT(*) FROM ingress_journal WHERE status = 'pending'"
+            ).fetchone()[0])
+    
+    def purge(self) -> int:
+        """Delete all entries. Returns count removed."""
+        with self._lock, self._connect() as conn:
+            n = conn.execute("SELECT COUNT(*) FROM ingress_journal").fetchone()[0]
+            conn.execute("DELETE FROM ingress_journal")
+            return int(n)
+    
+    def __repr__(self) -> str:
+        return (
+            f"InboundJournal(path={str(self.path)!r}, "
+            f"size={self.size()}, pending={self.pending_count()}, "
+            f"max_size={self.max_size}, ttl={self.ttl_seconds}s)"
+        )
+
+
+__all__ = ["InboundJournal", "JournalEntry", "ClaimContext"]