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

ksadk/studio/compatibility_report.py

@@ -0,0 +1,456 @@
+"""Deterministic build-time compatibility report for AgentBundle v2.
+
+The report contains only immutable, already-resolved facts.  It deliberately
+does not inspect environment variables, import plugin entrypoints, or claim
+that a process is healthy.  Runtime readiness remains an Activation concern.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from ksadk.plugins.builtins import builtin_capability_permissions
+from ksadk.plugins.contracts import LockedCapability, PluginLockEntry, PluginManifest
+from ksadk.plugins.resolver import (
+    PluginResolutionError,
+    ResolvedComposition,
+    version_satisfies,
+)
+from ksadk.studio.contracts import AgentDraft
+
+COMPATIBILITY_REPORT_FORMAT = "agentkit.compatibility-report/v1"
+CURRENT_KERNEL_API_VERSION = "1.0.0"
+CURRENT_RUNTIME_CONTRACT = "agentkit.runtime/v1"
+SUPPORTED_RUNTIME_PROTOCOLS = (CURRENT_RUNTIME_CONTRACT,)
+
+
+def compatibility_facts_digest(
+    *,
+    draft: AgentDraft,
+    composition: ResolvedComposition | None,
+    runtime_lock: Mapping[str, Any],
+) -> str:
+    """Address every static input that can change a compatibility conclusion."""
+
+    payload: dict[str, Any] = {
+        "allowedPermissions": sorted(set(draft.spec.security.allowed_permissions)),
+        "hostOwnedPermissions": (
+            sorted(builtin_capability_permissions(composition.profile))
+            if composition is not None
+            else []
+        ),
+        "runtime": {
+            "type": str(runtime_lock.get("type") or ""),
+            "version": str(runtime_lock.get("version") or ""),
+        },
+        "composition": None,
+    }
+    if composition is not None:
+        payload["composition"] = {
+            "profileDigest": composition.profile_digest,
+            "pluginLockDigest": composition.plugin_lock_digest,
+            "manifests": [
+                manifest.model_dump(
+                    by_alias=True,
+                    exclude_none=True,
+                    mode="json",
+                )
+                for manifest in sorted(
+                    composition.manifests,
+                    key=lambda item: (item.metadata.id, item.metadata.version),
+                )
+            ],
+        }
+    canonical = json.dumps(
+        payload,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+    return f"sha256:{hashlib.sha256(canonical).hexdigest()}"
+
+
+def build_bundle_compatibility_report(
+    *,
+    draft: AgentDraft,
+    composition: ResolvedComposition | None,
+    runtime_lock: Mapping[str, Any],
+    resolved_digest: str,
+    facts_digest: str,
+    plugin_lock_digest: str,
+    composition_profile_digest: str | None,
+) -> dict[str, Any]:
+    """Project auditable static compatibility without reading host secrets."""
+
+    bundle = {
+        "bundleFormat": "agentkit.bundle/v2",
+        "compatibilityFactsDigest": facts_digest,
+        "resolvedDigest": resolved_digest,
+        "pluginLockDigest": plugin_lock_digest,
+        **(
+            {"compositionProfileDigest": composition_profile_digest}
+            if composition_profile_digest is not None
+            else {}
+        ),
+    }
+    allowed_permissions = sorted(
+        set(draft.spec.security.allowed_permissions)
+        | set(builtin_capability_permissions(composition.profile))
+        if composition is not None
+        else set(draft.spec.security.allowed_permissions)
+    )
+    if composition is None:
+        return _legacy_report(
+            bundle=bundle,
+            runtime_lock=runtime_lock,
+            allowed_permissions=allowed_permissions,
+        )
+
+    manifests = {manifest.metadata.id: manifest for manifest in composition.manifests}
+    locked = {entry.id: entry for entry in composition.plugin_lock.plugins}
+    blockers: list[dict[str, str]] = []
+
+    def block(code: str, subject: str, reason: str) -> None:
+        blockers.append({"code": code, "subject": subject, "reason": reason})
+
+    permission_items: list[dict[str, Any]] = []
+    protocol_items: list[dict[str, Any]] = []
+    kernel_items: list[dict[str, str]] = []
+    capability_items: list[dict[str, str]] = []
+
+    for entry in composition.plugin_lock.plugins:
+        manifest = manifests.get(entry.id)
+        if manifest is None:
+            block(
+                "plugin_manifest_facts_missing",
+                entry.id,
+                "The exact manifest used to resolve this lock entry is unavailable.",
+            )
+            permission_items.append(
+                {
+                    "pluginId": entry.id,
+                    "required": [],
+                    "unapproved": [],
+                    "status": "blocked",
+                }
+            )
+            protocol_items.append(
+                {
+                    "pluginId": entry.id,
+                    "required": [],
+                    "supported": list(SUPPORTED_RUNTIME_PROTOCOLS),
+                    "status": "blocked",
+                }
+            )
+            kernel_items.append(
+                {
+                    "pluginId": entry.id,
+                    "required": "unknown",
+                    "resolved": CURRENT_KERNEL_API_VERSION,
+                    "status": "blocked",
+                }
+            )
+            for capability in entry.provides:
+                capability_items.append(
+                    _capability_item(entry, capability, mode="unknown", status="blocked")
+                )
+            continue
+
+        _append_manifest_conclusions(
+            entry=entry,
+            manifest=manifest,
+            allowed_permissions=allowed_permissions,
+            permission_items=permission_items,
+            protocol_items=protocol_items,
+            kernel_items=kernel_items,
+            capability_items=capability_items,
+            block=block,
+        )
+
+    provider_ref = composition.profile.agent_provider.ref
+    provider_id, requested_version = _plugin_ref_parts(provider_ref)
+    provider_entry = locked.get(provider_id)
+    provider_manifest = manifests.get(provider_id)
+    if provider_entry is None:
+        block(
+            "agent_provider_lock_missing",
+            provider_id,
+            "The CompositionProfile AgentProvider has no exact PluginLock entry.",
+        )
+    elif provider_entry.version != requested_version:
+        block(
+            "agent_provider_version_mismatch",
+            provider_id,
+            (
+                f"Profile requests {requested_version}, but the lock resolves "
+                f"{provider_entry.version}."
+            ),
+        )
+
+    blockers.sort(key=lambda item: (item["code"], item["subject"], item["reason"]))
+    blocked_subjects = {item["subject"] for item in blockers}
+    overall = "blocked" if blockers else "compatible"
+    provider_status = "blocked" if provider_id in blocked_subjects else "compatible"
+
+    return {
+        "format": COMPATIBILITY_REPORT_FORMAT,
+        "scope": "build-time-static",
+        "overallStatus": overall,
+        "bundle": bundle,
+        "host": {
+            "kind": _host_kind(provider_manifest),
+            "kernelApiVersion": CURRENT_KERNEL_API_VERSION,
+            "runtimeContract": CURRENT_RUNTIME_CONTRACT,
+            "readiness": "notEvaluated",
+            "status": overall,
+        },
+        "provider": _provider_conclusion(
+            provider_ref=provider_ref,
+            provider_id=provider_id,
+            requested_version=requested_version,
+            entry=provider_entry,
+            manifest=provider_manifest,
+            status=provider_status,
+        ),
+        "kernelApi": sorted(kernel_items, key=lambda item: item["pluginId"]),
+        "protocols": sorted(protocol_items, key=lambda item: item["pluginId"]),
+        "permissions": {
+            "allowed": allowed_permissions,
+            "plugins": sorted(permission_items, key=lambda item: item["pluginId"]),
+            "status": (
+                "blocked"
+                if any(item["status"] == "blocked" for item in permission_items)
+                else "compatible"
+            ),
+        },
+        "capabilities": sorted(
+            capability_items,
+            key=lambda item: (item["definition"], item["slot"], item["owner"]),
+        ),
+        "blockingReasons": blockers,
+    }
+
+
+def _legacy_report(
+    *,
+    bundle: dict[str, Any],
+    runtime_lock: Mapping[str, Any],
+    allowed_permissions: list[str],
+) -> dict[str, Any]:
+    runtime_type = str(runtime_lock.get("type") or "")
+    version = str(runtime_lock.get("version") or "")
+    return {
+        "format": COMPATIBILITY_REPORT_FORMAT,
+        "scope": "build-time-static",
+        "overallStatus": "compatible",
+        "bundle": bundle,
+        "host": {
+            "kind": "legacy-runtime",
+            "kernelApiVersion": CURRENT_KERNEL_API_VERSION,
+            "runtimeContract": CURRENT_RUNTIME_CONTRACT,
+            "readiness": "notEvaluated",
+            "status": "compatible",
+        },
+        "provider": {
+            "ref": None,
+            "id": runtime_type or "builtin.legacy",
+            "hostRuntime": runtime_type or "unknown",
+            "isolation": "legacy",
+            "source": "builtin",
+            "digest": None,
+            "version": {
+                "requested": version or None,
+                "resolved": version or None,
+                "status": "compatible" if version else "unknown",
+            },
+            "status": "compatible",
+        },
+        "kernelApi": [],
+        "protocols": [
+            {
+                "pluginId": runtime_type or "builtin.legacy",
+                "required": [CURRENT_RUNTIME_CONTRACT],
+                "supported": list(SUPPORTED_RUNTIME_PROTOCOLS),
+                "status": "compatible",
+            }
+        ],
+        "permissions": {
+            "allowed": allowed_permissions,
+            "plugins": [],
+            "status": "compatible",
+        },
+        "capabilities": [],
+        "blockingReasons": [],
+    }
+
+
+def _append_manifest_conclusions(
+    *,
+    entry: PluginLockEntry,
+    manifest: PluginManifest,
+    allowed_permissions: list[str],
+    permission_items: list[dict[str, Any]],
+    protocol_items: list[dict[str, Any]],
+    kernel_items: list[dict[str, str]],
+    capability_items: list[dict[str, str]],
+    block: Callable[[str, str, str], None],
+) -> None:
+    if (
+        manifest.metadata.id != entry.id
+        or manifest.metadata.version != entry.version
+        or manifest.spec.provenance.digest != entry.digest
+    ):
+        block(
+            "plugin_manifest_lock_mismatch",
+            entry.id,
+            "Resolved manifest identity or digest does not match the PluginLock entry.",
+        )
+
+    required_permissions = sorted(set(manifest.spec.permissions))
+    unapproved = sorted(set(required_permissions) - set(allowed_permissions))
+    permission_status = "blocked" if unapproved else "compatible"
+    permission_items.append(
+        {
+            "pluginId": entry.id,
+            "required": required_permissions,
+            "unapproved": unapproved,
+            "status": permission_status,
+        }
+    )
+    if unapproved:
+        block(
+            "plugin_permission_unapproved",
+            entry.id,
+            "Unapproved permissions: " + ", ".join(unapproved),
+        )
+
+    protocols = sorted(set(manifest.spec.compatibility.runtime_protocols))
+    protocol_status = (
+        "compatible" if not protocols or CURRENT_RUNTIME_CONTRACT in protocols else "blocked"
+    )
+    protocol_items.append(
+        {
+            "pluginId": entry.id,
+            "required": protocols,
+            "supported": list(SUPPORTED_RUNTIME_PROTOCOLS),
+            "status": protocol_status,
+        }
+    )
+    if protocol_status == "blocked":
+        block(
+            "runtime_protocol_incompatible",
+            entry.id,
+            f"Plugin accepts {', '.join(protocols)}, host provides {CURRENT_RUNTIME_CONTRACT}.",
+        )
+
+    kernel_constraint = manifest.spec.compatibility.kernel_api
+    try:
+        kernel_compatible = version_satisfies(
+            CURRENT_KERNEL_API_VERSION,
+            kernel_constraint,
+        )
+    except PluginResolutionError:
+        kernel_compatible = False
+    kernel_items.append(
+        {
+            "pluginId": entry.id,
+            "required": kernel_constraint,
+            "resolved": CURRENT_KERNEL_API_VERSION,
+            "status": "compatible" if kernel_compatible else "blocked",
+        }
+    )
+    if not kernel_compatible:
+        block(
+            "kernel_api_incompatible",
+            entry.id,
+            f"Plugin requires {kernel_constraint}, host provides {CURRENT_KERNEL_API_VERSION}.",
+        )
+
+    offers = {(offer.definition, offer.slot): offer for offer in manifest.spec.provides}
+    for capability in entry.provides:
+        offer = offers.get((capability.definition, capability.slot))
+        status = "compatible" if capability.owner == entry.id and offer is not None else "blocked"
+        capability_items.append(
+            _capability_item(
+                entry,
+                capability,
+                mode=offer.mode if offer is not None else "unknown",
+                status=status,
+            )
+        )
+        if status == "blocked":
+            block(
+                "capability_lock_mismatch",
+                entry.id,
+                f"Locked capability {capability.definition} at {capability.slot} "
+                "does not match the resolved manifest owner.",
+            )
+
+
+def _capability_item(
+    entry: PluginLockEntry,
+    capability: LockedCapability,
+    *,
+    mode: str,
+    status: str,
+) -> dict[str, str]:
+    return {
+        "definition": capability.definition,
+        "slot": capability.slot,
+        "owner": capability.owner,
+        "version": entry.version,
+        "mode": mode,
+        "status": status,
+    }
+
+
+def _provider_conclusion(
+    *,
+    provider_ref: str,
+    provider_id: str,
+    requested_version: str,
+    entry: PluginLockEntry | None,
+    manifest: PluginManifest | None,
+    status: str,
+) -> dict[str, Any]:
+    return {
+        "ref": provider_ref,
+        "id": provider_id,
+        "hostRuntime": manifest.spec.runtime if manifest is not None else "unknown",
+        "isolation": manifest.spec.isolation if manifest is not None else "unknown",
+        "source": entry.source if entry is not None else "unknown",
+        "digest": entry.digest if entry is not None else None,
+        "version": {
+            "requested": requested_version,
+            "resolved": entry.version if entry is not None else None,
+            "status": (
+                "compatible"
+                if entry is not None and entry.version == requested_version
+                else "blocked"
+            ),
+        },
+        "status": status,
+    }
+
+
+def _host_kind(provider: PluginManifest | None) -> str:
+    if provider is not None and provider.spec.domain == "runtime-native":
+        return "runtime-native"
+    return "composition-host"
+
+
+def _plugin_ref_parts(value: str) -> tuple[str, str]:
+    plugin_id, version = value.removeprefix("plugin://").rsplit("@", 1)
+    return plugin_id, version
+
+
+__all__ = [
+    "COMPATIBILITY_REPORT_FORMAT",
+    "CURRENT_KERNEL_API_VERSION",
+    "CURRENT_RUNTIME_CONTRACT",
+    "build_bundle_compatibility_report",
+    "compatibility_facts_digest",
+]

ksadk/studio/compiler.py

@@ -6,6 +6,8 @@ from dataclasses import dataclass
 from typing import Any
 from urllib.parse import urlparse
 
+from ksadk.plugins.providers.legacy_catalog import CODEX_AGENT_PROVIDER_PLUGIN_ID
+from ksadk.resource_runtime.plugin_config import resource_plugin_config
 from ksadk.studio.capabilities import (
     CapabilityResolver,
     LocalCapabilityResolver,
@@ -20,6 +22,7 @@ from ksadk.studio.contracts import (
 )
 from ksadk.studio.errors import StudioError
 from ksadk.studio.resource_catalog import LocalResourceCatalog
+from ksadk.studio.soul import compose_system_instruction
 from ksadk.studio.validator import AgentValidator
 from ksadk.studio.workspace import Workspace
 
@@ -45,6 +48,39 @@ class AgentCompiler:
         self.catalog = catalog or LocalResourceCatalog(workspace)
 
     def compile(self, draft: AgentDraft) -> CompileResult:
+        unsupported_plugins = [
+            binding.plugin_ref
+            for binding in draft.spec.bindings.plugins
+            if binding.enabled
+            and resource_plugin_config(
+                binding.plugin_ref,
+                binding.ecosystem,
+                binding.config,
+                enabled=True,
+            )
+            is None
+        ]
+        if unsupported_plugins:
+            raise StudioError(
+                "NATIVE_PLUGIN_RUNTIME_INCOMPATIBLE",
+                "Framework Agent 不能直接绑定未物化的原生插件快照",
+                status_code=422,
+                field="spec.bindings.plugins",
+                details={"pluginRefs": sorted(unsupported_plugins)},
+            )
+        direct_dynamic = [
+            server.name
+            for server in draft.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)},
+            )
         source_payload = draft.model_dump(by_alias=True, exclude_none=True, mode="json")
         source_digest = sha256_digest(canonical_json(source_payload))
         materialized = self._materialize_bindings(draft)
@@ -61,10 +97,7 @@ class AgentCompiler:
             for ref in materialized.spec.capabilities.mcp_servers
             if ref.enabled
         ]
-        tools = [
-            self.resolver.resolve_tool(tool)
-            for tool in materialized.spec.capabilities.tools
-        ]
+        tools = [self.resolver.resolve_tool(tool) for tool in materialized.spec.capabilities.tools]
         skills.sort(key=lambda item: (item["name"], item["version"], item["digest"]))
         mcp_servers.sort(key=lambda item: (item["name"], item["version"], item["digest"]))
         tools.sort(key=lambda item: (item.name, item.version, item.digest or ""))
@@ -72,7 +105,11 @@ class AgentCompiler:
         resolved = ResolvedAgentSpec(
             agent_id=draft.metadata.id,
             source_revision=draft.metadata.revision,
-            instructions=materialized.spec.instructions,
+            instructions=compose_system_instruction(
+                materialized.spec.instructions,
+                materialized.spec.soul,
+            ),
+            soul=materialized.spec.soul,
             model=self.resolver.resolve_model(materialized.spec.model),
             capabilities=ResolvedCapabilities(
                 skills=skills,
@@ -106,21 +143,53 @@ class AgentCompiler:
             "skills": skills,
             "mcpServers": mcp_servers,
             "tools": [
-                tool.model_dump(by_alias=True, exclude_none=True, mode="json")
-                for tool in tools
+                tool.model_dump(by_alias=True, exclude_none=True, mode="json") for tool in tools
             ],
         }
         return CompileResult(resolved=resolved, dependency_lock=dependency_lock)
 
     def _materialize_bindings(self, draft: AgentDraft) -> AgentDraft:
+        runtime = draft.spec.runtime
+        uses_codex_native_tools = bool(
+            runtime
+            and (
+                runtime.type == "codex"
+                or (
+                    runtime.type == "plugin"
+                    and runtime.provider_ref
+                    and runtime.provider_ref.startswith(
+                        f"plugin://{CODEX_AGENT_PROVIDER_PLUGIN_ID}@"
+                    )
+                )
+            )
+        )
         bindings = draft.spec.bindings
+        if uses_codex_native_tools and bindings.tools:
+            bindings = bindings.model_copy(update={"tools": []})
         if (
-            not bindings.model_profile_id
+            not uses_codex_native_tools
+            and not bindings.model_profile_id
             and not bindings.tools
             and not bindings.mcp_servers
             and not bindings.skills
         ):
             return draft
+        runtime_type = draft.spec.runtime.type if draft.spec.runtime is not None else None
+        for binding in bindings.mcp_servers:
+            if not binding.enabled:
+                continue
+            descriptor = self.catalog.get(binding.resource_id)
+            if (
+                descriptor.contract.get("materialization") == "dsh-profile"
+                and runtime_type != "harness"
+            ):
+                raise StudioError(
+                    "DSH_MCP_RUNTIME_INCOMPATIBLE",
+                    "DSH Profile MCP 当前只支持 Harness Runtime",
+                    status_code=422,
+                    field="spec.runtime.type",
+                    details={"runtimeType": runtime_type},
+                )
         materialized = draft.model_copy(deep=True)
         model = self.catalog.resolve_model(bindings) or materialized.spec.model
         if model is None:
@@ -142,9 +211,13 @@ class AgentCompiler:
                 *self.catalog.resolve_mcp_servers(bindings),
             ],
             tools=[
-                *materialized.spec.capabilities.tools,
+                *([] if uses_codex_native_tools else materialized.spec.capabilities.tools),
                 *bound_tools,
-                *bound_mcp_tools,
+                # Non-Codex runtimes consume the probed MCP contracts through
+                # the generic Tool execution path. Codex connects to the MCP
+                # server natively, so expanding those contracts here turns a
+                # valid MCP binding into unsupported third-party tools.
+                *([] if uses_codex_native_tools else bound_mcp_tools),
             ],
         )
         self._require_unique(
@@ -164,11 +237,7 @@ class AgentCompiler:
         materialized.spec.security.allowed_permissions = sorted(
             set(materialized.spec.security.allowed_permissions)
             | set(permissions)
-            | {
-                permission
-                for tool in bound_mcp_tools
-                for permission in tool.permissions
-            }
+            | {permission for tool in bound_mcp_tools for permission in tool.permissions}
         )
         endpoint = model.endpoint_url or model.base_url or ""
         hostname = (urlparse(endpoint).hostname or "").lower().rstrip(".")