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

ksadk/studio/plugin_kernel_adapter.py

@@ -1,128 +1,43 @@
-"""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 resume(
-        self,
-        handle: RunHandle,
-        target: ResumeTarget,
-        payload: ResumePayload | None,
-    ) -> RunHandle:
-        return await self._require_delegate().resume(handle, target, payload)
-
-    async def attach(self, handle: RunHandle) -> RunHandle:
-        delegate = await self._plugin_runtime.kernel_adapter(
-            self._spec,
-            session_id=handle.session_id,
+        self._policy_supported = (
+            spec.request_config.get("provider_runtime_type") == "harness"
+            and getattr(plugin_runtime, "execution_policy_resolver", None) is not None
         )
-        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 bind_delegate(session_id: str):  # type: ignore[no-untyped-def]
+            return await plugin_runtime.kernel_adapter(spec, session_id=session_id)
 
-    async def inject(self, handle: RunHandle, payload: InjectPayload) -> None:
-        await self._require_delegate().inject(handle, payload)
+        async def release_binding(session_id: str) -> None:
+            await plugin_runtime.close_session_if_dynamic(spec, session_id)
 
-    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,
+        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.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()
+        # Studio wires a durable Workspace store before activating Harness.
+        if self._delegate is None and self._runtime_type == "harness":
+            from ksadk.harness.managed_runtime import managed_harness_capabilities
 
-    def _require_delegate(self) -> RuntimeAdapter:
-        if self._delegate is None:
-            raise UnsupportedControlError(
-                "PluginHost RuntimeAdapter has not started a provider activation"
+            return managed_harness_capabilities(
+                durable=True, execution_policy=self._policy_supported,
             )
-        return self._delegate
+        return super().capabilities()
 
 
 __all__ = ["StudioPluginKernelAdapter"]

ksadk/studio/plugin_lifecycle.py

@@ -0,0 +1,80 @@
+"""Credential-free failures shared by local plugin lifecycle surfaces."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from ksadk.studio.errors import StudioError
+
+RECOVERY_URL = "/studio-recovery/"
+_MESSAGES = {
+    "DSH_PROFILE_IN_USE": "仍有执行或审批正在进行，请结束执行后再变更插件 Profile。",
+    "authority_in_use": "已有本地宿主占用团队存储；请等待原宿主退出后重试。",
+    "artifact_migration_required": (
+        "插件版本已更新，需要先检查旧团队数据。已结束的兼容历史可以备份升级。"
+    ),
+    "migration_active_runs": "仍有在途任务，请先恢复原版本并核对执行状态，再升级历史。",
+    "local_upgrade_unsupported": "此历史版本需要专门迁移，请保留备份并使用原锁定版本。",
+    "migration_uncertain_execution": "仍有结果未确认的执行，请先核查原单再迁移。",
+    "execution_node_in_use": "这个工作区已有执行节点在运行，请等待其退出后重试。",
+    "DSH_TOOLCHAIN_MISSING": "本地插件工具链缺失，请先安装或修复 DSH。",
+    "dsh_toolchain_required": "本地插件工具链尚未配置，请先安装并启用 DSH。",
+    "teams_credentials_required": "团队服务连接凭据不可用，请更新本地配置后重试。",
+    "COMPANION_GRAPH_INCOMPLETE": "团队插件组件不完整，请修复或禁用插件。",
+    "COMPANION_GRAPH_NOT_READY": "团队插件组件尚未就绪，请重试或禁用插件。",
+}
+_REQUIRES_CHANGE = {
+    "artifact_migration_required",
+    "artifact_required",
+    "artifact_scope_mismatch",
+    "COMPANION_GRAPH_INCOMPLETE",
+    "COMPANION_PROFILE_MISMATCH",
+    "DSH_HOME_VERSION_UNVERIFIED",
+    "DSH_TOOLCHAIN_MISSING",
+    "authority_profile_unavailable",
+    "dsh_toolchain_required",
+}
+
+
+def lifecycle_failure(error: BaseException, stage: str) -> dict[str, Any]:
+    """Never expose exception text, transport addresses, or credentials."""
+    code = getattr(error, "code", "plugin_lifecycle_failed")
+    if not isinstance(code, str) or not re.fullmatch(r"[A-Za-z0-9_.-]{1,96}", code):
+        code = "plugin_lifecycle_failed"
+    details = getattr(error, "details", {})
+    prior_stage = details.get("stage") if isinstance(details, dict) else None
+    if isinstance(prior_stage, str) and re.fullmatch(r"[a-z_]{1,64}", prior_stage):
+        stage = prior_stage
+    reason = details.get("reason") if isinstance(details, dict) else None
+    if not isinstance(reason, str) or not re.fullmatch(r"[A-Za-z0-9_.-]{1,96}", reason):
+        reason = None
+    return {
+        "code": code,
+        "message": _MESSAGES.get(code, "插件暂时不可用，请查看诊断信息或重试。"),
+        "stage": stage,
+        "retryable": (reason or code) not in _REQUIRES_CHANGE,
+        "recoveryUrl": RECOVERY_URL,
+        **({"reason": reason} if reason else {}),
+    }
+
+
+def lifecycle_error(error: BaseException, stage: str) -> StudioError:
+    failure = lifecycle_failure(error, stage)
+    if isinstance(error, StudioError):
+        return StudioError(
+            error.code,
+            error.message,
+            status_code=error.status_code,
+            field=error.field,
+            details={**error.details, **failure},
+        )
+    status = getattr(error, "status", 503)
+    if not isinstance(status, int) or not 400 <= status <= 599:
+        status = 503
+    return StudioError(
+        failure["code"],
+        _MESSAGES.get(failure["code"], "插件未能完成装配，请打开恢复页面查看状态。"),
+        status_code=status,
+        details=failure,
+    )