ciris-agent 1.7.7__py3-none-any.whl

main.py

@@ -0,0 +1,766 @@
+#!/usr/bin/env python3
+# Load environment variables from .env if present
+# Load from all standard config paths in priority order
+try:
+    from pathlib import Path
+
+    from dotenv import load_dotenv
+
+    # Priority order: ./env (highest), ~/ciris/.env, /etc/ciris/.env (lowest)
+    # Note: ~/.ciris/ is for keys/secrets only, NOT config!
+    config_paths = [
+        Path.cwd() / ".env",
+        Path.home() / "ciris" / ".env",
+        Path("/etc/ciris/.env"),
+    ]
+
+    for config_path in config_paths:
+        if config_path.exists():
+            load_dotenv(config_path, override=False)  # Don't override already-set vars
+
+except ImportError:
+    pass  # dotenv is optional; skip if not installed
+import asyncio
+import json
+import logging
+import os
+import signal
+import sys
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+import click
+
+from ciris_engine.logic.runtime.ciris_runtime import CIRISRuntime
+from ciris_engine.logic.utils.logging_config import setup_basic_logging
+from ciris_engine.logic.utils.runtime_utils import load_config
+from ciris_engine.schemas.dma.results import ActionSelectionDMAResult
+from ciris_engine.schemas.runtime.enums import HandlerActionType, ThoughtStatus
+from ciris_engine.schemas.runtime.models import Thought
+
+logger = logging.getLogger(__name__)
+
+
+def setup_signal_handlers(runtime: CIRISRuntime) -> None:
+    """Setup signal handlers for graceful shutdown."""
+    shutdown_initiated = {"value": False}  # Use dict to allow modification in nested function
+
+    def signal_handler(signum: int, frame: Any) -> None:
+        if shutdown_initiated["value"]:
+            logger.warning(f"Signal {signum} received again, forcing immediate exit")
+            # Don't call sys.exit() in async context - just raise to let Python handle it
+            raise KeyboardInterrupt("Forced shutdown")
+
+        shutdown_initiated["value"] = True
+        logger.info(f"Received signal {signum}, requesting graceful shutdown...")
+
+        try:
+            runtime.request_shutdown(f"Signal {signum}")
+        except Exception as e:
+            logger.error(f"Error during shutdown request: {e}")
+            # Don't call sys.exit() in async context - raise instead
+            raise KeyboardInterrupt("Shutdown error") from e
+
+    signal.signal(signal.SIGTERM, signal_handler)
+    signal.signal(signal.SIGINT, signal_handler)
+
+
+def setup_global_exception_handler() -> None:
+    """Setup global exception handler to catch all uncaught exceptions."""
+
+    def handle_exception(exc_type: type[BaseException], exc_value: BaseException, exc_traceback: Any) -> None:
+        if issubclass(exc_type, KeyboardInterrupt):
+            # Let KeyboardInterrupt be handled by signal handlers
+            sys.__excepthook__(exc_type, exc_value, exc_traceback)
+            return
+
+        logger.error("UNCAUGHT EXCEPTION:", exc_info=(exc_type, exc_value, exc_traceback))
+        logger.error("This should never happen - please report this bug!")
+
+    sys.excepthook = handle_exception
+
+
+def _create_thought() -> Thought:
+    now = datetime.now(timezone.utc).isoformat()
+    return Thought(
+        thought_id=str(uuid.uuid4()),
+        source_task_id=str(uuid.uuid4()),
+        thought_type="standard",
+        status=ThoughtStatus.PENDING,
+        created_at=now,
+        updated_at=now,
+        content="manual invocation",
+        context={},
+    )
+
+
+async def _execute_handler(runtime: CIRISRuntime, handler: str, params: Optional[str]) -> None:
+    if not runtime.agent_processor:
+        raise RuntimeError("Agent processor not initialized")
+    handler_type = HandlerActionType[handler.upper()]
+    dispatcher = runtime.agent_processor.action_dispatcher
+    handler_instance = dispatcher.handlers.get(handler_type)
+    if not handler_instance:
+        raise ValueError(f"Handler {handler} not registered")
+    payload = json.loads(params) if params else {}
+    result = ActionSelectionDMAResult(
+        selected_action=handler_type,
+        action_parameters=payload,
+        rationale="manual trigger",
+    )
+    thought = _create_thought()
+    # Create a proper DispatchContext
+    from ciris_engine.schemas.runtime.contexts import DispatchContext
+    from ciris_engine.schemas.runtime.system_context import ChannelContext
+
+    dispatch_context = DispatchContext(
+        channel_context=ChannelContext(
+            channel_id=runtime.startup_channel_id, channel_type="CLI", created_at=datetime.now(timezone.utc)
+        ),
+        author_id="system",
+        author_name="System",
+        origin_service="main",
+        handler_name=handler,
+        action_type=handler_type,
+        thought_id=thought.thought_id,
+        task_id=thought.source_task_id,
+        source_task_id=thought.source_task_id,
+        event_summary=f"Manual trigger: {handler}",
+        event_timestamp=datetime.now(timezone.utc).isoformat(),
+    )
+    await handler_instance.handle(result, thought, dispatch_context)
+
+
+async def _run_runtime(runtime: CIRISRuntime, timeout: Optional[int], num_rounds: Optional[int] = None) -> None:
+    """Run the runtime with optional timeout and graceful shutdown."""
+    logger.debug(f"[DEBUG] _run_runtime called with timeout={timeout}, num_rounds={num_rounds}")
+    shutdown_called = False
+    try:
+        if timeout:
+            # Create task and handle timeout manually to allow graceful shutdown
+            logger.debug(f"[DEBUG] Setting up timeout for {timeout} seconds")
+            runtime_task = asyncio.create_task(runtime.run(num_rounds))
+
+            try:
+                # Wait for either the task to complete or timeout
+                await asyncio.wait_for(asyncio.shield(runtime_task), timeout=timeout)
+            except asyncio.TimeoutError:
+                logger.info(f"Timeout of {timeout} seconds reached, initiating graceful shutdown...")
+                # Request shutdown but don't cancel the task immediately
+                runtime.request_shutdown(f"Runtime timeout after {timeout} seconds")
+
+                # Give the shutdown processor time to run (up to 30 seconds)
+                try:
+                    await asyncio.wait_for(runtime_task, timeout=30.0)
+                    logger.info("Graceful shutdown completed within timeout")
+                except asyncio.TimeoutError:
+                    logger.warning("Graceful shutdown did not complete within 30 seconds, cancelling...")
+                    runtime_task.cancel()
+                    try:
+                        await runtime_task
+                    except asyncio.CancelledError:
+                        # Expected when we cancel the task
+                        pass  # NOSONAR - Intentionally not re-raising after timeout cancellation
+
+                    # Ensure shutdown is called if the task was cancelled
+                    logger.info("Calling shutdown explicitly after task cancellation")
+                    await runtime.shutdown()
+
+                shutdown_called = True
+        else:
+            # Run without timeout
+            logger.debug("[DEBUG] Running without timeout")
+            await runtime.run(num_rounds)
+    except KeyboardInterrupt:
+        logger.info("Received interrupt signal, shutting down gracefully...")
+        runtime.request_shutdown("User interrupt")
+        # Don't call shutdown here if runtime.run() will handle it
+        if not shutdown_called:
+            await runtime.shutdown()
+    except Exception as e:
+        logger.error(f"FATAL ERROR: Unhandled exception in runtime: {e}", exc_info=True)
+        try:
+            runtime.request_shutdown(f"Fatal error: {e}")
+            if not shutdown_called:
+                await runtime.shutdown()
+        except Exception as shutdown_error:
+            logger.error(f"Error during emergency shutdown: {shutdown_error}", exc_info=True)
+        raise  # Re-raise to ensure non-zero exit code
+
+
+@click.command()
+@click.option(
+    "--adapter",
+    "adapter_types_list",
+    multiple=True,
+    default=[],
+    help="One or more adapters to run. Specify multiple times for multiple adapters (e.g., --adapter cli --adapter api --adapter discord).",
+)
+@click.option("--template", default="default", help="Agent template name (only used for first-time setup)")
+@click.option("--config", "config_file_path", type=click.Path(), help="Path to app config")
+@click.option("--task", multiple=True, help="Task description to add before starting")
+@click.option("--timeout", type=int, help="Maximum runtime duration in seconds")
+@click.option("--handler", help="Direct handler to execute and exit")
+@click.option("--params", help="JSON parameters for handler execution")
+@click.option(
+    "--host",
+    "api_host",
+    default=None,
+    help="API host (default: 127.0.0.1 for security, use 0.0.0.0 for all interfaces)",
+)
+@click.option("--port", "api_port", default=None, type=int, help="API port (default: 8080)")
+@click.option("--debug/--no-debug", default=False, help="Enable debug logging")
+@click.option(
+    "--no-interactive/--interactive", "cli_interactive", default=True, help="Enable/disable interactive CLI input"
+)
+@click.option(
+    "--discord-token", "discord_bot_token", default=os.environ.get("DISCORD_BOT_TOKEN"), help="Discord bot token"
+)
+@click.option("--mock-llm/--no-mock-llm", default=False, help="Use the mock LLM service for offline testing")
+@click.option("--num-rounds", type=int, help="Maximum number of processing rounds (default: infinite)")
+def main(
+    adapter_types_list: tuple[str, ...],
+    template: str,
+    config_file_path: Optional[str],
+    task: tuple[str],
+    timeout: Optional[int],
+    handler: Optional[str],
+    params: Optional[str],
+    api_host: Optional[str],
+    api_port: Optional[int],
+    debug: bool,
+    cli_interactive: bool,
+    discord_bot_token: Optional[str],
+    mock_llm: bool,
+    num_rounds: Optional[int],
+) -> None:
+    """Unified CIRIS agent entry point."""
+    # Setup basic console logging first (without file logging)
+    # File logging will be set up later once TimeService is available
+    setup_basic_logging(
+        level=logging.DEBUG if debug else logging.INFO,
+        log_to_file=False,
+        console_output=True,
+        enable_incident_capture=False,  # Will be enabled later with TimeService
+    )
+
+    async def _async_main() -> None:
+        nonlocal mock_llm, handler, params, task, num_rounds
+        from ciris_engine.logic.config.env_utils import get_env_var
+
+        # Check for CIRIS_MOCK_LLM environment variable
+        if not mock_llm and get_env_var("CIRIS_MOCK_LLM"):
+            mock_llm_env = get_env_var("CIRIS_MOCK_LLM", "")
+            if mock_llm_env:
+                mock_llm_env = mock_llm_env.lower()
+            if mock_llm_env in ("true", "1", "yes", "on"):
+                logger.info("CIRIS_MOCK_LLM environment variable detected, enabling mock LLM")
+                mock_llm = True
+
+        # Handle first-run setup if needed
+        from ciris_engine.logic.setup.first_run import check_macos_python, is_first_run, is_interactive_environment
+        from ciris_engine.logic.setup.wizard import run_setup_wizard
+
+        # Check macOS Python installation
+        python_valid, python_message = check_macos_python()
+        if not python_valid:
+            click.echo("=" * 70, err=True)
+            click.echo("❌ PYTHON INSTALLATION ISSUE", err=True)
+            click.echo("=" * 70, err=True)
+            click.echo(python_message, err=True)
+            click.echo("=" * 70, err=True)
+            sys.exit(1)
+
+        first_run = is_first_run()
+        # When running in import/CI mode, bypass interactive first-run gating so
+        # CLI smoke tests can execute without configuration prompts or exits.
+        if os.environ.get("CIRIS_IMPORT_MODE") == "true":
+            first_run = False
+
+        # Handle adapter selection FIRST (before first-run wizard logic)
+        # This allows us to determine which adapter will handle first-run setup
+        final_adapter_types_list = list(adapter_types_list)
+        if not final_adapter_types_list:
+            # Check CIRIS_ADAPTER environment variable
+            env_adapter = get_env_var("CIRIS_ADAPTER")
+            if env_adapter:
+                # Support comma-separated adapters (e.g., "api,discord")
+                final_adapter_types_list = [a.strip() for a in env_adapter.split(",")]
+            else:
+                # Default to API adapter (GUI setup wizard)
+                final_adapter_types_list = ["api"]
+
+        # Check if we're running in CLI mode explicitly
+        is_cli_mode = any(adapter.startswith("cli") for adapter in final_adapter_types_list)
+
+        # First-run handling: only run CLI wizard if explicitly in CLI mode
+        if first_run and not adapter_types_list:
+            # First run detected and no adapter explicitly specified via CLI
+
+            if is_cli_mode and not is_interactive_environment():
+                # CLI mode but non-interactive environment (Docker, systemd, CI, etc.)
+                # No adapter in CLI or environment - EXIT with instructions
+                click.echo("=" * 70, err=True)
+                click.echo("❌ CONFIGURATION REQUIRED", err=True)
+                click.echo("=" * 70, err=True)
+                click.echo("CIRIS is not configured. Please set environment variables:", err=True)
+                click.echo("", err=True)
+                click.echo("Required:", err=True)
+                click.echo("  OPENAI_API_KEY=your_api_key", err=True)
+                click.echo("  CIRIS_ADAPTER=api", err=True)
+                click.echo("", err=True)
+                click.echo("For local LLM (Ollama, LM Studio, etc.):", err=True)
+                click.echo("  OPENAI_API_KEY=local", err=True)
+                click.echo("  OPENAI_API_BASE=http://localhost:11434", err=True)
+                click.echo("  OPENAI_MODEL=llama3", err=True)
+                click.echo("", err=True)
+                click.echo("Or mount a .env file at:", err=True)
+                click.echo("  ~/.ciris/.env", err=True)
+                click.echo("  ./.env", err=True)
+                click.echo("=" * 70, err=True)
+                sys.exit(1)
+            elif is_cli_mode and is_interactive_environment():
+                # CLI mode in interactive environment - run CLI setup wizard
+                try:
+                    click.echo()
+                    click.echo("=" * 70)
+                    click.echo("First run detected - running CLI setup wizard...")
+                    click.echo("=" * 70)
+                    config_path = run_setup_wizard()
+                    # Reload environment after setup
+                    try:
+                        from dotenv import load_dotenv
+
+                        load_dotenv(config_path)
+                        click.echo(f"✅ Configuration loaded from: {config_path}")
+                    except ImportError:
+                        pass  # dotenv is optional
+                except KeyboardInterrupt:
+                    click.echo("\nSetup cancelled by user")
+                    sys.exit(1)
+                except Exception as e:
+                    click.echo(f"\n❌ Setup failed: {e}", err=True)
+                    click.echo("You can configure manually by creating a .env file", err=True)
+                    sys.exit(1)
+            # else: API mode (default) - let API adapter handle GUI setup wizard
+
+        # Check for API key - NEVER default to mock LLM in production
+        # Skip this check during first-run (API adapter will handle setup)
+        api_key = get_env_var("OPENAI_API_KEY")
+        if not mock_llm and not api_key and not first_run:
+            # No API key and not explicitly using mock LLM
+            click.echo("=" * 70, err=True)
+            click.echo("❌ LLM API KEY REQUIRED", err=True)
+            click.echo("=" * 70, err=True)
+            click.echo("No OPENAI_API_KEY found in environment.", err=True)
+            click.echo("", err=True)
+            click.echo("Options:", err=True)
+            click.echo("  1. Set OPENAI_API_KEY environment variable", err=True)
+            click.echo("  2. Add to .env file", err=True)
+            click.echo("  3. Use --mock-llm flag for testing only", err=True)
+            click.echo("", err=True)
+            click.echo("For local LLM:", err=True)
+            click.echo("  export OPENAI_API_KEY=local", err=True)
+            click.echo("  export OPENAI_API_BASE=http://localhost:11434", err=True)
+            click.echo("  export OPENAI_MODEL=llama3", err=True)
+            click.echo("=" * 70, err=True)
+            sys.exit(1)
+
+        # Support multiple instances of same adapter type like "discord:instance1" or "api:port8081"
+        selected_adapter_types = list(final_adapter_types_list)
+
+        # Validate Discord adapter types have tokens available
+        validated_adapter_types = []
+        for adapter_type in selected_adapter_types:
+            if adapter_type.startswith("discord"):
+                base_adapter_type, instance_id = (adapter_type.split(":", 1) + [None])[:2]
+                # Check for instance-specific token or fallback to general token
+                token_vars = []
+                if instance_id:
+                    token_vars.extend(
+                        [f"DISCORD_{instance_id.upper()}_BOT_TOKEN", f"DISCORD_BOT_TOKEN_{instance_id.upper()}"]
+                    )
+                token_vars.append("DISCORD_BOT_TOKEN")
+
+                has_token = discord_bot_token or any(get_env_var(var) for var in token_vars)
+                if not has_token:
+                    click.echo(
+                        f"ERROR: No Discord bot token found for {adapter_type}. Discord adapter cannot start without a bot token.",
+                        err=True,
+                    )
+                    click.echo(
+                        "Please set DISCORD_BOT_TOKEN environment variable or use --discord-bot-token flag.", err=True
+                    )
+                    # Still add Discord to attempt loading - it will fail properly
+                    validated_adapter_types.append(adapter_type)
+                else:
+                    validated_adapter_types.append(adapter_type)
+            else:
+                validated_adapter_types.append(adapter_type)
+
+        selected_adapter_types = validated_adapter_types
+
+        # Check for modular services matching adapter names
+        from ciris_engine.logic.runtime.adapter_loader import AdapterLoader
+
+        adapter_loader = AdapterLoader()
+        discovered_services = adapter_loader.discover_services()
+        adapter_map = {svc.module.name.lower().replace("_adapter", ""): svc for svc in discovered_services}
+
+        # Separate built-in adapters from potential modular services
+        builtin_adapters = ["cli", "api", "discord"]
+        final_adapter_types = []
+        adapters_to_load = []
+
+        for adapter_type in selected_adapter_types:
+            base_type = adapter_type.split(":")[0]  # Handle instance IDs
+
+            # Check if it's a built-in adapter
+            if any(base_type.startswith(builtin) for builtin in builtin_adapters):
+                final_adapter_types.append(adapter_type)
+            # Check if it matches a modular service
+            elif base_type.lower() in adapter_map:
+                manifest = adapter_map[base_type.lower()]
+                logger.info(f"Found modular service '{manifest.module.name}' for adapter type '{adapter_type}'")
+
+                # Validate required configuration is present
+                if manifest.configuration:
+                    missing_required = []
+                    for config_key, config_spec in manifest.configuration.items():
+                        env_var = config_spec.env
+                        if env_var and not get_env_var(env_var):
+                            # Check if it has a default value
+                            if config_spec.default is None:
+                                missing_required.append(f"{env_var}")
+
+                    if missing_required:
+                        click.echo(
+                            f"ERROR: Modular service '{manifest.module.name}' requires configuration:",
+                            err=True,
+                        )
+                        for var in missing_required:
+                            click.echo(f"  - {var}", err=True)
+                        click.echo(
+                            f"Skipping modular service '{manifest.module.name}' due to missing configuration.",
+                            err=True,
+                        )
+                        continue
+
+                # Add to modular services to load
+                adapters_to_load.append((adapter_type, manifest))
+                logger.info(f"Modular service '{manifest.module.name}' validated and will be loaded")
+            else:
+                # Unknown adapter type
+                click.echo(
+                    f"WARNING: Unknown adapter type '{adapter_type}'. Not a built-in adapter or modular service.",
+                    err=True,
+                )
+                final_adapter_types.append(adapter_type)  # Try to load anyway
+
+        selected_adapter_types = final_adapter_types
+
+        # Load config
+        try:
+            # Validate config file exists if provided
+            if config_file_path and not Path(config_file_path).exists():
+                logger.error(f"Configuration file not found: {config_file_path}")
+                raise SystemExit(1)
+
+            # Create CLI overrides including the template parameter
+            cli_overrides: dict[str, Any] = {}
+            if template and template != "default":
+                cli_overrides["default_template"] = template
+
+            app_config = await load_config(config_file_path, cli_overrides)
+        except SystemExit:
+            raise  # Re-raise SystemExit to exit cleanly
+        except Exception as e:
+            error_msg = f"Failed to load config: {e}"
+            logger.error(error_msg)
+            # Write directly to stderr to ensure it's captured
+            print(error_msg, file=sys.stderr)
+            # Ensure outputs are flushed before exit
+            sys.stdout.flush()
+            sys.stderr.flush()
+            # Also flush logging handlers
+            for log_handler in logger.handlers:
+                log_handler.flush()
+            # Give a tiny bit of time for output to be written
+            import time
+
+            time.sleep(0.1)  # NOSONAR - Sync sleep is appropriate here before program exit
+            # Force immediate exit to avoid hanging in subprocess
+            # Use os._exit only when running under coverage
+            if sys.gettrace() is not None or "coverage" in sys.modules:
+                logger.debug("EXITING NOW VIA os._exit(1) AT _handle_precommit_wrapper coverage")
+                os._exit(1)
+            else:
+                logger.debug("EXITING NOW VIA sys.exit(1) AT _handle_precommit_wrapper")
+                sys.exit(1)
+
+        # Handle mock LLM as a module to load
+        modules_to_load = []
+        if mock_llm:
+            modules_to_load.append("mock_llm")
+            logger.info("Mock LLM module will be loaded")
+
+        # Add modular services as modules to load
+        for adapter_type, manifest in adapters_to_load:
+            modules_to_load.append(f"modular:{manifest.module.name}")
+            logger.info(f"Modular service '{manifest.module.name}' added to modules to load")
+
+        # Import AdapterConfig for proper type conversion
+        from ciris_engine.schemas.runtime.adapter_management import AdapterConfig
+
+        # Create adapter configurations for each adapter type and determine startup channel
+        adapter_configs = {}
+        startup_channel_id = getattr(app_config, "startup_channel_id", None)
+        # No discord_channel_id in EssentialConfig
+
+        for adapter_type in selected_adapter_types:
+            if adapter_type.startswith("api"):
+                base_adapter_type, instance_id = (adapter_type.split(":", 1) + [None])[:2]
+                from ciris_engine.logic.adapters.api.config import APIAdapterConfig
+
+                api_config = APIAdapterConfig()
+                # Load environment variables first
+                api_config.load_env_vars()
+                # Then override with command line args if provided
+                if api_host:
+                    api_config.host = api_host
+                if api_port:
+                    api_config.port = api_port
+
+                # Convert APIAdapterConfig to generic AdapterConfig
+                adapter_configs[adapter_type] = AdapterConfig(
+                    adapter_type="api", enabled=True, settings=api_config.model_dump()  # Convert all fields to dict
+                )
+                api_channel_id = api_config.get_home_channel_id(api_config.host, api_config.port)
+                if not startup_channel_id:
+                    startup_channel_id = api_channel_id
+
+            elif adapter_type.startswith("discord"):
+                base_adapter_type, instance_id = (adapter_type.split(":", 1) + [None])[:2]
+                from ciris_engine.logic.adapters.discord.config import DiscordAdapterConfig
+
+                discord_config = DiscordAdapterConfig()
+                if discord_bot_token:
+                    discord_config.bot_token = discord_bot_token
+
+                # Load environment variables into the config
+                discord_config.load_env_vars()
+
+                # Convert DiscordAdapterConfig to generic AdapterConfig
+                adapter_configs[adapter_type] = AdapterConfig(
+                    adapter_type="discord",
+                    enabled=True,
+                    settings=discord_config.model_dump(),  # Convert all fields to dict
+                )
+                discord_channel_id = discord_config.get_home_channel_id()
+                if discord_channel_id and not startup_channel_id:
+                    # For Discord, use formatted channel ID with discord_ prefix
+                    # Guild ID will be added by the adapter when it connects
+                    startup_channel_id = discord_config.get_formatted_startup_channel_id()
+
+            elif adapter_type.startswith("cli"):
+                base_adapter_type, instance_id = (adapter_type.split(":", 1) + [None])[:2]
+                from ciris_engine.logic.adapters.cli.config import CLIAdapterConfig
+
+                cli_config = CLIAdapterConfig()
+
+                # Environment variables are loaded by global configuration bootstrap
+
+                # CLI arguments take precedence over environment variables
+                if not cli_interactive:
+                    cli_config.interactive = False
+
+                # Convert CLIAdapterConfig to generic AdapterConfig
+                adapter_configs[adapter_type] = AdapterConfig(
+                    adapter_type="cli", enabled=True, settings=cli_config.model_dump()  # Convert all fields to dict
+                )
+                cli_channel_id = cli_config.get_home_channel_id()
+                if not startup_channel_id:
+                    startup_channel_id = cli_channel_id
+
+        # Setup global exception handling
+        setup_global_exception_handler()
+
+        # Template parameter is now passed via cli_overrides to the essential config
+
+        # Create runtime using new CIRISRuntime directly with adapter configs
+        runtime = CIRISRuntime(
+            adapter_types=selected_adapter_types,
+            essential_config=app_config,  # app_config is actually EssentialConfig
+            startup_channel_id=startup_channel_id,
+            adapter_configs=adapter_configs,
+            interactive=cli_interactive,
+            host=api_host,
+            port=api_port,
+            discord_bot_token=discord_bot_token,
+            modules=modules_to_load,  # Pass modules to load
+        )
+        await runtime.initialize()
+
+        # Setup signal handlers for graceful shutdown
+        setup_signal_handlers(runtime)
+
+        # Store preload tasks to be loaded after WORK state transition
+        preload_tasks = list(task) if task else []
+        runtime.set_preload_tasks(preload_tasks)
+
+        if handler:
+            await _execute_handler(runtime, handler, params)
+            await runtime.shutdown()
+            return
+
+        # Use CLI num_rounds if provided, otherwise fall back to config
+        effective_num_rounds = num_rounds
+        # Use default num_rounds if not specified
+        if effective_num_rounds is None:
+            from ciris_engine.logic.utils.constants import DEFAULT_NUM_ROUNDS
+
+            effective_num_rounds = DEFAULT_NUM_ROUNDS
+
+        # For CLI adapter, create a monitor task that forces exit when shutdown completes
+        monitor_task = None
+        if "cli" in selected_adapter_types:
+            # Create an event for signaling shutdown completion
+            shutdown_event = asyncio.Event()
+            # Store the event on the runtime so shutdown() can set it
+            runtime._shutdown_event = shutdown_event
+
+            async def monitor_shutdown() -> None:
+                """Monitor for shutdown completion and force exit for CLI mode."""
+                # Wait for the shutdown event to be set by the shutdown() method
+                await shutdown_event.wait()
+
+                # Shutdown is truly complete, give a moment for final logs
+                logger.info("CLI runtime shutdown complete, preparing clean exit")
+                await asyncio.sleep(0.2)  # Brief pause for final log entries
+
+                # Flush all output in parallel
+                async def flush_handler(handler: Any) -> None:
+                    """Flush a single handler."""
+                    try:
+                        await asyncio.to_thread(handler.flush)
+                    except Exception:
+                        pass  # Ignore flush errors during shutdown
+
+                # Create flush tasks for all operations
+                flush_tasks = [
+                    asyncio.create_task(asyncio.to_thread(sys.stdout.flush)),
+                    asyncio.create_task(asyncio.to_thread(sys.stderr.flush)),
+                ]
+
+                # Add tasks for each log handler
+                for log_handler in logging.getLogger().handlers:
+                    flush_tasks.append(asyncio.create_task(flush_handler(log_handler)))
+
+                # Wait for all flush operations to complete
+                await asyncio.gather(*flush_tasks, return_exceptions=True)
+
+                # Force exit to handle the blocking input thread
+                logger.info("Forcing exit to handle blocking CLI input thread")
+                # COMMENTED OUT: This was causing immediate exit before graceful shutdown could complete
+                # import os
+                # logger.info("DEBUG: EXITING NOW VIA os._exit(0) AT monitor_shutdown for CLI adapter")
+                # os._exit(0)
+
+            monitor_task = asyncio.create_task(monitor_shutdown())
+
+        try:
+            await _run_runtime(runtime, timeout, effective_num_rounds)
+        finally:
+            # For CLI adapter, wait for monitor task to force exit
+            if monitor_task and not monitor_task.done():
+                logger.debug("Waiting for CLI monitor task to detect shutdown completion...")
+                try:
+                    # Give the monitor task time to detect shutdown and force exit
+                    await asyncio.wait_for(monitor_task, timeout=5.0)
+                except asyncio.TimeoutError:
+                    logger.warning("Monitor task did not complete within 5 seconds")
+                    monitor_task.cancel()
+                except Exception as e:
+                    logger.error(f"Monitor task error: {e}")
+
+        # If we get here and CLI adapter is used, force exit anyway
+        if "cli" in selected_adapter_types:
+            logger.info("CLI runtime completed, forcing exit")
+            await asyncio.sleep(0.5)  # Give time for final logs to flush
+
+            # Flush all output in parallel
+            async def flush_handler(handler: Any) -> None:
+                """Flush a single handler."""
+                try:
+                    await asyncio.to_thread(handler.flush)
+                except Exception:
+                    pass  # Ignore flush errors during shutdown
+
+            # Create flush tasks for all operations
+            flush_tasks = [
+                asyncio.create_task(asyncio.to_thread(sys.stdout.flush)),
+                asyncio.create_task(asyncio.to_thread(sys.stderr.flush)),
+            ]
+
+            # Add tasks for each log handler
+            for log_handler in logging.getLogger().handlers:
+                flush_tasks.append(asyncio.create_task(flush_handler(log_handler)))
+
+            # Wait for all flush operations to complete
+            await asyncio.gather(*flush_tasks, return_exceptions=True)
+
+            logger.debug("EXITING NOW VIA os._exit(0) AT CLI runtime completed")
+            os._exit(0)
+
+    try:
+        asyncio.run(_async_main())
+    except KeyboardInterrupt:
+        logger.info("Interrupted by user, exiting...")
+        logger.debug("EXITING NOW VIA sys.exit(0) AT KeyboardInterrupt in main")
+        sys.exit(0)
+    except SystemExit:
+        raise  # Re-raise SystemExit to exit with the correct code
+    except Exception as e:
+        logger.error(f"Fatal error in main: {e}", exc_info=True)
+        logger.debug("EXITING NOW VIA sys.exit(1) AT Fatal error in main")
+        sys.exit(1)
+
+    # Ensure clean exit after successful run
+    # Force flush all outputs
+    sys.stdout.flush()
+    sys.stderr.flush()
+
+    # asyncio.run() already closes the event loop, so we don't need to do it again
+    # Just exit cleanly
+    logger.info("CIRIS agent exiting cleanly")
+
+    # For API mode subprocess tests, ensure immediate exit
+    if "--adapter" in sys.argv and "api" in sys.argv and "--timeout" in sys.argv:
+        logger.debug("EXITING NOW VIA os._exit(0) AT API mode subprocess tests")
+        os._exit(0)
+
+    # For CLI mode, force exit to handle blocking input thread
+    # This is necessary because asyncio.to_thread(input) creates a daemon thread
+    # that prevents normal exit even after shutdown completes
+    if "--adapter" in sys.argv and "cli" in sys.argv:
+        logger.info("CLI mode completed, forcing exit to handle blocking input thread")
+        # Ensure the log message is flushed
+        sys.stdout.flush()
+        sys.stderr.flush()
+        for log_handler in logging.getLogger().handlers:
+            log_handler.flush()
+        import time
+
+        time.sleep(0.1)  # Brief pause to ensure logs are written
+
+        logger.debug("EXITING NOW VIA os._exit(0) AT CLI mode force exit")
+        os._exit(0)
+
+    logger.debug("EXITING NOW VIA sys.exit(0) AT end of main")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()