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

ksadk/plugins/host.py

@@ -4,6 +4,7 @@ The host has no knowledge of AgentControl, SessionEvent sequencing, or cloud
 deployment.  It only stages a fully resolved profile, atomically swaps it once
 healthy, and disposes owned effects in reverse dependency order.
 """
+
 from __future__ import annotations
 
 import asyncio
@@ -79,6 +80,9 @@ class PluginExecutionContext:
     profile_digest: str
     plugin_lock_digest: str
     bindings: tuple[PluginCapabilityBinding, ...]
+    # The host owns this key. Capability plugins may use it to bind ephemeral
+    # leases to the same provider activation without learning request payloads.
+    activation_key: str = ""
 
     def all(
         self,
@@ -89,8 +93,7 @@ class PluginExecutionContext:
         return tuple(
             binding
             for binding in self.bindings
-            if binding.definition == definition
-            and (slot is None or binding.slot == slot)
+            if binding.definition == definition and (slot is None or binding.slot == slot)
         )
 
     def require(
@@ -157,6 +160,7 @@ class _ActiveActivation:
     bundle_digest: str
     runtime: PreparedAgent
     operation_lock: asyncio.Lock
+    operation_task: asyncio.Task[Any] | None = None
     closed: bool = False
 
 
@@ -370,7 +374,11 @@ class PluginHost:
                 await self._finish_cleanup(self._dispose_unpinned_retired_graphs())
 
             graph = self._require_bundle_graph(bundle)
-            runtime = await self._prepare_activation(graph, bundle)
+            runtime = await self._prepare_activation(
+                graph,
+                bundle,
+                activation_key=key,
+            )
             active = _ActiveActivation(
                 key=key,
                 graph=graph,
@@ -406,11 +414,7 @@ class PluginHost:
         """Drain and dispose active plus retired graphs; there is no implicit restart."""
 
         async with self._transaction_lock:
-            graphs = [
-                graph
-                for graph in [self._active, *self._retired]
-                if graph is not None
-            ]
+            graphs = [graph for graph in [self._active, *self._retired] if graph is not None]
             self._active = None
             self._retired = []
             if graphs:
@@ -491,9 +495,7 @@ class PluginHost:
     def _require_bundle_graph(self, bundle: ResolvedPluginBundle) -> _ActiveGraph:
         graph = self._active
         if graph is None:
-            raise PluginHostError(
-                "plugin_profile_inactive", "no plugin profile is active"
-            )
+            raise PluginHostError("plugin_profile_inactive", "no plugin profile is active")
         if not self._bundle_matches_graph(bundle, graph):
             raise PluginHostError(
                 "plugin_bundle_profile_mismatch",
@@ -512,11 +514,11 @@ class PluginHost:
         self,
         graph: _ActiveGraph,
         bundle: ResolvedPluginBundle,
+        *,
+        activation_key: str,
     ) -> PreparedAgent:
-        capabilities = self._execution_context(graph)
-        provider_binding = capabilities.require(
-            "agent.provider/v1", slot="agent.execution"
-        )
+        capabilities = self._execution_context(graph, activation_key=activation_key)
+        provider_binding = capabilities.require("agent.provider/v1", slot="agent.execution")
         provider = provider_binding.runtime
         if not isinstance(provider, ExecutableAgentProvider):
             raise PluginHostError(
@@ -541,15 +543,11 @@ class PluginHost:
             try:
                 await activation.start()
             except Exception as error:  # noqa: BLE001 - activation boundary
-                raise PluginHostError(
-                    "agent_activation_start_failed", str(error)
-                ) from error
+                raise PluginHostError("agent_activation_start_failed", str(error)) from error
             try:
                 healthy = await activation.health()
             except Exception as error:  # noqa: BLE001 - activation boundary
-                raise PluginHostError(
-                    "agent_activation_health_failed", str(error)
-                ) from error
+                raise PluginHostError("agent_activation_health_failed", str(error)) from error
             if not healthy:
                 raise PluginHostError(
                     "agent_activation_health_failed",
@@ -572,15 +570,18 @@ class PluginHost:
         request: Any,
     ) -> Any:
         async with active.operation_lock:
-            if active.closed:
-                raise PluginHostError(
-                    "agent_activation_closed",
-                    f"Agent activation {active.key!r} is closed",
-                )
+            task = asyncio.current_task()
+            active.operation_task = task
             try:
+                if active.closed:
+                    raise PluginHostError(
+                        "agent_activation_closed",
+                        f"Agent activation {active.key!r} is closed",
+                    )
                 result = await active.runtime.execute(request)
             except asyncio.CancelledError:
-                await self._dispose_activation(active.runtime)
+                if not active.closed:
+                    await self._dispose_activation(active.runtime)
                 active.closed = True
                 raise
             except PluginHostError as error:
@@ -594,6 +595,9 @@ class PluginHost:
                 await self._dispose_activation(active.runtime)
                 active.closed = True
                 raise failure from error
+            finally:
+                if active.operation_task is task:
+                    active.operation_task = None
             self._last_failure = None
             return result
 
@@ -623,28 +627,86 @@ class PluginHost:
             return adapter
 
     async def _close_activation_record(self, active: _ActiveActivation) -> None:
-        async with active.operation_lock:
-            if active.closed:
-                return
-            await self._dispose_activation(active.runtime)
-            active.closed = True
+        await self._finish_cleanup(self._close_activation_record_owned(active))
+
+    async def _close_activation_record_owned(self, active: _ActiveActivation) -> None:
+        """Finish the entire terminal close before propagating caller cancellation."""
+
+        if active.closed and active.operation_task is None:
+            return
+        active.closed = True
+        operation = active.operation_task
+        await self._abort_activation(active.runtime)
+        if operation is not None and operation is not asyncio.current_task():
+            operation.cancel()
+        try:
+            await asyncio.wait_for(active.operation_lock.acquire(), timeout=2.0)
+        except TimeoutError:
+            await self._bounded_dispose_activation(active.runtime)
+            return
+        try:
+            await self._bounded_dispose_activation(active.runtime)
+        finally:
+            active.operation_lock.release()
+
+    @staticmethod
+    async def _abort_activation(activation: PreparedAgent) -> None:
+        """Finish provider revocation before a close can report success.
+
+        ``abort`` is currently implemented only by the Harness activation and
+        revokes activation-scoped MCP credentials.  A host-side timeout would
+        let close return while those credentials still authorize requests.
+        The underlying DSH lifecycle operation owns its network timeout and
+        kills the whole generation when revocation cannot be proven.
+        """
+
+        abort = getattr(activation, "abort", None)
+        if not callable(abort):
+            return
+        try:
+            result = abort()
+            if asyncio.iscoroutine(result):
+                await result
+        except BaseException:  # abort is best-effort; disposal still follows
+            pass
+
+    @classmethod
+    async def _bounded_dispose_activation(cls, activation: PreparedAgent) -> None:
+        try:
+            await asyncio.wait_for(cls._dispose_activation(activation), timeout=2.0)
+        except BaseException:  # terminal close cannot wait forever on provider code
+            pass
 
     async def _close_graph_activations(self, graph: _ActiveGraph) -> None:
-        for key, active in tuple(self._activations.items()):
-            if active.graph is not graph:
-                continue
-            await self._close_activation_record(active)
+        selected = [
+            (key, active)
+            for key, active in tuple(self._activations.items())
+            if active.graph is graph
+        ]
+        if selected:
+            await asyncio.gather(
+                *(self._close_activation_record(active) for _key, active in selected)
+            )
+        for key, active in selected:
             if self._activations.get(key) is active:
                 self._activations.pop(key, None)
 
     async def _close_all_activations(self) -> None:
-        for key, active in tuple(self._activations.items()):
-            await self._close_activation_record(active)
+        selected = tuple(self._activations.items())
+        if selected:
+            await asyncio.gather(
+                *(self._close_activation_record(active) for _key, active in selected)
+            )
+        for key, active in selected:
             if self._activations.get(key) is active:
                 self._activations.pop(key, None)
 
     @staticmethod
-    def _execution_context(graph: _ActiveGraph) -> PluginExecutionContext:
+    def _execution_context(
+        graph: _ActiveGraph,
+        *,
+        activation_key: str = "",
+    ) -> PluginExecutionContext:
         bindings = tuple(
             PluginCapabilityBinding(
                 plugin_id=plugin.entry.id,
@@ -660,6 +722,7 @@ class PluginHost:
             profile_digest=graph.resolved.profile_digest,
             plugin_lock_digest=graph.resolved.plugin_lock_digest,
             bindings=bindings,
+            activation_key=activation_key,
         )
 
     @staticmethod

ksadk/plugins/kernel_adapter.py

@@ -0,0 +1,205 @@
+"""Provider-neutral AgentKernel adapter for PluginHost runtimes."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+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,
+)
+
+BindDelegate = Callable[[str], Awaitable[RuntimeAdapter]]
+ReleaseBinding = Callable[[str], Awaitable[None]]
+
+_PROVIDER_RUNTIME_TYPE_KEY = "_ksadk_plugin_provider_runtime_type"
+
+
+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 PluginKernelAdapter(RuntimeAdapter):
+    """Expose a lazily activated Agent Provider through the Kernel contract."""
+
+    def __init__(
+        self,
+        *,
+        runtime_type: str,
+        bind_delegate: BindDelegate,
+        release_binding: ReleaseBinding,
+    ) -> None:
+        super().__init__(_PluginKernelRuntime(runtime_type))
+        self._runtime_type = runtime_type
+        self._bind_delegate_callback = bind_delegate
+        self._release_binding_callback = release_binding
+        self._delegate: RuntimeAdapter | None = None
+        self._native_handle: RunHandle | None = None
+
+    async def start(self, request: StartRequest) -> RunHandle:
+        try:
+            delegate = await self._bind_delegate(request.session_id)
+            metadata = dict(request.metadata)
+            if not metadata.get("invocation_id") and metadata.get("run_id"):
+                metadata["invocation_id"] = metadata["run_id"]
+            native_handle = await delegate.start(
+                request.model_copy(update={"metadata": metadata})
+            )
+            self._native_handle = native_handle
+            return self._outer_handle(native_handle)
+        except BaseException:
+            await self._release_failed_binding(request.session_id)
+            raise
+
+    def stream(self, handle: RunHandle):  # type: ignore[no-untyped-def]
+        return self._require_delegate().stream(self._provider_handle(handle))
+
+    async def cancel(self, handle: RunHandle) -> CancelResult:
+        return await self._require_delegate().cancel(self._provider_handle(handle))
+
+    async def pause(self, handle: RunHandle) -> PauseResult:
+        return await self._require_delegate().pause(self._provider_handle(handle))
+
+    async def submit(self, handle: RunHandle, payload: ResumePayload) -> None:
+        await self._require_delegate().submit(self._provider_handle(handle), payload)
+
+    async def resume(
+        self,
+        handle: RunHandle,
+        target: ResumeTarget,
+        payload: ResumePayload | None,
+    ) -> RunHandle:
+        native_handle = await self._require_delegate().resume(
+            self._provider_handle(handle), target, payload
+        )
+        self._native_handle = native_handle
+        return self._outer_handle(native_handle)
+
+    async def attach(self, handle: RunHandle) -> RunHandle:
+        try:
+            delegate = await self._bind_delegate(handle.session_id)
+            native_handle = await delegate.attach(self._provider_handle(handle))
+            self._native_handle = native_handle
+            return self._outer_handle(native_handle)
+        except BaseException:
+            await self._release_failed_binding(handle.session_id)
+            raise
+
+    async def steer(self, handle: RunHandle, payload: SteerPayload) -> None:
+        await self._require_delegate().steer(self._provider_handle(handle), payload)
+
+    async def inject(self, handle: RunHandle, payload: InjectPayload) -> None:
+        await self._require_delegate().inject(self._provider_handle(handle), payload)
+
+    async def checkpoint(self, handle: RunHandle) -> CheckpointDescriptor:
+        return await self._require_delegate().checkpoint(self._provider_handle(handle))
+
+    async def durable_restore(self, handle: RunHandle) -> RunHandle:
+        try:
+            delegate = await self._bind_delegate(handle.session_id)
+            native_handle = await delegate.durable_restore(
+                self._provider_handle(handle)
+            )
+            self._native_handle = native_handle
+            return self._outer_handle(native_handle)
+        except BaseException:
+            await self._release_failed_binding(handle.session_id)
+            raise
+
+    def is_handle_attached(self, handle: RunHandle) -> bool:
+        return self._delegate is not None and self._delegate.is_handle_attached(
+            self._provider_handle(handle)
+        )
+
+    async def close(self, handle: RunHandle) -> None:
+        try:
+            await self._require_delegate().close(self._provider_handle(handle))
+        finally:
+            await self._release_binding_callback(handle.session_id)
+
+    def capabilities(self):  # type: ignore[no-untyped-def]
+        # Provider activation is asynchronous, so admission is deliberately
+        # conservative until a session has bound its delegate.
+        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
+
+    async def _bind_delegate(self, session_id: str) -> RuntimeAdapter:
+        delegate = await self._bind_delegate_callback(session_id)
+        if not isinstance(delegate, RuntimeAdapter):
+            raise RuntimeError("AgentProvider returned an invalid RuntimeAdapter")
+        self._delegate = delegate
+        return delegate
+
+    def _outer_handle(self, handle: RunHandle) -> RunHandle:
+        native_ref = dict(handle.native_ref)
+        native_ref[_PROVIDER_RUNTIME_TYPE_KEY] = handle.runtime_type
+        return handle.model_copy(
+            update={"runtime_type": self._runtime_type, "native_ref": native_ref}
+        )
+
+    def _provider_handle(self, handle: RunHandle) -> RunHandle:
+        cached = self._native_handle
+        if (
+            cached is not None
+            and cached.run_id == handle.run_id
+            and cached.session_id == handle.session_id
+        ):
+            return cached
+        native_ref = dict(handle.native_ref)
+        runtime_type = str(native_ref.pop(_PROVIDER_RUNTIME_TYPE_KEY, "")).strip()
+        if not runtime_type:
+            runtime_type = self._require_delegate().runtime.runtime_type
+        return handle.model_copy(
+            update={"runtime_type": runtime_type, "native_ref": native_ref}
+        )
+
+    async def _release_failed_binding(self, session_id: str) -> None:
+        """Close a partially opened activation even under cancellation."""
+
+        self._delegate = None
+        self._native_handle = None
+        cleanup = asyncio.create_task(self._release_binding_callback(session_id))
+        interrupted = False
+        while not cleanup.done():
+            try:
+                await asyncio.shield(cleanup)
+            except asyncio.CancelledError:
+                interrupted = True
+        try:
+            cleanup.result()
+        except Exception:
+            # Preserve the provider/delegate failure. Its owner still gets the
+            # terminal suspend path for disposing a host that could not close.
+            pass
+        if interrupted:
+            raise asyncio.CancelledError
+
+
+__all__ = ["BindDelegate", "PluginKernelAdapter", "ReleaseBinding"]

ksadk/plugins/providers/__init__.py

@@ -46,6 +46,29 @@ _EXPORTS = {
     "DshAgentProviderRuntime": ("dsh", "DshAgentProviderRuntime"),
     "DshPreparedAgent": ("dsh", "DshPreparedAgent"),
     "dsh_agent_provider_manifest": ("dsh", "dsh_agent_provider_manifest"),
+    "DSH_CAPABILITY_BUNDLE_PACKAGE": (
+        "dsh_capabilities",
+        "DSH_CAPABILITY_BUNDLE_PACKAGE",
+    ),
+    "DSH_CAPABILITY_HOST_PROTOCOL": ("dsh_capabilities", "DSH_CAPABILITY_HOST_PROTOCOL"),
+    "DSH_CAPABILITY_HOST_VERSION": ("dsh_capabilities", "DSH_CAPABILITY_HOST_VERSION"),
+    "DshCapabilityTool": ("dsh_capabilities", "DshCapabilityTool"),
+    "DshMcpConnectorLease": ("dsh_capabilities", "DshMcpConnectorLease"),
+    "DshProfileCapabilityDescriptor": (
+        "dsh_capabilities",
+        "DshProfileCapabilityDescriptor",
+    ),
+    "DshProfileCapabilityHost": ("dsh_capabilities", "DshProfileCapabilityHost"),
+    "DshProfileCapabilityInventory": (
+        "dsh_capabilities",
+        "DshProfileCapabilityInventory",
+    ),
+    "load_dsh_capability_bundle": ("dsh_capabilities", "load_dsh_capability_bundle"),
+    "DSH_PROFILE_MCP_PLUGIN_ID": ("dsh_mcp", "DSH_PROFILE_MCP_PLUGIN_ID"),
+    "DSH_PROFILE_MCP_PLUGIN_VERSION": ("dsh_mcp", "DSH_PROFILE_MCP_PLUGIN_VERSION"),
+    "DshProfileMCPFactory": ("dsh_mcp", "DshProfileMCPFactory"),
+    "DshProfileMCPRuntime": ("dsh_mcp", "DshProfileMCPRuntime"),
+    "dsh_profile_mcp_manifest": ("dsh_mcp", "dsh_profile_mcp_manifest"),
     "HarnessContextSource": ("harness", "HarnessContextSource"),
     "HarnessMCPSource": ("harness", "HarnessMCPSource"),
     "HarnessProviderInventory": ("harness", "HarnessProviderInventory"),

ksadk/plugins/providers/bundles/dsh-knowledge/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-knowledge
+      name: '@kingsoftcloud/dsh-knowledge'

ksadk/plugins/providers/bundles/dsh-knowledge/index.mjs

@@ -0,0 +1,53 @@
+export const name = 'dsh-knowledge'
+export const inject = ['tools', 'platformResources']
+
+export function apply(ctx) {
+  ctx.effect(() => ctx.platformResources.registerTool('search_knowledge_base', 'search_knowledge_base'))
+  ctx.tools.register({
+    name: 'search_knowledge_base',
+    description: 'Search the knowledge base bound to this Agent and return document sources.',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Non-empty query, at most 16000 characters.' },
+        top_k: { type: 'integer', description: 'Positive result count, capped by the binding policy.' },
+      },
+      required: ['query'],
+      additionalProperties: false,
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          status: { type: 'string', enum: ['ok', 'empty', 'failed'] },
+          bindingId: { type: 'string' },
+          items: { type: 'array', items: {
+            type: 'object',
+            properties: {
+              documentId: { type: 'string' }, documentName: { type: 'string' },
+              segmentId: { type: 'string' }, content: { type: 'string' }, score: { type: 'number' },
+            },
+            required: ['documentId', 'documentName', 'segmentId', 'content', 'score'],
+            additionalProperties: false,
+          } },
+          truncated: { type: 'boolean' }, requestId: { type: 'string' },
+          errorCode: { oneOf: [
+            { type: 'string', enum: ['KNOWLEDGE_RETRIEVAL_FAILED', 'RESOURCE_FORBIDDEN'] }, { type: 'null' },
+          ] },
+        },
+        required: ['status', 'bindingId', 'items', 'truncated', 'requestId'],
+        additionalProperties: false,
+      },
+      render(_args, result) {
+        const text = result.status === 'failed' ? 'Knowledge retrieval failed.'
+          : result.status === 'empty' ? 'No matching knowledge found.'
+          : result.items.map(item => `[${item.documentName || item.documentId}] ${item.content}`).join('\n\n')
+        return [{ type: 'text', text }]
+      },
+    },
+    isConcurrencySafe: () => true,
+    execute(args, execution) {
+      return ctx.platformResources.call('search_knowledge_base', args, { signal: execution.signal })
+    },
+  })
+}

ksadk/plugins/providers/bundles/dsh-knowledge/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@kingsoftcloud/dsh-knowledge",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Private development bundle for Agent-bound knowledge retrieval",
+  "exports": {".": "./index.mjs", "./cordis.patch.yml": "./cordis.patch.yml"},
+  "files": ["index.mjs", "cordis.patch.yml"],
+  "engines": {"node": ">=22.19.0"},
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
+    "@kingsoftcloud/dsh-platform-resources": "0.1.0"
+  },
+  "dsh": {"bundle": {"patch": "./cordis.patch.yml"}}
+}

ksadk/plugins/providers/bundles/dsh-memory/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-memory
+      name: '@kingsoftcloud/dsh-memory'