open-swarm 0.1.1744936173__py3-none-any.whl → 0.1.1744936297__py3-none-any.whl

swarm/extensions/blueprint/blueprint_base.py

@@ -1,3 +1,16 @@
+# --- REMOVE noisy debug/framework prints unless SWARM_DEBUG=1 ---
+import os
+
+def _should_debug():
+    return os.environ.get("SWARM_DEBUG") == "1"
+
+def _debug_print(*args, **kwargs):
+    if _should_debug():
+        print(*args, **kwargs)
+
+def _framework_print(*args, **kwargs):
+    if _should_debug():
+        print(*args, **kwargs)
 
 # --- Content for src/swarm/extensions/blueprint/blueprint_base.py ---
 import logging
@@ -8,9 +21,98 @@ from pathlib import Path
 from django.apps import apps # Import Django apps registry
 
 # Keep the function import
-from swarm.extensions.config.config_loader import get_profile_from_config
+from swarm.extensions.config.config_loader import get_profile_from_config, _substitute_env_vars
+
+from openai import AsyncOpenAI
+from agents import set_default_openai_client
+from .slash_commands import slash_registry, SlashCommandRegistry
+from blueprint_agents import *  # Import all from blueprint_agents
 
 logger = logging.getLogger(__name__)
+from rich.console import Console
+import traceback
+
+# --- PATCH: Suppress OpenAI tracing/telemetry errors if using LiteLLM/custom endpoint ---
+import logging
+import os
+if os.environ.get("LITELLM_BASE_URL") or os.environ.get("OPENAI_BASE_URL"):
+    # Silence openai.agents tracing/telemetry errors
+    logging.getLogger("openai.agents").setLevel(logging.CRITICAL)
+    try:
+        import openai.agents.tracing
+        openai.agents.tracing.TracingClient = lambda *a, **kw: None
+    except Exception:
+        pass
+
+# --- Spinner/Status Message Enhancements ---
+# To be used by all blueprints for consistent UX
+import itertools
+import sys
+import threading
+import time
+
+class Spinner:
+    def __init__(self, message_sequence=None, interval=0.3, slow_threshold=10):
+        self.message_sequence = message_sequence or ['Generating.', 'Generating..', 'Generating...', 'Running...']
+        self.interval = interval
+        self.slow_threshold = slow_threshold  # seconds before 'Taking longer than expected'
+        self._stop_event = threading.Event()
+        self._thread = None
+        self._start_time = None
+
+    def start(self):
+        self._stop_event.clear()
+        self._start_time = time.time()
+        self._thread = threading.Thread(target=self._spin)
+        self._thread.start()
+
+    def _spin(self):
+        for msg in itertools.cycle(self.message_sequence):
+            if self._stop_event.is_set():
+                break
+            elapsed = time.time() - self._start_time
+            if elapsed > self.slow_threshold:
+                sys.stdout.write('\rGenerating... Taking longer than expected   ')
+            else:
+                sys.stdout.write(f'\r{msg}   ')
+            sys.stdout.flush()
+            time.sleep(self.interval)
+        sys.stdout.write('\r')
+        sys.stdout.flush()
+
+    def stop(self, final_message=''):
+        self._stop_event.set()
+        if self._thread:
+            self._thread.join()
+        if final_message:
+            sys.stdout.write(f'\r{final_message}\n')
+            sys.stdout.flush()
+
+# Usage Example (to be called in blueprints):
+# spinner = Spinner()
+# spinner.start()
+# ... do work ...
+# spinner.stop('Done!')
+
+def configure_openai_client_from_env():
+    """
+    Framework-level function: Always instantiate and set the default OpenAI client.
+    Prints out the config being used for debug.
+    """
+    import os
+    from agents import set_default_openai_client
+    from openai import AsyncOpenAI
+    base_url = os.environ.get("LITELLM_BASE_URL") or os.environ.get("OPENAI_BASE_URL")
+    api_key = os.environ.get("LITELLM_API_KEY") or os.environ.get("OPENAI_API_KEY")
+    _debug_print(f"[DEBUG] Using OpenAI client config: base_url={base_url}, api_key={'set' if api_key else 'NOT SET'}")
+    if base_url and api_key:
+        client = AsyncOpenAI(base_url=base_url, api_key=api_key)
+        set_default_openai_client(client)
+        _framework_print(f"[FRAMEWORK] Set default OpenAI client: base_url={base_url}, api_key={'set' if api_key else 'NOT SET'}")
+    else:
+        _framework_print("[FRAMEWORK] WARNING: base_url or api_key missing, OpenAI client not set!")
+
+configure_openai_client_from_env()
 
 class BlueprintBase(ABC):
     """
@@ -18,53 +120,157 @@ class BlueprintBase(ABC):
 
     Defines the core interface for blueprint initialization and execution.
     """
-    def __init__(self, blueprint_id: str, config_path: Optional[Path] = None):
-        """
-        Initializes the blueprint.
+    enable_terminal_commands: bool = False  # By default, terminal command execution is disabled
 
-        Args:
-            blueprint_id: A unique identifier for this blueprint instance.
-            config_path: Optional path to a specific swarm_config.json file.
-                         If None, the standard search logic will be used.
+    @classmethod
+    def main(cls):
         """
-        if not blueprint_id:
-             raise ValueError("blueprint_id cannot be empty or None") # Add validation
-        self.blueprint_id = blueprint_id
-        self.config_path = config_path # Note: config_path is currently unused if we rely on AppConfig
-        self._config: Optional[Dict[str, Any]] = None
-        self._llm_profile_name: Optional[str] = None
-        self._llm_profile_data: Optional[Dict[str, Any]] = None
-        self._markdown_output: bool = True # Default
-
-        logger.info(f"Initializing blueprint '{self.blueprint_id}' (Type: {self.__class__.__name__})")
-        self._load_and_process_config()
+        Standard CLI entry point for all blueprints.
+        Subclasses can override metadata/config_path if needed.
+        """
+        from swarm.extensions.blueprint.cli_handler import run_blueprint_cli
+        from pathlib import Path
+        swarm_version = getattr(cls, "SWARM_VERSION", "1.0.0")
+        config_path = getattr(cls, "DEFAULT_CONFIG_PATH", Path(__file__).parent / "swarm_config.json")
+        run_blueprint_cli(cls, swarm_version=swarm_version, default_config_path=config_path)
+
+    def display_splash_screen(self, animated: bool = False):
+        """Default splash screen. Subclasses can override for custom CLI/API branding."""
+        console = Console()
+        console.print(f"[bold cyan]Welcome to {self.__class__.__name__}![/]", style="bold")
+
+    def __init__(self, blueprint_id: str, config_path: Optional[Path] = None, enable_terminal_commands: Optional[bool] = None):
+        try:
+            if not blueprint_id:
+                raise ValueError("blueprint_id cannot be empty or None")
+            self.blueprint_id = blueprint_id
+            self.config_path = config_path # Note: config_path is currently unused if we rely on AppConfig
+            self._config: Optional[Dict[str, Any]] = None
+            self._llm_profile_name: Optional[str] = None
+            self._llm_profile_data: Optional[Dict[str, Any]] = None
+            self._markdown_output: bool = True # Default
+            # Allow per-instance override
+            if enable_terminal_commands is not None:
+                self.enable_terminal_commands = enable_terminal_commands
+            # Else: use class attribute (default False or set by subclass)
+
+            logger.info(f"Initializing blueprint '{self.blueprint_id}' (Type: {self.__class__.__name__})")
+            
+            # --- Ensure custom OpenAI client for custom LLM providers ---
+            import os
+
+            # Remove monkey patching and envvar hacks. Always pass config values directly.
+            # (Retain only explicit AsyncOpenAI client instantiation in blueprints)
+            # (No changes needed here for direct client pattern)
+
+            self._load_and_process_config()
+        except AttributeError as e:
+            logger.debug(f"[BlueprintBase.__init__] AttributeError: {e}")
+            traceback.print_exc()
+            raise
 
     def _load_and_process_config(self):
-        """Loads the main Swarm config and extracts relevant settings."""
+        """Loads the main Swarm config and extracts relevant settings. Falls back to empty config if Django unavailable or not found."""
+        import os
+        import json
+        from pathlib import Path
+        def redact(val):
+            if not isinstance(val, str) or len(val) <= 4:
+                return "****"
+            return val[:2] + "*" * (len(val)-4) + val[-2:]
+        def redact_dict(d):
+            if isinstance(d, dict):
+                return {k: (redact_dict(v) if not (isinstance(v, str) and ("key" in k.lower() or "token" in k.lower() or "secret" in k.lower())) else redact(v)) for k, v in d.items()}
+            elif isinstance(d, list):
+                return [redact_dict(item) for item in d]
+            return d
         try:
-            # --- Get config from the AppConfig instance ---
-            app_config_instance = apps.get_app_config('swarm')
-            # Assuming the loaded config is stored in an attribute named 'config'
-            # Adjust 'config' if your AppConfig uses a different attribute name
-            if not hasattr(app_config_instance, 'config') or not app_config_instance.config:
-                 logger.error("Swarm configuration not found on AppConfig instance. Was ready() called?")
-                 raise ValueError("Swarm configuration unavailable via AppConfig.")
-            self._config = app_config_instance.config
-            # --- End change ---
-
-            logger.debug(f"Blueprint '{self.blueprint_id}' using loaded Swarm config.")
-
-            # Determine LLM profile
-            self._llm_profile_name = self._config.get("settings", {}).get("default_llm_profile", "default")
-            logger.debug(f"Attempting to use LLM profile: '{self._llm_profile_name}'")
-
-            # Get substituted profile data
-            self._llm_profile_data = get_profile_from_config(self._config, self._llm_profile_name)
-            logger.info(f"Successfully loaded LLM profile '{self._llm_profile_name}'. Provider: {self._llm_profile_data.get('provider')}")
-
-            # Get markdown setting
+            try:
+                # --- Get config from the AppConfig instance (Django) ---
+                app_config_instance = apps.get_app_config('swarm')
+                if not hasattr(app_config_instance, 'config') or not app_config_instance.config:
+                    raise ValueError("AppConfig for 'swarm' does not have a valid 'config' attribute.")
+                config = app_config_instance.config
+                logger.debug("Loaded config from Django AppConfig.")
+            except Exception as e:
+                if _should_debug():
+                    logger.warning(f"Falling back to CLI/home config due to error: {e}")
+                config = None
+                # 1. CLI argument (not handled here, handled in cli_handler)
+                # 2. Current working directory
+                cwd_config = Path.cwd() / "swarm_config.json"
+                if cwd_config.exists():
+                    with open(cwd_config, 'r') as f:
+                        config = json.load(f)
+                # 3. XDG_CONFIG_HOME or ~/.config/swarm/swarm_config.json
+                elif os.environ.get("XDG_CONFIG_HOME"):
+                    xdg_config = Path(os.environ["XDG_CONFIG_HOME"]) / "swarm" / "swarm_config.json"
+                    if xdg_config.exists():
+                        with open(xdg_config, 'r') as f:
+                            config = json.load(f)
+                elif (Path.home() / ".config/swarm/swarm_config.json").exists():
+                    with open(Path.home() / ".config/swarm/swarm_config.json", 'r') as f:
+                        config = json.load(f)
+                # 4. Legacy fallback: ~/.swarm/swarm_config.json
+                elif (Path.home() / ".swarm/swarm_config.json").exists():
+                    with open(Path.home() / ".swarm/swarm_config.json", 'r') as f:
+                        config = json.load(f)
+                # 5. Fallback: OPENAI_API_KEY envvar
+                elif os.environ.get("OPENAI_API_KEY"):
+                    config = {
+                        "llm": {"default": {"provider": "openai", "model": "gpt-3.5-turbo", "api_key": os.environ["OPENAI_API_KEY"]}},
+                        "settings": {"default_llm_profile": "default", "default_markdown_output": True},
+                        "blueprints": {},
+                        "llm_profile": "default",
+                        "mcpServers": {}
+                    }
+                    logger.info("No config file found, using default config with OPENAI_API_KEY for CLI mode.")
+                else:
+                    config = {}
+                    logger.warning("No config file found and OPENAI_API_KEY is not set. Using empty config. CLI blueprints may fail if LLM config is required.")
+                if config is not None:
+                    config = _substitute_env_vars(config)
+                self._config = config or {}
+
+            # --- After config is loaded, set OpenAI client from config if possible ---
+            try:
+                llm_profiles = self._config.get("llm", {})
+                default_profile = llm_profiles.get("default", {})
+                base_url = default_profile.get("base_url")
+                api_key = default_profile.get("api_key")
+                # Expand env vars if present
+                import os
+                if base_url and base_url.startswith("${"):
+                    var = base_url[2:-1]
+                    base_url = os.environ.get(var, base_url)
+                if api_key and api_key.startswith("${"):
+                    var = api_key[2:-1]
+                    api_key = os.environ.get(var, api_key)
+                if base_url and api_key:
+                    from openai import AsyncOpenAI
+                    from agents import set_default_openai_client
+                    _debug_print(f"[DEBUG] (config) Setting OpenAI client: base_url={base_url}, api_key={'set' if api_key else 'NOT SET'}")
+                    client = AsyncOpenAI(base_url=base_url, api_key=api_key)
+                    set_default_openai_client(client)
+            except Exception as e:
+                _debug_print(f"[DEBUG] Failed to set OpenAI client from config: {e}")
+
+            # --- Debug: Print and log redacted config ---
+            redacted_config = redact_dict(self._config)
+            logger.debug(f"Loaded config (redacted): {json.dumps(redacted_config, indent=2)}")
+
+            # --- Process LLM profile name and data ---
+            settings_section = self._config.get("settings", {})
+            llm_section = self._config.get("llm", {})
+            default_profile = settings_section.get("default_llm_profile") or "default"
+            self._llm_profile_name = self._config.get("llm_profile") or default_profile
+            if "profiles" in llm_section:
+                self._llm_profile_data = llm_section["profiles"].get(self._llm_profile_name, {})
+            else:
+                self._llm_profile_data = llm_section.get(self._llm_profile_name, {})
+
             blueprint_specific_settings = self._config.get("blueprints", {}).get(self.blueprint_id, {})
-            global_markdown_setting = self._config.get("settings", {}).get("default_markdown_output", True)
+            global_markdown_setting = settings_section.get("default_markdown_output", True)
             self._markdown_output = blueprint_specific_settings.get("markdown_output", global_markdown_setting)
             logger.debug(f"Markdown output for '{self.blueprint_id}': {self._markdown_output}")
 
@@ -96,6 +302,19 @@ class BlueprintBase(ABC):
              raise RuntimeError("LLM profile name accessed before initialization or after failure.")
         return self._llm_profile_name
 
+    @property
+    def slash_commands(self) -> SlashCommandRegistry:
+        """Access the global slash command registry. Blueprints can register new commands here."""
+        return slash_registry
+
+    def get_llm_profile(self, profile_name: str) -> dict:
+        """Returns the LLM profile dict for the given profile name from config, or empty dict if not found.
+        Supports both llm.profiles and direct llm keys for backward compatibility."""
+        llm_section = self.config.get("llm", {})
+        if "profiles" in llm_section:
+            return llm_section["profiles"].get(profile_name, {})
+        return llm_section.get(profile_name, {})
+
     @property
     def should_output_markdown(self) -> bool:
         """Returns whether the blueprint should format output as Markdown."""
@@ -106,6 +325,9 @@ class BlueprintBase(ABC):
         """
         The main execution method for the blueprint.
         """
+        import os
+        import pprint
+        logger.debug("ENVIRONMENT DUMP BEFORE MODEL CALL:")
+        pprint.pprint(dict(os.environ))
         raise NotImplementedError("Subclasses must implement the 'run' method.")
         yield {}
-

swarm/extensions/blueprint/blueprint_discovery.py

@@ -54,35 +54,38 @@ def discover_blueprints(blueprint_dir: str) -> Dict[str, Type[BlueprintBase]]:
         return blueprints
 
     # Iterate over items inside the base blueprint directory
-    for item_name in os.listdir(base_dir):
-        item_path = base_dir / item_name
-
-        if not item_path.is_dir():
+    for subdir in base_dir.iterdir():
+        if not subdir.is_dir():
             continue # Skip files directly under blueprints/
 
         # Use directory name as blueprint name (e.g., 'echocraft')
-        blueprint_name = item_name
-        logger.debug(f"Processing potential blueprint '{blueprint_name}' in directory: {item_name}")
+        blueprint_name = subdir.name
+        logger.debug(f"Processing potential blueprint '{blueprint_name}' in directory: {subdir.name}")
 
         # Look for the specific .py file, e.g., blueprint_echocraft.py
         py_file_name = f"blueprint_{blueprint_name}.py"
-        py_file_path = item_path / py_file_name
+        py_file_path = subdir / py_file_name
 
         if not py_file_path.is_file():
             # Also check for just {blueprint_name}.py if that's a convention
             alt_py_file_name = f"{blueprint_name}.py"
-            alt_py_file_path = item_path / alt_py_file_name
+            alt_py_file_path = subdir / alt_py_file_name
             if alt_py_file_path.is_file():
                  py_file_path = alt_py_file_path # Use the alternative path
                  py_file_name = alt_py_file_name
                  logger.debug(f"Found alternative blueprint file: {py_file_name}")
             else:
-                 logger.warning(f"Skipping directory '{item_name}': Neither '{py_file_name}' nor '{alt_py_file_name}' found.")
+                 logger.warning(f"Skipping directory '{subdir.name}': Neither '{py_file_name}' nor '{alt_py_file_name}' found.")
                  continue
 
 
         # Construct module import path, e.g., blueprints.echocraft.blueprint_echocraft
-        module_import_path = f"{base_dir.name}.{item_name}.{py_file_path.stem}"
+        if py_file_path.name.startswith('blueprint_gatcha'):
+            module_import_path = f"swarm.blueprints.gatcha.{py_file_path.stem}"
+        elif py_file_path.name.startswith('blueprint_'):
+            module_import_path = f"swarm.blueprints.{subdir.name}.{py_file_path.stem}"
+        else:
+            continue
 
         try:
             # Ensure parent directory is in path
@@ -123,4 +126,3 @@ def discover_blueprints(blueprint_dir: str) -> Dict[str, Type[BlueprintBase]]:
 
     logger.info(f"Blueprint discovery complete. Found: {list(blueprints.keys())}")
     return blueprints
-

swarm/extensions/blueprint/cli_handler.py

@@ -2,8 +2,10 @@ import argparse
 import asyncio
 import json
 import logging
+import os
 import signal
 import sys
+from dotenv import load_dotenv
 from pathlib import Path
 from typing import Any, Dict, Optional, Type
 
@@ -14,6 +16,19 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger("swarm.cli")
 
+# --- DEBUG PRINTS REMOVED BY CASCADE ---
+# print(f"[DEBUG] CLI handler startup: sys.argv={sys.argv}")
+# print(f"[DEBUG] CLI handler startup: LITELLM_MODEL={os.environ.get('LITELLM_MODEL')}, DEFAULT_LLM={os.environ.get('DEFAULT_LLM')}")
+
+# --- FORCE LOAD .env EARLY for CLI/LLM ---
+project_root = Path(__file__).parent.parent.parent.parent  # /home/chatgpt/open-swarm
+dotenv_path = project_root / ".env"
+load_dotenv(dotenv_path=dotenv_path, override=True)
+# print(f"[DEBUG] Loaded .env from: {dotenv_path}")
+# print(f"[DEBUG] LITELLM_MODEL={os.environ.get('LITELLM_MODEL')}")
+# print(f"[DEBUG] LITELLM_BASE_URL={os.environ.get('LITELLM_BASE_URL')}")
+# print(f"[DEBUG] LITELLM_API_KEY={'set' if os.environ.get('LITELLM_API_KEY') else 'NOT SET'}")
+
 async def _run_blueprint_async_with_shutdown(blueprint: 'BlueprintBase', instruction: str):
     """Runs the blueprint's async method and handles graceful shutdown."""
     loop = asyncio.get_running_loop()
@@ -40,55 +55,20 @@ async def _run_blueprint_async_with_shutdown(blueprint: 'BlueprintBase', instruc
                  logger.error(f"Unexpected error setting fallback signal handler for {sig.name}: {e}", exc_info=True)
 
 
-    # Wrap the main execution in a task to allow cancellation
-    main_task = loop.create_task(blueprint._run_non_interactive(instruction), name=f"BlueprintRun_{blueprint.__class__.__name__}")
-
-    # Wait for either the main task or the stop event
-    done, pending = await asyncio.wait(
-        [main_task, loop.create_task(stop_event.wait(), name="ShutdownWatcher")],
-        return_when=asyncio.FIRST_COMPLETED
-    )
+    # Instead of wrapping in a task and awaiting, use async for to support async generators
+    try:
+        async for chunk in blueprint._run_non_interactive(instruction):
+            # Print the full JSON chunk
+            print(json.dumps(chunk, ensure_ascii=False))
+            # If chunk contains 'messages', print each assistant message's content for CLI/test UX
+            if isinstance(chunk, dict) and 'messages' in chunk:
+                for msg in chunk['messages']:
+                    if msg.get('role') == 'assistant' and 'content' in msg:
+                        print(msg['content'])
+    except Exception as e:
+        logger.critical(f"Blueprint execution failed with unhandled exception: {e}", exc_info=True)
+        sys.exit(1)
 
-    # Cleanup signal handlers after wait returns
-    for sig in (signal.SIGINT, signal.SIGTERM):
-        try:
-            loop.remove_signal_handler(sig)
-        except NotImplementedError:
-            try:
-                signal.signal(sig, signal.SIG_DFL) # Restore default handler
-            except Exception:
-                pass # Ignore errors during cleanup
-
-    # Check if the stop event was triggered
-    if stop_event.is_set():
-        logger.warning("Graceful shutdown initiated. Cancelling main task...")
-        if not main_task.done():
-            main_task.cancel()
-            try:
-                # Wait briefly for cancellation to propagate and cleanup within the task
-                await asyncio.wait_for(main_task, timeout=10.0) # Increased timeout slightly
-            except asyncio.CancelledError:
-                logger.info("Main task successfully cancelled.")
-            except asyncio.TimeoutError:
-                logger.error("Main task did not cancel within timeout. Potential resource leak.")
-            except Exception as e:
-                logger.error(f"Error during task cancellation waiting: {e}", exc_info=True)
-        else:
-            logger.info("Main task already completed before cancellation request.")
-        # The _run_non_interactive's AsyncExitStack should handle MCP cleanup
-    else:
-        # If the main task finished first, check for exceptions
-        if main_task in done:
-            try:
-                main_task.result() # Raise exception if one occurred in the task
-                logger.debug("Main task completed successfully.")
-            except asyncio.CancelledError:
-                 logger.info("Main task was cancelled externally (unexpected).")
-            except Exception as e:
-                # Error should have been logged within _run_non_interactive
-                # We exit here because the main operation failed
-                logger.critical(f"Blueprint execution failed with unhandled exception: {e}", exc_info=True)
-                sys.exit(1) # Exit with error status if task failed
 
 
 def run_blueprint_cli(
@@ -149,14 +129,13 @@ def run_blueprint_cli(
     # --- Instantiate and Run Blueprint ---
     blueprint_instance: Optional['BlueprintBase'] = None
     try:
+        # Always provide a blueprint_id (use class name if not supplied by CLI args)
+        blueprint_id = getattr(args, 'blueprint_id', None) or getattr(blueprint_cls, 'DEFAULT_BLUEPRINT_ID', None) or blueprint_cls.__name__
         # Instantiate the blueprint, passing necessary config/flags
         blueprint_instance = blueprint_cls(
-            config_path_override=args.config_path,
-            profile_override=args.profile,
-            config_overrides=cli_config_overrides,
-            debug=args.debug,
-            quiet=args.quiet,
-            force_markdown=args.markdown,
+            blueprint_id,
+            config_path=args.config_path,
+
             # Pass necessary context if needed by __init__
             # default_config_path=default_config_path,
             # swarm_version=swarm_version
@@ -182,4 +161,3 @@ def run_blueprint_cli(
     finally:
         logger.debug("Blueprint CLI execution finished.")
         # Any final cleanup outside the async loop (rarely needed here)
-

swarm/extensions/blueprint/output_utils.py

@@ -4,6 +4,7 @@ Output utilities for Swarm blueprints.
 
 import json
 import logging
+import os
 import sys
 from typing import List, Dict, Any
 
@@ -11,6 +12,9 @@ from typing import List, Dict, Any
 try:
     from rich.markdown import Markdown
     from rich.console import Console
+    from rich.panel import Panel
+    from rich.text import Text
+    from rich.rule import Rule
     RICH_AVAILABLE = True
 except ImportError:
     RICH_AVAILABLE = False
@@ -28,6 +32,44 @@ def render_markdown(content: str) -> None:
     md = Markdown(content)
     console.print(md) # Rich handles flushing
 
+def ansi_box(title: str, content: str, color: str = "94", emoji: str = "🔎", border: str = "─", width: int = 70) -> str:
+    """Return a string or Panel with ANSI box formatting for search/analysis results using Rich if available."""
+    if RICH_AVAILABLE:
+        console = Console()
+        # Rich supports color names or hex, map color code to name
+        color_map = {
+            "94": "bright_blue",
+            "96": "bright_cyan",
+            "92": "bright_green",
+            "93": "bright_yellow",
+            "91": "bright_red",
+            "95": "bright_magenta",
+            "90": "grey82",
+        }
+        style = color_map.get(color, "bright_blue")
+        panel = Panel(
+            content,
+            title=f"{emoji} {title} {emoji}",
+            border_style=style,
+            width=width
+        )
+        # Return the rendered panel as a string for testability
+        with console.capture() as capture:
+            console.print(panel)
+        return capture.get()
+    # Fallback: legacy manual ANSI box
+    top = f"\033[{color}m{emoji} {border * (width - 4)} {emoji}\033[0m"
+    mid_title = f"\033[{color}m│ {title.center(width - 6)} │\033[0m"
+    lines = content.splitlines()
+    boxed = [top, mid_title, top]
+    for line in lines:
+        boxed.append(f"\033[{color}m│\033[0m {line.ljust(width - 6)} \033[{color}m│\033[0m")
+    boxed.append(top)
+    return "\n".join(boxed)
+
+def print_search_box(title: str, content: str, color: str = "94", emoji: str = "🔎"):
+    print(ansi_box(title, content, color=color, emoji=emoji))
+
 def pretty_print_response(messages: List[Dict[str, Any]], use_markdown: bool = False, spinner=None) -> None:
     """Format and print messages, optionally rendering assistant content as markdown."""
     # --- DEBUG PRINT ---
@@ -92,4 +134,40 @@ def pretty_print_response(messages: List[Dict[str, Any]], use_markdown: bool = F
             # --- DEBUG PRINT ---
             print(f"[DEBUG Skipping message {i} with role '{role}']", flush=True)
 
+def print_terminal_command_result(cmd: str, result: dict, max_lines: int = 10):
+    """
+    Render a terminal command result in the CLI with a shell prompt emoji, header, and Rich box.
+    - Header: 🐚 Ran terminal command
+    - Top line: colored, [basename(pwd)] > [cmd]
+    - Output: Rich Panel, max 10 lines, tailing if longer, show hint for toggle
+    """
+    if not RICH_AVAILABLE:
+        # Fallback to simple print
+        print(f"🐚 Ran terminal command\n[{os.path.basename(result['cwd'])}] > {cmd}")
+        lines = result['output'].splitlines()
+        if len(lines) > max_lines:
+            lines = lines[-max_lines:]
+            print("[Output truncated. Showing last 10 lines.]")
+        print("\n".join(lines))
+        return
 
+    console = Console()
+    cwd_base = os.path.basename(result['cwd'])
+    header = Text(f"🐚 Ran terminal command", style="bold yellow")
+    subheader = Rule(f"[{cwd_base}] > {cmd}", style="bright_black")
+    lines = result['output'].splitlines()
+    truncated = False
+    if len(lines) > max_lines:
+        lines = lines[-max_lines:]
+        truncated = True
+    output_body = "\n".join(lines)
+    panel = Panel(
+        output_body,
+        title="Output",
+        border_style="cyan",
+        subtitle="[Output truncated. Showing last 10 lines. Press [t] to expand.]" if truncated else "",
+        width=80
+    )
+    console.print(header)
+    console.print(subheader)
+    console.print(panel)