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

ksadk/studio/codex_agent_service.py

@@ -20,6 +20,7 @@ from typing import Any, Callable, cast
 from pydantic import ValidationError
 
 from ksadk.managed_runtime import installed_runtime_version
+from ksadk.plugins.providers.dsh import DSH_HOST_USER_PERMISSION
 from ksadk.studio.codex_builder import CodexBuildRecord
 from ksadk.studio.codex_manifest import (
     CodexAgentManifest,
@@ -168,6 +169,11 @@ class CodexAgentService:
             )
         resolved = (spec or default_agent_spec("blank")).model_copy(deep=True)
         resolved.runtime = RuntimeRef(type="codex", version=self._runtime_version(resolved))
+        # Selecting the wheel-owned Codex Runtime also selects its shipped Provider.
+        # Grant only that Provider's required host permission on first creation;
+        # third-party plugins still require explicit Agent-level authorization.
+        if DSH_HOST_USER_PERMISSION not in resolved.security.allowed_permissions:
+            resolved.security.allowed_permissions.append(DSH_HOST_USER_PERMISSION)
         self.ensure_bindings_supported(resolved)
         manifest = self._manifest(agent_id, resolved)
         snapshot = self.studio.codex_manifests.save(manifest)
@@ -204,6 +210,7 @@ class CodexAgentService:
             )
         resolved = spec.model_copy(deep=True)
         resolved.runtime = current.spec.runtime
+        self._ensure_mcp_bindings_supported(resolved)
         # 早期 Studio 曾把 ksadk Tool 写进 Codex 草稿，尽管 Codex Runtime
         # 从未执行这些绑定。允许原样保存这类 dormant 历史数据，避免用户只改
         # Prompt/Model 时被迫丢绑定；新增、删除或修改仍按当前能力矩阵拒绝。
@@ -251,8 +258,7 @@ class CodexAgentService:
         self.drafts.save(updated)
         return self._project(snapshot, current=updated)
 
-    @staticmethod
-    def ensure_bindings_supported(spec: AgentSpec) -> None:
+    def ensure_bindings_supported(self, spec: AgentSpec) -> None:
         bindings = spec.bindings
         if bindings.tools or spec.capabilities.tools:
             raise StudioError(
@@ -263,6 +269,34 @@ class CodexAgentService:
                 details={"runtimeType": "codex"},
             )
         # codex 支持 streamable-http MCP（通过 config_overrides 注入 mcp_servers）。
+        self._ensure_mcp_bindings_supported(spec)
+
+    def _ensure_mcp_bindings_supported(self, spec: AgentSpec) -> None:
+        direct_dynamic = [
+            server.name
+            for server in spec.capabilities.mcp_servers
+            if server.enabled and server.materialization == "dsh-profile"
+        ]
+        if direct_dynamic:
+            raise StudioError(
+                "DSH_MCP_MANAGED_BINDING_REQUIRED",
+                "DSH Profile MCP 必须从当前 Catalog Resource 显式绑定，不能直接写入 AgentSpec",
+                status_code=422,
+                field="spec.capabilities.mcpServers",
+                details={"servers": sorted(direct_dynamic)},
+            )
+        for binding in spec.bindings.mcp_servers:
+            if not binding.enabled:
+                continue
+            descriptor = self.studio.catalog.get(binding.resource_id)
+            if descriptor.contract.get("materialization") == "dsh-profile":
+                raise StudioError(
+                    "DSH_MCP_RUNTIME_INCOMPATIBLE",
+                    "DSH Profile MCP 当前只支持 Harness Runtime",
+                    status_code=422,
+                    field="spec.runtime.type",
+                    details={"runtimeType": "codex"},
+                )
 
     def _skill_resource_ids(self, spec: AgentSpec) -> list[str]:
         bindings = spec.bindings
@@ -277,7 +311,7 @@ class CodexAgentService:
         return ordered
 
     def _mcp_server_configs(self, spec: AgentSpec) -> list[dict[str, Any]]:
-        """Resolve bound MCP resource ids to codex streamable-http MCP configs."""
+        """Resolve bound MCP resources to native Codex HTTP or stdio configs."""
         bindings = spec.bindings
         ids = [b.resource_id for b in bindings.mcp_servers]
         ids.extend(spec.capabilities.mcp_servers or [])
@@ -299,26 +333,51 @@ class CodexAgentService:
             if descriptor is None:
                 continue
             contract = descriptor.contract or {}
+            if contract.get("materialization") == "dsh-profile":
+                raise StudioError(
+                    "DSH_MCP_RUNTIME_INCOMPATIBLE",
+                    "DSH Profile MCP 不能物化为 Codex MCP 配置",
+                    status_code=422,
+                    field="spec.bindings.mcpServers",
+                    details={"runtimeType": "codex"},
+                )
             url = str(
                 contract.get("endpointUrl")
                 or contract.get("endpoint_url")
                 or contract.get("url")
                 or ""
             ).strip()
-            if not url:
+            transport = str(contract.get("transport") or ("http" if url else "")).lower()
+            command = str(contract.get("command") or "").strip()
+            if transport == "stdio" and command:
+                entry: dict[str, Any] = {
+                    "name": descriptor.name,
+                    "transport": "stdio",
+                    "command": command,
+                    "args": [str(argument) for argument in (contract.get("args") or [])],
+                }
+            elif transport in {"http", "sse"} and url:
+                entry = {
+                    "name": descriptor.name,
+                    "url": url,
+                }
+                if transport == "sse":
+                    entry["transport"] = transport
+            else:
                 continue
             env_refs = contract.get("envRefs") or {}
-            env_key = ""
-            for ref in env_refs.values():
-                if isinstance(ref, str) and ref.startswith("env://"):
-                    env_key = ref.removeprefix("env://")
-                    break
-            entry: dict[str, Any] = {
-                "name": descriptor.name,
-                "url": url,
-            }
-            if env_key:
-                entry["env_key"] = env_key
+            if transport == "stdio" and isinstance(env_refs, dict) and env_refs:
+                entry["env_refs"] = {
+                    str(env_name): str(reference) for env_name, reference in env_refs.items()
+                }
+            elif isinstance(env_refs, dict):
+                env_key = ""
+                for ref in env_refs.values():
+                    if isinstance(ref, str) and ref.startswith("env://"):
+                        env_key = ref.removeprefix("env://")
+                        break
+                if env_key:
+                    entry["env_key"] = env_key
             ordered.append(entry)
         return ordered
 
@@ -398,7 +457,7 @@ class CodexAgentService:
 
     @staticmethod
     def build_view(record: CodexBuildRecord) -> dict:
-        return {
+        payload = {
             "id": record.id,
             "agentId": record.agent_name,
             "sourceRevision": record.source_revision,
@@ -412,9 +471,30 @@ class CodexAgentService:
             "manifestSha256": record.manifest_sha256,
             "runtimeLock": record.runtime_lock,
             "runtimeName": record.runtime_name,
+            "localExecution": record.local_execution,
+            "providerBundle": (record.provider_bundle.model_dump(by_alias=True)
+                               if record.provider_bundle else None),
             "runtimeVersion": record.runtime_version,
             "proxyMode": record.proxy_mode,
         }
+        if record.plugin_lock is not None:
+            payload.update(
+                {
+                    "pluginLock": record.plugin_lock.model_dump(
+                        by_alias=True, exclude_none=True, mode="json"
+                    ),
+                    "pluginLockDigest": record.plugin_lock_digest,
+                    "pluginMarketplace": (
+                        record.plugin_marketplace.model_dump(
+                            by_alias=True, exclude_none=True, mode="json"
+                        )
+                        if record.plugin_marketplace is not None
+                        else None
+                    ),
+                    "pluginRuntimeStatus": record.plugin_runtime_status or {},
+                }
+            )
+        return payload
 
     def submit_build(
         self,
@@ -426,6 +506,7 @@ class CodexAgentService:
         revision = self._project(self.studio.codex_manifests.load(resolved_id)).metadata.revision
 
         async def runner(_operation_id: str):
+            await self.studio.start()
             return await asyncio.to_thread(
                 self.studio.codex_builder.build,
                 resolved_id,
@@ -494,8 +575,7 @@ class CodexAgentService:
         bindings = self._model_bindings(manifest)
         mcp_bindings, _unresolved_mcp = self._mcp_bindings(manifest)
         skill_bindings = [
-            CapabilityBinding(resource_id=resource_id)
-            for resource_id in (manifest.skills or [])
+            CapabilityBinding(resource_id=resource_id) for resource_id in (manifest.skills or [])
         ]
         # 从 Manifest 恢复 PCM context/memory（方案 §5.1：Build 不可变）
         # Manifest 已在 model_validate 时严格校验；这里直接恢复
@@ -518,6 +598,7 @@ class CodexAgentService:
             draft.spec.bindings.model_profile_ids = bindings[1]
             draft.spec.bindings.skills = skill_bindings
             draft.spec.bindings.mcp_servers = mcp_bindings
+            draft.spec.bindings.plugins = list(manifest.plugins or [])
             draft.spec.context = context_spec
             draft.spec.memory = memory_spec
             draft.metadata.labels.update(self._labels(manifest))
@@ -542,6 +623,7 @@ class CodexAgentService:
                     model_profile_ids=profiles,
                     skills=skill_bindings,
                     mcp_servers=mcp_bindings,
+                    plugins=list(manifest.plugins or []),
                 ),
                 context=context_spec,
                 memory=memory_spec,
@@ -589,6 +671,7 @@ class CodexAgentService:
             soul=spec.soul,
             skills=skill_ids or None,
             mcp_servers=mcp_servers or None,
+            plugins=list(spec.bindings.plugins) or None,
             sandbox=spec.execution.sandbox,
             approval_mode=spec.execution.approval_mode,
             context=context_payload,
@@ -668,22 +751,41 @@ class CodexAgentService:
                 or contract.get("url")
                 or ""
             ).strip()
-            if name and url:
-                resources.setdefault((name, url), descriptor.resource_id)
+            transport = str(contract.get("transport") or ("http" if url else "")).lower()
+            address = (
+                json.dumps(
+                    [str(contract.get("command") or ""), *(contract.get("args") or [])],
+                    separators=(",", ":"),
+                )
+                if transport == "stdio"
+                else url
+            )
+            if name and address:
+                resources.setdefault((name, address), descriptor.resource_id)
 
         bindings: builtins.list[CapabilityBinding] = []
         unresolved: builtins.list[dict[str, str]] = []
         for entry in manifest.mcp_servers or []:
             name = str(entry.get("name") or "").strip()
-            url = str(entry.get("url") or "").strip()
-            resource_id = resources.get((name, url))
+            transport = str(entry.get("transport") or ("http" if entry.get("url") else "")).lower()
+            address = (
+                json.dumps(
+                    [str(entry.get("command") or ""), *(entry.get("args") or [])],
+                    separators=(",", ":"),
+                )
+                if transport == "stdio"
+                else str(entry.get("url") or "").strip()
+            )
+            resource_id = resources.get((name, address))
             if resource_id:
                 bindings.append(CapabilityBinding(resource_id=resource_id))
             else:
-                unresolved.append({
-                    "name": name or "未命名 MCP",
-                    "reason": "not-in-resource-catalog",
-                })
+                unresolved.append(
+                    {
+                        "name": name or "未命名 MCP",
+                        "reason": "not-in-resource-catalog",
+                    }
+                )
         return bindings, unresolved
 
     @staticmethod

ksadk/studio/codex_builder.py

@@ -12,7 +12,7 @@ from pathlib import Path
 from typing import Any, Callable, Literal, cast
 
 import yaml  # type: ignore[import-untyped]
-from pydantic import ValidationError
+from pydantic import ValidationError, model_validator
 
 from ksadk.builders.managed_runtime_builder import (
     ManagedRuntimeBuilder,
@@ -24,9 +24,25 @@ from ksadk.managed_runtime import (
     validate_installed_runtime,
     validate_runtime_binary,
 )
+from ksadk.plugins.artifacts import PluginArtifactReceipt
+from ksadk.plugins.contracts import (
+    LockedPluginComponent,
+    PluginLock,
+    PluginLockEntry,
+    plugin_lock_digest,
+)
 from ksadk.studio.codex_manifest import CodexManifestRepository
+from ksadk.studio.codex_plugin_store import (
+    CodexPinnedMarketplace,
+    CodexPluginSnapshotStore,
+    CodexWorkspacePluginSnapshot,
+    component_selector,
+)
+from ksadk.studio.codex_provider_build import CodexProviderBuildReference
 from ksadk.studio.contracts import ContractModel, ModelSpec
 from ksadk.studio.errors import StudioError, not_found
+from ksadk.studio.resource_binding_validation import resource_binding_diagnostics
+from ksadk.studio.resource_connections import ResourceConnectionRepository
 from ksadk.studio.workspace import Workspace
 from ksadk.version import VERSION as SDK_VERSION
 
@@ -58,8 +74,22 @@ class CodexBuildRecord(ContractModel):
     # stale with an actionable rebuild; Phase 2 has not shipped yet, so the
     # deployment path does not carry a legacy identity-migration branch.
     model_profile_ids: list[str] | None = None
+    # Omitted for builds without native plugins so existing on-disk receipts
+    # and their historical build ids remain byte-shape compatible.
+    plugin_lock: PluginLock | None = None
+    plugin_lock_digest: str | None = None
+    plugin_marketplace: CodexPinnedMarketplace | None = None
+    plugin_runtime_status: dict[str, dict[str, Any]] | None = None
+    local_execution: Literal["legacy", "provider"] = "legacy"
+    provider_bundle: CodexProviderBuildReference | None = None
     created_at: datetime
 
+    @model_validator(mode="after")
+    def local_execution_reference(self):
+        if (self.local_execution == "provider") != (self.provider_bundle is not None):
+            raise ValueError("Provider execution requires its complete local Bundle reference")
+        return self
+
 
 class CodexBuildRepository:
     def __init__(self, workspace: Workspace) -> None:
@@ -259,6 +289,10 @@ class CodexStudioBuilder:
         runtime_inspector: RuntimeInspector = _inspect_runtime,
         resource_catalog: Any = None,
         draft_repository: Any = None,
+        plugin_snapshot_store: CodexPluginSnapshotStore | None = None,
+        resource_connections: ResourceConnectionRepository | None = None,
+        provider_build: Callable[..., CodexProviderBuildReference] | None = None,
+        provider_validate: Callable[[CodexBuildRecord], Any] | None = None,
     ) -> None:
         self.workspace = workspace
         self.manifests = manifest_repository or CodexManifestRepository(workspace)
@@ -266,6 +300,10 @@ class CodexStudioBuilder:
         self.runtime_inspector = runtime_inspector
         self.catalog = resource_catalog
         self.drafts = draft_repository
+        self.plugin_snapshots = plugin_snapshot_store or CodexPluginSnapshotStore(workspace)
+        self.resource_connections = resource_connections
+        self.provider_build = provider_build
+        self.provider_validate = provider_validate
 
     def build(
         self,
@@ -274,16 +312,45 @@ class CodexStudioBuilder:
         source_revision: int = 1,
     ) -> CodexBuildRecord:
         snapshot = self.manifests.load(agent_id)
+        if self.resource_connections is not None:
+            diagnostics = resource_binding_diagnostics(
+                snapshot.manifest.plugins or [], snapshot.manifest.memory,
+                self.resource_connections,
+            )
+            if any(item.severity == "error" for item in diagnostics):
+                raise StudioError(
+                    "RESOURCE_BINDING_VALIDATION_FAILED", "资源连接或策略校验失败",
+                    status_code=422,
+                    details={
+                        "diagnostics": [item.model_dump(by_alias=True) for item in diagnostics]
+                    },
+                )
         model_profiles = self._model_profile_snapshot(
             snapshot.manifest.name,
             allowed_models=snapshot.manifest.allowed_models,
             ignore_missing=True,
         )
         model_profile_ids = self._bound_model_profile_ids(snapshot.manifest.name)
+        (
+            native_plugin_lock,
+            plugin_selections,
+            plugin_runtime_status,
+        ) = self._native_plugin_lock(snapshot.manifest.plugins or [])
+        native_plugin_lock_digest = (
+            plugin_lock_digest(native_plugin_lock) if native_plugin_lock.plugins else None
+        )
+        provider_bundle = (
+            self.provider_build(
+                snapshot, model_profiles, model_profile_ids, native_plugin_lock_digest,
+            )
+            if self.provider_build is not None else None
+        )
         build_id = self._build_id(
             snapshot.manifest_sha256,
             model_profiles,
             model_profile_ids=model_profile_ids,
+            plugin_lock_digest_value=native_plugin_lock_digest,
+            provider_bundle_digest=provider_bundle.digest if provider_bundle else None,
         )
         try:
             existing = self.repository.get(build_id)
@@ -336,6 +403,14 @@ class CodexStudioBuilder:
                 "构建产物与当前 agentengine.yaml 摘要不一致",
                 status_code=500,
             )
+        pinned_marketplace = (
+            self.plugin_snapshots.materialize_marketplace(
+                plugin_lock_digest=native_plugin_lock_digest,
+                selections=plugin_selections,
+            )
+            if native_plugin_lock_digest is not None
+            else None
+        )
         record = CodexBuildRecord(
             id=build_id,
             agent_name=snapshot.manifest.name,
@@ -350,14 +425,75 @@ class CodexStudioBuilder:
             runtime_lock=lock,
             model_profiles=model_profiles,
             model_profile_ids=model_profile_ids,
+            plugin_lock=native_plugin_lock if native_plugin_lock.plugins else None,
+            plugin_lock_digest=native_plugin_lock_digest,
+            plugin_marketplace=pinned_marketplace,
+            plugin_runtime_status=plugin_runtime_status or None,
+            local_execution="provider" if provider_bundle else "legacy",
+            provider_bundle=provider_bundle,
             created_at=datetime.now(timezone.utc),
         )
         return self.repository.save(record)
 
+    def export_plugin_artifact(self, build_id: str) -> tuple[PluginArtifactReceipt, Path]:
+        """Export frozen plugin bytes without mutating the Build or installing.
+
+        This is the C1 content boundary. Deployment must still negotiate
+        control-plane support and validate the target dependency environment.
+        """
+        from ksadk.plugins.artifacts import export_plugin_artifact
+
+        build = self.repository.get(build_id)
+        pinned = build.plugin_marketplace
+        if pinned is None or build.plugin_lock is None:
+            raise StudioError("PLUGIN_ARTIFACT_EMPTY", "此 Build 未绑定原生插件", status_code=422)
+        if plugin_lock_digest(build.plugin_lock) != build.plugin_lock_digest:
+            raise StudioError("PLUGIN_LOCK_INVALID", "Build 插件锁摘要不匹配", status_code=422)
+        if pinned.plugin_lock_digest != build.plugin_lock_digest:
+            raise StudioError("PLUGIN_LOCK_INVALID", "插件快照与 Build 锁不匹配", status_code=422)
+        root = self.plugin_snapshots.verify_marketplace(pinned)
+        receipt, archive = export_plugin_artifact(
+            root,
+            self.workspace.resolve(".agentkit/plugin-artifacts"),
+            runtime_version=build.runtime_version,
+            plugin_lock_digest=build.plugin_lock_digest,
+        )
+        # Reject concurrent modifications; exported bytes must correspond to
+        # the frozen receipt, never a mutable workspace installation.
+        self.plugin_snapshots.verify_marketplace(pinned)
+        return receipt, archive
+
     def is_current(self, record: CodexBuildRecord) -> bool:
+        if record.local_execution == "provider":
+            if self.provider_validate is None:
+                return False
+            try:
+                self.provider_validate(record)
+            except StudioError:
+                return False
         snapshot = self.manifests.load(record.agent_name)
         if record.manifest_sha256 != snapshot.manifest_sha256:
             return False
+        current_plugin_lock, _selections, _status = self._native_plugin_lock(
+            snapshot.manifest.plugins or []
+        )
+        current_plugin_digest = (
+            plugin_lock_digest(current_plugin_lock) if current_plugin_lock.plugins else None
+        )
+        if record.plugin_lock_digest != current_plugin_digest:
+            return False
+        if record.plugin_lock is not None and record.plugin_lock != current_plugin_lock:
+            return False
+        if record.plugin_lock is None and current_plugin_lock.plugins:
+            return False
+        if record.plugin_marketplace is not None:
+            try:
+                self.plugin_snapshots.materialize_marketplace(
+                    plugin_lock_digest=record.plugin_marketplace.plugin_lock_digest,
+                    selections=_selections,
+                )
+            except (StudioError, ValueError):
+                return False
         if record.model_profiles is None:
             return True
         if record.model_profile_ids is None:
@@ -387,13 +523,21 @@ class CodexStudioBuilder:
         model_profiles: dict[str, dict[str, Any]],
         *,
         model_profile_ids: list[str] | None = None,
+        plugin_lock_digest_value: str | None = None,
+        provider_bundle_digest: str | None = None,
     ) -> str:
-        if not model_profiles and not model_profile_ids:
+        if (not model_profiles and not model_profile_ids
+                and plugin_lock_digest_value is None and provider_bundle_digest is None):
             return f"build_{manifest_sha256[:20]}"
         fingerprint = json.dumps(
             {
                 "profiles": model_profiles,
                 "resourceIds": sorted(model_profile_ids or []),
+                "pluginLockDigest": plugin_lock_digest_value,
+                **(
+                    {"providerBundleDigest": provider_bundle_digest}
+                    if provider_bundle_digest else {}
+                ),
             },
             ensure_ascii=False,
             sort_keys=True,
@@ -404,6 +548,101 @@ class CodexStudioBuilder:
         digest = hashlib.sha256(f"{manifest_sha256}\n{fingerprint}".encode()).hexdigest()
         return f"build_{digest[:20]}"
 
+    def _native_plugin_lock(
+        self,
+        bindings: list[Any] | tuple[Any, ...],
+    ) -> tuple[
+        PluginLock,
+        tuple[
+            tuple[CodexWorkspacePluginSnapshot, tuple[Any, ...]],
+            ...,
+        ],
+        dict[str, dict[str, Any]],
+    ]:
+        entries: list[PluginLockEntry] = []
+        selections: list[tuple[CodexWorkspacePluginSnapshot, tuple[Any, ...]]] = []
+        statuses: dict[str, dict[str, Any]] = {}
+        for binding in bindings:
+            if not binding.enabled:
+                continue
+            if binding.ecosystem != "codex":
+                from ksadk.resource_runtime.plugin_config import resource_plugin_config
+
+                # Official platform resources are DSH capabilities materialized by
+                # the Provider Bundle.  They belong in the resource Build lock,
+                # never in Codex's native marketplace lock.
+                if resource_plugin_config(
+                    binding.plugin_ref,
+                    binding.ecosystem,
+                    binding.config,
+                    enabled=True,
+                ) is not None:
+                    continue
+                raise StudioError(
+                    "CODEX_PLUGIN_ECOSYSTEM_UNSUPPORTED",
+                    "Codex Agent 目前只能运行 Codex 原生插件绑定",
+                    status_code=422,
+                    details={"pluginRef": binding.plugin_ref},
+                )
+            stored = self.plugin_snapshots.load(binding.snapshot_digest)
+            if stored.plugin_ref != binding.plugin_ref:
+                raise StudioError(
+                    "CODEX_PLUGIN_BINDING_MISMATCH",
+                    "Codex 插件绑定与不可变快照身份不一致",
+                    status_code=409,
+                    details={
+                        "pluginRef": binding.plugin_ref,
+                        "snapshotPluginRef": stored.plugin_ref,
+                        "snapshotDigest": binding.snapshot_digest,
+                    },
+                )
+            selected = stored.select_components(binding.components)
+            plugin_id, version = binding.plugin_ref.removeprefix("plugin://").rsplit("@", 1)
+            components = tuple(
+                LockedPluginComponent(
+                    id=component_selector(component),
+                    kind=component.kind,
+                    digest=component.content_digest,
+                    path=component.path,
+                )
+                for component in selected
+            )
+            entries.append(
+                PluginLockEntry(
+                    id=plugin_id,
+                    version=version,
+                    digest=stored.artifact_digest,
+                    source="local" if stored.source.type == "local" else "market",
+                    license=stored.manifest.license,
+                    upstream=stored.source.to_plugin_source_snapshot(),
+                    components=components,
+                )
+            )
+            hook_selectors = [
+                component_selector(component) for component in selected if component.kind == "hook"
+            ]
+            statuses[binding.plugin_ref] = (
+                {
+                    "runnable": False,
+                    "hookTrust": "unsupported",
+                    "reason": "official-trust-api-unavailable",
+                    "components": hook_selectors,
+                }
+                if hook_selectors
+                else {"runnable": True, "hookTrust": "not-required"}
+            )
+            selections.append((stored, selected))
+        try:
+            lock = PluginLock(plugins=entries)
+        except ValueError as exc:
+            raise StudioError(
+                "CODEX_PLUGIN_LOCK_INVALID",
+                "Codex 插件绑定无法编译为唯一、精确的 PluginLock",
+                status_code=422,
+                details={"reason": str(exc)},
+            ) from exc
+        return lock, tuple(selections), statuses
+
     def _model_profile_snapshot(
         self,
         agent_id: str,