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

ksadk/studio/native_workspace_diagnostics.py

@@ -0,0 +1,183 @@
+"""Bounded post-write observations owned by the Studio tool host.
+
+This first provider parses Python only. It never executes workspace code,
+imports a project, starts a language server, or establishes task acceptance.
+The frozen profile is part of the ToolDefinition identity, not model policy.
+"""
+
+from __future__ import annotations
+
+import ast
+import hashlib
+import json
+import os
+import stat
+import sys
+import warnings
+from pathlib import Path, PurePosixPath
+from typing import Literal
+
+from pydantic import Field
+
+from ksadk.harness.native.model import ModelTextContent
+from ksadk.harness.native.state import Contract
+
+WORKSPACE_WRITERS = frozenset(
+    {
+        "write_workspace_file",
+        "write_workspace_files",
+        "edit_workspace_file",
+        "multi_edit_workspace_file",
+    }
+)
+MAX_FILES = 8
+MAX_FILE_BYTES = 128 * 1024
+MAX_TOTAL_BYTES = 512 * 1024
+
+
+def feedback_profile_digest() -> str:
+    payload = {
+        "version": "workspace-diagnostics/v1",
+        "provider": "python_ast_parse",
+        "python_version": list(sys.version_info[:3]),
+        "max_files": MAX_FILES,
+        "max_file_bytes": MAX_FILE_BYTES,
+        "max_total_bytes": MAX_TOTAL_BYTES,
+        "symlinks": "deny",
+        "acceptance": "not_evaluated",
+    }
+    return (
+        "sha256:"
+        + hashlib.sha256(
+            json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
+        ).hexdigest()
+    )
+
+
+class FileDiagnostic(Contract):
+    path: str = Field(min_length=1, max_length=512)
+    status: Literal["passed", "error", "not_run"]
+    code: Literal[
+        "python_parse_passed",
+        "python_syntax_error",
+        "unsupported_file_type",
+        "path_rejected",
+        "file_unavailable",
+        "byte_budget_exceeded",
+        "parser_resource_limit",
+    ]
+    content_digest: str | None = Field(default=None, pattern=r"^sha256:[0-9a-f]{64}$")
+    line: int | None = Field(default=None, ge=1)
+    column: int | None = Field(default=None, ge=1)
+
+
+class WorkspaceDiagnostics(Contract):
+    version: Literal["workspace-diagnostics/v1"] = "workspace-diagnostics/v1"
+    scope: Literal["python_parse_only"] = "python_parse_only"
+    acceptance: Literal["not_evaluated"] = "not_evaluated"
+    profile_digest: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+    files: tuple[FileDiagnostic, ...] = Field(max_length=MAX_FILES)
+    omitted_file_count: int = Field(ge=0)
+
+
+def _read_file(root: Path, relative: PurePosixPath, limit: int) -> bytes | None:
+    """Open under the authorized root, refusing symlinks and special files.
+
+    Directory descriptors keep component replacement from redirecting the read
+    outside that root. Nonblocking open avoids waiting on a substituted FIFO.
+    None means the bounded read did not establish a complete file observation.
+    """
+    if not all(hasattr(os, name) for name in ("O_DIRECTORY", "O_NOFOLLOW", "O_NONBLOCK")):
+        raise OSError("diagnostic reader is unavailable on this platform")
+    if os.open not in os.supports_dir_fd:
+        raise OSError("diagnostic reader needs directory descriptor support")
+    directory = os.open(root, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+    try:
+        for component in relative.parts[:-1]:
+            child = os.open(
+                component, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=directory
+            )
+            os.close(directory)
+            directory = child
+        fd = os.open(relative.name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=directory)
+        with os.fdopen(fd, "rb") as source:
+            info = os.fstat(source.fileno())
+            if not stat.S_ISREG(info.st_mode):
+                raise OSError("diagnostic target is not a regular file")
+            if info.st_size > limit:
+                return None
+            data = source.read(limit + 1)
+            return data if len(data) <= limit else None
+    finally:
+        os.close(directory)
+
+
+def observe_workspace_writes(*, root: Path, paths: tuple[str, ...]) -> ModelTextContent:
+    files = []
+    remaining_bytes = MAX_TOTAL_BYTES
+    for path in paths[:MAX_FILES]:
+        # SDK result paths are untrusted file names. Never return source lines
+        # or parser exception messages; either can contain private file bytes.
+        if not path or len(path) > 512:
+            continue
+        relative = PurePosixPath(path)
+        report = {"path": path, "status": "not_run"}
+        if relative.is_absolute() or ".." in relative.parts or "\\" in path or "\x00" in path:
+            files.append(FileDiagnostic(**report, code="path_rejected"))
+            continue
+        if relative.suffix != ".py":
+            files.append(FileDiagnostic(**report, code="unsupported_file_type"))
+            continue
+        if remaining_bytes == 0:
+            files.append(FileDiagnostic(**report, code="byte_budget_exceeded"))
+            continue
+        try:
+            data = _read_file(
+                root.resolve(strict=True), relative, min(MAX_FILE_BYTES, remaining_bytes)
+            )
+        except (OSError, RuntimeError, ValueError):
+            files.append(FileDiagnostic(**report, code="file_unavailable"))
+            continue
+        if data is None:
+            files.append(FileDiagnostic(**report, code="byte_budget_exceeded"))
+            continue
+        remaining_bytes -= len(data)
+        content_digest = "sha256:" + hashlib.sha256(data).hexdigest()
+        try:
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore")
+                ast.parse(data, filename=path)
+        except SyntaxError as exc:
+            files.append(
+                FileDiagnostic(
+                    path=path,
+                    status="error",
+                    code="python_syntax_error",
+                    content_digest=content_digest,
+                    line=max(1, exc.lineno or 1),
+                    column=max(1, exc.offset or 1),
+                )
+            )
+        except (ValueError, RecursionError, MemoryError):
+            files.append(
+                FileDiagnostic(
+                    **report,
+                    code="parser_resource_limit",
+                    content_digest=content_digest,
+                )
+            )
+        else:
+            files.append(
+                FileDiagnostic(
+                    path=path,
+                    status="passed",
+                    code="python_parse_passed",
+                    content_digest=content_digest,
+                )
+            )
+    report = WorkspaceDiagnostics(
+        profile_digest=feedback_profile_digest(),
+        files=tuple(files),
+        omitted_file_count=len(paths) - len(files),
+    )
+    return ModelTextContent(text=report.model_dump_json(exclude_none=True))

ksadk/studio/native_workspace_port.py

@@ -0,0 +1,43 @@
+"""Bind a read-only Native workspace observer to one Studio activation scope."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ksadk.harness.native.ports import WorkspaceObservation, WorkspaceRequest
+from ksadk.harness.native.state import RunScope
+from ksadk.harness.stores.native_contract import RunStore
+from ksadk.harness.workspace_adapters.native_directory import LocalWorkspacePort
+
+
+class StudioNativeWorkspacePort:
+    """Capture the locked workspace only for a Run owned by this activation."""
+
+    def __init__(self, *, root: Path, scope: RunScope, store: RunStore) -> None:
+        self._root = root.resolve()
+        self._scope = scope.model_copy(deep=True)
+        self._store = store
+        # Browser screenshots are host observation artifacts. Their changing
+        # bytes must not look like the Agent changed the delivered project.
+        self._delegate = LocalWorkspacePort(self._root, ignored_path_parts=(".artifacts",))
+
+    async def capture(self, request: WorkspaceRequest) -> WorkspaceObservation:
+        if request.scope != self._scope:
+            raise ValueError("native_workspace_scope_mismatch")
+        try:
+            run = self._store.load(self._scope, request.run_id)
+        except Exception:
+            return WorkspaceObservation(
+                operation_key=request.operation_key,
+                status="unavailable",
+                reason="run_unavailable",
+            )
+        if run.scope != self._scope or run.run_id != request.run_id:
+            raise ValueError("native_workspace_run_mismatch")
+        if self._root.resolve() != self._root:
+            return WorkspaceObservation(
+                operation_key=request.operation_key,
+                status="unavailable",
+                reason="workspace_root_changed",
+            )
+        return await self._delegate.capture(request)

ksadk/studio/operations.py

@@ -39,6 +39,7 @@ class OperationManager:
         idempotency_key: str,
         metadata: dict | None = None,
         runner: Callable[[str], Awaitable[object]],
+        deferred_start: bool = False,
     ) -> Operation:
         existing = self._find_by_idempotency_key(idempotency_key)
         if existing is not None:
@@ -51,7 +52,7 @@ class OperationManager:
         )
         self._write(operation, [], idempotency_key)
         self.append(operation.id, "operation.queued", {"kind": kind})
-        task = asyncio.create_task(self._run(operation.id, runner))
+        task = asyncio.create_task(self._run(operation.id, runner, deferred_start=deferred_start))
         self._tasks[operation.id] = task
 
         def remove_completed(_task: asyncio.Task, op_id: str = operation.id) -> None:
@@ -64,13 +65,16 @@ class OperationManager:
         self,
         operation_id: str,
         runner: Callable[[str], Awaitable[object]],
+        *,
+        deferred_start: bool,
     ) -> None:
-        operation = self.get(operation_id)
-        operation.status = OperationStatus.RUNNING
-        self._save_record(operation)
-        self.append(operation_id, "operation.started", {})
+        if not deferred_start:
+            self.mark_started(operation_id)
         try:
             result = await runner(operation_id)
+            if deferred_start:
+                self.mark_started(operation_id)
+            operation = self.get(operation_id)
             result_id = getattr(result, "id", None)
             if result_id:
                 operation.resource_id = str(result_id)
@@ -83,21 +87,27 @@ class OperationManager:
                 {"resourceId": operation.resource_id},
             )
         except asyncio.CancelledError:
-            operation.status = OperationStatus.CANCELLED
-            operation.completed_at = datetime.now(timezone.utc)
-            self._save_record(operation)
-            self.append(operation_id, "operation.cancelled", {})
+            operation = self.get(operation_id)
+            if operation.status != OperationStatus.CANCELLED:
+                operation.status = OperationStatus.CANCELLED
+                operation.completed_at = datetime.now(timezone.utc)
+                self._save_record(operation)
+                self.append(operation_id, "operation.cancelled", {})
         except StudioError as exc:
+            operation = self.get(operation_id)
             operation.status = OperationStatus.FAILED
             operation.error = {
                 "code": exc.code,
                 "message": exc.message,
                 "field": exc.field,
             }
+            if exc.code in {"A2A_BINDING_TARGET_UNAVAILABLE", "A2A_BINDING_VERSION_DRIFT"} and exc.details:
+                operation.error["details"] = exc.details
             operation.completed_at = datetime.now(timezone.utc)
             self._save_record(operation)
             self.append(operation_id, "operation.failed", operation.error)
         except Exception as exc:
+            operation = self.get(operation_id)
             # Keep the browser response generic so an exception cannot leak a
             # credential, but retain the traceback in the local Studio log for
             # an operator to diagnose a failed deployment.
@@ -126,6 +136,17 @@ class OperationManager:
             self._save_record(operation)
             self.append(operation_id, "operation.failed", operation.error)
 
+    def mark_started(self, operation_id: str) -> None:
+        """Admit a queued operation at the point its effectful owner starts."""
+        operation = self.get(operation_id)
+        if operation.status == OperationStatus.RUNNING:
+            return
+        if operation.status != OperationStatus.QUEUED:
+            raise asyncio.CancelledError()
+        operation.status = OperationStatus.RUNNING
+        self._save_record(operation)
+        self.append(operation_id, "operation.started", {})
+
     def get(self, operation_id: str) -> Operation:
         operation, _, _ = self._read(operation_id)
         return operation
@@ -254,6 +275,10 @@ class OperationManager:
                 continue
         return None
 
+    def find_by_idempotency_key(self, key: str) -> Operation | None:
+        """Read the original persisted operation without submitting it again."""
+        return self._find_by_idempotency_key(key)
+
     def _recover_interrupted(self) -> None:
         directory = self.workspace.resolve(".agentkit/operations")
         for path in directory.glob("op_*.json"):

ksadk/studio/plugin_composition.py

@@ -1,6 +1,6 @@
 """Studio Agent revision -> immutable PluginHost composition binding.
 
-This is the production build seam for Phase 2.  It admits built-in providers
+This is the production build seam for Release.  It admits built-in providers
 or one exact AgentProvider registration emitted by the active DSH host,
 then delegates the deterministic Profile/Lock construction to
 ``CompositionCompiler``.  Legacy ADK/LangGraph drafts intentionally bypass
@@ -18,6 +18,7 @@ from ksadk.harness.tools import HARNESS_SANDBOX_TOOL_NAMES
 from ksadk.plugins.builtins import (
     BUILTIN_PLUGIN_VERSION,
     CORE_RENDERER_PLUGIN_ID,
+    LOCAL_MEMORY_PROVIDER_PLUGIN_ID,
     READ_ONLY_CONTEXT_PLUGIN_ID,
     SQLITE_SESSION_STORE_PLUGIN_ID,
     WORKSPACE_MCP_PLUGIN_ID,
@@ -54,6 +55,8 @@ 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.native_context_registration import StudioNativeContextRegistration
+from ksadk.studio.native_hook_registration import StudioNativeHookRegistration
 from ksadk.studio.resource_build_admission import resource_build_required
 from ksadk.studio.resource_catalog import LocalResourceCatalog
 from ksadk.studio.workspace import Workspace
@@ -91,10 +94,14 @@ class StudioPluginCompositionCompiler:
         catalog: LocalResourceCatalog,
         *,
         provider_manifests: Mapping[str, PluginManifest] | None = None,
+        hook_registrations: tuple[StudioNativeHookRegistration, ...] = (),
+        context_registrations: tuple[StudioNativeContextRegistration, ...] = (),
     ) -> None:
         self._workspace = workspace
         self._catalog = catalog
         self._provider_manifests = dict(provider_manifests or {})
+        self._hook_registrations = tuple(hook_registrations)
+        self._context_registrations = tuple(context_registrations)
 
     def replace_provider_registrations(
         self, provider_manifests: Mapping[str, PluginManifest]
@@ -145,6 +152,16 @@ class StudioPluginCompositionCompiler:
                     field="spec.runtime.type",
                 )
             manifests.append(harness_manifest)
+        hook_registrations = tuple(
+            item for item in self._hook_registrations
+            if runtime.type == "harness" and draft.metadata.id in item.agent_ids
+        )
+        manifests.extend(item.manifest for item in hook_registrations)
+        context_registrations = tuple(
+            item for item in self._context_registrations
+            if runtime.type == "harness" and draft.metadata.id in item.agent_ids
+        )
+        manifests.extend(item.manifest for item in context_registrations)
         providers: dict[str, RuntimePluginSelection] = {}
         if runtime.type == "plugin":
             assert runtime.provider_ref is not None  # RuntimeRef validates this boundary.
@@ -154,6 +171,15 @@ class StudioPluginCompositionCompiler:
                 provider_ref=runtime.provider_ref,
             )
 
+        host_capabilities = [item.selection
+                             for item in (*hook_registrations, *context_registrations)]
+        if requires_platform_resources:
+            host_capabilities.append(PluginCapabilitySelection(
+                ref=PLATFORM_RESOURCE_MCP_REF,
+                definition="mcp.connector/v1",
+                slot="mcp.platform-resources",
+                config={"artifactPath": "platform-resources"},
+            ))
         policy = CompositionPolicy(
             runtimes={"harness": RuntimePluginSelection(provider_ref=harness_ref)},
             providers=providers,
@@ -164,16 +190,7 @@ class StudioPluginCompositionCompiler:
             ),
             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 (),
+            host_capabilities=tuple(host_capabilities),
             context_contributors={
                 "workspace_rules": _selection(
                     READ_ONLY_CONTEXT_PLUGIN_ID,
@@ -437,7 +454,17 @@ class StudioPluginCompositionCompiler:
         """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://"):
+        if not memory.enabled:
+            return {}
+        if memory.provider_ref == "local-default":
+            return {
+                memory.provider_ref: _selection(
+                    LOCAL_MEMORY_PROVIDER_PLUGIN_ID,
+                    "memory.provider/v1",
+                    "memory.primary",
+                )
+            }
+        if not memory.provider_ref.startswith("binding://"):
             return {}
         binding_id = memory.provider_ref.removeprefix("binding://")
         for binding in draft.spec.bindings.plugins:

ksadk/studio/plugin_kernel_adapter.py

@@ -2,9 +2,13 @@
 
 from __future__ import annotations
 
+from collections.abc import Awaitable, Callable
+from inspect import isawaitable
 from typing import Any
 
+from ksadk.harness.native_runtime import NativeRuntimeAdapter
 from ksadk.plugins.kernel_adapter import PluginKernelAdapter
+from ksadk.runtime import RunHandle, RuntimeAdapter, StartRequest
 from ksadk.studio.run_service import StudioRunSpec
 
 
@@ -12,17 +16,102 @@ class StudioPluginKernelAdapter(PluginKernelAdapter):
     """Bind a Studio Build/session to its profile-fenced provider activation."""
 
     def __init__(self, plugin_runtime: Any, spec: StudioRunSpec) -> None:
+        self._studio_spec = spec
+        self._native_admission: (
+            Callable[
+                [NativeRuntimeAdapter, StartRequest], StartRequest | Awaitable[StartRequest]
+            ] | None
+        ) = None
+        self._policy_supported = (
+            spec.request_config.get("provider_runtime_type") == "harness"
+            and getattr(plugin_runtime, "execution_policy_resolver", None) is not None
+        )
+
         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 release_binding(session_id: str) -> None:
             await plugin_runtime.close_session_if_dynamic(spec, session_id)
 
+        async def release_failed_binding(session_id: str) -> None:
+            close_session = getattr(plugin_runtime, "close_failed_session", None)
+            if not callable(close_session):
+                close_session = getattr(plugin_runtime, "close_session", None)
+            if callable(close_session):
+                await close_session(session_id)
+            else:
+                await release_binding(session_id)
+
         super().__init__(
             runtime_type=spec.launch_context.runtime_type,
             bind_delegate=bind_delegate,
             release_binding=release_binding,
+            release_failed_binding=release_failed_binding,
         )
 
+    def bind_native_admission(
+        self, admission: Callable[
+            [NativeRuntimeAdapter, StartRequest], StartRequest | Awaitable[StartRequest]
+        ]
+    ) -> None:
+        if self._delegate is not None or self._native_admission is not None:
+            raise RuntimeError("Native admission must be bound once before start")
+        self._native_admission = admission
+
+    async def _prepare_start_request(
+        self, delegate: RuntimeAdapter, request: StartRequest
+    ) -> StartRequest:
+        if isinstance(delegate, NativeRuntimeAdapter):
+            if self._native_admission is None:
+                raise ValueError("native_studio_admission_unavailable")
+            admitted = self._native_admission(delegate, request)
+            return await admitted if isawaitable(admitted) else admitted
+        return request
+
+    async def _prepare_restore_handle(
+        self, delegate: RuntimeAdapter, handle: RunHandle
+    ) -> RunHandle:
+        if isinstance(delegate, NativeRuntimeAdapter):
+            spec = self._studio_spec
+            delegate.admit_studio_build(
+                build_id=spec.build_id,
+                manifest_sha256=spec.manifest_sha256,
+                model=spec.model,
+                request_config=spec.request_config,
+                project_dir=spec.launch_context.project_dir,
+                launch_config=spec.launch_context.config,
+                require_pin=True,
+            )
+        return handle
+
+    async def prepare_native_restore(self, handle: RunHandle, *, expected_goal: str) -> None:
+        """Validate a cold Native ledger through its original locked activation."""
+        try:
+            delegate = await self._bind_delegate(handle.session_id)
+            if not isinstance(delegate, NativeRuntimeAdapter):
+                raise ValueError("native_studio_restore_provider_changed")
+            matrix = delegate.capabilities()
+            if not (matrix.attach.supported and matrix.durable_restore.supported):
+                raise ValueError("native_studio_durable_restore_unavailable")
+            await self._prepare_restore_handle(delegate, handle)
+            snapshot = delegate.snapshot(self._provider_handle(handle))
+            if not snapshot.matches_initial_goal(expected_goal):
+                raise ValueError("native_studio_restore_goal_mismatch")
+            if delegate.session_parent_run_id(handle.session_id) != handle.run_id:
+                raise ValueError("native_studio_restore_session_head_mismatch")
+        except BaseException:
+            await self._release_failed_binding(handle.session_id)
+            raise
+
+    def capabilities(self):  # type: ignore[no-untyped-def]
+        # Studio wires a durable Workspace store before activating Harness.
+        if self._delegate is None and self._runtime_type == "harness":
+            from ksadk.harness.runtime_capabilities import managed_harness_capabilities
+
+            return managed_harness_capabilities(
+                durable=True, execution_policy=self._policy_supported,
+            )
+        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,
+    )