agentengine-sdk-python 0.8.0__py3-none-any.whl → 0.8.2__py3-none-any.whl

ksadk/cli/cmd_replay.py

@@ -17,8 +17,13 @@ import json
 import click
 
 from ksadk.cli.resource_common import CONTEXT_SETTINGS
-from ksadk.events.replay import replay_transcript
+from ksadk.events.reducer import StreamReducer
 from ksadk.events.store import RuntimeEventStore
+from ksadk.events.v1_compat import (
+    RuntimeEventV1Parser,
+    RuntimeEventV1ProjectionContext,
+    project_to_v1,
+)
 
 _HELP = dict(help_option_names=["-h", "--help"])
 
@@ -43,9 +48,28 @@ async def _run(session_id: str, *, after_seq_id: int, before_seq_id: int | None,
     from ksadk.sessions import resolve_session_service
 
     store = RuntimeEventStore(resolve_session_service())
-    parser = await replay_transcript(
-        store, session_id, after_seq_id=after_seq_id, before_seq_id=before_seq_id
-    )
+    service = resolve_session_service()
+    session = await service.get_session(session_id)
+    events = await store.list(session_id)
+    parser = RuntimeEventV1Parser()
+    reducers: dict[str, StreamReducer] = {}
+    for event in events:
+        reducer = reducers.get(event.run_id)
+        if reducer is not None and reducer.snapshot().status in {"completed", "failed", "canceled"}:
+            reducer = None
+        if reducer is None:
+            reducer = StreamReducer()
+            reducers[event.run_id] = reducer
+        reducer.apply(event)
+        projection = reducer.snapshot()
+        context = RuntimeEventV1ProjectionContext(
+            agent_id=session.agent_id if session else "",
+            user_id=session.user_id if session else "",
+            session_id=session_id,
+            projection=projection,
+        )
+        for v1_event in project_to_v1(event, mode="identity_replace", context=context):
+            parser.feed(v1_event)
     transcript = parser.transcript()
     if fmt == "json":
         click.echo(json.dumps(transcript, ensure_ascii=False, sort_keys=True))

ksadk/cli/cmd_run.py

@@ -11,14 +11,15 @@ import sys
 from pathlib import Path
 
 import click
+import uvicorn
 
 from ksadk.cli.error_utils import ensure_json_output_supported, print_exception
 from ksadk.cli.local_runtime import reexec_with_project_venv_if_needed
+from ksadk.cli.runtime_bootstrap import create_runtime_web_app
 from ksadk.cli.ui import (
     print_error,
     print_info,
     print_kv,
-    print_rule,
     print_success,
     print_title,
     print_warn,
@@ -117,59 +118,45 @@ def run(
     configure_local_runtime_persistence(agent_path, result.type.value)
 
     # 2. 根据框架类型选择处理方式
-    # 所有框架统一使用 _run_custom() 以支持 Langfuse 自动插桩
-    # (Langfuse instrumentation 需要在同一进程内生效)
+    # 所有框架统一使用 _run_custom()，让 OTel instrumentation 在同一进程生效。
     _run_custom(
         result, agent_path, port, interactive, no_trace, show_thinking, no_stream, no_alt_screen
     )
 
 
 def _run_adk_cli(agent_path: Path, port: int = 8080, command: str = "run"):
-    """运行 ADK Agent，支持 Langfuse tracing
-
-    对于 Langfuse 集成，我们需要在同一进程内运行 ADK，
-    因为 OpenTelemetry instrumentation 只在进程内生效。
-    """
+    """运行 ADK Agent，使用标准 OTLP 配置。"""
     import os
 
-    has_langfuse = bool(os.getenv("LANGFUSE_PUBLIC_KEY"))
+    has_otlp = bool(
+        os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT")
+        or os.getenv("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT")
+        or os.getenv("CLOUD_MONITOR_OTLP_ENDPOINT")
+        or os.getenv("CLOUD_MONITOR_OTLP_TRACES_ENDPOINT")
+    )
 
     # 必须先初始化 Tracing（在导入 ADK 之前）
-    if has_langfuse:
+    if has_otlp:
         try:
             from ksadk.tracing import setup_tracing
 
             setup_tracing(
                 enable_inmemory=False,
-                enable_langfuse=True,
                 enable_adk_instrumentation=True,
             )
-            print_info("Tracing: Enabled (Langfuse + ADK Instrumentation)")
+            print_info("Tracing: Enabled (OTLP + ADK Instrumentation)")
         except Exception as e:
-            print_warn(f"Langfuse 初始化失败: {e}")
+            print_warn(f"OTLP tracing 初始化失败: {e}")
 
     print_kv("调用 ADK 原生 CLI", f"adk {command}")
 
-    # 使用 subprocess（Langfuse instrumentation 在子进程中不生效，但环境变量会传递）
-    # ADK CLI 本身不支持 Langfuse，需要用户在项目中集成
+    # 子进程继承标准 OTLP 环境变量；项目内 instrumentation 负责创建 spans。
     if command == "run":
         cmd = [sys.executable, "-m", "google.adk.cli", "run", "."]
     else:
         cmd = [sys.executable, "-m", "google.adk.cli", "web", ".", "--port", str(port)]
 
-    # 传递 Langfuse 环境变量
     env = os.environ.copy()
-    langfuse_vars = ["LANGFUSE_PUBLIC_KEY", "LANGFUSE_SECRET_KEY", "LANGFUSE_BASE_URL"]
-    for var in langfuse_vars:
-        if var in os.environ:
-            env[var] = os.environ[var]
-
-    # 提示用户如何在 ADK 项目中启用 Langfuse
-    if has_langfuse:
-        print_rule("ADK 项目 Langfuse 集成提示")
-        print_info("在 agent.py 中添加以下代码:")
-        print_info("from openinference.instrumentation.google_adk import GoogleADKInstrumentor")
-        print_info("GoogleADKInstrumentor().instrument()")
 
     try:
         subprocess.run(cmd, cwd=str(agent_path), check=True, env=env)
@@ -191,8 +178,7 @@ def _run_custom(
     no_stream: bool = False,
     no_alt_screen: bool = False,
 ):
-    """使用自定义实现 (LangChain/LangGraph/DeepAgents)"""
-    from ksadk.runners.factory import create_runner
+    """Run one detected project through the canonical RuntimeAdapter composition."""
 
     # 初始化 Tracing
     if not no_trace:
@@ -201,62 +187,38 @@ def _run_custom(
 
             from ksadk.tracing import setup_tracing
 
-            has_langfuse = bool(os.getenv("LANGFUSE_PUBLIC_KEY"))
             has_otlp = bool(
                 os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT")
                 or os.getenv("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT")
             )
 
-            use_callback_only = os.getenv("LANGFUSE_USE_CALLBACK", "").strip().lower() in (
-                "1",
-                "true",
-                "yes",
-                "on",
-            )
-
             setup_tracing(
                 enable_inmemory=True,
                 enable_langfuse=None,
-                use_callback_only=use_callback_only,
             )
 
             if has_otlp:
                 print_info("Tracing: Enabled (InMemory + OTLP HTTP)")
-            elif has_langfuse:
-                print_info(
-                    f"Tracing: Enabled (InMemory + Langfuse, CallbackOnly={use_callback_only})"
-                )
             else:
                 print_info("Tracing: Enabled")
         except Exception as e:
             print_warn(f"Tracing 初始化失败: {e}")
 
-    # 创建 Runner
+    if interactive:
+        del show_thinking, no_stream, no_alt_screen
+        print_error(
+            "RuntimeAdapter TUI 尚未接通；请使用 `ksadk web` 或不带 --interactive 启动"
+        )
+        raise SystemExit(2)
+
     try:
-        print_info("初始化 Runner...")
-        runner = create_runner(result, str(agent_path))
-        runner.load_agent()
-        print_success("Agent 加载成功")
+        runtime_app = create_runtime_web_app(result, agent_path)
     except Exception as e:
-        print_exception("Agent 加载失败", e)
-        # import traceback
-        # traceback.print_exc()
+        print_exception("RuntimeAdapter 初始化失败", e)
         raise SystemExit(1)
 
-    # 运行
-    if interactive:
-        # TUI 交互模式
-        from ksadk.tui.loop import run_tui
-
-        run_tui(
-            runner,
-            show_thinking=show_thinking,
-            project_dir=str(agent_path),
-            no_alt_screen=no_alt_screen,
-        )
-    else:
-        print_success(f"Server running at http://0.0.0.0:{port}")
-        print_kv("API Docs", f"http://0.0.0.0:{port}/docs")
-        print_kv("Chat API", f"http://0.0.0.0:{port}/chat")
-        print_info("Press Ctrl+C to stop")
-        runner.run_server(port=port)
+    print_success(f"Server running at http://127.0.0.1:{port}")
+    print_kv("API Docs", f"http://127.0.0.1:{port}/docs")
+    print_kv("Chat API", f"http://127.0.0.1:{port}/chat")
+    print_info("Press Ctrl+C to stop")
+    uvicorn.run(runtime_app, host="127.0.0.1", port=port)

ksadk/cli/cmd_studio.py

@@ -0,0 +1,201 @@
+"""agentengine studio - start the local-first Agent authoring control plane."""
+
+from __future__ import annotations
+
+import logging
+import os
+import secrets
+import webbrowser
+from pathlib import Path
+
+import click
+import uvicorn
+
+from ksadk.cli.env_options import load_env_file
+from ksadk.cli.ui import print_info, print_kv, print_success, print_title
+
+# veadk 风格：日志行带模块名与行号（filename:lineno），本地排障时能直接定位代码。
+_LOG_FORMAT = "%(asctime)s %(levelname)s %(name)s %(filename)s:%(lineno)d %(message)s"
+
+_STUDIO_LOG_CONFIG = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "formatters": {
+        "default": {"format": _LOG_FORMAT},
+        "access": {"format": _LOG_FORMAT},
+    },
+    "handlers": {
+        "default": {
+            "class": "logging.StreamHandler",
+            "formatter": "default",
+            "stream": "ext://sys.stderr",
+        },
+        "access": {
+            "class": "logging.StreamHandler",
+            "formatter": "access",
+            "stream": "ext://sys.stdout",
+        },
+    },
+    "loggers": {
+        "uvicorn": {"handlers": ["default"], "level": "INFO", "propagate": False},
+        "uvicorn.error": {"level": "INFO"},
+        "uvicorn.access": {"handlers": ["access"], "level": "INFO", "propagate": False},
+    },
+    "root": {"handlers": ["default"], "level": "INFO"},
+}
+
+from ksadk.studio.api import create_studio_app
+from ksadk.studio.service import StudioService
+
+# 模型环境变量白名单。OPENAI_BASE_URL 与 OPENAI_API_BASE 互为别名，两者都接受；
+# 加载时做别名归一（见 studio()），运行时统一 OPENAI_BASE_URL 优先（与 cmd_config/cmd_model
+# /api.py 一致，方案 §2.4 第 5 点）。
+_MODEL_ENV_KEYS = (
+    "OPENAI_BASE_URL",
+    "OPENAI_API_BASE",
+    "OPENAI_API_KEY",
+    "OPENAI_MODEL_NAME",
+)
+# Cloud-control credentials are intentionally process-only as well.  Studio
+# needs them to use the Server Action API for a deployed Agent, but they must
+# never become browser settings, workspace files, or runtime environment.
+_CLOUD_CONTROL_ENV_KEYS = (
+    "KSYUN_ACCESS_KEY",
+    "KSYUN_SECRET_KEY",
+    "KSYUN_REGION",
+    "AGENTENGINE_REGION",
+    "AGENTENGINE_SERVER_URL",
+    "AGENTENGINE_STREAM_SERVER_URL",
+    "AGENTENGINE_SIGN_SERVICE",
+    "KS3_BUCKET",
+    "KS3_ACCESS_KEY",
+    "KS3_SECRET_KEY",
+)
+_STUDIO_ENV_FILE_KEYS = (*_MODEL_ENV_KEYS, *_CLOUD_CONTROL_ENV_KEYS)
+# 别名归一：两者任一有值时，把另一个也设上，保证下游无论读哪个都命中。
+_MODEL_BASE_URL_ALIASES = ("OPENAI_BASE_URL", "OPENAI_API_BASE")
+
+
+@click.command(context_settings=dict(help_option_names=["-h", "--help"]))
+@click.argument("workspace", default=".", type=click.Path())
+@click.option("--port", "-p", default=8080, type=click.IntRange(1, 65535))
+@click.option("--no-open", is_flag=True, help="仅打印 URL，不自动打开浏览器")
+@click.option(
+    "--env-file",
+    type=click.Path(exists=True, dir_okay=False),
+    help=(
+        "本地模型与云端控制环境文件；只读取允许的 OPENAI/KSYUN/KS3 "
+        "字段，且仅保留在 Studio 进程"
+    ),
+)
+@click.option(
+    "--codex-proxy",
+    type=click.Choice(["inherit", "auto", "forced", "direct"]),
+    default="inherit",
+    show_default=True,
+    help="Codex Responses→Chat 代理策略",
+)
+def studio(
+    workspace: str,
+    port: int,
+    no_open: bool,
+    env_file: str | None,
+    codex_proxy: str,
+) -> None:
+    """启动本地 AgentKit Studio。
+
+    \b
+    WORKSPACE: Agent 工作区目录，目录不存在时自动初始化。
+    """
+
+    root = Path(workspace).expanduser().resolve()
+    managed_keys = (*_STUDIO_ENV_FILE_KEYS, "KSADK_CODEX_USE_PROXY")
+    previous = {key: os.environ.get(key) for key in managed_keys}
+    previously_present = {key for key in managed_keys if key in os.environ}
+    try:
+        if env_file:
+            try:
+                values = load_env_file(env_file)
+            except ValueError as exc:
+                raise click.ClickException(str(exc)) from exc
+            loaded_models = 0
+            loaded_cloud_control = 0
+            for key, value in values.items():
+                if key not in _STUDIO_ENV_FILE_KEYS or not value:
+                    continue
+                if key in _MODEL_ENV_KEYS:
+                    loaded_models += 1
+                else:
+                    loaded_cloud_control += 1
+                # An explicit --env-file is the operator's selected cloud
+                # identity.  Do not silently reuse inherited AK/SK from the
+                # shell, which can point Studio at another tenant.  Model
+                # values keep their historical shell-first precedence.
+                if key in _CLOUD_CONTROL_ENV_KEYS or key not in os.environ:
+                    os.environ[key] = value
+            # 别名归一（方案 §2.4 第 5 点）：OPENAI_BASE_URL 与 OPENAI_API_BASE 互为别名。
+            # 加载后任一有值则把另一个也设上，保证下游无论读哪个都命中；OPENAI_BASE_URL 优先。
+            resolved_base_url = os.environ.get("OPENAI_BASE_URL") or os.environ.get(
+                "OPENAI_API_BASE"
+            )
+            if resolved_base_url:
+                os.environ["OPENAI_BASE_URL"] = resolved_base_url
+                os.environ["OPENAI_API_BASE"] = resolved_base_url
+                # base_url 至少算一次，避免显示 0/4 误导。
+                loaded_models = max(loaded_models, 2)
+            print_kv(
+                "模型环境",
+                f"已安全加载 {loaded_models}/{len(_MODEL_ENV_KEYS)} 个字段",
+            )
+            if loaded_cloud_control:
+                print_kv(
+                    "云端控制",
+                    "已安全加载 "
+                    f"{loaded_cloud_control}/{len(_CLOUD_CONTROL_ENV_KEYS)} 个字段"
+                    "（仅本地进程）",
+                )
+        if codex_proxy == "forced":
+            os.environ["KSADK_CODEX_USE_PROXY"] = "1"
+        elif codex_proxy == "direct":
+            os.environ["KSADK_CODEX_USE_PROXY"] = "0"
+        elif codex_proxy == "auto":
+            os.environ.pop("KSADK_CODEX_USE_PROXY", None)
+        session_token = os.environ.get("KSADK_STUDIO_SESSION_TOKEN") or secrets.token_urlsafe(32)
+        csrf_token = secrets.token_urlsafe(24)
+        service = StudioService(root)
+        app = create_studio_app(
+            root,
+            service=service,
+            session_token=session_token,
+            csrf_token=csrf_token,
+            security_enabled=os.environ.get("KSADK_STUDIO_NO_SECURITY") != "1",
+        )
+        base_url = f"http://127.0.0.1:{port}/"
+        launch_url = f"{base_url}#session={session_token}"
+
+        print_title("启动 AgentKit Local Studio")
+        print_kv("工作区", str(root))
+        print_kv("访问地址", launch_url, value_style="#58a6ff")
+        print_success("构建与运行均在本地执行")
+        print_info("按 Ctrl+C 停止")
+        if not no_open:
+            webbrowser.open(launch_url)
+        # 业务日志（ksadk.*）走 root handler，同样带 filename:lineno。
+        logging.basicConfig(level=logging.INFO, format=_LOG_FORMAT)
+        uvicorn.run(
+            app,
+            host="127.0.0.1",
+            port=port,
+            log_level="info",
+            # Access logging stays enabled through the Studio log config while
+            # retaining filename/line-number context for both API and business
+            # logs.  This preserves master's observability intent and the
+            # branch's richer diagnostic format.
+            log_config=_STUDIO_LOG_CONFIG,
+        )
+    finally:
+        for key in managed_keys:
+            if key in previously_present:
+                os.environ[key] = previous[key] or ""
+            else:
+                os.environ.pop(key, None)

ksadk/cli/cmd_web.py

@@ -6,10 +6,12 @@ import webbrowser
 from pathlib import Path
 
 import click
+import uvicorn
 import yaml
 
 from ksadk.cli.error_utils import ensure_json_output_supported, print_exception
 from ksadk.cli.local_runtime import reexec_with_project_venv_if_needed
+from ksadk.cli.runtime_bootstrap import create_runtime_web_app
 from ksadk.cli.ui import (
     print_error,
     print_info,
@@ -20,7 +22,6 @@ from ksadk.cli.ui import (
 )
 from ksadk.configs import setup_environment
 from ksadk.detection import FrameworkDetector
-from ksadk.runners.factory import create_runner
 
 _PERSISTENT_STM_FRAMEWORKS = {"adk", "langgraph", "langchain", "deepagents"}
 _STM_ENV_NAMES = (
@@ -226,9 +227,14 @@ def configure_local_runtime_persistence(
 @click.command(context_settings=dict(help_option_names=["-h", "--help"]))
 @click.argument("agent_dir", default=".", type=click.Path(exists=True))
 @click.option("--port", "-p", default=8080, help="Web UI 端口")
+@click.option(
+    "--host",
+    default="127.0.0.1",
+    help="Web UI 绑定地址(容器部署用 0.0.0.0)",
+)
 @click.option("--model", help="指定模型名称 (覆盖 .env 配置)")
 @click.option("--no-open", is_flag=True, help="仅打印 URL，不自动打开浏览器")
-def web(agent_dir: str, port: int, model: str, no_open: bool):
+def web(agent_dir: str, port: int, host: str, model: str, no_open: bool):
     """启动本地统一 Web UI（Invoke UI）
 
     \b
@@ -248,6 +254,9 @@ def web(agent_dir: str, port: int, model: str, no_open: bool):
 
     agent_path = Path(agent_dir).resolve()
     command_args = ["web", str(agent_path), "--port", str(port)]
+    if host != "127.0.0.1":
+        # re-exec 进项目 venv 时透传非默认 host(容器/远端托管场景绑 0.0.0.0)
+        command_args.extend(["--host", host])
     if model:
         command_args.extend(["--model", model])
     if no_open:
@@ -340,10 +349,10 @@ def web(agent_dir: str, port: int, model: str, no_open: bool):
     launch_path = _configure_custom_ui_env(agent_path)
 
     try:
-        print_info("初始化 Runner...")
-        runner = create_runner(result, str(agent_path))
+        print_info("初始化 RuntimeAdapter...")
+        runtime_app = create_runtime_web_app(result, agent_path)
     except Exception as e:
-        print_exception("Runner 初始化失败", e)
+        print_exception("RuntimeAdapter 初始化失败", e)
         raise SystemExit(1)
 
     print_success("启动统一 Web UI")
@@ -356,7 +365,7 @@ def web(agent_dir: str, port: int, model: str, no_open: bool):
         webbrowser.open(launch_url)
 
     try:
-        runner.run_server(port=port)
+        uvicorn.run(runtime_app, host=host, port=port)
     except KeyboardInterrupt:
         raise SystemExit(0)
     except Exception as e:

ksadk/cli/dry_run.py

@@ -13,6 +13,7 @@ from click.core import ParameterSource
 from ksadk.api.client import DryRunExit
 from ksadk.cli.resource_common import build_dry_run_envelope
 from ksadk.cli.ui import emit_json, is_json_output
+from ksadk.configs.env_registry import is_sensitive_env_var
 
 _T = TypeVar("_T")
 _DEFAULT_DONE_MSG = "✅ Dry Run Completed: 请求已打印，未执行实际变更。"
@@ -117,7 +118,7 @@ def _mask_if_sensitive(value: Any, *, sensitive: bool) -> Any:
 def _sanitize_dry_run_value(value: Any, *, parent_key: str | None = None) -> Any:
     if isinstance(value, dict):
         env_key = str(value.get("Key") or "")
-        env_sensitive = bool(value.get("IsSensitive")) or _is_sensitive_key(env_key)
+        env_sensitive = bool(value.get("IsSensitive")) or is_sensitive_env_var(env_key)
         sanitized: dict[str, Any] = {}
         for key, item in value.items():
             key_text = str(key)

ksadk/cli/env_options.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import os
 import re
 from pathlib import Path
 
@@ -62,11 +63,93 @@ def resolve_explicit_env_vars(
     env_pairs: tuple[str, ...] | list[str] | None,
     base_dir: Path,
 ) -> dict[str, str]:
+    """Resolve explicit env vars from ``--env-file``/``--env`` (no auto-``./.env``).
+
+    Used by the generic ``agentengine deploy``/``launch`` which read model
+    config from ``agentengine.yaml``, not from ``./.env``. Framework-specific
+    deploys (hermes/openclaw) use ``resolve_runtime_env_overrides`` instead,
+    which auto-discovers ``./.env`` and returns shell_keys for os.environ merge.
+    """
     env_vars = load_env_file(env_file, base_dir=base_dir)
     env_vars.update(parse_env_pairs(env_pairs))
     return env_vars
 
 
+def apply_explicit_env_with_shell_priority(
+    base_env: dict[str, str],
+    cli_env: dict[str, str],
+    auto_dotenv: dict[str, str],
+    shell_keys: set[str],
+) -> dict[str, str]:
+    """Merge env into base with precedence: cli_env > shell > auto_dotenv.
+
+    ``shell_keys`` is the snapshot of ``os.environ`` keys captured BEFORE any
+    env load. ``cli_env`` (``--env``/``--env-file``) is the highest explicit
+    CLI intent and overwrites everything. ``auto_dotenv`` (auto-discovered
+    ``./.env``) only fills keys not already set by shell.
+    """
+    for key, value in auto_dotenv.items():
+        if key in shell_keys:
+            continue
+        base_env.setdefault(key, value)
+    for key, value in cli_env.items():
+        base_env[key] = value
+    return base_env
+
+
+def inject_env_to_environ(
+    cli_env: dict[str, str],
+    auto_dotenv: dict[str, str],
+    shell_keys: set[str],
+) -> int:
+    """Apply env to ``os.environ`` with precedence: cli_env > shell > auto_dotenv.
+
+    ``auto_dotenv`` only fills keys absent from shell (shell wins over auto
+    ``./.env``). ``cli_env`` overwrites shell (explicit CLI intent wins).
+    Returns the number of keys injected from ``auto_dotenv`` (for user-facing
+    messages); ``cli_env`` overwrites are not counted.
+    """
+    loaded = 0
+    for key, value in auto_dotenv.items():
+        if key in shell_keys:
+            continue
+        os.environ.setdefault(key, value)
+        loaded += 1
+    for key, value in cli_env.items():
+        os.environ[key] = value
+    return loaded
+
+
+def resolve_runtime_env_overrides(
+    *,
+    env_file: str | None,
+    extra_env: tuple[str, ...] | list[str] | None,
+    base_dir: Path,
+) -> tuple[dict[str, str], dict[str, str], set[str], str | None]:
+    """Resolve runtime env overrides with precedence ``--env > --env-file > shell > auto ./.env``.
+
+    Returns ``(cli_env, auto_dotenv, shell_keys, source)``:
+    - ``cli_env``: merged ``--env-file`` + ``--env`` (``--env`` wins); explicit
+      CLI intent, overwrites shell at merge time.
+    - ``auto_dotenv``: auto-discovered ``./.env`` (only when ``env_file`` is
+      None); does NOT overwrite shell.
+    - ``shell_keys``: snapshot of ``os.environ`` captured before any load.
+    - ``source``: the file path used (for user-facing messages) or ``None``.
+    """
+    shell_keys = set(os.environ)
+    explicit_file_env = load_env_file(env_file, base_dir=base_dir) if env_file else {}
+    auto_dotenv: dict[str, str] = {}
+    auto_source: str | None = None
+    if not env_file:
+        auto_path = base_dir / ".env"
+        if auto_path.exists():
+            auto_dotenv = load_env_file(str(auto_path), base_dir=base_dir)
+            auto_source = str(auto_path)
+    pair_env = parse_env_pairs(extra_env)
+    cli_env = {**explicit_file_env, **pair_env}
+    return cli_env, auto_dotenv, shell_keys, env_file or auto_source
+
+
 def env_options(func):
     func = click.option(
         "--env-file",

ksadk/cli/global_options.py

@@ -18,7 +18,9 @@ def ensure_global_cli_options(command: click.Command) -> click.Command:
     """Inject hidden common options into groups/commands that do not declare them locally."""
     if not _has_long_option(command, "--dry-run"):
         command.params.insert(0, build_dry_run_click_option(hidden=True, expose_value=False))
-    if not _has_long_option(command, "--output"):
+    if not getattr(command, "disable_global_output_option", False) and not _has_long_option(
+        command, "--output"
+    ):
         command.params.insert(0, build_output_click_option(hidden=True, expose_value=False))
     if not _has_long_option(command, "--no-color"):
         command.params.insert(0, build_no_color_click_option(hidden=True, expose_value=False))