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

ksadk/studio/codex_provider_build.py

@@ -0,0 +1,231 @@
+"""Local Codex Provider admission and Bundle references, separate from cloud YAML.
+
+A local Provider Bundle binds the existing immutable Codex record; native
+marketplace bytes remain governed by that record's original plugin lock.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+from pydantic import Field
+
+from ksadk.plugins.providers.codex_dsh import (
+    SHIPPED_CODEX_PROVIDER_ID,
+    SHIPPED_CODEX_PROVIDER_VERSION,
+)
+from ksadk.studio.contracts import ContractModel, RuntimeRef
+from ksadk.studio.errors import StudioError
+from ksadk.studio.resource_build_admission import (
+    admit_resource_build,
+    resource_build_required,
+)
+
+CODEX_PROVIDER_REF = f"plugin://{SHIPPED_CODEX_PROVIDER_ID}@{SHIPPED_CODEX_PROVIDER_VERSION}"
+
+
+def _digest(value: Any) -> str:
+    return (
+        "sha256:"
+        + hashlib.sha256(
+            json.dumps(
+                value,
+                sort_keys=True,
+                separators=(",", ":"),
+                ensure_ascii=False,
+            ).encode()
+        ).hexdigest()
+    )
+
+
+class CodexProviderBuildReference(ContractModel):
+    provider_ref: str = Field(pattern=r"^plugin://io\.ksadk\.codex-provider@[^/]+$")
+    registration_digest: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+    bundle_build_id: str = Field(pattern=r"^build_[0-9a-f]+$")
+    bundle_digest: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+
+    @property
+    def digest(self) -> str:
+        return _digest(self.model_dump(by_alias=True))
+
+
+class CodexProviderBuildManager:
+    def __init__(self, studio: Any):
+        self.studio = studio
+
+    def _registration_digest(self) -> str:
+        manifest = self.studio._active_provider_manifests.get(CODEX_PROVIDER_REF)
+        if manifest is None:
+            raise StudioError(
+                "AGENT_PROVIDER_NOT_REGISTERED",
+                "Codex Provider 未注册；请在插件中心安装并启用官方 Codex Provider，"
+                "确认 DSH 工具链可用后重试",
+                status_code=409,
+            )
+        return _digest(manifest.model_dump(by_alias=True, mode="json", exclude_none=True))
+
+    def prepare(
+        self,
+        snapshot,
+        model_profiles: dict,
+        model_profile_ids: list[str],
+        native_plugin_lock_digest: str | None,
+    ) -> CodexProviderBuildReference:
+        registration_digest = self._registration_digest()
+        # The current Provider owns one native client connection per activation.
+        # Model names may vary, but a different endpoint/credential needs a new
+        # activation contract; never silently send it to the default connection.
+        connections = {
+            (
+                p.get("provider", "openai-compatible"),
+                p.get("endpointUrl"),
+                p.get("baseUrl"),
+                p.get("credentialRef"),
+                p.get("wireApi"),
+            )
+            for p in model_profiles.values()
+        }
+        missing_profiles = set(snapshot.manifest.allowed_models) - set(model_profiles)
+        if len(connections) > 1 or (model_profiles and missing_profiles):
+            raise StudioError(
+                "CODEX_PROVIDER_MODEL_CONNECTION_UNSUPPORTED",
+                "当前 Codex Provider Build 的模型必须具有完整且相同的连接快照；"
+                "请补齐模型配置，或拆分不同连接的 Agent",
+                status_code=422,
+            )
+        draft = self.studio.codex_agents._project(snapshot).model_copy(deep=True)
+        draft.spec.runtime = RuntimeRef(
+            type="plugin",
+            provider_ref=CODEX_PROVIDER_REF,
+            version=snapshot.manifest.runtime.version,
+            provider_config={
+                "studioManifestDigest": "sha256:" + snapshot.manifest_sha256,
+                "studioBuildFingerprint": _digest(
+                    {
+                        "manifest": snapshot.manifest_sha256,
+                        "profiles": model_profiles,
+                        "resourceIds": sorted(model_profile_ids),
+                        "pluginLockDigest": native_plugin_lock_digest,
+                    }
+                ),
+            },
+        )
+        # This Bundle describes the Python AgentProvider. Codex-native marketplace
+        # selections stay in the manifest lock, while official DSH platform
+        # resources remain in this projected Draft and pass the same trusted
+        # resource admission used by framework runtimes.
+        draft.spec.bindings.plugins = [
+            binding
+            for binding in draft.spec.bindings.plugins
+            if binding.ecosystem == "dsh"
+        ]
+        manifest = self.studio._active_provider_manifests[CODEX_PROVIDER_REF]
+        missing_permissions = sorted(
+            set(manifest.spec.permissions) - set(draft.spec.security.allowed_permissions)
+        )
+        if missing_permissions:
+            raise StudioError(
+                "AGENT_PROVIDER_PERMISSION_DENIED",
+                "请打开 Agent 编辑页，在 Codex 本地执行权限中确认 Provider 请求的权限并保存；"
+                "安装插件时的同意不代替 Agent 授权",
+                status_code=422,
+                field="spec.security.allowedPermissions",
+                details={"missingPermissions": missing_permissions},
+            )
+        composition = self.studio.plugin_compositions.compile(draft)
+        resource_build = None
+        if resource_build_required(draft):
+            resource_build = admit_resource_build(
+                draft,
+                authority=self.studio.resource_authority,
+                connections=self.studio.resource_connections,
+                dsh_profile=(
+                    self.studio.resource_dsh_capabilities.capture_resource_build_snapshot()
+                ),
+            )
+        built = self.studio.builder.build(
+            draft,
+            composition=composition,
+            resource_build=resource_build,
+        )
+        # Refuse a registration change during staging, before saving success.
+        if self._registration_digest() != registration_digest:
+            raise StudioError(
+                "CODEX_PROVIDER_CHANGED", "Provider 构建期间发生变更", status_code=409
+            )
+        return CodexProviderBuildReference(
+            provider_ref=CODEX_PROVIDER_REF,
+            registration_digest=registration_digest,
+            bundle_build_id=built.id,
+            bundle_digest=built.bundle_digest,
+        )
+
+    def bundle_root(self, record):
+        reference = record.provider_bundle
+        if reference is None:
+            return None
+        if reference.provider_ref != CODEX_PROVIDER_REF or (
+            reference.registration_digest != self._registration_digest()
+        ):
+            raise StudioError(
+                "CODEX_PROVIDER_CHANGED", "Provider 注册已变更，请重新构建", status_code=409
+            )
+        try:
+            built = self.studio.builds.get(reference.bundle_build_id)
+        except StudioError as error:
+            raise StudioError(
+                "CODEX_PROVIDER_BUNDLE_UNAVAILABLE", "Provider Bundle 记录不可用，请重新构建",
+                status_code=409,
+            ) from error
+        if built.agent_id != record.agent_name or built.bundle_digest != reference.bundle_digest:
+            raise StudioError(
+                "CODEX_PROVIDER_BUILD_MISMATCH", "Provider Bundle 与 Build 不一致", status_code=409
+            )
+        root = self.studio.plugin_runs._bundle_root(built)
+        bundle = self.studio.plugin_runs._resolve_bundle(root)
+        if (
+            bundle.bundle_digest != reference.bundle_digest
+            or (bundle.composition.profile.agent_provider.ref != reference.provider_ref)
+            or bundle.composition.profile.agent_provider.config.get("studioManifestDigest")
+            != ("sha256:" + record.manifest_sha256)
+            or bundle.composition.profile.agent_provider.config.get("studioBuildFingerprint")
+            != _digest(
+                {
+                    "manifest": record.manifest_sha256,
+                    "profiles": record.model_profiles,
+                    "resourceIds": sorted(record.model_profile_ids or []),
+                    "pluginLockDigest": record.plugin_lock_digest,
+                }
+            )
+        ):
+            raise StudioError(
+                "CODEX_PROVIDER_BUILD_MISMATCH", "Provider Bundle 引用校验失败", status_code=409
+            )
+        return root
+
+    def native_launch(self, bundle):
+        """Trusted host callback; no model arguments or serialized secrets accepted."""
+        marker = bundle.composition.profile.agent_provider.config.get("studioManifestDigest")
+        if marker is None:
+            return None
+        registration_digest = self._registration_digest()
+        matches = [
+            record
+            for record in self.studio.codex_builds.list()
+            if record.provider_bundle is not None
+            and record.provider_bundle.bundle_digest == bundle.bundle_digest
+            and record.provider_bundle.registration_digest == registration_digest
+        ]
+        if len(matches) != 1:
+            raise StudioError(
+                "CODEX_PROVIDER_BUILD_MISMATCH",
+                "Provider Bundle 缺少唯一 Codex Build",
+                status_code=409,
+            )
+        record = matches[0]
+        self.bundle_root(record)
+        # Retain native bootstrap, credentials, exact build HOME and workspace
+        # from the existing resolver. No cloud schema or second launch policy.
+        return self.studio.codex_runs.resolve(record.id).launch_context

ksadk/studio/codex_run.py

@@ -2,19 +2,25 @@
 
 from __future__ import annotations
 
+import json
 import os
 import zipfile
 from typing import Any, cast
+from urllib.parse import urlparse
 
 import yaml  # type: ignore[import-untyped]
 
 from ksadk.configs import ModelConfig
+from ksadk.plugins.contracts import plugin_lock_digest
 from ksadk.runtime import RuntimeLaunchContext
 from ksadk.studio.codex_builder import CodexBuildRepository
+from ksadk.studio.codex_credentials import restore_mcp_oauth_credentials
 from ksadk.studio.codex_manifest import CodexAgentManifest, CodexManifestRepository
-from ksadk.studio.contracts import ModelSpec
+from ksadk.studio.codex_plugin_store import CodexPluginSnapshotStore
+from ksadk.studio.contracts import Instructions, ModelSpec
 from ksadk.studio.errors import StudioError
 from ksadk.studio.run_service import StudioRunSpec
+from ksadk.studio.soul import compose_system_instruction
 from ksadk.studio.workspace import Workspace
 from ksadk.tools.gateway import normalize_tool_approval_mode
 
@@ -31,6 +37,8 @@ class CodexRunSpecResolver:
         credential_resolver: Any = None,
         resource_catalog: Any = None,
         draft_repository: Any = None,
+        plugin_snapshot_store: CodexPluginSnapshotStore | None = None,
+        provider_bundle_resolver: Any = None,
     ) -> None:
         self.workspace = workspace
         self.builds = build_repository or CodexBuildRepository(workspace)
@@ -38,6 +46,8 @@ class CodexRunSpecResolver:
         self.credentials = credential_resolver
         self.catalog = resource_catalog
         self.drafts = draft_repository
+        self.plugin_snapshots = plugin_snapshot_store or CodexPluginSnapshotStore(workspace)
+        self.provider_bundle_resolver = provider_bundle_resolver
 
     def resolve(
         self,
@@ -48,6 +58,16 @@ class CodexRunSpecResolver:
         approval_mode: str | None = None,
     ) -> StudioRunSpec:
         build = self.builds.get(build_id)
+        provider_root = None
+        if build.local_execution == "provider":
+            if self.provider_bundle_resolver is None:
+                raise StudioError("CODEX_PROVIDER_REQUIRED", "此 Build 必须通过 Provider 运行",
+                                  status_code=409)
+            provider_root = self.provider_bundle_resolver(build)
+            if provider_root is None:
+                raise StudioError(
+                    "CODEX_PROVIDER_REQUIRED", "Provider Bundle 不可用", status_code=409,
+                )
         current = self.manifests.load(build.agent_name)
         if build.manifest_sha256 != current.manifest_sha256:
             raise StudioError(
@@ -60,6 +80,13 @@ class CodexRunSpecResolver:
                 },
             )
         manifest = self._load_build_manifest(build.artifact_path)
+        restore_mcp_oauth_credentials(
+            self.workspace.root,
+            build,
+            self.builds.list(),
+            manifest.mcp_servers or [],
+        )
+        plugin_bootstrap = self._plugin_bootstrap(build, manifest)
         selected_model = self._select_model(manifest, model)
         project_dir = self.workspace.root.resolve()
         skills = self._skill_inputs(manifest)
@@ -71,15 +98,20 @@ class CodexRunSpecResolver:
             approval_mode=approval_profile or None,
         )
         if sandbox == "workspace-write":
-            # workspace-write 默认断网；MCP/搜索类工具需要显式放行网络
+            # workspace-write 默认断网；原生搜索和 MCP 都需要显式放行网络。
             codex_overrides = [*codex_overrides, "sandbox_workspace_write.network_access=true"]
         launch_config: dict[str, Any] = {
+            "model": selected_model,
+            "models": list(manifest.allowed_models),
             "sandbox_read_only": sandbox == "read-only",
             "sandbox": sandbox,
             "approval_mode": approval,
+            "codex_home_key": build.id,
         }
         if codex_overrides:
             launch_config["codex_overrides"] = codex_overrides
+        if plugin_bootstrap is not None:
+            launch_config["codex_plugin_bootstrap"] = plugin_bootstrap
         runtime_env = {
             **self._resolve_model_env(build, manifest, selected_model),
             **self._resolve_mcp_env(manifest),
@@ -87,18 +119,22 @@ class CodexRunSpecResolver:
         if runtime_env:
             launch_config["env"] = runtime_env
         agent_task = str(manifest.task_prompt or "").strip()
+        agent_system = compose_system_instruction(
+            Instructions(system=manifest.prompt),
+            manifest.soul,
+        ).system
         # PCM 策略从不可变 Manifest 读取（方案 §5.1：Build 锁定后 sidecar 修改不影响旧 Build）
         # manifest.context/memory 由 _manifest() 从 AgentSpec 写入，随 Build 进入 Artifact
         resolved_context = manifest.context
         resolved_memory = manifest.memory
-        base_instructions = manifest.prompt
+        base_instructions = agent_system
         if agent_task:
-            base_instructions = f"{manifest.prompt}\n\n{agent_task}"
+            base_instructions = f"{agent_system}\n\n{agent_task}"
         request_config: dict[str, Any] = {
             # Codex 原生只接收 base_instructions，因此运行前合并；PCM 证据仍使用下面
             # 两个独立来源生成 agent_identity / agent_policy 的分段 hash。
             "base_instructions": base_instructions,
-            "agent_system": manifest.prompt,
+            "agent_system": agent_system,
             "agent_task": agent_task,
             "cwd": str(project_dir),
             "skills": skills,
@@ -136,6 +172,13 @@ class CodexRunSpecResolver:
         }
         if approval_profile:
             request_config["tool_approval_mode"] = approval_profile
+        if manifest.soul is not None:
+            request_config.update(
+                {
+                    "soul_source": manifest.soul_source,
+                    "soul_digest": manifest.soul_digest,
+                }
+            )
         return StudioRunSpec(
             launch_context=RuntimeLaunchContext(
                 runtime_type="codex",
@@ -147,8 +190,85 @@ class CodexRunSpecResolver:
             model=selected_model,
             request_config=request_config,
             manifest_sha256=build.manifest_sha256,
+            plugin_bundle_root=provider_root,
         )
 
+    def _plugin_bootstrap(
+        self,
+        build: Any,
+        manifest: CodexAgentManifest,
+    ) -> dict[str, Any] | None:
+        # Only Codex-native bindings belong to the App Server bootstrap. DSH
+        # bindings are materialized by the Provider Bundle and intentionally do
+        # not have entries in the Codex plugin snapshot store.
+        bindings = [
+            item
+            for item in (manifest.plugins or [])
+            if item.enabled and item.ecosystem == "codex"
+        ]
+        lock = getattr(build, "plugin_lock", None)
+        lock_digest = getattr(build, "plugin_lock_digest", None)
+        marketplace = getattr(build, "plugin_marketplace", None)
+        statuses = getattr(build, "plugin_runtime_status", None) or {}
+        if not bindings:
+            if lock is not None or lock_digest is not None or marketplace is not None:
+                raise StudioError(
+                    "CODEX_PLUGIN_BUILD_INVALID",
+                    "Codex Build 含有未绑定的插件锁信息",
+                    status_code=409,
+                    details={"buildId": build.id},
+                )
+            return None
+        if lock is None or lock_digest is None or marketplace is None:
+            raise StudioError(
+                "CODEX_PLUGIN_REBUILD_REQUIRED",
+                "Codex Build 缺少原生插件不可变快照，请重新构建",
+                status_code=409,
+                details={"buildId": build.id},
+            )
+        actual_lock_digest = plugin_lock_digest(lock)
+        if actual_lock_digest != lock_digest or marketplace.plugin_lock_digest != lock_digest:
+            raise StudioError(
+                "CODEX_PLUGIN_LOCK_DIGEST_MISMATCH",
+                "Codex Build 的 PluginLock 摘要不一致",
+                status_code=409,
+                details={
+                    "buildId": build.id,
+                    "expected": lock_digest,
+                    "actual": actual_lock_digest,
+                },
+            )
+        for binding in bindings:
+            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},
+                )
+            stored.select_components(binding.components)
+            status = statuses.get(binding.plugin_ref) or {}
+            if status.get("runnable") is False or any(
+                selector.startswith("hook:") for selector in binding.components
+            ):
+                raise StudioError(
+                    "CODEX_PLUGIN_HOOK_TRUST_UNAVAILABLE",
+                    "Codex App Server 尚无可验证的 hook trust API；该绑定已安全阻断",
+                    status_code=409,
+                    details={
+                        "pluginRef": binding.plugin_ref,
+                        "hookTrust": status.get("hookTrust", "unsupported"),
+                    },
+                )
+        root = self.plugin_snapshots.verify_marketplace(marketplace)
+        return {
+            "marketplace_path": str(root),
+            "marketplace_name": marketplace.marketplace_name,
+            "plugin_names": list(marketplace.plugin_names),
+            "snapshot_digest": marketplace.marketplace_digest,
+        }
+
     def _resolve_model_env(
         self,
         build: Any,
@@ -172,12 +292,23 @@ class CodexRunSpecResolver:
             if profile is not None
             else ModelConfig().api_base.rstrip("/")
         )
-        return {
+        env = {
             "OPENAI_API_KEY": credential,
             "OPENAI_BASE_URL": base_url,
             "OPENAI_API_BASE": base_url,
             "OPENAI_MODEL_NAME": selected_model,
         }
+        # A chat-only profile necessarily needs the Responses-to-Chat bridge.
+        # KSPMAS build snapshots created before wireApi was persisted have the
+        # same requirement. Route those known profiles directly so every fresh
+        # Studio process does not spend several seconds probing /models and two
+        # /responses payload dialects before the user's first turn.
+        if "KSADK_CODEX_USE_PROXY" not in os.environ and (
+            (profile is not None and profile.wire_api == "chat")
+            or self._is_known_chat_model_gateway(base_url)
+        ):
+            env["KSADK_CODEX_USE_PROXY"] = "1"
+        return env
 
     def _resolve_model_profile(
         self,
@@ -236,19 +367,41 @@ class CodexRunSpecResolver:
                 return raw[: -len(suffix)]
         return raw
 
+    @staticmethod
+    def _is_known_chat_model_gateway(base_url: str) -> bool:
+        host = (urlparse(base_url).hostname or "").lower()
+        return host == "kspmas.ksyun.com" or host.startswith("kspmas-internal.")
+
     @staticmethod
     def _mcp_overrides(manifest: CodexAgentManifest) -> list[str]:
         """Translate bound MCP servers into codex --config overrides."""
         overrides: list[str] = []
         for server in manifest.mcp_servers or []:
             name = str(server.get("name") or "").strip()
+            transport = str(
+                server.get("transport") or ("http" if server.get("url") else "")
+            ).lower()
             url = str(server.get("url") or "").strip()
-            if not name or not url:
+            if not name:
                 continue
-            overrides.append(f"mcp_servers.{name}.url={url}")
-            env_key = str(server.get("env_key") or "").strip()
-            if env_key:
-                overrides.append(f"mcp_servers.{name}.bearer_token_env_var={env_key}")
+            if transport == "stdio":
+                command = str(server.get("command") or "").strip()
+                if not command:
+                    continue
+                args = [str(argument) for argument in (server.get("args") or [])]
+                overrides.append(f"mcp_servers.{name}.command={json.dumps(command)}")
+                overrides.append(f"mcp_servers.{name}.args={json.dumps(args)}")
+                env_refs = server.get("env_refs") or {}
+                if isinstance(env_refs, dict) and env_refs:
+                    overrides.append(
+                        f"mcp_servers.{name}.env_vars="
+                        f"{json.dumps(sorted(str(key) for key in env_refs))}"
+                    )
+            elif transport in {"http", "sse"} and url:
+                overrides.append(f"mcp_servers.{name}.url={url}")
+                env_key = str(server.get("env_key") or "").strip()
+                if env_key:
+                    overrides.append(f"mcp_servers.{name}.bearer_token_env_var={env_key}")
         return overrides
 
     def _resolve_mcp_env(self, manifest: CodexAgentManifest) -> dict[str, str]:
@@ -260,10 +413,20 @@ class CodexRunSpecResolver:
         """
         env: dict[str, str] = {}
         for server in manifest.mcp_servers or []:
+            references: dict[str, str] = {}
             env_key = str(server.get("env_key") or "").strip()
-            if not env_key:
-                continue
-            if env_key in env:
+            if env_key:
+                references[env_key] = f"env://{env_key}"
+            raw_references = server.get("env_refs") or {}
+            if isinstance(raw_references, dict):
+                references.update(
+                    {
+                        str(name).strip(): str(reference).strip()
+                        for name, reference in raw_references.items()
+                        if str(name).strip() and str(reference).strip()
+                    }
+                )
+            if not references:
                 continue
             resolver = self.credentials
             if resolver is None:
@@ -271,19 +434,22 @@ class CodexRunSpecResolver:
 
                 resolver = CredentialResolver(self.workspace)
                 self.credentials = resolver
-            try:
-                env[env_key] = resolver.resolve(f"env://{env_key}")
-            except Exception as exc:
-                raise StudioError(
-                    "MCP_CREDENTIAL_MISSING",
-                    f"MCP Server「{server.get('name')}」需要凭证 {env_key}，"
-                    "请先在 MCP 页连接时保存该环境变量的值",
-                    status_code=422,
-                    details={
-                        "server": str(server.get("name") or ""),
-                        "reference": f"env://{env_key}",
-                    },
-                ) from exc
+            for name, reference in references.items():
+                if name in env:
+                    continue
+                try:
+                    env[name] = resolver.resolve(reference)
+                except Exception as exc:
+                    raise StudioError(
+                        "MCP_CREDENTIAL_MISSING",
+                        f"MCP Server「{server.get('name')}」需要凭证 {name}，"
+                        "请先保存对应 Secret 引用",
+                        status_code=422,
+                        details={
+                            "server": str(server.get("name") or ""),
+                            "reference": reference,
+                        },
+                    ) from exc
         return env
 
     @staticmethod
@@ -314,11 +480,16 @@ class CodexRunSpecResolver:
         if approval_mode:
             return approval_presets[normalize_tool_approval_mode(approval_mode)]
         raw = (
-            (override or os.environ.get("KSADK_CODEX_SANDBOX") or manifest.sandbox or "read_only")
+            (
+                override
+                or os.environ.get("KSADK_CODEX_SANDBOX")
+                or manifest.sandbox
+                or "workspace_write_auto"
+            )
             .strip()
             .lower()
         )
-        return presets.get(raw, ("read-only", "deny_all"))
+        return presets.get(raw, ("workspace-write", "auto_review"))
 
     def _skill_inputs(self, manifest: CodexAgentManifest) -> list[dict[str, str]]:
         """Resolve bound skill resource ids to codex SkillInput wire dicts."""