fix(wrapper): resolve 3 architectural gaps in praisonai wrapper layer

- Fix dual CLI entry points with semantic drift by making Typer single dispatcher
- Fix thread-unsafe module-level lazy state with proper synchronization
- Fix closed framework-adapter registry with proper registry pattern and entry points

Addresses core architecture violations of protocol-driven core, performance-first,
and multi-agent + async safe by default principles.

Fixes #1533

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

Author: praisonai-triage-agent[bot]

src/praisonai/praisonai/__init__.py

@@ -27,26 +27,37 @@
     'LocalManagedConfig',
 ]
 
-# Telemetry initialization state
+# Telemetry initialization state - thread-safe
+import threading
+
+_telemetry_lock = threading.Lock()
 _telemetry_initialized = False
 
 def _ensure_telemetry_defaults() -> None:
-    """Apply telemetry env defaults exactly once, on first observability use."""
+    """Apply telemetry env defaults exactly once, on first observability use.
+    
+    Thread-safe implementation using double-checked locking pattern.
+    """
     global _telemetry_initialized
     if _telemetry_initialized:
         return
-    import os
-    langfuse_configured = bool(
-        os.getenv("LANGFUSE_PUBLIC_KEY")
-        or os.path.exists(os.path.expanduser("~/.praisonai/langfuse.env"))
-    )
-    if langfuse_configured:
-        # Explicitly enable OTEL for Langfuse integration
-        os.environ["OTEL_SDK_DISABLED"] = "false"
-    else:
-        os.environ.setdefault("OTEL_SDK_DISABLED", "true")
-    os.environ.setdefault("EC_TELEMETRY", "false")  # respect user overrides
-    _telemetry_initialized = True
+    
+    with _telemetry_lock:
+        if _telemetry_initialized:
+            return
+        
+        import os
+        langfuse_configured = bool(
+            os.getenv("LANGFUSE_PUBLIC_KEY")
+            or os.path.exists(os.path.expanduser("~/.praisonai/langfuse.env"))
+        )
+        if langfuse_configured:
+            # Explicitly enable OTEL for Langfuse integration
+            os.environ["OTEL_SDK_DISABLED"] = "false"
+        else:
+            os.environ.setdefault("OTEL_SDK_DISABLED", "true")
+        os.environ.setdefault("EC_TELEMETRY", "false")  # respect user overrides
+        _telemetry_initialized = True
 
 
 # Lazy loading for heavy imports

src/praisonai/praisonai/__main__.py

@@ -3,118 +3,43 @@
 PraisonAI CLI — Unified Entry Point.
 
 Single entry point for all CLI invocations.
-Routes to Typer-based commands for known subcommands,
-falls back to legacy argparse for direct prompts and YAML files.
+Makes Typer the single dispatcher with narrow legacy shim for bare prompts/YAML.
 
 Design:
-  - Typer-first: all registered commands auto-discovered via Click
-  - Legacy fallback: prompts, .yaml paths, and deprecated --flags
-  - No manual command lists needed — adding a Typer command Just Works
+  - Typer owns all command resolution
+  - Legacy shim only for bare prompt/YAML invocations via Typer callback
+  - Fail loud on registration errors - no silent degradation
 """
 
 import sys
 
 
-# ---------------------------------------------------------------------------
-# Internal helpers
-# ---------------------------------------------------------------------------
-
-_typer_commands_cache = None
-
-
-def _get_typer_commands():
-    """Auto-discover registered Typer commands via Click introspection.
-
-    Returns a set of command names that the Typer app knows about.
-    This is populated from app.py's register_commands() — no manual
-    lists to maintain.
+def _is_legacy_invocation(argv: list[str]) -> bool:
+    """Check if this is a bare prompt or bare YAML invocation.
+    
+    Legacy invocations are:
+    - Bare YAML file: "agents.yaml"
+    - Free-text prompt: "Create a weather app"
+    
+    All other invocations should be handled by Typer commands.
     """
-    global _typer_commands_cache
-    if _typer_commands_cache is not None:
-        return _typer_commands_cache
-
-    try:
-        from praisonai.cli.app import app, register_commands
-        register_commands()
-
-        import typer.main
-        import click
-        click_app = typer.main.get_command(app)
-        ctx = click.Context(click_app, info_name="praisonai")
-        _typer_commands_cache = set(click_app.list_commands(ctx))
-    except Exception:
-        _typer_commands_cache = set()
-
-    return _typer_commands_cache
-
-
-def _find_first_command(argv):
-    """Find the first non-flag argument in argv.
-
-    Skips global flags (--json, --verbose, etc.) and their values.
-    Returns the first positional arg, or None if only flags are present.
-    """
-    # Flags that consume a following value
-    VALUE_FLAGS = {"--output-format", "-o"}
-
-    skip_next = False
     for arg in argv:
-        if skip_next:
-            skip_next = False
-            continue
         if arg.startswith("-"):
-            if arg in VALUE_FLAGS:
-                skip_next = True
             continue
-        return arg  # First non-flag arg
-    return None
-
-
-def _run_typer(argv):
-    """Dispatch to the Typer CLI app."""
-    from praisonai.cli.app import app, register_commands
-    register_commands()  # idempotent
-
-    original = sys.argv
-    sys.argv = ["praisonai"] + list(argv)
-    try:
-        app()
-    except SystemExit as e:
-        sys.exit(e.code if isinstance(e.code, int) else 0)
-    finally:
-        sys.argv = original
+        # Check if it's a YAML file or contains spaces (free-text prompt)
+        return (arg.endswith((".yaml", ".yml")) or 
+                " " in arg or 
+                not arg.isidentifier())
+    return False
 
 
-def _run_legacy(argv):
-    """Dispatch to the legacy argparse CLI (prompts, YAML, deprecated flags)."""
-    from praisonai.cli.main import PraisonAI
-
-    original = sys.argv
-    sys.argv = ["praisonai"] + list(argv)
-    try:
-        praison = PraisonAI()
-        result = praison.main()
-        code = 0 if result is None else (1 if result is False else 0)
-        sys.exit(code)
-    except SystemExit as e:
-        sys.exit(e.code if isinstance(e.code, int) else 0)
-    finally:
-        sys.argv = original
-
-
-# ---------------------------------------------------------------------------
-# Main entry point
-# ---------------------------------------------------------------------------
-
 def main():
-    """Unified CLI entry point — Typer-first, legacy fallback.
+    """Unified CLI entry point - Typer is the single dispatcher.
 
     Routing rules (in order):
-      1. --version / -V          → print version and exit
-      2. --help / -h             → Typer help (global or command-level)
-      3. No arguments            → Typer interactive TUI
-      4. First arg is a Typer cmd→ Typer (auto-discovered from app.py)
-      5. Everything else         → Legacy (prompt, .yaml, deprecated flags)
+      1. --version / -V    → print version and exit
+      2. Legacy invocation → legacy shim (bare prompts/YAML only)
+      3. Everything else   → Typer (owns all subcommands)
     """
     argv = sys.argv[1:]
 
@@ -124,30 +49,36 @@ def main():
         print(f"PraisonAI version {__version__}")
         return
 
-    # 2. Help flags → always Typer (global help or command help)
-    if "--help" in argv or "-h" in argv:
-        _run_typer(argv)
-        return
-
-    # 3. No arguments → Typer (interactive TUI)
-    if not argv:
-        _run_typer(argv)
+    # 2. Check for legacy invocation (bare prompt/YAML)
+    if _is_legacy_invocation(argv):
+        from praisonai.cli.main import PraisonAI
+        original = sys.argv
+        sys.argv = ["praisonai"] + list(argv)
+        try:
+            praison = PraisonAI()
+            result = praison.main()
+            code = 0 if result is None else (1 if result is False else 0)
+            sys.exit(code)
+        except SystemExit as e:
+            sys.exit(e.code if isinstance(e.code, int) else 0)
+        finally:
+            sys.argv = original
         return
 
-    # 4. Find first non-flag argument and check if it's a Typer command
-    first_cmd = _find_first_command(argv)
-
-    if first_cmd is None:
-        # Only flags, no command → Typer handles global flags
-        _run_typer(argv)
-        return
-
-    if first_cmd in _get_typer_commands():
-        # Known Typer command → Typer
-        _run_typer(argv)
-    else:
-        # Prompt, YAML file, or legacy invocation → legacy
-        _run_legacy(argv)
+    # 3. All other invocations → Typer (fail loud on registration errors)
+    from praisonai.cli.app import app, register_commands
+    
+    # CRITICAL: Fail loud - do not swallow registration exceptions
+    register_commands()  # Let any ImportError/other exceptions propagate
+    
+    original = sys.argv
+    sys.argv = ["praisonai"] + list(argv)
+    try:
+        app()
+    except SystemExit as e:
+        sys.exit(e.code if isinstance(e.code, int) else 0)
+    finally:
+        sys.argv = original
 
 
 if __name__ == "__main__":

src/praisonai/praisonai/_async_bridge.py

@@ -34,6 +34,18 @@ def get(self) -> asyncio.AbstractEventLoop:
                 )
                 self._thread.start()
             return self._loop
+            
+    def get_unlocked(self) -> asyncio.AbstractEventLoop:
+        """Get loop assuming caller holds _lock. For run_sync() use only."""
+        if self._loop is None or self._loop.is_closed():
+            self._loop = asyncio.new_event_loop()
+            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:
@@ -87,12 +99,11 @@ def run_sync(coro: Awaitable[T], *, timeout: float | None = _DEFAULT_TIMEOUT) ->
     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())
+    # Submit the coroutine inside the lock to prevent shutdown races
+    with _BG._lock:
+        loop = _BG.get_unlocked()  # get loop while holding lock
+        fut: Future = asyncio.run_coroutine_threadsafe(coro, loop)
+    
     return fut.result(timeout=timeout)
 
 

src/praisonai/praisonai/agents_generator.py

@@ -17,10 +17,8 @@
 import keyword
 
 # Import new architecture components
-from .framework_adapters import (
-    FrameworkAdapter, CrewAIAdapter, AutoGenAdapter, 
-    AutoGenV4Adapter, AG2Adapter, PraisonAIAdapter
-)
+from .framework_adapters.base import FrameworkAdapter
+from .framework_adapters.registry import FrameworkAdapterRegistry
 from .tool_registry import ToolRegistry
 
 # Import availability flags
@@ -51,14 +49,8 @@
 except ImportError:
     pass
 
-# Registry of available adapters (lazy-loaded)
-FRAMEWORK_ADAPTERS = {
-    "crewai": CrewAIAdapter,
-    "autogen": AutoGenAdapter, 
-    "autogen_v4": AutoGenV4Adapter,
-    "ag2": AG2Adapter,
-    "praisonai": PraisonAIAdapter
-}
+# Framework adapter registry - now uses proper registry pattern
+# This replaces the hardcoded FRAMEWORK_ADAPTERS dict
 
 # Note: OTEL_SDK_DISABLED moved to CLI entry point per issue requirements
 
@@ -258,12 +250,8 @@ def _get_framework_adapter(self, framework: str) -> FrameworkAdapter:
         Raises:
             ValueError: If framework is not supported
         """
-        if framework not in FRAMEWORK_ADAPTERS:
-            raise ValueError(f"Unsupported framework: {framework}. "
-                           f"Supported frameworks: {list(FRAMEWORK_ADAPTERS.keys())}")
-        
-        adapter_class = FRAMEWORK_ADAPTERS[framework]
-        return adapter_class()
+        adapter_registry = FrameworkAdapterRegistry.get_instance()
+        return adapter_registry.create(framework)
 
     def _merge_cli_config(self, config, cli_config):
         """

src/praisonai/praisonai/async_agent_scheduler.py

@@ -7,6 +7,7 @@
 
 import asyncio
 import logging
+import threading
 from datetime import datetime
 from typing import Optional, Dict, Any, Callable, Union
 from abc import ABC, abstractmethod
@@ -106,16 +107,25 @@ def __init__(
         self._success_count = 0  
         self._failure_count = 0
 
-        # Created lazily on first async entry — binds to the caller's loop
+        # Sync lock for async primitives creation and bound loop tracking
+        self._primitives_lock = threading.Lock()
         self._cancel_event: Optional[asyncio.Event] = None
         self._stats_lock: Optional[asyncio.Lock] = None
+        self._bound_loop: Optional[asyncio.AbstractEventLoop] = None
 
     def _ensure_async_primitives(self) -> None:
-        """Create async primitives if they don't exist yet."""
-        if self._cancel_event is None:
-            self._cancel_event = asyncio.Event()
-        if self._stats_lock is None:
-            self._stats_lock = asyncio.Lock()
+        """Create async primitives if they don't exist yet.
+        
+        Thread-safe and loop-aware: primitives are bound to the current running loop.
+        If called from a different loop, new primitives are created.
+        """
+        loop = asyncio.get_running_loop()  # must be called from a coroutine
+        
+        with self._primitives_lock:
+            if self._bound_loop is not loop:
+                self._cancel_event = asyncio.Event()
+                self._stats_lock = asyncio.Lock()
+                self._bound_loop = loop
 
     async def start(
         self,