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

ksadk/studio/plugin_composition.py

@@ -9,9 +9,12 @@ this module and retain their established source-build behavior.
 
 from __future__ import annotations
 
+import re
 from collections.abc import Mapping
 from copy import deepcopy
+from dataclasses import replace
 
+from ksadk.harness.tools import HARNESS_SANDBOX_TOOL_NAMES
 from ksadk.plugins.builtins import (
     BUILTIN_PLUGIN_VERSION,
     CORE_RENDERER_PLUGIN_ID,
@@ -30,14 +33,28 @@ from ksadk.plugins.composition import (
     RuntimePluginSelection,
 )
 from ksadk.plugins.contracts import PluginManifest
+from ksadk.plugins.providers.dsh_mcp import (
+    DSH_PROFILE_MCP_PLUGIN_ID,
+    DSH_PROFILE_MCP_PLUGIN_VERSION,
+    DSH_PROFILE_TOOL_PERMISSION,
+    dsh_harness_tool_alias,
+    dsh_profile_mcp_manifest,
+)
 from ksadk.plugins.providers.legacy_catalog import (
     BUILTIN_PROVIDER_VERSION,
     KSADK_HARNESS_AGENT_PROVIDER_PLUGIN_ID,
     builtin_agent_provider_manifests,
 )
+from ksadk.plugins.providers.platform_resources import (
+    PLATFORM_RESOURCE_MCP_REF,
+    platform_resource_mcp_manifest,
+)
 from ksadk.plugins.resolver import PluginRegistry, ResolvedComposition
+from ksadk.resource_runtime.plugin_config import resource_plugin_config
+from ksadk.studio.capabilities import canonical_json, sha256_digest
 from ksadk.studio.contracts import AgentDraft, CapabilityBinding
 from ksadk.studio.errors import StudioError
+from ksadk.studio.resource_build_admission import resource_build_required
 from ksadk.studio.resource_catalog import LocalResourceCatalog
 from ksadk.studio.workspace import Workspace
 
@@ -109,7 +126,11 @@ class StudioPluginCompositionCompiler:
         manifests = [
             *builtin_agent_provider_manifests(),
             *builtin_capability_manifests(),
+            dsh_profile_mcp_manifest(),
         ]
+        requires_platform_resources = resource_build_required(draft)
+        if requires_platform_resources:
+            manifests.append(platform_resource_mcp_manifest())
         harness_ref = _plugin_ref(
             KSADK_HARNESS_AGENT_PROVIDER_PLUGIN_ID,
             BUILTIN_PROVIDER_VERSION,
@@ -142,15 +163,24 @@ class StudioPluginCompositionCompiler:
                 "session.events",
             ),
             resource_materializations=self._resource_materializations(draft),
+            memory_providers=self._memory_providers(draft),
+            host_capabilities=(
+                PluginCapabilitySelection(
+                    ref=PLATFORM_RESOURCE_MCP_REF,
+                    definition="mcp.connector/v1",
+                    slot="mcp.platform-resources",
+                    config={"artifactPath": "platform-resources"},
+                ),
+            )
+            if requires_platform_resources
+            else (),
             context_contributors={
                 "workspace_rules": _selection(
                     READ_ONLY_CONTEXT_PLUGIN_ID,
                     "context.contributor/v1",
                     "context.bundle",
                     config={
-                        "paths": ["instructions/soul.md"]
-                        if draft.spec.soul is not None
-                        else [],
+                        "paths": ["instructions/soul.md"] if draft.spec.soul is not None else [],
                         "maxChars": draft.spec.context.max_input_tokens * 4,
                     },
                 )
@@ -165,9 +195,18 @@ class StudioPluginCompositionCompiler:
             default_runtime="harness",
         )
         try:
-            return CompositionCompiler(
+            resolved = CompositionCompiler(
                 PluginRegistry(manifests), self._catalog, policy
             ).compile(draft)
+            source_payload = draft.model_dump(
+                by_alias=True,
+                exclude_none=True,
+                mode="json",
+            )
+            return replace(
+                resolved,
+                source_digest=sha256_digest(canonical_json(source_payload)),
+            )
         except CompositionCompileError as error:
             raise StudioError(
                 error.code.upper(),
@@ -217,10 +256,7 @@ class StudioPluginCompositionCompiler:
                 status_code=422,
                 field="spec.runtime.providerRef",
             )
-        if (
-            manifest.metadata.id != plugin_id
-            or manifest.metadata.version != version
-        ):
+        if manifest.metadata.id != plugin_id or manifest.metadata.version != version:
             raise StudioError(
                 "AGENT_PROVIDER_REGISTRATION_MISMATCH",
                 "DSH AgentProvider 注册信息与精确引用不一致",
@@ -228,15 +264,9 @@ class StudioPluginCompositionCompiler:
                 field="spec.runtime.providerRef",
             )
         offers = [
-            offer
-            for offer in manifest.spec.provides
-            if offer.definition == _PROVIDER_DEFINITION
+            offer for offer in manifest.spec.provides if offer.definition == _PROVIDER_DEFINITION
         ]
-        if (
-            len(offers) != 1
-            or offers[0].slot != _PROVIDER_SLOT
-            or offers[0].mode != "unique"
-        ):
+        if len(offers) != 1 or offers[0].slot != _PROVIDER_SLOT or offers[0].mode != "unique":
             raise StudioError(
                 "AGENT_PROVIDER_MANIFEST_INVALID",
                 "插件必须唯一提供 agent.provider/v1 的 agent.execution 槽位",
@@ -251,8 +281,7 @@ class StudioPluginCompositionCompiler:
                 field="spec.runtime.providerRef",
             )
         missing_permissions = sorted(
-            set(manifest.spec.permissions)
-            - set(draft.spec.security.allowed_permissions)
+            set(manifest.spec.permissions) - set(draft.spec.security.allowed_permissions)
         )
         if missing_permissions:
             raise StudioError(
@@ -288,14 +317,152 @@ class StudioPluginCompositionCompiler:
                         field=f"spec.bindings.{kind}",
                         details={"resourceId": binding.resource_id},
                     )
-                plugin_id = (
-                    WORKSPACE_MCP_PLUGIN_ID if kind == "mcp" else WORKSPACE_SKILL_PLUGIN_ID
-                )
+                config = deepcopy(binding.config)
+                if kind == "mcp" and descriptor.contract.get("materialization") == "dsh-profile":
+                    if binding.approval != "never":
+                        raise StudioError(
+                            "DSH_MCP_AUTONOMOUS_APPROVAL_REQUIRED",
+                            "Harness 尚不支持 DSH 工具逐调用审批；必须显式允许自主调用",
+                            status_code=422,
+                            field="spec.bindings.mcpServers.approval",
+                        )
+                    unknown = sorted(set(config) - {"toolFilter", "toolNamePrefix"})
+                    if unknown:
+                        raise StudioError(
+                            "DSH_MCP_BINDING_CONFIG_INVALID",
+                            "DSH MCP 绑定只支持 toolFilter 与 toolNamePrefix",
+                            status_code=422,
+                            field="spec.bindings.mcpServers",
+                            details={"unknownFields": unknown},
+                        )
+                    tool_filter = config.get("toolFilter")
+                    if (
+                        not isinstance(tool_filter, list)
+                        or not tool_filter
+                        or any(
+                            not isinstance(item, str) or not item.strip() for item in tool_filter
+                        )
+                        or len(tool_filter) != len(set(tool_filter))
+                        or len(tool_filter) > 32
+                        or sum(len(item.encode("utf-8")) for item in tool_filter) > 2048
+                    ):
+                        raise StudioError(
+                            "DSH_MCP_TOOL_FILTER_REQUIRED",
+                            "DSH MCP 绑定必须显式选择至少一个且不重复的工具",
+                            status_code=422,
+                            field="spec.bindings.mcpServers",
+                        )
+                    tool_filter = [item.strip() for item in tool_filter]
+                    config["toolFilter"] = tool_filter
+                    known_tools = {
+                        str(item.get("name"))
+                        for item in descriptor.contract.get("discoveredTools") or []
+                        if isinstance(item, Mapping)
+                    }
+                    unknown_tools = sorted(set(tool_filter) - known_tools)
+                    if unknown_tools:
+                        raise StudioError(
+                            "DSH_MCP_TOOL_FILTER_INVALID",
+                            "DSH MCP toolFilter 包含当前 Profile 不存在的工具",
+                            status_code=422,
+                            field="spec.bindings.mcpServers",
+                            details={"unknownTools": unknown_tools},
+                        )
+                    if DSH_PROFILE_TOOL_PERMISSION not in draft.spec.security.allowed_permissions:
+                        raise StudioError(
+                            "DSH_MCP_HOST_PERMISSION_REQUIRED",
+                            "DSH Profile 工具在宿主用户权限下运行，必须显式授权",
+                            status_code=422,
+                            field="spec.security.allowedPermissions",
+                            details={"missingPermissions": [DSH_PROFILE_TOOL_PERMISSION]},
+                        )
+                    prefix = config.get("toolNamePrefix")
+                    if prefix is not None and (
+                        not isinstance(prefix, str)
+                        or not prefix.strip()
+                        or len(prefix.strip()) > 16
+                        or re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_-]{0,15}", prefix.strip()) is None
+                    ):
+                        raise StudioError(
+                            "DSH_MCP_BINDING_CONFIG_INVALID",
+                            "DSH MCP toolNamePrefix 必须是 1-16 个字母、数字、下划线或连字符",
+                            status_code=422,
+                            field="spec.bindings.mcpServers",
+                        )
+                    prefix = prefix.strip() if isinstance(prefix, str) else None
+                    aliases = [dsh_harness_tool_alias(name, prefix) for name in tool_filter]
+                    if len(aliases) != len(set(aliases)):
+                        raise StudioError(
+                            "DSH_MCP_TOOL_ALIAS_COLLISION",
+                            "所选 DSH 工具映射为模型工具名后发生冲突",
+                            status_code=422,
+                            field="spec.bindings.mcpServers",
+                        )
+                    reserved_aliases = sorted(set(aliases) & HARNESS_SANDBOX_TOOL_NAMES)
+                    if reserved_aliases:
+                        raise StudioError(
+                            "DSH_MCP_TOOL_ALIAS_RESERVED",
+                            "DSH 工具名与 Harness 内置 sandbox 工具冲突，请设置 toolNamePrefix",
+                            status_code=422,
+                            field="spec.bindings.mcpServers",
+                            details={"reservedAliases": reserved_aliases},
+                        )
+                    config["toolNamePrefix"] = prefix
+                    plugin_id = DSH_PROFILE_MCP_PLUGIN_ID
+                    plugin_version = DSH_PROFILE_MCP_PLUGIN_VERSION
+                    config.update(
+                        {
+                            "profile": descriptor.contract.get("profile"),
+                            "profileDigest": descriptor.contract.get("profileDigest"),
+                            "descriptorDigest": descriptor.contract.get("descriptorDigest"),
+                            "inventoryDigest": descriptor.contract.get("inventoryDigest"),
+                        }
+                    )
+                else:
+                    plugin_id = (
+                        WORKSPACE_MCP_PLUGIN_ID if kind == "mcp" else WORKSPACE_SKILL_PLUGIN_ID
+                    )
+                    plugin_version = BUILTIN_PLUGIN_VERSION
                 materializations[binding.resource_id] = ResourcePluginMaterialization(
                     kind=kind,  # type: ignore[arg-type]
-                    plugin_ref=_plugin_ref(plugin_id, BUILTIN_PLUGIN_VERSION),
-                    config=deepcopy(binding.config),
+                    plugin_ref=_plugin_ref(plugin_id, plugin_version),
+                    config=config,
                 )
         return materializations
 
+    @staticmethod
+    def _memory_providers(
+        draft: AgentDraft,
+    ) -> dict[str, PluginCapabilitySelection]:
+        """Materialize a bound platform memory through its official DSH owner."""
+
+        memory = draft.spec.memory
+        if not memory.enabled or not memory.provider_ref.startswith("binding://"):
+            return {}
+        binding_id = memory.provider_ref.removeprefix("binding://")
+        for binding in draft.spec.bindings.plugins:
+            if not binding.enabled:
+                continue
+            config = resource_plugin_config(
+                binding.plugin_ref,
+                binding.ecosystem,
+                binding.config,
+                enabled=True,
+            )
+            if (
+                config is not None
+                and config.binding.id == binding_id
+                and config.binding.resource.kind == "memory-instance"
+            ):
+                return {
+                    memory.provider_ref: PluginCapabilitySelection(
+                        ref=PLATFORM_RESOURCE_MCP_REF,
+                        definition="memory.provider/v1",
+                        slot="memory.primary",
+                        config={"artifactPath": "platform-resources"},
+                    )
+                }
+        return {}
+
+
 __all__ = ["StudioPluginCompositionCompiler"]

ksadk/studio/plugin_kernel_adapter.py

@@ -1,128 +1,28 @@
-"""AgentKernel adapter for an immutable Studio PluginHost Build."""
+"""Studio wiring for the provider-neutral PluginHost Kernel adapter."""
 
 from __future__ import annotations
 
 from typing import Any
 
-from ksadk.kernel.contracts import InjectPayload, SteerPayload
-from ksadk.kernel.errors import UnsupportedControlError
-from ksadk.runtime import (
-    BaseRuntime,
-    CancelResult,
-    CheckpointDescriptor,
-    PauseResult,
-    ResumePayload,
-    ResumeTarget,
-    RunHandle,
-    RuntimeAdapter,
-    StartRequest,
-)
+from ksadk.plugins.kernel_adapter import PluginKernelAdapter
 from ksadk.studio.run_service import StudioRunSpec
 
 
-class _PluginKernelRuntime(BaseRuntime):
-    def __init__(self, runtime_type: str) -> None:
-        self.runtime_type = runtime_type
-
-    def native_capabilities(self) -> dict[str, Any]:
-        return {
-            "provider_owned": True,
-            "runtime_adapter": True,
-            "session_continuity": {"durable": False, "scope": "process"},
-        }
-
-
-class StudioPluginKernelAdapter(RuntimeAdapter):
-    """Lazily bind one Worker run to its profile-fenced provider activation."""
+class StudioPluginKernelAdapter(PluginKernelAdapter):
+    """Bind a Studio Build/session to its profile-fenced provider activation."""
 
     def __init__(self, plugin_runtime: Any, spec: StudioRunSpec) -> None:
-        super().__init__(_PluginKernelRuntime(spec.launch_context.runtime_type))
-        self._plugin_runtime = plugin_runtime
-        self._spec = spec
-        self._delegate: RuntimeAdapter | None = None
-
-    async def start(self, request: StartRequest) -> RunHandle:
-        delegate = await self._plugin_runtime.kernel_adapter(
-            self._spec,
-            session_id=request.session_id,
-        )
-        if not isinstance(delegate, RuntimeAdapter):
-            raise RuntimeError("AgentProvider returned an invalid RuntimeAdapter")
-        self._delegate = delegate
-        metadata = dict(request.metadata)
-        if not metadata.get("invocation_id") and metadata.get("run_id"):
-            metadata["invocation_id"] = metadata["run_id"]
-        return await delegate.start(request.model_copy(update={"metadata": metadata}))
-
-    def stream(self, handle: RunHandle):  # type: ignore[no-untyped-def]
-        return self._require_delegate().stream(handle)
-
-    async def cancel(self, handle: RunHandle) -> CancelResult:
-        return await self._require_delegate().cancel(handle)
-
-    async def pause(self, handle: RunHandle) -> PauseResult:
-        return await self._require_delegate().pause(handle)
-
-    async def submit(self, handle: RunHandle, payload: ResumePayload) -> None:
-        await self._require_delegate().submit(handle, payload)
+        async def bind_delegate(session_id: str):  # type: ignore[no-untyped-def]
+            return await plugin_runtime.kernel_adapter(spec, session_id=session_id)
 
-    async def resume(
-        self,
-        handle: RunHandle,
-        target: ResumeTarget,
-        payload: ResumePayload | None,
-    ) -> RunHandle:
-        return await self._require_delegate().resume(handle, target, payload)
+        async def release_binding(session_id: str) -> None:
+            await plugin_runtime.close_session_if_dynamic(spec, session_id)
 
-    async def attach(self, handle: RunHandle) -> RunHandle:
-        delegate = await self._plugin_runtime.kernel_adapter(
-            self._spec,
-            session_id=handle.session_id,
+        super().__init__(
+            runtime_type=spec.launch_context.runtime_type,
+            bind_delegate=bind_delegate,
+            release_binding=release_binding,
         )
-        if not isinstance(delegate, RuntimeAdapter):
-            raise RuntimeError("AgentProvider returned an invalid RuntimeAdapter")
-        self._delegate = delegate
-        return await delegate.attach(handle)
-
-    async def steer(self, handle: RunHandle, payload: SteerPayload) -> None:
-        await self._require_delegate().steer(handle, payload)
-
-    async def inject(self, handle: RunHandle, payload: InjectPayload) -> None:
-        await self._require_delegate().inject(handle, payload)
-
-    async def checkpoint(self, handle: RunHandle) -> CheckpointDescriptor:
-        return await self._require_delegate().checkpoint(handle)
-
-    async def durable_restore(self, handle: RunHandle) -> RunHandle:
-        delegate = await self._plugin_runtime.kernel_adapter(
-            self._spec,
-            session_id=handle.session_id,
-        )
-        if not isinstance(delegate, RuntimeAdapter):
-            raise RuntimeError("AgentProvider returned an invalid RuntimeAdapter")
-        self._delegate = delegate
-        return await delegate.durable_restore(handle)
-
-    def is_handle_attached(self, handle: RunHandle) -> bool:
-        return self._delegate is not None and self._delegate.is_handle_attached(handle)
-
-    async def close(self, handle: RunHandle) -> None:
-        await self._require_delegate().close(handle)
-
-    def capabilities(self):  # type: ignore[no-untyped-def]
-        # Before ``start`` the provider activation is async and not yet bound.
-        # Keep admission conservative; enqueue remains available and the live
-        # execution delegates supported controls after binding.
-        if self._delegate is None:
-            return super().capabilities()
-        return self._delegate.capabilities()
-
-    def _require_delegate(self) -> RuntimeAdapter:
-        if self._delegate is None:
-            raise UnsupportedControlError(
-                "PluginHost RuntimeAdapter has not started a provider activation"
-            )
-        return self._delegate
 
 
 __all__ = ["StudioPluginKernelAdapter"]