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

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
 
@@ -51,8 +67,29 @@ class CodexBuildRecord(ContractModel):
     # New builds always persist a mapping (possibly empty), so run resolution
     # never consults mutable Catalog state after the build has been created.
     model_profiles: dict[str, dict[str, Any]] | None = None
+    # Resource ids and model names are different namespaces.  Keep the exact
+    # Studio bindings separately so currentness checks never compare a model
+    # name (``glm-5.2``) with a Catalog id (``model:provider:glm-5-2:live``).
+    # ``None`` only allows older local records to be read and rejected as
+    # 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:
@@ -252,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)
@@ -259,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,
@@ -267,12 +312,46 @@ 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,
         )
-        build_id = self._build_id(snapshot.manifest_sha256, model_profiles)
+        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)
         except StudioError as exc:
@@ -324,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,
@@ -337,39 +424,121 @@ class CodexStudioBuilder:
             proxy_mode=current_proxy_mode(),
             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
-        try:
-            current_profiles = self._model_profile_snapshot(
-                snapshot.manifest.name,
-                allowed_models=snapshot.manifest.allowed_models,
-            )
-        except StudioError as exc:
-            if exc.code == "RESOURCE_NOT_FOUND":
-                # A completed Build owns its connection snapshot.  A later
-                # Catalog cleanup must not make that immutable Build
-                # undeployable; launch resolution reads the snapshot instead.
-                return True
-            raise
+        if record.model_profile_ids is None:
+            return False
+        draft = self.drafts.get(record.agent_name) if self.drafts is not None else None
+        if draft is None:
+            return not record.model_profiles
+
+        bound_ids = set(self._bound_model_profile_ids(record.agent_name))
+        if set(record.model_profile_ids) != bound_ids:
+            return False
+        current_profiles = self._model_profile_snapshot(
+            snapshot.manifest.name,
+            allowed_models=snapshot.manifest.allowed_models,
+            ignore_missing=True,
+        )
+        # Provider-discovered Catalog entries are process-local.  A restart may
+        # temporarily remove them, but the Build still owns an immutable,
+        # runnable connection snapshot and must remain deployable.
+        if bound_ids and not current_profiles:
+            return True
         return record.model_profiles == current_profiles
 
     @staticmethod
     def _build_id(
         manifest_sha256: str,
         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:
+        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(
-            model_profiles,
+            {
+                "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,
             separators=(",", ":"),
@@ -379,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,
@@ -417,10 +681,24 @@ class CodexStudioBuilder:
                 by_alias=True,
                 exclude_defaults=True,
                 exclude_none=True,
+                exclude={"metadata", "discovery"},
                 mode="json",
             )
         return profiles
 
+    def _bound_model_profile_ids(self, agent_id: str) -> list[str]:
+        if self.drafts is None:
+            return []
+        draft = self.drafts.get(agent_id)
+        if draft is None:
+            return []
+        bindings = draft.spec.bindings
+        resource_ids = list(getattr(bindings, "model_profile_ids", []) or [])
+        default_id = getattr(bindings, "model_profile_id", None)
+        if not resource_ids and default_id:
+            resource_ids = [default_id]
+        return list(dict.fromkeys(resource_ids))
+
     @staticmethod
     def _runtime_lock(artifact_path: Path) -> dict:
         if artifact_path.suffix == ".zip":

ksadk/studio/codex_credentials.py

@@ -0,0 +1,90 @@
+"""Keep local MCP OAuth grants usable across one Agent's immutable builds.
+
+Plugin snapshots and native transcripts remain build-isolated. Only grants for
+explicitly bound, identical MCP server names and URLs may cross that boundary;
+Codex account credentials and other Agents' grants never do.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import tempfile
+from pathlib import Path
+from typing import Any, Iterable
+
+from ksadk.runtime.factory import _isolated_codex_home
+from ksadk.studio.codex_builder import CodexBuildRecord
+
+
+def restore_mcp_oauth_credentials(
+    project_dir: Path,
+    build: CodexBuildRecord,
+    builds: Iterable[CodexBuildRecord],
+    servers: list[dict[str, Any]],
+) -> None:
+    allowed = {
+        (str(server.get("name") or ""), str(server.get("url") or ""))
+        for server in servers
+        if server.get("enabled", True) and server.get("url") and not server.get("env_key")
+    }
+    if not allowed:
+        return
+    home = _isolated_codex_home(project_dir, build.id)
+    marker = home / ".ksadk-mcp-oauth-initialized"
+    if marker.exists():
+        return
+    target = home / ".credentials.json"
+    if target.is_symlink() or marker.is_symlink():
+        raise ValueError("Codex MCP credential store must not be a symlink")
+    current = _read(target)
+    merged = dict(current)
+    previous = max(
+        (
+            candidate
+            for candidate in builds
+            if candidate.agent_name == build.agent_name
+            and candidate.id != build.id
+            and candidate.created_at <= build.created_at
+            and re.fullmatch(r"build_[0-9a-f]{8,64}", candidate.id)
+        ),
+        key=lambda candidate: (candidate.created_at, candidate.source_revision),
+        default=None,
+    )
+    # Only the immediately preceding build may contribute grants. Searching
+    # further back could resurrect credentials removed by a user's logout.
+    if previous is not None:
+        source = home.parent / previous.id / ".credentials.json"
+        if source.is_file() and not source.is_symlink() and not source.parent.is_symlink():
+            for key, grant in _read(source).items():
+                if key in merged or not isinstance(grant, dict):
+                    continue
+                if (grant.get("server_name"), grant.get("server_url")) in allowed:
+                    merged[key] = grant
+    if merged != current:
+        fd, temporary = tempfile.mkstemp(prefix=".mcp-oauth-", dir=home)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as stream:
+                # mkstemp creates a private 0600 file. Never log or serialize
+                # this into a Build, deployment manifest, or response.
+                json.dump(merged, stream)
+            os.replace(temporary, target)
+        finally:
+            Path(temporary).unlink(missing_ok=True)
+    # Initialization is deliberately one-shot, even if no grant was found.
+    # Subsequent login, refresh and logout belong to the current build.
+    try:
+        fd = os.open(marker, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    except FileExistsError:
+        return
+    os.close(fd)
+
+
+def _read(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    value = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(value, dict):
+        raise ValueError("Invalid Codex MCP credential store")
+    return value

ksadk/studio/codex_manifest.py

@@ -13,8 +13,9 @@ import yaml  # type: ignore[import-untyped]
 from pydantic import BaseModel, ConfigDict, Field, ValidationError, model_validator
 
 from ksadk.builders.managed_runtime_builder import serialize_managed_runtime_manifest
-from ksadk.studio.contracts import ContextSpec, MemorySpec
+from ksadk.studio.contracts import ContextSpec, MemorySpec, NativePluginBinding, SoulDocument
 from ksadk.studio.errors import StudioError, not_found
+from ksadk.studio.soul import soul_digest as compute_soul_digest
 from ksadk.studio.workspace import Workspace
 
 
@@ -43,8 +44,15 @@ class CodexAgentManifest(BaseModel):
     # Codex Runtime 最终仍消费合并后的 base_instructions；该字段用于在 AgentVersion /
     # Build 中保留任务契约来源，避免为了运行投影而破坏 PromptSection 审计。
     task_prompt: str | None = Field(default=None, max_length=32768)
+    # Soul remains reviewed source in the ManagedRuntime manifest. Runtime
+    # launch deterministically compiles it before ``prompt``; these provenance
+    # fields prevent a Draft-only Soul from masquerading as deployed behavior.
+    soul: SoulDocument | None = None
+    soul_source: Literal["AgentSpec.soul"] | None = None
+    soul_digest: str | None = Field(default=None, pattern=r"^sha256:[0-9a-f]{64}$")
     skills: list[str] | None = None
     mcp_servers: list[dict[str, Any]] | None = None
+    plugins: list[NativePluginBinding] | None = None
     sandbox: str | None = None
     approval_mode: str | None = None
     # PCM 策略（方案 §5.1）：严格类型化，Build 不可变。
@@ -88,16 +96,53 @@ class CodexAgentManifest(BaseModel):
                 if not isinstance(server, dict):
                     raise ValueError("mcp_servers 必须是对象列表")
                 name = str(server.get("name") or "").strip()
-                url = str(server.get("url") or "").strip()
+                transport = str(
+                    server.get("transport") or ("http" if server.get("url") else "")
+                ).strip()
+                url = str(server.get("url") or server.get("endpoint_url") or "").strip()
+                command = str(server.get("command") or "").strip()
                 if not name:
                     raise ValueError("mcp_servers 每项必须有 name")
-                if not url:
-                    raise ValueError("mcp_servers 每项必须有 url")
+                if transport == "stdio":
+                    args = server.get("args") or []
+                    if (
+                        not command
+                        or not isinstance(args, list)
+                        or any(not isinstance(argument, str) for argument in args)
+                    ):
+                        raise ValueError("stdio mcp_servers 必须有 command 与字符串 args")
+                    if url:
+                        raise ValueError("stdio mcp_servers 不能配置 url")
+                elif transport in {"http", "sse"}:
+                    if not url:
+                        raise ValueError("HTTP/SSE mcp_servers 每项必须有 url")
+                    if command:
+                        raise ValueError("HTTP/SSE mcp_servers 不能配置 command")
+                else:
+                    raise ValueError("mcp_servers transport 必须是 stdio/http/sse")
                 if name in mcp_seen:
                     raise ValueError("mcp_servers 不能包含重复 name")
                 mcp_seen.add(name)
                 mcp_deduped.append(server)
             self.mcp_servers = mcp_deduped
+        if self.plugins is not None:
+            refs = [binding.plugin_ref for binding in self.plugins if binding.enabled]
+            if len(refs) != len(set(refs)):
+                raise ValueError("plugins 不能包含重复的启用 pluginRef")
+            from ksadk.resource_runtime.plugin_config import validate_resource_plugin_bindings
+
+            validate_resource_plugin_bindings(self.plugins)
+        if self.soul is None:
+            if self.soul_source is not None or self.soul_digest is not None:
+                raise ValueError("soul source/digest require a SoulDocument")
+        else:
+            expected_digest = compute_soul_digest(self.soul)
+            if self.soul_source not in {None, "AgentSpec.soul"}:
+                raise ValueError("soul_source must identify AgentSpec.soul")
+            if self.soul_digest not in {None, expected_digest}:
+                raise ValueError("soul_digest does not match the SoulDocument")
+            self.soul_source = "AgentSpec.soul"
+            self.soul_digest = expected_digest
         return self
 
     @property
@@ -113,6 +158,8 @@ def normalized_manifest_bytes(manifest: CodexAgentManifest) -> bytes:
         payload["context"] = manifest.context.model_dump(mode="python", by_alias=True)
     if manifest.memory is not None:
         payload["memory"] = manifest.memory.model_dump(mode="python", by_alias=True)
+    if manifest.soul is not None:
+        payload["soul"] = manifest.soul.model_dump(mode="python", by_alias=True)
     return serialize_managed_runtime_manifest(payload)