feat: Round-2 Gap Closure — Interrupts, Error Classifier, Path Overlap, Message Sanitization, Title Auto-Gen (5/12) (#1489)

* feat: implement Round-2 Gap Closure (G2, G5, G6, G8)

- G2: Add InterruptController for cooperative cancellation of agent runs
- G5: Add multi-category error classifier for intelligent retry logic
- G6: Add message sanitization for surrogate/non-ASCII characters
- G8: Add session title auto-generation from first exchange

All features follow protocol-driven design with zero impact when disabled.
Maintains full backward compatibility with existing APIs.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-authored-by: Mervin Praison <MervinPraison@users.noreply.github.com>

* feat: implement G4 parallel tool path overlap detection

- Add path_overlap module with conflict detection for write operations
- Integrate with ParallelToolCallExecutor to fallback to sequential when conflicts detected
- Prevent file corruption from concurrent writes to same/overlapping paths
- Support path conflict grouping for sophisticated scheduling
- Zero impact when no path conflicts exist

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-authored-by: Mervin Praison <MervinPraison@users.noreply.github.com>

* fix: align gap-closure utilities with unit-test expectations

Agent-Logs-Url: https://github.com/MervinPraison/PraisonAI/sessions/46d33039-4077-44a4-abb3-f7a4571f6162

Co-authored-by: MervinPraison <454862+MervinPraison@users.noreply.github.com>

* docs+fix: guard retry attempt floor and align backoff examples

Agent-Logs-Url: https://github.com/MervinPraison/PraisonAI/sessions/46d33039-4077-44a4-abb3-f7a4571f6162

Co-authored-by: MervinPraison <454862+MervinPraison@users.noreply.github.com>

* fix: resolve all 8 hard blockers and CodeRabbit issues

- B1: Wire error classifier into retry paths with proper attempt handling
- B2: Add interrupt controller checks to sync run_autonomous()
- B3: Fix silent failure - fail closed when path overlap unavailable
- B4: Enhanced path overlap detection with custom write tool support
- B5: Skip empty path strings (already implemented)
- B6: Fix SessionMessage attribute access + async I/O blocking
- B7: Handle asyncio.run() in running loop context
- B8: Implement recursive sanitization for nested tool call arguments

Additional fixes:
- Add missing type imports (InterruptController)
- Replace undefined MemoryManager with Any
- Fix test determinism with threading.Event coordination
- Add missing __all__ exports for error_classifier
- Add InterruptControllerProtocol for extension point

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-authored-by: Claude <noreply@anthropic.com>

* fix: resolve over-conservative write tool detection in path overlap

- Add _READ_NAME_HINTS to distinguish read-only tools from writers
- Update _is_potential_write_tool() to check read hints before fallback
- Require both path args AND payload args for unknown tools
- Fixes test_read_tool_no_paths while preserving custom write detection
- Resolves performance regression from B4 fix in commit 76264e2

All 23 path overlap tests now pass. Read tools like read_file, get_file
can run in parallel while custom write tools are still safely detected.

Co-authored-by: Mervin Praison <MervinPraison@users.noreply.github.com>

---------

Co-authored-by: praisonai-triage-agent[bot] <272766704+praisonai-triage-agent[bot]@users.noreply.github.com>
Co-authored-by: Mervin Praison <MervinPraison@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: MervinPraison <454862+MervinPraison@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>

Author: 4 people

src/praisonai-agents/praisonaiagents/agent/__init__.py

@@ -33,6 +33,10 @@ def __getattr__(name):
         from .heartbeat import HeartbeatConfig
         _lazy_cache[name] = HeartbeatConfig
         return HeartbeatConfig
+    if name == 'InterruptController':
+        from .interrupt import InterruptController
+        _lazy_cache[name] = InterruptController
+        return InterruptController
 
     # Specialized agents - lazy loaded (import rich)
     if name == 'ImageAgent':
@@ -194,6 +198,7 @@ def __getattr__(name):
     'BudgetExceededError',
     'Heartbeat',
     'HeartbeatConfig',
+    'InterruptController',
     'ImageAgent',
     'VideoAgent',
     'VideoConfig',

src/praisonai-agents/praisonaiagents/agent/agent.py

@@ -245,6 +245,7 @@ def _get_default_server_registry() -> ServerRegistry:
     from ..context.models import ContextConfig
     from ..context.manager import ContextManager
     from ..knowledge.knowledge import Knowledge
+    from .interrupt import InterruptController
     from ..agent.autonomy import AutonomyConfig
     from ..task.task import Task
     from .handoff import Handoff, HandoffConfig, HandoffResult
@@ -531,7 +532,7 @@ def __init__(
         # CONSOLIDATED FEATURE PARAMS (agent-centric API)
         # Each follows: False=disabled, True=defaults, Config=custom
         # ============================================================
-        memory: Optional[Union[bool, str, 'MemoryConfig', 'MemoryManager']] = None,
+        memory: Optional[Union[bool, str, 'MemoryConfig', Any]] = None,
         knowledge: Optional[Union[bool, str, List[str], 'KnowledgeConfig', 'Knowledge']] = None,
         planning: Optional[Union[bool, str, 'PlanningConfig']] = False,
         reflection: Optional[Union[bool, str, 'ReflectionConfig']] = None,
@@ -551,6 +552,7 @@ def __init__(
         parallel_tool_calls: bool = False,  # Gap 2: Enable parallel execution of batched LLM tool calls
         learn: Optional[Union[bool, str, Dict[str, Any], 'LearnConfig']] = None,  # Continuous learning (peer to memory)
         backend: Optional[Any] = None,  # External managed agent backend (e.g., ManagedAgentIntegration)
+        interrupt_controller: Optional['InterruptController'] = None,  # G2: Cooperative cancellation
     ):
         """Initialize an Agent instance.
 
@@ -575,7 +577,7 @@ def __init__(
             memory: Memory system configuration. Accepts:
                 - bool: True enables defaults, False disables
                 - MemoryConfig: Custom configuration
-                - MemoryManager: Pre-configured instance
+                - Any: Pre-configured memory instance
             knowledge: Knowledge sources. Accepts:
                 - bool: True enables defaults
                 - List[str]: File paths, URLs, or text content
@@ -1458,6 +1460,8 @@ def __init__(
         self.instructions = instructions
         # Gap 2: Store parallel tool calls setting for ToolCallExecutor selection
         self.parallel_tool_calls = parallel_tool_calls
+        # G2: Store interrupt controller for cooperative cancellation
+        self.interrupt_controller = interrupt_controller
         # Check for model name in environment variable if not provided
         self._using_custom_llm = False
         # Flag to track if final result has been displayed to prevent duplicates
@@ -2851,6 +2855,19 @@ def run_autonomous(
                         started_at=started_at,
                     )
 
+                # G2: Check for interrupt request (cooperative cancellation) - sync version
+                if self.interrupt_controller and self.interrupt_controller.is_set():
+                    reason = self.interrupt_controller.reason or "unknown"
+                    return AutonomyResult(
+                        success=False,
+                        output=f"Task interrupted: {reason}",
+                        completion_reason="interrupted",
+                        iterations=iterations,
+                        stage=stage,
+                        actions=actions_taken,
+                        duration_seconds=time_module.time() - start_time,
+                        started_at=started_at,
+                    )
 
                 # Execute one turn using the agent's chat method
                 # Always use the original prompt (prompt re-injection)
@@ -3248,6 +3265,20 @@ async def main():
                         started_at=started_at,
                     )
 
+                # G2: Check for interrupt request (cooperative cancellation)
+                if self.interrupt_controller and self.interrupt_controller.is_set():
+                    reason = self.interrupt_controller.reason or "unknown"
+                    return AutonomyResult(
+                        success=False,
+                        output=f"Task interrupted: {reason}",
+                        completion_reason="interrupted",
+                        iterations=iterations,
+                        stage=stage,
+                        actions=actions_taken,
+                        duration_seconds=time_module.time() - start_time,
+                        started_at=started_at,
+                    )
+                
 
                 # Execute one turn using the agent's async chat method
                 # Always use the original prompt (prompt re-injection)

src/praisonai-agents/praisonaiagents/agent/interrupt.py

@@ -0,0 +1,105 @@
+"""
+Interrupt Controller - Cooperative cancellation for agent runs.
+
+Provides thread-safe, cooperative cancellation mechanism for long-running agent
+operations. Follows protocol-driven design with zero overhead when not used.
+"""
+
+import threading
+from typing import Optional, Protocol
+from dataclasses import dataclass, field
+
+__all__ = ["InterruptControllerProtocol", "InterruptController"]
+
+
+class InterruptControllerProtocol(Protocol):
+    """Protocol for interrupt controller extension point."""
+    
+    def request(self, reason: str = "user") -> None:
+        """Request cancellation with optional reason."""
+        ...
+    
+    def clear(self) -> None:
+        """Clear interrupt state."""
+        ...
+    
+    def is_set(self) -> bool:
+        """Check if interrupt was requested."""
+        ...
+    
+    @property
+    def reason(self) -> Optional[str]:
+        """Get interrupt reason if set."""
+        ...
+    
+    def check(self) -> None:
+        """Check for interrupt and raise if set."""
+        ...
+
+
+@dataclass
+class InterruptController:
+    """Thread-safe cooperative cancellation for agent runs.
+    
+    Provides a lightweight mechanism for requesting cancellation of agent
+    operations. Uses threading.Event for thread safety and cooperative
+    checking patterns.
+    
+    Examples:
+        Basic usage:
+        >>> controller = InterruptController()
+        >>> # In another thread:
+        >>> controller.request("user_cancel")
+        >>> # In agent loop:
+        >>> if controller.is_set():
+        >>>     return f"Cancelled: {controller.reason}"
+    """
+    
+    _flag: threading.Event = field(default_factory=threading.Event, init=False, repr=False)
+    _reason: Optional[str] = field(default=None, init=False)
+    _lock: threading.Lock = field(default_factory=threading.Lock, init=False, repr=False)
+
+    def request(self, reason: str = "user") -> None:
+        """Request cancellation with a reason.
+        
+        Args:
+            reason: Human-readable reason for cancellation
+        """
+        with self._lock:
+            if not self._flag.is_set():
+                self._reason = reason
+                self._flag.set()
+
+    def clear(self) -> None:
+        """Clear the cancellation request."""
+        with self._lock:
+            self._reason = None
+            self._flag.clear()
+
+    def is_set(self) -> bool:
+        """Check if cancellation has been requested.
+        
+        Returns:
+            True if cancellation was requested
+        """
+        return self._flag.is_set()
+
+    @property
+    def reason(self) -> Optional[str]:
+        """Get the reason for cancellation.
+        
+        Returns:
+            Reason string if cancelled, None otherwise
+        """
+        with self._lock:
+            return self._reason
+
+    def check(self) -> None:
+        """Check for cancellation and raise if requested.
+        
+        Raises:
+            InterruptedError: If cancellation was requested
+        """
+        if self.is_set():
+            reason = self.reason or "unknown"
+            raise InterruptedError(f"Operation cancelled: {reason}")

src/praisonai-agents/praisonaiagents/llm/__init__.py

@@ -159,6 +159,26 @@ def __getattr__(name):
             from .unified_adapters import create_llm_dispatcher
             _lazy_cache[name] = create_llm_dispatcher
             return create_llm_dispatcher
+        elif name == "sanitize_messages":
+            from .sanitize import sanitize_messages
+            _lazy_cache[name] = sanitize_messages
+            return sanitize_messages
+        elif name == "strip_surrogates":
+            from .sanitize import strip_surrogates
+            _lazy_cache[name] = strip_surrogates
+            return strip_surrogates
+        elif name == "sanitize_text":
+            from .sanitize import sanitize_text
+            _lazy_cache[name] = sanitize_text
+            return sanitize_text
+        elif name == "ErrorCategory":
+            from .error_classifier import ErrorCategory
+            _lazy_cache[name] = ErrorCategory
+            return ErrorCategory
+        elif name == "classify_error":
+            from .error_classifier import classify_error
+            _lazy_cache[name] = classify_error
+            return classify_error
 
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
@@ -199,5 +219,12 @@ def __getattr__(name):
     "LLMProviderError",
     "RateLimitError",
     "ModelNotAvailableError",
-    "ContextLengthExceededError"
+    "ContextLengthExceededError",
+    # Sanitization (G6)
+    "sanitize_messages",
+    "strip_surrogates", 
+    "sanitize_text",
+    # Error Classification (G5)
+    "ErrorCategory",
+    "classify_error"
 ]