agentengine-sdk-python 0.8.3__py3-none-any.whl → 0.8.4__py3-none-any.whl

ksadk/plugins/providers/codex.py

@@ -8,20 +8,28 @@ stream or transcript is created here.
 
 from __future__ import annotations
 
+import hashlib
 import json
+import os
+import re
 from collections.abc import Callable, Mapping, Sequence
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from pathlib import Path, PurePosixPath
 from typing import Any
+from urllib.parse import urlparse
 
 from ksadk.plugins.bundle import ResolvedPluginBundle
 from ksadk.plugins.contracts import CompositionProfile, PluginManifest
 from ksadk.plugins.host import PluginExecutionContext, PluginHostError
+from ksadk.plugins.providers.codex_native import codex_runtime_registry
+from ksadk.plugins.providers.mcp_projection import (
+    MCPProjectionLease,
+    project_mcp_capabilities,
+)
 from ksadk.runtime import (
     RuntimeExecutor,
     RuntimeLaunchContext,
     RuntimeServices,
-    build_default_runtime_registry,
 )
 from ksadk.runtime.conversation_execution import invoke_runtime_conversation_once
 from ksadk.sessions import create_session_service
@@ -96,9 +104,7 @@ class CodexTurnRequest:
         raw_messages = value.get("messages")
         if raw_messages is None and value.get("input") is not None:
             raw_messages = ({"role": "user", "content": value.get("input")},)
-        if not isinstance(raw_messages, Sequence) or isinstance(
-            raw_messages, (str, bytes)
-        ):
+        if not isinstance(raw_messages, Sequence) or isinstance(raw_messages, (str, bytes)):
             raise PluginHostError("codex_input_invalid", "Codex input requires messages")
         messages: list[Mapping[str, Any]] = []
         for index, message in enumerate(raw_messages):
@@ -114,29 +120,19 @@ class CodexTurnRequest:
                 )
             messages.append(dict(message))
         if not messages or messages[-1].get("role") != "user":
-            raise PluginHostError(
-                "codex_input_invalid", "Codex turn must end with a user message"
-            )
+            raise PluginHostError("codex_input_invalid", "Codex turn must end with a user message")
         metadata = value.get("request_metadata") or value.get("requestMetadata")
         if metadata is not None and not isinstance(metadata, Mapping):
-            raise PluginHostError(
-                "codex_input_invalid", "request_metadata must be an object"
-            )
-        session_id = str(
-            value.get("session_id") or value.get("sessionId") or ""
-        ).strip()
-        invocation_id = str(
-            value.get("invocation_id") or value.get("invocationId") or ""
-        ).strip()
+            raise PluginHostError("codex_input_invalid", "request_metadata must be an object")
+        session_id = str(value.get("session_id") or value.get("sessionId") or "").strip()
+        invocation_id = str(value.get("invocation_id") or value.get("invocationId") or "").strip()
         if len(invocation_id) > 256:
             raise PluginHostError(
                 "codex_input_invalid", "Codex invocation_id exceeds 256 characters"
             )
         model = str(value.get("model") or "").strip()
         if len(model) > 256:
-            raise PluginHostError(
-                "codex_input_invalid", "Codex model exceeds 256 characters"
-            )
+            raise PluginHostError("codex_input_invalid", "Codex model exceeds 256 characters")
         collaboration_mode = (
             str(value.get("collaboration_mode") or value.get("collaborationMode") or "")
             .strip()
@@ -195,11 +191,17 @@ class CodexAgentProviderRuntime:
         session_service: BaseSessionService,
         codex_client_factory: Callable[..., Any] | None,
         credential_resolver: Any = None,
+        runtime_state_root: Path | None = None,
+        local_launch_resolver: Callable[..., RuntimeLaunchContext | None] | None = None,
+        runtime_executor: RuntimeExecutor | None = None,
     ) -> None:
         self._plugin_id = plugin_id
         self._session_service = session_service
         self._client_factory = codex_client_factory
         self._credentials = credential_resolver
+        self._runtime_state_root = runtime_state_root
+        self._local_launch_resolver = local_launch_resolver
+        self._runtime_executor = runtime_executor
         self._ready = False
         self._disposed = False
         self._last_activation: CodexAgentActivation | None = None
@@ -234,21 +236,40 @@ class CodexAgentProviderRuntime:
         capabilities: PluginExecutionContext,
     ) -> "CodexAgentActivation":
         if not self._ready or self._disposed:
-            raise PluginHostError(
-                "codex_provider_unavailable", "Codex provider is not ready"
-            )
+            raise PluginHostError("codex_provider_unavailable", "Codex provider is not ready")
         _reject_external_execution(bundle, capabilities)
-        config = _resolve_bundle_config(
+        projection = await project_mcp_capabilities(
+            capabilities,
             bundle,
-            plugin_id=self._plugin_id,
-            credential_resolver=self._credentials,
-        )
-        activation = CodexAgentActivation(
-            bundle=bundle,
-            config=config,
-            session_service=self._session_service,
-            codex_client_factory=self._client_factory,
+            activation_only=True,
         )
+        marker = bundle.composition.profile.agent_provider.config.get("studioManifestDigest")
+        launch = self._local_launch_resolver(bundle) if self._local_launch_resolver else None
+        if marker is not None and launch is None:
+            await projection.aclose()
+            raise PluginHostError("codex_local_build_required", "Local Codex Build is unavailable")
+        try:
+            config = _with_projected_mcp(
+                _resolve_bundle_config(
+                    bundle,
+                    plugin_id=self._plugin_id,
+                    credential_resolver=self._credentials,
+                    runtime_state_root=self._runtime_state_root,
+                    local_launch=launch,
+                ),
+                projection,
+            )
+            activation = CodexAgentActivation(
+                bundle=bundle,
+                config=config,
+                session_service=self._session_service,
+                codex_client_factory=self._client_factory,
+                mcp_projection=projection,
+                runtime_executor=self._runtime_executor,
+            )
+        except BaseException:
+            await projection.aclose()
+            raise
         self._last_activation = activation
         return activation
 
@@ -284,11 +305,24 @@ class CodexAgentProviderFactory:
             )
         client_factory = self._client_factory or services.get("codex_client_factory")
         credentials = self._credentials or services.get("credential_resolver")
+        raw_state_root = services.get("runtime_state_root")
+        runtime_state_root = (
+            Path(str(raw_state_root)).expanduser().resolve() if raw_state_root is not None else None
+        )
+        runtime_executor = services.get("runtime_executor")
+        if runtime_executor is not None and not isinstance(runtime_executor, RuntimeExecutor):
+            raise PluginHostError(
+                "codex_runtime_executor_invalid",
+                "Codex provider requires a RuntimeExecutor",
+            )
         self.runtime = CodexAgentProviderRuntime(
             plugin_id=manifest.metadata.id,
             session_service=service,
             codex_client_factory=client_factory,
             credential_resolver=credentials,
+            runtime_state_root=runtime_state_root,
+            local_launch_resolver=services.get("codex_local_launch_resolver"),
+            runtime_executor=runtime_executor,
         )
         return self.runtime
 
@@ -301,11 +335,14 @@ class CodexAgentActivation:
         config: _CodexBundleConfig,
         session_service: BaseSessionService,
         codex_client_factory: Callable[..., Any] | None,
+        mcp_projection: MCPProjectionLease,
+        runtime_executor: RuntimeExecutor | None = None,
     ) -> None:
         self._bundle = bundle
         self._config = config
         self._session_service = session_service
-        self._executor = RuntimeExecutor(build_default_runtime_registry())
+        self._mcp_projection = mcp_projection
+        self._executor = runtime_executor or RuntimeExecutor(codex_runtime_registry())
         self._launch_context = RuntimeLaunchContext(
             runtime_type="codex",
             project_dir=config.project_dir,
@@ -330,9 +367,7 @@ class CodexAgentActivation:
 
     async def execute(self, request: Any) -> CodexTurnResult:
         if not self._ready or self._disposed:
-            raise PluginHostError(
-                "codex_activation_unavailable", "Codex activation is not ready"
-            )
+            raise PluginHostError("codex_activation_unavailable", "Codex activation is not ready")
         turn = CodexTurnRequest.parse(request)
         selected_model = turn.model or self._config.model
         if selected_model not in self._config.allowed_models:
@@ -379,9 +414,7 @@ class CodexAgentActivation:
         """
 
         if not self._ready or self._disposed:
-            raise PluginHostError(
-                "codex_activation_unavailable", "Codex activation is not ready"
-            )
+            raise PluginHostError("codex_activation_unavailable", "Codex activation is not ready")
         adapter = self._executor.create_adapter(self._launch_context)
         self._kernel_adapters.append(adapter)
         return adapter
@@ -405,6 +438,9 @@ class CodexAgentActivation:
     async def drain(self) -> None:
         self._ready = False
 
+    async def abort(self) -> None:
+        await self._mcp_projection.aclose()
+
     async def dispose(self) -> None:
         self._ready = False
         first_error: BaseException | None = None
@@ -423,6 +459,11 @@ class CodexAgentActivation:
         except BaseException as error:  # cleanup must continue
             if first_error is None:
                 first_error = error
+        try:
+            await self._mcp_projection.aclose()
+        except BaseException as error:  # security cleanup must still finish
+            if first_error is None:
+                first_error = error
         self._disposed = True
         if first_error is not None:
             raise first_error
@@ -440,13 +481,69 @@ def _reject_aliased_duplicates(
             )
 
 
+def _with_projected_mcp(
+    config: _CodexBundleConfig,
+    projection: MCPProjectionLease,
+) -> _CodexBundleConfig:
+    """Add activation-scoped connectors to Codex's generic launch config."""
+
+    launch = dict(config.launch_config)
+    servers = [dict(item) for item in launch.get("mcp_servers") or []]
+    environment = dict(launch.get("env") or {})
+    names = {str(item.get("name") or "") for item in servers}
+    for spec in projection.specs:
+        parsed = urlparse(spec.url)
+        if (
+            parsed.scheme not in {"http", "https"}
+            or not parsed.hostname
+            or parsed.username is not None
+            or parsed.password is not None
+            or parsed.fragment
+        ):
+            raise PluginHostError(
+                "codex_mcp_projection_invalid",
+                f"projected MCP connector {spec.name!r} has an invalid endpoint",
+            )
+        if spec.name in names:
+            raise PluginHostError(
+                "codex_mcp_projection_ambiguous",
+                f"projected MCP connector {spec.name!r} conflicts with the Bundle",
+            )
+        server: dict[str, Any] = {
+            "name": spec.name,
+            "transport": "http",
+            "url": spec.url,
+        }
+        if spec.api_key is not None:
+            suffix = hashlib.sha256(spec.name.encode()).hexdigest()[:16].upper()
+            env_key = f"KSADK_ACTIVATION_MCP_TOKEN_{suffix}"
+            if env_key in environment:
+                raise PluginHostError(
+                    "codex_mcp_projection_ambiguous",
+                    f"projected MCP connector {spec.name!r} has an environment collision",
+                )
+            environment[env_key] = spec.api_key
+            server["env_key"] = env_key
+        servers.append(server)
+        names.add(spec.name)
+    launch["mcp_servers"] = servers
+    launch["env"] = environment
+    inventory = replace(
+        config.inventory,
+        mcp_servers=tuple(item["name"] for item in servers),
+    )
+    return replace(config, launch_config=launch, inventory=inventory)
+
+
 def _reject_external_execution(
     bundle: ResolvedPluginBundle,
     capabilities: PluginExecutionContext,
 ) -> None:
     del capabilities
     profile_config = bundle.composition.profile.agent_provider.config
-    allowed_config = {"runtimeType", "runtimeVersion"}
+    allowed_config = {
+        "runtimeType", "runtimeVersion", "studioManifestDigest", "studioBuildFingerprint",
+    }
     unsupported_config = sorted(set(profile_config) - allowed_config)
     execution = bundle.resolved_agent_spec.get("execution")
     strategy = (
@@ -472,6 +569,8 @@ def _resolve_bundle_config(
     *,
     plugin_id: str,
     credential_resolver: Any,
+    runtime_state_root: Path | None,
+    local_launch: RuntimeLaunchContext | None = None,
 ) -> _CodexBundleConfig:
     spec = bundle.resolved_agent_spec
     raw_model = spec.get("model")
@@ -485,6 +584,13 @@ def _resolve_bundle_config(
             "codex_bundle_model_missing", "Bundle resolved Agent spec has no model"
         )
     allowed_models = _resolve_allowed_models(bundle, default_model=model)
+    if local_launch is not None:
+        # The trusted host verified the original Codex manifest referenced by
+        # this Bundle. YAML-only model names may have no Catalog profile IDs.
+        model = str(local_launch.config["model"])
+        allowed_models = tuple(local_launch.config["models"])
+        if not allowed_models or model not in allowed_models:
+            raise PluginHostError("codex_bundle_model_inventory_invalid", "Invalid local models")
     instructions = spec.get("instructions")
     if not isinstance(instructions, Mapping):
         raise PluginHostError(
@@ -512,29 +618,46 @@ def _resolve_bundle_config(
             "codex_tools_unsupported", "Codex only accepts its native tools, MCP, and Skills"
         )
     skills = _resolve_skills(bundle.root, capabilities.get("skills"))
-    mcp_servers, env = _resolve_mcp(
+    mcp_servers, mcp_env = _resolve_mcp(
         capabilities.get("mcpServers") or capabilities.get("mcp_servers"),
         credential_resolver=credential_resolver,
     )
+    # Local Studio has already resolved its original Codex credential policy.
+    # A second, stricter generic Bundle lookup would reject native-auth builds
+    # before their approved launch environment can be applied below.
+    model_env = {} if local_launch is not None else _resolve_model_env(
+        raw_model,
+        model=model,
+        credential_resolver=credential_resolver,
+    )
     execution = spec.get("execution")
     execution = execution if isinstance(execution, Mapping) else {}
-    project_dir = bundle.root / "runtime"
-    if not project_dir.is_dir():
-        project_dir = bundle.root
+    project_dir = (
+        local_launch.project_dir if local_launch is not None
+        else _resolve_runtime_workspace(bundle, runtime_state_root=runtime_state_root)
+    )
     launch_config: dict[str, Any] = {
         "model": model,
         "models": list(allowed_models),
         "prompt": str(instructions.get("system") or "").strip(),
         "task_prompt": str(instructions.get("task") or "").strip(),
-        "sandbox": str(execution.get("sandbox") or "read_only"),
+        # Match Studio's workspace default.  A missing execution stanza should
+        # still allow ordinary project work while auto-reviewing risky actions;
+        # read-only remains available when the Bundle declares it explicitly.
+        "sandbox": str(execution.get("sandbox") or "workspace_write_auto"),
         "approval_mode": str(execution.get("approvalMode") or execution.get("approval_mode") or ""),
         "turn_timeout_seconds": int(
             execution.get("timeoutSeconds") or execution.get("timeout_seconds") or 120
         ),
         "mcp_servers": mcp_servers,
         "skills": skills,
-        "env": env,
+        "env": {**mcp_env, **model_env},
     }
+    if local_launch is not None:
+        launch_config.update(local_launch.config)
+    # Local launch compatibility never replaces immutable Bundle Skill bytes.
+    launch_config["skills"] = skills
+    launch_config["enforce_bound_skills"] = True
     return _CodexBundleConfig(
         model=model,
         allowed_models=allowed_models,
@@ -550,6 +673,116 @@ def _resolve_bundle_config(
     )
 
 
+def _resolve_runtime_workspace(
+    bundle: ResolvedPluginBundle,
+    *,
+    runtime_state_root: Path | None,
+) -> Path:
+    """Keep Codex state and generated files outside the immutable Bundle.
+
+    A Bundle is integrity-checked again whenever a session opens. Using it as
+    Codex's working directory lets CODEX_HOME and ordinary workspace writes add
+    undeclared files, which makes the next open look like bundle corruption.
+    """
+
+    state_root = (
+        runtime_state_root
+        if runtime_state_root is not None
+        else bundle.root.parent / ".runtime-state"
+    ).resolve()
+    safe_agent_id = (
+        "".join(
+            character if character.isalnum() or character in {"-", "_", "."} else "-"
+            for character in bundle.manifest.agent_id
+        ).strip("-.")
+        or "agent"
+    )
+    workspace = (state_root / "codex-workspaces" / safe_agent_id).resolve()
+    try:
+        workspace.relative_to(bundle.root)
+    except ValueError:
+        pass
+    else:
+        raise PluginHostError(
+            "codex_runtime_state_invalid",
+            "Codex runtime state must be outside the immutable Bundle",
+        )
+    try:
+        workspace.mkdir(parents=True, exist_ok=True)
+    except OSError as error:
+        raise PluginHostError(
+            "codex_runtime_state_unavailable",
+            "Codex runtime workspace could not be initialized",
+        ) from error
+    return workspace
+
+
+def _resolve_model_env(
+    value: Mapping[str, Any],
+    *,
+    model: str,
+    credential_resolver: Any,
+) -> dict[str, str]:
+    """Resolve the Bundle-pinned model connection for the Codex subprocess."""
+
+    endpoint = str(
+        value.get("endpointUrl")
+        or value.get("endpoint_url")
+        or value.get("baseUrl")
+        or value.get("base_url")
+        or ""
+    ).strip()
+    for suffix in ("/chat/completions", "/responses"):
+        if endpoint.endswith(suffix):
+            endpoint = endpoint[: -len(suffix)]
+            break
+
+    env = {"OPENAI_MODEL_NAME": model}
+    if endpoint:
+        env["OPENAI_BASE_URL"] = endpoint.rstrip("/")
+        env["OPENAI_API_BASE"] = endpoint.rstrip("/")
+
+    wire_api = str(value.get("wireApi") or value.get("wire_api") or "").strip().lower()
+    host = (urlparse(endpoint).hostname or "").lower() if endpoint else ""
+    if "KSADK_CODEX_USE_PROXY" not in os.environ and (
+        wire_api == "chat" or host == "kspmas.ksyun.com" or host.endswith(".kspmas.ksyun.com")
+    ):
+        # Codex speaks Responses natively.  Known chat-only gateways need the
+        # local protocol bridge and must not spend the first turn probing an
+        # endpoint whose protocol is already declared by the immutable Bundle.
+        env["KSADK_CODEX_USE_PROXY"] = "1"
+
+    reference = str(value.get("credentialRef") or value.get("credential_ref") or "").strip()
+    if not reference:
+        return env
+    if credential_resolver is None:
+        raise PluginHostError(
+            "codex_model_credential_unavailable",
+            "Codex Bundle model requires a credential resolver",
+        )
+    try:
+        credential = (
+            credential_resolver.resolve(reference)
+            if hasattr(credential_resolver, "resolve")
+            else credential_resolver(reference)
+        )
+    except Exception as error:
+        raise PluginHostError(
+            "codex_model_credential_unavailable",
+            "Codex Bundle model credential could not be resolved",
+        ) from error
+    if not str(credential):
+        raise PluginHostError(
+            "codex_model_credential_unavailable",
+            "Codex Bundle model credential is empty",
+        )
+    # Model connection keys are reserved for the model. An MCP binding may use
+    # arbitrary environment names, but it must not replace the model gateway's
+    # credential or endpoint in the child process.
+    env["OPENAI_API_KEY"] = str(credential)
+    return env
+
+
 def _resolve_allowed_models(
     bundle: ResolvedPluginBundle,
     *,
@@ -563,14 +796,10 @@ def _resolve_allowed_models(
     instead of silently widening run-level model selection.
     """
 
-    if not any(
-        entry.path == "runtime-lock.json" for entry in bundle.manifest.files
-    ):
+    if not any(entry.path == "runtime-lock.json" for entry in bundle.manifest.files):
         return (default_model,)
     try:
-        payload = json.loads(
-            (bundle.root / "runtime-lock.json").read_text(encoding="utf-8")
-        )
+        payload = json.loads((bundle.root / "runtime-lock.json").read_text(encoding="utf-8"))
     except (OSError, UnicodeError, json.JSONDecodeError) as error:
         raise PluginHostError(
             "codex_bundle_model_inventory_invalid",
@@ -587,9 +816,7 @@ def _resolve_allowed_models(
             "codex_bundle_model_inventory_invalid",
             "Bundle runtime-lock.json must declare models as a list",
         )
-    models = tuple(
-        dict.fromkeys(str(item).strip() for item in raw_models if str(item).strip())
-    )
+    models = tuple(dict.fromkeys(str(item).strip() for item in raw_models if str(item).strip()))
     if not models or default_model not in models:
         raise PluginHostError(
             "codex_bundle_model_inventory_invalid",
@@ -624,9 +851,7 @@ def _resolve_skills(root: Path, value: Any) -> list[dict[str, str]]:
                 "codex_skill_invalid", f"Bundle Skill {name!r} escapes the Bundle root"
             ) from error
         if not (path / "SKILL.md").is_file():
-            raise PluginHostError(
-                "codex_skill_missing", f"Bundle Skill {name!r} has no SKILL.md"
-            )
+            raise PluginHostError("codex_skill_missing", f"Bundle Skill {name!r} has no SKILL.md")
         if name in seen:
             raise PluginHostError("codex_skill_invalid", f"duplicate Bundle Skill {name!r}")
         seen.add(name)
@@ -641,12 +866,12 @@ def _resolve_mcp(
     value: Any,
     *,
     credential_resolver: Any,
-) -> tuple[list[dict[str, str]], dict[str, str]]:
+) -> tuple[list[dict[str, Any]], dict[str, str]]:
     if value is None:
         return [], {}
     if not isinstance(value, Sequence) or isinstance(value, (str, bytes)):
         raise PluginHostError("codex_mcp_invalid", "Bundle MCP servers must be a list")
-    servers: list[dict[str, str]] = []
+    servers: list[dict[str, Any]] = []
     env: dict[str, str] = {}
     seen: set[str] = set()
     for index, item in enumerate(value):
@@ -659,26 +884,62 @@ def _resolve_mcp(
         url = str(item.get("endpointUrl") or item.get("endpoint_url") or "").strip()
         if not name or name in seen:
             raise PluginHostError("codex_mcp_invalid", "Bundle MCP names must be unique")
-        if transport not in {"http", "sse"} or not url:
-            raise PluginHostError(
-                "codex_mcp_transport_unsupported",
-                f"Codex Bundle MCP {name!r} requires an http/sse endpoint",
-            )
         env_refs = item.get("envRefs") or item.get("env_refs") or {}
         if not isinstance(env_refs, Mapping):
             raise PluginHostError(
                 "codex_mcp_invalid", f"Bundle MCP {name!r} envRefs must be an object"
             )
-        if len(env_refs) > 1:
+        if transport in {"http", "sse"} and len(env_refs) > 1:
             raise PluginHostError(
                 "codex_mcp_credentials_unsupported",
                 f"Codex HTTP MCP {name!r} accepts at most one bearer credential",
             )
-        server = {"name": name, "url": url}
+        if transport == "stdio":
+            command = str(item.get("command") or "").strip()
+            raw_args = item.get("args") or []
+            if (
+                not command
+                or not isinstance(raw_args, Sequence)
+                or isinstance(raw_args, (str, bytes))
+                or len(raw_args) > 128
+                or any(
+                    not isinstance(argument, str) or len(argument) > 4096 or "\x00" in argument
+                    for argument in raw_args
+                )
+            ):
+                raise PluginHostError(
+                    "codex_mcp_invalid",
+                    f"Codex Bundle stdio MCP {name!r} has an invalid command or args",
+                )
+            executable = Path(command).name.casefold()
+            if executable in {"sh", "bash", "zsh", "cmd", "cmd.exe", "powershell", "pwsh"}:
+                raise PluginHostError(
+                    "codex_mcp_command_denied",
+                    f"Codex Bundle stdio MCP {name!r} cannot launch a shell",
+                )
+            if any(argument in {"-c", "-e", "--eval"} for argument in raw_args):
+                raise PluginHostError(
+                    "codex_mcp_command_denied",
+                    f"Codex Bundle stdio MCP {name!r} cannot use inline evaluation",
+                )
+            server: dict[str, Any] = {
+                "name": name,
+                "transport": "stdio",
+                "command": command,
+                "args": list(raw_args),
+            }
+        elif transport in {"http", "sse"} and url:
+            server = {"name": name, "transport": transport, "url": url}
+        else:
+            raise PluginHostError(
+                "codex_mcp_transport_unsupported",
+                f"Codex Bundle MCP {name!r} requires stdio or an http/sse endpoint",
+            )
+        forwarded_env: dict[str, str] = {}
         for env_name, reference in env_refs.items():
             env_key = str(env_name).strip()
             ref = str(reference).strip()
-            if not env_key or not ref.startswith(
+            if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", env_key) or not ref.startswith(
                 ("env://", "secret://", "credential://", "vault://")
             ):
                 raise PluginHostError(
@@ -707,7 +968,12 @@ def _resolve_mcp(
                     f"Bundle MCP {name!r} credential is empty",
                 )
             env[env_key] = str(value)
-            server["env_key"] = env_key
+            if transport == "stdio":
+                forwarded_env[env_key] = ref
+            else:
+                server["env_key"] = env_key
+        if forwarded_env:
+            server["env_refs"] = forwarded_env
         servers.append(server)
         seen.add(name)
     return servers, env