PraisonAI 4.6.28__tar.gz → 4.6.30__tar.gz

{praisonai-4.6.28 → praisonai-4.6.30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PraisonAI
-Version: 4.6.28
+Version: 4.6.30
 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.28
+Requires-Dist: praisonaiagents>=1.6.30
 Requires-Dist: python-dotenv>=0.19.0
 Requires-Dist: litellm<=1.82.6,>=1.81.0
 Requires-Dist: PyYAML>=6.0

{praisonai-4.6.28 → praisonai-4.6.30}/PraisonAI.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PraisonAI
-Version: 4.6.28
+Version: 4.6.30
 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.28
+Requires-Dist: praisonaiagents>=1.6.30
 Requires-Dist: python-dotenv>=0.19.0
 Requires-Dist: litellm<=1.82.6,>=1.81.0
 Requires-Dist: PyYAML>=6.0

{praisonai-4.6.28 → praisonai-4.6.30}/PraisonAI.egg-info/SOURCES.txt

@@ -11,11 +11,11 @@ praisonai/__main__.py
 praisonai/_approval_spec.py
 praisonai/_async_bridge.py
 praisonai/_logging.py
+praisonai/agent.py
 praisonai/agent_scheduler.py
 praisonai/agents_generator.py
 praisonai/async_agent_scheduler.py
 praisonai/auto.py
-praisonai/chainlit_ui.py
 praisonai/deploy.py
 praisonai/profiler.py
 praisonai/scheduler.py
@@ -60,13 +60,16 @@ praisonai/bots/__init__.py
 praisonai/bots/_ack.py
 praisonai/bots/_approval.py
 praisonai/bots/_approval_base.py
+praisonai/bots/_auth.py
 praisonai/bots/_chunk.py
 praisonai/bots/_commands.py
 praisonai/bots/_config_schema.py
 praisonai/bots/_debounce.py
+praisonai/bots/_defaults.py
 praisonai/bots/_discord_approval.py
 praisonai/bots/_email_utils.py
 praisonai/bots/_http_approval.py
+praisonai/bots/_pairing_ui.py
 praisonai/bots/_protocol_mixin.py
 praisonai/bots/_rate_limit.py
 praisonai/bots/_registry.py
@@ -74,6 +77,7 @@ praisonai/bots/_resilience.py
 praisonai/bots/_session.py
 praisonai/bots/_slack_approval.py
 praisonai/bots/_telegram_approval.py
+praisonai/bots/_unknown_user.py
 praisonai/bots/_webhook_approval.py
 praisonai/bots/_whatsapp_web_adapter.py
 praisonai/bots/agentmail.py
@@ -127,8 +131,6 @@ praisonai/capabilities/skills.py
 praisonai/capabilities/vector_store_files.py
 praisonai/capabilities/vector_stores.py
 praisonai/capabilities/videos.py
-praisonai/chat/__init__.py
-praisonai/chat/app.py
 praisonai/claw/__init__.py
 praisonai/claw/default_app.py
 praisonai/cli/__init__.py
@@ -182,10 +184,12 @@ praisonai/cli/commands/lsp.py
 praisonai/cli/commands/managed.py
 praisonai/cli/commands/mcp.py
 praisonai/cli/commands/memory.py
+praisonai/cli/commands/mint_link.py
 praisonai/cli/commands/n8n.py
 praisonai/cli/commands/obs.py
 praisonai/cli/commands/onboard.py
 praisonai/cli/commands/package.py
+praisonai/cli/commands/pairing.py
 praisonai/cli/commands/paths.py
 praisonai/cli/commands/plugins.py
 praisonai/cli/commands/port.py
@@ -411,6 +415,9 @@ praisonai/cli/ui/events.py
 praisonai/cli/ui/mg_backend.py
 praisonai/cli/ui/plain.py
 praisonai/cli/ui/rich_backend.py
+praisonai/cli_backends/__init__.py
+praisonai/cli_backends/claude.py
+praisonai/cli_backends/registry.py
 praisonai/code/__init__.py
 praisonai/code/agent_tools.py
 praisonai/code/diff/__init__.py
@@ -484,9 +491,14 @@ praisonai/framework_adapters/base.py
 praisonai/framework_adapters/crewai_adapter.py
 praisonai/framework_adapters/praisonai_adapter.py
 praisonai/gateway/__init__.py
+praisonai/gateway/auth.py
+praisonai/gateway/cookie_auth.py
 praisonai/gateway/exec_approval.py
 praisonai/gateway/gateway_approval.py
+praisonai/gateway/magic_link.py
+praisonai/gateway/origin_check.py
 praisonai/gateway/pairing.py
+praisonai/gateway/pairing_routes.py
 praisonai/gateway/push_channels.py
 praisonai/gateway/push_delivery.py
 praisonai/gateway/push_polling.py
@@ -511,6 +523,7 @@ praisonai/integrations/gemini_cli.py
 praisonai/integrations/managed_agents.py
 praisonai/integrations/managed_local.py
 praisonai/integrations/registry.py
+praisonai/integrations/sandboxed_agent.py
 praisonai/integrations/compute/__init__.py
 praisonai/integrations/compute/daytona.py
 praisonai/integrations/compute/docker.py
@@ -723,22 +736,10 @@ praisonai/train/llm/__init__.py
 praisonai/train/llm/trainer.py
 praisonai/ui/_aiui_datastore.py
 praisonai/ui/_external_agents.py
-praisonai/ui/agents.py
-praisonai/ui/bot.py
 praisonai/ui/callbacks.py
-praisonai/ui/chainlit_compat.py
-praisonai/ui/chat.py
-praisonai/ui/code.py
-praisonai/ui/colab.py
-praisonai/ui/colab_chainlit.py
 praisonai/ui/context.py
 praisonai/ui/database_config.py
-praisonai/ui/db.py
-praisonai/ui/realtime.py
-praisonai/ui/sql_alchemy.py
 praisonai/ui/components/aicoder.py
-praisonai/ui/realtimeclient/__init__.py
-praisonai/ui/realtimeclient/tools.py
 praisonai/ui_agents/__init__.py
 praisonai/ui_agents/default_app.py
 praisonai/ui_bot/__init__.py
@@ -761,4 +762,5 @@ tests/test_phase2_refactor.py
 tests/test_recipe.py
 tests/test_registry.py
 tests/test_runner.py
+tests/test_sandboxed_agent_compatibility.py
 tests/test_serve_features.py

{praisonai-4.6.28 → praisonai-4.6.30}/PraisonAI.egg-info/requires.txt

@@ -1,7 +1,7 @@
 rich>=13.7
 markdown>=3.5
 pyparsing>=3.0.0
-praisonaiagents>=1.6.28
+praisonaiagents>=1.6.30
 python-dotenv>=0.19.0
 litellm<=1.82.6,>=1.81.0
 PyYAML>=6.0

{praisonai-4.6.28 → praisonai-4.6.30}/praisonai/__init__.py

@@ -15,6 +15,7 @@ __all__ = [
     'CloudProvider',
     'AgentOS',  # Production deployment platform (v0.14.16+)
     'AgentApp',  # Silent alias for AgentOS (backward compat)
+    'Agent',  # Wrapper Agent with CLI backend string resolution
     'recipe',
     'embed',
     'embedding',
@@ -22,8 +23,10 @@ __all__ = [
     'ManagedAgent',
     'ManagedConfig',
     'AnthropicManagedAgent',
-    'LocalManagedAgent',
-    'LocalManagedConfig',
+    'LocalManagedAgent',          # backward compat alias
+    'LocalManagedConfig',         # backward compat alias
+    'SandboxedAgent',             # new honest name
+    'SandboxedAgentConfig',       # new honest name
 ]
 
 # Telemetry initialization state
@@ -57,6 +60,9 @@ def __getattr__(name):
     if name == 'PraisonAI':
         from .cli import PraisonAI
         return PraisonAI
+    elif name == 'Agent':
+        from .agent import Agent
+        return Agent
     elif name == 'Deploy':
         from .deploy import Deploy
         return Deploy
@@ -108,6 +114,12 @@ def __getattr__(name):
     elif name == 'LocalManagedConfig':
         from .integrations.managed_local import LocalManagedConfig
         return LocalManagedConfig
+    elif name == 'SandboxedAgent':
+        from .integrations.sandboxed_agent import SandboxedAgent
+        return SandboxedAgent
+    elif name == 'SandboxedAgentConfig':
+        from .integrations.sandboxed_agent import SandboxedAgentConfig
+        return SandboxedAgentConfig
     elif name in ('ManagedConfig', 'ManagedBackendConfig'):
         from .integrations.managed_agents import ManagedConfig
         return ManagedConfig

praisonai-4.6.30/praisonai/_async_bridge.py

@@ -0,0 +1,101 @@
+"""
+Async bridge module - single source of truth for running coroutines synchronously.
+
+This module provides a safe way to run async functions from sync contexts,
+handling nested event loop scenarios without creating a new event loop
+on every call (which is expensive and breaks multi-agent workflows).
+"""
+import asyncio
+import atexit
+import os
+import threading
+from concurrent.futures import Future
+from typing import Awaitable, TypeVar
+
+T = TypeVar("T")
+
+_DEFAULT_TIMEOUT = float(os.environ.get("PRAISONAI_RUN_SYNC_TIMEOUT", "300"))
+
+class _BackgroundLoop:
+    def __init__(self) -> None:
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._thread: threading.Thread | None = None
+        self._lock = threading.Lock()
+
+    def get(self) -> asyncio.AbstractEventLoop:
+        with self._lock:
+            if self._loop is None or self._loop.is_closed():
+                self._loop = asyncio.new_event_loop()
+                # non-daemon so shutdown must be explicit and clean
+                self._thread = threading.Thread(
+                    target=self._loop.run_forever,
+                    name="praisonai-async",
+                    daemon=False,
+                )
+                self._thread.start()
+            return self._loop
+
+    def shutdown(self, timeout: float = 5.0) -> None:
+        with self._lock:
+            loop, thread = self._loop, self._thread
+            if loop is None:
+                return
+            # Cancel outstanding tasks, then stop the loop.
+            async def _cancel_all() -> None:
+                tasks = [t for t in asyncio.all_tasks(loop) if not t.done()]
+                for t in tasks:
+                    t.cancel()
+                await asyncio.gather(*tasks, return_exceptions=True)
+            try:
+                asyncio.run_coroutine_threadsafe(_cancel_all(), loop).result(timeout)
+            finally:
+                loop.call_soon_threadsafe(loop.stop)
+                if thread is not None:
+                    thread.join(timeout)
+                if not loop.is_closed():
+                    loop.close()
+                self._loop = None
+                self._thread = None
+
+_BG = _BackgroundLoop()
+atexit.register(_BG.shutdown)
+
+
+def run_sync(coro: Awaitable[T], *, timeout: float | None = _DEFAULT_TIMEOUT) -> T:
+    """
+    Run a coroutine synchronously, safe inside a running loop.
+    
+    This function automatically detects if there's already a running event loop
+    and handles the execution appropriately:
+    - If no loop is running: uses background loop (consistent behavior)
+    - If a loop is running: schedules on background loop (safe path)
+    
+    Args:
+        coro: The coroutine to run
+        timeout: Maximum time to wait for completion (seconds)
+        
+    Returns:
+        The result of the coroutine
+        
+    Raises:
+        TimeoutError: If timeout is exceeded
+        Any exception raised by the coroutine
+    """
+    try:
+        asyncio.get_running_loop()
+        running = True
+    except RuntimeError:
+        running = False
+
+    if not running:
+        # Reuse the background loop instead of creating a new one per call.
+        fut: Future = asyncio.run_coroutine_threadsafe(coro, _BG.get())
+        return fut.result(timeout=timeout)
+
+    fut = asyncio.run_coroutine_threadsafe(coro, _BG.get())
+    return fut.result(timeout=timeout)
+
+
+def shutdown() -> None:
+    """Public hook for servers (gateway, a2u, mcp_server) to stop the bridge cleanly."""
+    _BG.shutdown()

praisonai-4.6.30/praisonai/agent.py

@@ -0,0 +1,63 @@
+"""Wrapper Agent class with CLI backend resolution support.
+
+This module provides a wrapper around praisonaiagents.Agent that handles
+CLI backend string resolution in the wrapper layer, maintaining proper
+dependency direction per AGENTS.md.
+"""
+
+from typing import Union, Optional, Any
+from praisonaiagents import Agent as CoreAgent
+
+
+class Agent(CoreAgent):
+    """Agent wrapper with CLI backend string resolution support.
+    
+    This class extends the core Agent to handle CLI backend string resolution
+    in the wrapper layer, maintaining proper architectural separation between
+    core protocols and heavy implementations.
+    """
+    
+    def __init__(self, *args, cli_backend: Optional[Union[str, Any]] = None, **kwargs):
+        """Initialize Agent with CLI backend string resolution.
+        
+        Args:
+            *args: Positional arguments for core Agent
+            cli_backend: CLI backend for delegating full turns. Accepts:
+                - str: Backend ID ("claude-code", "codex-cli") - resolved in wrapper
+                - CliBackendProtocol: Pre-resolved backend instance
+                - callable: Factory function returning CliBackendProtocol
+                - None: No CLI backend
+            **kwargs: Keyword arguments for core Agent
+        """
+        # Resolve string CLI backends to instances in wrapper layer
+        if isinstance(cli_backend, str):
+            cli_backend = self._resolve_string_backend(cli_backend)
+        
+        # Pass resolved backend to core Agent
+        super().__init__(*args, cli_backend=cli_backend, **kwargs)
+    
+    def _resolve_string_backend(self, backend_id: str) -> Any:
+        """Resolve string backend ID to CliBackendProtocol instance.
+        
+        Args:
+            backend_id: Backend identifier (e.g., "claude-code")
+            
+        Returns:
+            CliBackendProtocol instance
+            
+        Raises:
+            ImportError: If CLI backends module not available
+            ValueError: If backend_id is not registered
+        """
+        try:
+            from .cli_backends import resolve_cli_backend
+            return resolve_cli_backend(backend_id)
+        except ImportError:
+            raise ImportError(
+                f"CLI backend '{backend_id}' requested but CLI backends not available. "
+                "This may indicate a packaging or installation issue."
+            )
+
+
+# Export the wrapper Agent as the default for import from praisonai
+__all__ = ["Agent"]

{praisonai-4.6.28 → praisonai-4.6.30}/praisonai/agents_generator.py

@@ -140,6 +140,51 @@ def sanitize_agent_name_for_autogen_v4(name):
     
     return sanitized
 
+def _resolve_yaml_cli_backend(cli_backend_config, logger):
+    """Resolve a YAML ``cli_backend`` field to a CliBackendProtocol instance.
+
+    Accepts ``None`` (no backend), a string id (e.g. ``"claude-code"``), or a
+    dict of shape ``{"id": "claude-code", "overrides": {...}}``. Returns
+    ``None`` on any error after logging a warning, so YAML parsing never raises.
+
+    Kept at module scope so it is unit-testable without constructing a full
+    ``AgentsGenerator`` instance.
+    """
+    if not cli_backend_config:
+        return None
+
+    # Pre-seed label from config before import so we can show it in error logs
+    if isinstance(cli_backend_config, str):
+        label = cli_backend_config
+    elif isinstance(cli_backend_config, dict):
+        label = cli_backend_config.get('id') or "<missing>"
+    else:
+        label = type(cli_backend_config).__name__
+
+    try:
+        from praisonai.cli_backends import resolve_cli_backend
+        if isinstance(cli_backend_config, str):
+            return resolve_cli_backend(cli_backend_config)
+        if isinstance(cli_backend_config, dict):
+            backend_id = cli_backend_config.get('id')
+            if not backend_id:
+                raise ValueError("cli_backend dict must contain an 'id' field")
+            overrides = cli_backend_config.get('overrides') or {}
+            return resolve_cli_backend(backend_id, overrides=overrides)
+        raise ValueError(
+            f"cli_backend must be string or dict, got: {type(cli_backend_config).__name__}"
+        )
+    except ImportError:
+        logger.warning(
+            "CLI backend '%s' requested but not available", label
+        )
+    except Exception as e:
+        logger.warning(
+            "Failed to resolve CLI backend '%s': %s", label, e
+        )
+    return None
+
+
 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):
         """
@@ -187,7 +232,11 @@ class AgentsGenerator:
         elif os.environ.get('LOGLEVEL'):
             self.logger.setLevel(getattr(logging, os.environ.get('LOGLEVEL', 'INFO').upper(), logging.INFO))
         
-        # Initialize tool registry (replaces globals() pattern)
+        # Initialize tool resolver (single source of truth for tool resolution)
+        from .tool_resolver import ToolResolver
+        self.tool_resolver = ToolResolver()
+        
+        # Keep tool registry for backward compatibility with autogen adapters
         self.tool_registry = ToolRegistry()
         self.tool_registry.register_builtin_autogen_adapters()
         
@@ -456,27 +505,32 @@ class AgentsGenerator:
         topic = config.get('input', config.get('topic', ''))
         tools_dict = {}
         
-        # Only try to use praisonai_tools if it's available and needed
+        # Use ToolResolver to get available tools (consistent tool resolution)
         if PRAISONAI_TOOLS_AVAILABLE and (CREWAI_AVAILABLE or AUTOGEN_AVAILABLE or PRAISONAI_AVAILABLE or AG2_AVAILABLE):
-            tools_dict = {
-                'CodeDocsSearchTool': CodeDocsSearchTool(),
-                'CSVSearchTool': CSVSearchTool(),
-                'DirectorySearchTool': DirectorySearchTool(),
-                'DOCXSearchTool': DOCXSearchTool(),
-                'DirectoryReadTool': DirectoryReadTool(),
-                'FileReadTool': FileReadTool(),
-                'TXTSearchTool': TXTSearchTool(),
-                'JSONSearchTool': JSONSearchTool(),
-                'MDXSearchTool': MDXSearchTool(),
-                'PDFSearchTool': PDFSearchTool(),
-                'RagTool': RagTool(),
-                'ScrapeElementFromWebsiteTool': ScrapeElementFromWebsiteTool(),
-                'ScrapeWebsiteTool': ScrapeWebsiteTool(),
-                'WebsiteSearchTool': WebsiteSearchTool(),
-                'XMLSearchTool': XMLSearchTool(),
-                'YoutubeChannelSearchTool': YoutubeChannelSearchTool(),
-                'YoutubeVideoSearchTool': YoutubeVideoSearchTool(),
-            }
+            try:
+                # Get available tools from the resolver
+                available_tools = self.tool_resolver.list_available()
+                tools_dict = {}
+                
+                # Standard praisonai-tools tool names
+                standard_tools = [
+                    'CodeDocsSearchTool', 'CSVSearchTool', 'DirectorySearchTool', 'DOCXSearchTool',
+                    'DirectoryReadTool', 'FileReadTool', 'TXTSearchTool', 'JSONSearchTool',
+                    'MDXSearchTool', 'PDFSearchTool', 'RagTool', 'ScrapeElementFromWebsiteTool',
+                    'ScrapeWebsiteTool', 'WebsiteSearchTool', 'XMLSearchTool',
+                    'YoutubeChannelSearchTool', 'YoutubeVideoSearchTool',
+                ]
+                
+                # Resolve only tools that are actually available
+                for tool_name in standard_tools:
+                    if tool_name in available_tools:
+                        resolved_tool = self.tool_resolver.resolve(tool_name)
+                        if resolved_tool is not None:
+                            tools_dict[tool_name] = resolved_tool() if inspect.isclass(resolved_tool) else resolved_tool
+                            
+            except Exception as e:
+                self.logger.debug(f"Error resolving praisonai_tools: {e}")
+                tools_dict = {}
             
             # Add tools from class names
             for tool_class in self.tools:
@@ -1066,9 +1120,7 @@ class AgentsGenerator:
         tasks = []
         tasks_dict = {}
 
-        # Import tool resolver (lazy import to avoid circular deps)
-        from praisonai.tool_resolver import ToolResolver
-        tool_resolver = ToolResolver()
+        # Use existing tool resolver instance
         
         # Load tools from local tools.py (backward compat)
         tools_list = self.load_tools_from_tools_py()
@@ -1144,7 +1196,7 @@ class AgentsGenerator:
                     )
                     
                     if not already_loaded:
-                        resolved_tool = tool_resolver.resolve(tool_name)
+                        resolved_tool = self.tool_resolver.resolve(tool_name)
                         if resolved_tool is not None:
                             agent_tools.append(resolved_tool)
                             self.logger.debug(f"Resolved tool '{tool_name}' for agent {role}")
@@ -1240,6 +1292,11 @@ class AgentsGenerator:
             # string, or a full SkillsConfig dict (paths/dirs/auto_discover).
             agent_skills = details.get('skills')
 
+            # H17: CLI Backend support - delegates full turns to external CLI tools
+            cli_backend_resolved = _resolve_yaml_cli_backend(
+                details.get('cli_backend'), self.logger
+            )
+
             agent = PraisonAgent(
                 name=role_filled,
                 role=role_filled,
@@ -1257,6 +1314,7 @@ class AgentsGenerator:
                 approval=approval_config,
                 output=output_config,
                 skills=agent_skills,
+                cli_backend=cli_backend_resolved,
             )
             
             if self.agent_callback:

praisonai-4.6.30/praisonai/bots/_auth.py

@@ -0,0 +1,140 @@
+"""
+Unknown User Handler for PraisonAI Bots.
+
+Handles unknown users according to the configured policy:
+- deny: Drop messages silently (backward compatible)
+- allow: Allow all users  
+- pair: Use pairing flow for owner approval
+
+Shared across all bot adapters (Telegram, Discord, Slack, WhatsApp).
+"""
+
+import logging
+import time
+from typing import Optional, Literal, Dict, Any, Callable, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from praisonaiagents.bots import BotConfig, BotMessage
+    from praisonai.gateway.pairing import PairingStore
+
+logger = logging.getLogger(__name__)
+
+
+class UnknownUserHandler:
+    """Handler for unknown users in bot interactions.
+    
+    Provides centralized logic for handling users not in the allowed_users list.
+    Supports rate limiting and pairing flow for secure user approval.
+    """
+    
+    def __init__(
+        self, 
+        config: "BotConfig", 
+        pairing_store: Optional["PairingStore"] = None,
+        send_message_callback: Optional[Callable] = None
+    ):
+        self.config = config
+        self.pairing_store = pairing_store
+        self.send_message_callback = send_message_callback
+        
+        # Rate limiting: user_id -> last_code_generation_time
+        self._rate_limits: Dict[str, float] = {}
+        self._rate_limit_window = 600  # 10 minutes
+        
+    async def handle(self, message: "BotMessage") -> Literal["allow", "drop"]:
+        """Handle an unknown user message according to policy.
+        
+        Args:
+            message: The bot message from unknown user
+            
+        Returns:
+            "allow" if message should be processed, "drop" if it should be ignored
+        """
+        user_id = message.sender.user_id if message.sender else ""
+        platform = message.channel.channel_type if message.channel else "unknown"
+        
+        # Check if user is actually allowed
+        if self.config.is_user_allowed(user_id):
+            return "allow"
+        
+        # Apply policy
+        if self.config.unknown_user_policy == "deny":
+            logger.debug(f"Dropping message from unknown user {user_id} (policy: deny)")
+            return "drop"
+        
+        if self.config.unknown_user_policy == "allow":
+            return "allow"
+            
+        if self.config.unknown_user_policy == "pair":
+            return await self._handle_pairing(message, user_id, platform)
+        
+        # Fallback to deny
+        logger.warning(f"Unknown policy '{self.config.unknown_user_policy}', falling back to deny")
+        return "drop"
+    
+    async def _handle_pairing(self, message: "BotMessage", user_id: str, platform: str) -> Literal["allow", "drop"]:
+        """Handle pairing flow for unknown user.
+        
+        Returns:
+            "allow" if user is already paired, "drop" after sending pairing code
+        """
+        if not self.pairing_store:
+            logger.warning("Pairing policy set but no pairing store available")
+            return "drop"
+        
+        # Use channel_id for pairing, not user_id
+        channel_id = message.channel.channel_id if message.channel else user_id
+        
+        # Check if already paired
+        if self.pairing_store.is_paired(channel_id, platform):
+            logger.debug(f"Channel {channel_id} already paired for {platform}")
+            return "allow"
+        
+        # Rate limiting check - also key by channel_id
+        now = time.time()
+        
+        # Evict stale entries to keep the dict bounded
+        cutoff = now - self._rate_limit_window
+        self._rate_limits = {
+            cid: ts for cid, ts in self._rate_limits.items() if ts >= cutoff
+        }
+        
+        last_code_time = self._rate_limits.get(channel_id, 0)
+        if now - last_code_time < self._rate_limit_window:
+            logger.debug(f"Rate limited channel {channel_id} (last code: {now - last_code_time:.1f}s ago)")
+            return "drop"
+        
+        # Generate pairing code and send to user
+        try:
+            code = self.pairing_store.generate_code(channel_type=platform, channel_id=channel_id)
+            self._rate_limits[channel_id] = now
+            
+            # Send pairing instructions to user
+            await self._send_pairing_instructions(message, code, platform)
+            
+            logger.info(f"Generated pairing code for {user_id} on {platform}: {code}")
+            
+        except Exception as e:
+            logger.error(f"Failed to generate pairing code for {user_id}: {e}")
+        
+        return "drop"  # Always drop after pairing flow
+    
+    async def _send_pairing_instructions(self, message: "BotMessage", code: str, platform: str):
+        """Send pairing instructions to the user.
+        
+        Uses the callback provided during initialization, or logs if not available.
+        """
+        instructions = (
+            f"Your pairing code: `{code}`\n"
+            f"Owner: `praisonai pairing approve {platform} {code}`"
+        )
+        
+        # Try to use the send message callback
+        if self.send_message_callback and message.channel:
+            try:
+                await self.send_message_callback(message.channel.channel_id, instructions)
+            except Exception as e:
+                logger.warning(f"Failed to send pairing instructions: {e}")
+        else:
+            logger.warning("Cannot send pairing instructions - no callback available")
+            logger.info(f"Pairing instructions for {message.sender.user_id if message.sender else 'unknown'}: {instructions}")