PraisonAI 4.6.57__tar.gz → 4.6.58__tar.gz

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

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

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

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

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

@@ -79,6 +79,7 @@ praisonai/bots/_protocol_mixin.py
 praisonai/bots/_rate_limit.py
 praisonai/bots/_registry.py
 praisonai/bots/_resilience.py
+praisonai/bots/_run_control.py
 praisonai/bots/_session.py
 praisonai/bots/_slack_approval.py
 praisonai/bots/_streaming.py
@@ -418,6 +419,7 @@ praisonai/cli/session/__init__.py
 praisonai/cli/session/unified.py
 praisonai/cli/state/__init__.py
 praisonai/cli/state/identifiers.py
+praisonai/cli/state/project_sessions.py
 praisonai/cli/state/sessions.py
 praisonai/cli/ui/__init__.py
 praisonai/cli/ui/config.py
@@ -425,6 +427,7 @@ praisonai/cli/ui/events.py
 praisonai/cli/ui/mg_backend.py
 praisonai/cli/ui/plain.py
 praisonai/cli/ui/rich_backend.py
+praisonai/cli/utils/project.py
 praisonai/cli_backends/__init__.py
 praisonai/cli_backends/claude.py
 praisonai/cli_backends/registry.py

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

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

{praisonai-4.6.57 → praisonai-4.6.58}/praisonai/bots/_commands.py

@@ -12,6 +12,7 @@ from typing import Dict, Optional, TYPE_CHECKING
 
 if TYPE_CHECKING:
     from praisonaiagents import Agent
+    from ._run_control import SessionRunControl
 
 
 def format_status(
@@ -64,6 +65,7 @@ def format_help(
         "Available Commands",
         "/status - Show bot status and info",
         "/new - Reset conversation session",
+        "/stop - Cancel current agent task",
         "/help - Show this help message",
     ]
     if extra_commands:
@@ -72,3 +74,65 @@ def format_help(
     lines.append(f"\nAgent: {agent_name}")
     lines.append(f"Model: {model}")
     return "\n".join(lines)
+
+
+async def handle_stop_command(
+    user_id: str,
+    run_control: Optional["SessionRunControl"] = None,
+) -> str:
+    """Handle /stop command to cancel current agent task.
+    
+    Args:
+        user_id: User identifier
+        run_control: SessionRunControl instance for managing runs
+        
+    Returns:
+        Response message to send to user
+    """
+    if run_control is None:
+        return "❌ Stop command not available (run control not enabled)"
+        
+    try:
+        stopped = await run_control.stop(user_id)
+        if stopped:
+            return "✅ Current task cancelled. Send a new message to start fresh."
+        else:
+            return "ℹ️ No active task to cancel."
+    except Exception as e:
+        return f"❌ Error stopping task: {e}"
+
+
+def handle_run_status_command(
+    user_id: str,
+    run_control: Optional["SessionRunControl"] = None,
+) -> str:
+    """Handle request for current run status.
+    
+    Args:
+        user_id: User identifier
+        run_control: SessionRunControl instance
+        
+    Returns:
+        Status message
+    """
+    if run_control is None:
+        return "Run control not enabled"
+        
+    try:
+        status = run_control.get_run_status(user_id)
+        
+        if not status["is_running"]:
+            pending_info = " (has queued message)" if status["has_pending"] else ""
+            return f"💤 No active task{pending_info}"
+            
+        elapsed = status.get("elapsed_seconds", 0)
+        elapsed_str = f"{elapsed//60}m {elapsed%60}s" if elapsed > 60 else f"{elapsed}s"
+        
+        pending_info = ""
+        if status["has_pending"]:
+            preview = status.get("pending_preview", "")
+            pending_info = f"\n📝 Queued: {preview}"
+            
+        return f"⚡ Task running for {elapsed_str}{pending_info}"
+    except Exception as e:
+        return f"Error getting status: {e}"

praisonai-4.6.58/praisonai/bots/_run_control.py

@@ -0,0 +1,346 @@
+"""
+Per-session run control for PraisonAI bots.
+
+Provides busy feedback, pending message slots, interrupt support, and
+optional steering for in-flight agent runs. Solves the silent lock
+problem where mid-run messages queue invisibly with no user feedback.
+
+Usage inside a bot message handler::
+
+    # Initialize with busy mode policy
+    run_ctrl = SessionRunControl(busy_mode="queue")  # or "interrupt", "steer"
+    
+    # Handle message with run control
+    decision = await run_ctrl.submit(user_id, message_text)
+    
+    if decision == RunDecision.RUN_NOW:
+        # Start agent.chat() with interrupt controller
+        response = await session_mgr.chat(agent, user_id, text)
+    elif decision == RunDecision.QUEUED:
+        # Return acknowledgment, message will be processed after current run
+        return "⏳ Noted - will consider this after the current task finishes"
+    elif decision == RunDecision.MERGED:
+        # Message was merged into pending slot
+        return "⏳ Added to pending message"
+
+Key features:
+- Busy acknowledgment for mid-run messages instead of silent queuing
+- Per-user pending slot that merges follow-ups received mid-run
+- /stop command via InterruptController integration
+- Optional steering mode to inject messages into running turns
+- Run generation tracking to prevent canceled runs overwriting fresh state
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from enum import Enum
+from typing import Dict, Optional, Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from praisonaiagents.agent.interrupt import InterruptController
+
+logger = logging.getLogger(__name__)
+
+
+class RunDecision(Enum):
+    """Decision for how to handle a submitted message."""
+    RUN_NOW = "run_now"          # No current run, start immediately
+    QUEUED = "queued"            # Current run active, message queued for next turn
+    MERGED = "merged"            # Message merged into existing pending slot
+    INTERRUPTED = "interrupted"  # Current run was interrupted, start new run
+
+
+class BusyMode(Enum):
+    """Policy for handling messages during active runs."""
+    QUEUE = "queue"        # Queue message for next turn (default)
+    INTERRUPT = "interrupt"  # Cancel current run and start new one
+    STEER = "steer"       # Inject message into current run via steering
+
+
+class SessionRunState:
+    """Per-user run state tracking."""
+    
+    def __init__(self):
+        self.is_running = False
+        self.run_generation = 0  # Incremented on each run start
+        self.pending_message: Optional[str] = None
+        self.interrupt_controller: Optional["InterruptController"] = None
+        self.start_time: Optional[float] = None
+        self.last_activity: float = time.time()  # Always track activity for cleanup
+
+
+class SessionRunControl:
+    """Per-session pending slot + interrupt handle around agent runs.
+    
+    Manages run states, pending messages, and interrupt controllers
+    for each user session to provide better UX around long-running
+    agent operations.
+    """
+
+    def __init__(
+        self, 
+        busy_mode: str = "queue",
+        busy_ack_template: str = "⏳ {action} — will be considered next"
+    ):
+        """Initialize session run control.
+        
+        Args:
+            busy_mode: Policy for mid-run messages ("queue", "interrupt", "steer")
+            busy_ack_template: Template for busy acknowledgment messages
+        """
+        try:
+            self._busy_mode = BusyMode(busy_mode)
+        except ValueError:
+            logger.warning(f"Invalid busy_mode '{busy_mode}', using 'queue'")
+            self._busy_mode = BusyMode.QUEUE
+            
+        self._busy_ack_template = busy_ack_template
+        self._sessions: Dict[str, SessionRunState] = {}
+        self._locks: Dict[str, asyncio.Lock] = {}
+
+    def _get_lock(self, user_id: str) -> asyncio.Lock:
+        """Get or create lock for user."""
+        if user_id not in self._locks:
+            self._locks[user_id] = asyncio.Lock()
+        return self._locks[user_id]
+
+    def _get_session(self, user_id: str) -> SessionRunState:
+        """Get or create session state for user."""
+        if user_id not in self._sessions:
+            self._sessions[user_id] = SessionRunState()
+        return self._sessions[user_id]
+
+    async def submit(self, user_id: str, text: str) -> RunDecision:
+        """Submit a message and get decision on how to handle it.
+        
+        Args:
+            user_id: User identifier
+            text: Message text
+            
+        Returns:
+            RunDecision indicating how to proceed
+        """
+        lock = self._get_lock(user_id)
+        async with lock:
+            session = self._get_session(user_id)
+            session.last_activity = time.time()  # Update activity timestamp
+            
+            if not session.is_running:
+                # No active run, start immediately
+                session.is_running = True
+                session.run_generation += 1
+                session.start_time = time.time()
+                
+                # Create interrupt controller for this run
+                try:
+                    from praisonaiagents.agent.interrupt import InterruptController
+                    session.interrupt_controller = InterruptController()
+                except ImportError:
+                    logger.warning("InterruptController not available")
+                    session.interrupt_controller = None
+                    
+                return RunDecision.RUN_NOW
+            
+            # There's an active run, handle based on busy mode
+            if self._busy_mode == BusyMode.INTERRUPT:
+                # Cancel current run and start new one
+                if session.interrupt_controller:
+                    session.interrupt_controller.request("user_new_message")
+                
+                session.pending_message = None  # Clear any pending
+                session.run_generation += 1
+                session.start_time = time.time()
+                
+                # Create new interrupt controller
+                try:
+                    from praisonaiagents.agent.interrupt import InterruptController
+                    session.interrupt_controller = InterruptController()
+                except ImportError:
+                    session.interrupt_controller = None
+                    
+                return RunDecision.INTERRUPTED
+                
+            elif self._busy_mode == BusyMode.STEER:
+                # Try to inject into running agent via steering
+                # Note: This requires the agent to have steering enabled
+                # For now, we'll fall back to queueing
+                logger.warning("Steer mode is not yet implemented, falling back to queue mode")
+                # TODO: Implement steering integration when agent reference is available
+                
+            # Default to queue mode (or steer fallback)
+            if session.pending_message is None:
+                session.pending_message = text
+                return RunDecision.QUEUED
+            else:
+                # Merge with existing pending message
+                session.pending_message = f"{session.pending_message}\n{text}"
+                return RunDecision.MERGED
+
+    async def get_busy_ack_message(self, user_id: str, decision: RunDecision) -> str:
+        """Get appropriate busy acknowledgment message.
+        
+        Args:
+            user_id: User identifier
+            decision: The decision returned by submit()
+            
+        Returns:
+            Acknowledgment message to send to user
+        """
+        session = self._get_session(user_id)
+        
+        if decision == RunDecision.QUEUED:
+            action = "noted"
+        elif decision == RunDecision.MERGED:
+            action = "added to pending request"
+        elif decision == RunDecision.INTERRUPTED:
+            return "⚠️ Previous task cancelled, starting your new request"
+        else:
+            return ""  # No ack needed for RUN_NOW
+            
+        # Add timing info if available
+        timing = ""
+        if session.start_time:
+            elapsed = int(time.time() - session.start_time)
+            if elapsed > 60:
+                timing = f" (running for {elapsed//60}m {elapsed%60}s)"
+            elif elapsed > 10:
+                timing = f" (running for {elapsed}s)"
+        
+        return self._busy_ack_template.format(action=action) + timing
+
+    async def stop(self, user_id: str) -> bool:
+        """Stop the current run for a user.
+        
+        Args:
+            user_id: User identifier
+            
+        Returns:
+            True if a run was stopped, False if no active run
+        """
+        lock = self._get_lock(user_id)
+        async with lock:
+            session = self._get_session(user_id)
+            
+            if not session.is_running:
+                return False
+                
+            # Request interrupt
+            if session.interrupt_controller:
+                session.interrupt_controller.request("user_stop_command")
+                
+            # Clear state
+            session.is_running = False
+            session.pending_message = None
+            session.interrupt_controller = None
+            session.start_time = None
+            
+            return True
+
+    def next_pending(self, user_id: str) -> Optional[str]:
+        """Get and clear the next pending message for a user.
+        
+        Args:
+            user_id: User identifier
+            
+        Returns:
+            Pending message if any, None otherwise
+        """
+        session = self._get_session(user_id)
+        pending = session.pending_message
+        session.pending_message = None
+        return pending
+
+    async def finish_run(self, user_id: str, run_generation: Optional[int] = None):
+        """Mark a run as finished.
+        
+        Args:
+            user_id: User identifier
+            run_generation: Generation of the run that finished (for race protection)
+        """
+        lock = self._get_lock(user_id)
+        async with lock:
+            session = self._get_session(user_id)
+            session.last_activity = time.time()  # Update activity timestamp
+            
+            # Race protection: only clear if this is the current generation
+            if run_generation is None or run_generation == session.run_generation:
+                session.is_running = False
+                session.interrupt_controller = None
+                session.start_time = None
+
+    def get_interrupt_controller(self, user_id: str) -> Optional["InterruptController"]:
+        """Get the interrupt controller for a user's current run.
+        
+        Args:
+            user_id: User identifier
+            
+        Returns:
+            InterruptController if run is active, None otherwise
+        """
+        session = self._get_session(user_id)
+        if session.is_running:
+            return session.interrupt_controller
+        return None
+
+    def get_run_status(self, user_id: str) -> Dict[str, Any]:
+        """Get run status for a user.
+        
+        Args:
+            user_id: User identifier
+            
+        Returns:
+            Dict with run status information
+        """
+        session = self._get_session(user_id)
+        
+        status = {
+            "is_running": session.is_running,
+            "run_generation": session.run_generation,
+            "has_pending": session.pending_message is not None,
+            "busy_mode": self._busy_mode.value
+        }
+        
+        if session.start_time:
+            status["elapsed_seconds"] = int(time.time() - session.start_time)
+            
+        if session.pending_message:
+            status["pending_preview"] = session.pending_message[:100] + "..." if len(session.pending_message) > 100 else session.pending_message
+            
+        return status
+
+    @property
+    def active_sessions_count(self) -> int:
+        """Number of sessions with active runs."""
+        return sum(1 for session in self._sessions.values() if session.is_running)
+
+    def cleanup_stale_sessions(self, max_age_seconds: int = 3600) -> int:
+        """Clean up stale sessions older than max_age_seconds.
+        
+        Args:
+            max_age_seconds: Maximum age in seconds
+            
+        Returns:
+            Number of sessions cleaned up
+        """
+        if max_age_seconds <= 0:
+            return 0
+            
+        now = time.time()
+        stale_users = []
+        
+        for user_id, session in self._sessions.items():
+            # Clean up based on last activity instead of only active runs
+            if (now - session.last_activity) > max_age_seconds:
+                stale_users.append(user_id)
+                
+        for user_id in stale_users:
+            del self._sessions[user_id]
+            self._locks.pop(user_id, None)
+            
+        if stale_users:
+            logger.debug(f"SessionRunControl: cleaned up {len(stale_users)} stale sessions")
+            
+        return len(stale_users)

{praisonai-4.6.57 → praisonai-4.6.58}/praisonai/bots/_session.py

@@ -65,6 +65,7 @@ class BotSessionManager:
         dlq: Optional[Any] = None,
         identity_resolver: Optional[Any] = None,
         ingress_journal: Optional[Any] = None,
+        run_control: Optional[Any] = None,
     ) -> None:
         self._histories: Dict[str, List[Dict[str, Any]]] = {}
         self._locks: Dict[str, asyncio.Lock] = {}
@@ -86,6 +87,8 @@ class BotSessionManager:
         # crash recovery and webhook redelivery protection.
         self._ingress_journal = ingress_journal
         self._last_journal_key = None  # Store key for delayed completion
+        # Run control for in-flight message handling
+        self._run_control = run_control
 
     def _storage_key(self, user_id: str) -> str:
         """Resolve a raw platform user id to the in-memory/store key.
@@ -345,6 +348,129 @@ class BotSessionManager:
                 except Exception as e:
                     logger.debug("Failed to clear task-local session context for ctx_token=%r: %s", ctx_token, e)
 
+    async def chat_with_run_control(
+        self,
+        agent: "Agent",
+        user_id: str,
+        prompt: str,
+        chat_id: str = "",
+        thread_id: str = "",
+        user_name: str = "",
+    ) -> Dict[str, Any]:
+        """Run agent.chat() with run control for better UX during long operations.
+        
+        This method integrates with SessionRunControl to provide:
+        - Busy acknowledgment for mid-run messages
+        - Pending message slot for follow-ups
+        - Interrupt support via /stop command
+        - Optional steering for real-time guidance
+        
+        Returns:
+            Dict with 'response' (str) and 'metadata' (dict) keys.
+            Metadata includes run control information.
+        """
+        if self._run_control is None:
+            # Fall back to regular chat if no run control
+            response = await self.chat(agent, user_id, prompt, chat_id, thread_id, user_name)
+            return {"response": response, "metadata": {"run_control": False}}
+        
+        try:
+            # Import here to avoid circular dependency
+            from ._run_control import RunDecision
+        except ImportError:
+            # Fall back if run control not available
+            response = await self.chat(agent, user_id, prompt, chat_id, thread_id, user_name)
+            return {"response": response, "metadata": {"run_control": False, "error": "run_control_unavailable"}}
+        
+        # Submit message to run control
+        decision = await self._run_control.submit(user_id, prompt)
+        
+        if decision in (RunDecision.QUEUED, RunDecision.MERGED):
+            # Message was queued or merged, return acknowledgment
+            ack_msg = await self._run_control.get_busy_ack_message(user_id, decision)
+            return {
+                "response": ack_msg,
+                "metadata": {
+                    "run_control": True,
+                    "decision": decision.value,
+                    "queued": True
+                }
+            }
+        
+        # We're running now (RUN_NOW or INTERRUPTED)
+        run_generation = None
+        interrupt_controller = None
+        
+        if decision == RunDecision.RUN_NOW:
+            # Get the interrupt controller for this run
+            interrupt_controller = self._run_control.get_interrupt_controller(user_id)
+        elif decision == RunDecision.INTERRUPTED:
+            # Previous run was cancelled, get new controller
+            interrupt_controller = self._run_control.get_interrupt_controller(user_id)
+        
+        # Get current run generation for race protection
+        status = self._run_control.get_run_status(user_id)
+        run_generation = status.get("run_generation")
+        
+        try:
+            # Attach interrupt controller to agent if available
+            original_interrupt = None
+            if interrupt_controller and hasattr(agent, '_interrupt_controller'):
+                original_interrupt = getattr(agent, '_interrupt_controller', None)
+                agent._interrupt_controller = interrupt_controller
+            
+            # Run the chat with the existing method
+            response = await self.chat(agent, user_id, prompt, chat_id, thread_id, user_name)
+            
+            # Check for pending messages to process next
+            pending = self._run_control.next_pending(user_id)
+            pending_info = {}
+            if pending:
+                pending_info = {
+                    "next_pending": pending[:100] + "..." if len(pending) > 100 else pending
+                }
+            
+            return {
+                "response": response,
+                "metadata": {
+                    "run_control": True,
+                    "decision": decision.value,
+                    "completed": True,
+                    "run_generation": run_generation,
+                    **pending_info
+                }
+            }
+            
+        except Exception as e:
+            # Handle interruption specifically
+            if interrupt_controller and interrupt_controller.is_set():
+                reason = interrupt_controller.reason or "unknown"
+                return {
+                    "response": f"⚠️ Task cancelled: {reason}",
+                    "metadata": {
+                        "run_control": True,
+                        "decision": decision.value,
+                        "interrupted": True,
+                        "reason": reason,
+                        "run_generation": run_generation
+                    }
+                }
+            else:
+                # Re-raise other exceptions
+                raise
+                
+        finally:
+            # Restore original interrupt controller
+            if interrupt_controller and hasattr(agent, '_interrupt_controller'):
+                if original_interrupt is not None:
+                    agent._interrupt_controller = original_interrupt
+                else:
+                    agent._interrupt_controller = None
+            
+            # Mark run as finished
+            if run_generation is not None:
+                await self._run_control.finish_run(user_id, run_generation)
+
     def reap_stale(self, max_age_seconds: int) -> int:
         """Remove sessions older than *max_age_seconds*.  Returns count reaped.
 

{praisonai-4.6.57 → praisonai-4.6.58}/praisonai/bots/telegram.py

@@ -100,9 +100,22 @@ class TelegramBot(ChatCommandMixin, MessageHookMixin):
             _store = get_default_session_store()
         except Exception:
             _store = None
+        # Create run control if busy mode is configured
+        run_control = None
+        if hasattr(self.config, 'busy_mode') and self.config.busy_mode != "queue":
+            try:
+                from ._run_control import SessionRunControl
+                run_control = SessionRunControl(
+                    busy_mode=self.config.busy_mode,
+                    busy_ack_template=getattr(self.config, 'busy_ack', "⏳ {action} — will be considered next")
+                )
+            except ImportError:
+                logger.warning("Run control not available, falling back to basic session management")
+        
         self._session: BotSessionManager = BotSessionManager(
             store=_store,
             platform="telegram",
+            run_control=run_control,
         )
         self._debouncer: InboundDebouncer = InboundDebouncer(
             debounce_ms=self.config.debounce_ms,

{praisonai-4.6.57 → praisonai-4.6.58}/praisonai/browser/server.py

@@ -120,7 +120,7 @@ class BrowserServer:
         app.add_middleware(
             CORSMiddleware,
             allow_origins=cors_origins,
-            allow_origin_regex=r"chrome-extension://[a-z0-9]{32}",
+            allow_origin_regex=r"chrome-extension://[a-z0-9]{32}$",
             allow_credentials=True,
             allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
             allow_headers=["Authorization", "Content-Type", "Origin", "Accept"],
@@ -183,7 +183,7 @@ class BrowserServer:
             if origin in cors_origins:
                 is_allowed = True
             # Check chrome extension regex pattern (same as CORS middleware)
-            elif parsed_origin.scheme == "chrome-extension" and re.match(r"chrome-extension://[a-z0-9]{32}", origin):
+            elif parsed_origin.scheme == "chrome-extension" and re.match(r"chrome-extension://[a-z0-9]{32}$", origin):
                 is_allowed = True
             
             if not is_allowed: