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

ksadk/studio/event_store.py

@@ -43,16 +43,64 @@ class RunEventStore:
         stored in the run JSON so the Studio events timeline survives restarts.
         Runs that never call ``append`` keep ``set(run_payload) == {"record"}``.
         """
+        return self.append_many(run_id, [(event_type, data)])[0]
+
+    def append_many(
+        self,
+        run_id: str,
+        entries: list[tuple[str, dict[str, Any]]],
+    ) -> list[RunEvent]:
+        """Persist one logical Studio transition with a single file replace."""
         record, events = self._read(run_id)
-        event = RunEvent(
-            id=len(events) + 1,
+        appended: list[RunEvent] = []
+        for event_type, data in entries:
+            event = RunEvent(
+                id=len(events) + 1,
+                run_id=run_id,
+                type=event_type,
+                data=data,
+            )
+            events.append(event)
+            appended.append(event)
+        if appended:
+            self._write(record, events)
+        return appended
+
+    def append_interaction_resolution(
+        self,
+        run_id: str,
+        *,
+        resolved_type: str,
+        resolved_data: dict[str, Any],
+        action_data: dict[str, Any],
+    ) -> tuple[RunEvent, RunEvent, dict[str, Any]]:
+        """Atomically persist a terminal interaction and its replay receipt."""
+        record, events = self._read(run_id)
+        resolution_event_id = len(events) + 1
+        action_event_id = resolution_event_id + 1
+        receipt = {
+            "runId": run_id,
+            "interactionId": str(action_data.get("interactionId") or ""),
+            "status": "resolved",
+            "revision": int(action_data.get("revision") or 0),
+            "resolutionEventId": resolution_event_id,
+            "eventId": action_event_id,
+        }
+        resolved = RunEvent(
+            id=resolution_event_id,
+            run_id=run_id,
+            type=resolved_type,
+            data=resolved_data,
+        )
+        action = RunEvent(
+            id=action_event_id,
             run_id=run_id,
-            type=event_type,
-            data=data,
+            type="a2ui.action",
+            data={**action_data, "receipt": receipt},
         )
-        events.append(event)
+        events.extend((resolved, action))
         self._write(record, events)
-        return event
+        return resolved, action, receipt
 
     def events(self, run_id: str, *, after: int = 0) -> list[RunEvent]:
         _, events = self._read(run_id)

ksadk/studio/framework_run.py

@@ -8,6 +8,7 @@ from pathlib import Path
 from typing import Any
 
 from ksadk.detection.detector import FrameworkDetector
+from ksadk.plugins.bundle_security import BundleSecurityError, assert_bundle_security
 from ksadk.runtime import RuntimeLaunchContext
 from ksadk.studio.capabilities import compute_bundle_digest
 from ksadk.studio.contracts import BundleManifest
@@ -120,9 +121,11 @@ class FrameworkRunSpecResolver:
             raise StudioError("BUILD_NOT_READY", "Build 尚未生成制品", status_code=409)
         artifact_root = self.workspace.resolve(build.artifact_path, must_exist=True).parent
         bundle_root = artifact_root / "agent-bundle"
-        self._verify_bundle_integrity(
-            bundle_root, expected_bundle_digest=build.bundle_digest
-        )
+        self._verify_bundle_integrity(bundle_root, expected_bundle_digest=build.bundle_digest)
+        # v1 artifacts predate the no-literal-secret Bundle admission rule and
+        # must stay runnable. Every v2 bundle is checked again before local
+        # execution, including an externally restored but integrity-valid ZIP.
+        self._verify_bundle_security(bundle_root)
         project_dir = bundle_root / "runtime"
         if not project_dir.is_dir():
             raise StudioError(
@@ -301,6 +304,37 @@ class FrameworkRunSpecResolver:
                     },
                 )
 
+    @staticmethod
+    def _verify_bundle_security(bundle_dir: Path) -> None:
+        try:
+            manifest = BundleManifest.model_validate_json(
+                (bundle_dir / "manifest.json").read_text(encoding="utf-8")
+            )
+        except (OSError, ValueError):
+            # Integrity verification reports the canonical error for a malformed
+            # manifest; do not mask it with a second diagnostic path.
+            return
+        if manifest.bundle_format != "agentkit.bundle/v2":
+            return
+        try:
+            assert_bundle_security(bundle_dir)
+        except BundleSecurityError as exc:
+            raise StudioError(
+                "BUILD_ARTIFACT_INVALID",
+                "Bundle 包含不允许的明文凭证或本机路径",
+                status_code=422,
+                details={
+                    "securityFindings": [
+                        {
+                            "path": finding.path,
+                            "kind": finding.kind,
+                            **({"field": finding.field} if finding.field else {}),
+                        }
+                        for finding in exc.findings
+                    ]
+                },
+            ) from exc
+
 
 __all__ = ["FrameworkRunSpecResolver"]
 
@@ -309,7 +343,6 @@ def _resolved_memory_enabled(resolved: Any) -> bool:
     memory = resolved.get("memory") if isinstance(resolved, dict) else {}
     return bool(memory.get("enabled", False)) if isinstance(memory, dict) else False
 
-
     memory = resolved.get("memory") if isinstance(resolved, dict) else {}
     if not isinstance(memory, dict) or not memory.get("enabled", False):
         return False

ksadk/studio/hosted_kernel.py

@@ -21,7 +21,7 @@ from ksadk.studio.errors import StudioError
 AGENT_KERNEL_V1_CONTRACT_SET = "agent-kernel/v1"
 # This mirrors contracts/agent-kernel/v1/manifest.json. A Studio test compares
 # the two, so a frozen-contract update cannot leave packaged preflight stale.
-AGENT_KERNEL_V1_CONTRACT_DIGEST = "47e1003e03d97abeba232cc3e03a14b9cbcf78b1109870ccd2ce371f073b6211"
+AGENT_KERNEL_V1_CONTRACT_DIGEST = "b610a25aae957306b9f84a2cc2c948b30d1ce6218585cfd2a91f96736b92d102"
 HOSTED_KERNEL_REQUIREMENTS_PATH = "hosted-kernel-requirements.json"
 HOSTED_KERNEL_REQUIREMENTS_FORMAT = "agentkit.hosted-kernel-requirements/v1"
 HOSTED_KERNEL_RUNTIME_CONTRACT = "agentkit.runtime/v1"

ksadk/studio/operations.py

@@ -12,6 +12,7 @@ from uuid import uuid4
 
 from pydantic import ValidationError
 
+from ksadk.api import AgentEngineAPIError
 from ksadk.studio.contracts import (
     Operation,
     OperationEvent,
@@ -108,10 +109,19 @@ class OperationManager:
                 "exceptionType": type(exc).__name__,
             }
             # TypeError carries only Python call-shape information and is safe
-            # to surface to the local operator.  Do not expose arbitrary
-            # exception text: it may include provider request data.
+            # to surface to the local operator.  AgentEngineAPIError carries
+            # a structured server-side Action API message (not credentials),
+            # so surface it to help the operator diagnose a failed deployment.
             if isinstance(exc, TypeError):
                 operation.error["exceptionMessage"] = str(exc)
+            elif isinstance(exc, StudioError):
+                operation.error["code"] = exc.code
+                operation.error["message"] = exc.message
+            elif isinstance(exc, AgentEngineAPIError):
+                operation.error["code"] = f"AGENT_ENGINE_API_ERROR_{exc.code}"
+                operation.error["message"] = exc.message
+                if 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)

ksadk/studio/plugin_composition.py

@@ -0,0 +1,301 @@
+"""Studio Agent revision -> immutable PluginHost composition binding.
+
+This is the production build seam for Phase 2.  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
+this module and retain their established source-build behavior.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from copy import deepcopy
+
+from ksadk.plugins.builtins import (
+    BUILTIN_PLUGIN_VERSION,
+    CORE_RENDERER_PLUGIN_ID,
+    READ_ONLY_CONTEXT_PLUGIN_ID,
+    SQLITE_SESSION_STORE_PLUGIN_ID,
+    WORKSPACE_MCP_PLUGIN_ID,
+    WORKSPACE_SKILL_PLUGIN_ID,
+    builtin_capability_manifests,
+)
+from ksadk.plugins.composition import (
+    CompositionCompileError,
+    CompositionCompiler,
+    CompositionPolicy,
+    PluginCapabilitySelection,
+    ResourcePluginMaterialization,
+    RuntimePluginSelection,
+)
+from ksadk.plugins.contracts import PluginManifest
+from ksadk.plugins.providers.legacy_catalog import (
+    BUILTIN_PROVIDER_VERSION,
+    KSADK_HARNESS_AGENT_PROVIDER_PLUGIN_ID,
+    builtin_agent_provider_manifests,
+)
+from ksadk.plugins.resolver import PluginRegistry, ResolvedComposition
+from ksadk.studio.contracts import AgentDraft, CapabilityBinding
+from ksadk.studio.errors import StudioError
+from ksadk.studio.resource_catalog import LocalResourceCatalog
+from ksadk.studio.workspace import Workspace
+
+_COMPOSED_RUNTIME_TYPES = frozenset({"harness", "plugin"})
+_PROVIDER_DEFINITION = "agent.provider/v1"
+_PROVIDER_SLOT = "agent.execution"
+
+
+def _plugin_ref(plugin_id: str, version: str) -> str:
+    return f"plugin://{plugin_id}@{version}"
+
+
+def _selection(
+    plugin_id: str,
+    definition: str,
+    slot: str,
+    *,
+    config: Mapping[str, object] | None = None,
+) -> PluginCapabilitySelection:
+    return PluginCapabilitySelection(
+        ref=_plugin_ref(plugin_id, BUILTIN_PLUGIN_VERSION),
+        definition=definition,
+        slot=slot,
+        config=deepcopy(dict(config or {})),
+    )
+
+
+class StudioPluginCompositionCompiler:
+    """Bind a Studio revision to installed/built-in provider manifests."""
+
+    def __init__(
+        self,
+        workspace: Workspace,
+        catalog: LocalResourceCatalog,
+        *,
+        provider_manifests: Mapping[str, PluginManifest] | None = None,
+    ) -> None:
+        self._workspace = workspace
+        self._catalog = catalog
+        self._provider_manifests = dict(provider_manifests or {})
+
+    def replace_provider_registrations(
+        self, provider_manifests: Mapping[str, PluginManifest]
+    ) -> None:
+        """Bind the exact startup registration snapshot before any build."""
+
+        self._provider_manifests = dict(provider_manifests)
+
+    @staticmethod
+    def required_for(draft: AgentDraft) -> bool:
+        runtime = draft.spec.runtime
+        return runtime is not None and runtime.type in _COMPOSED_RUNTIME_TYPES
+
+    def compile_if_required(self, draft: AgentDraft) -> ResolvedComposition | None:
+        if not self.required_for(draft):
+            return None
+        return self.compile(draft)
+
+    def compile(self, draft: AgentDraft) -> ResolvedComposition:
+        runtime = draft.spec.runtime
+        if runtime is None or runtime.type not in _COMPOSED_RUNTIME_TYPES:
+            raise StudioError(
+                "PLUGIN_COMPOSITION_NOT_REQUIRED",
+                "当前 Runtime 继续使用既有构建链，不应声明 PluginHost composition",
+                status_code=422,
+                field="spec.runtime.type",
+            )
+
+        manifests = [
+            *builtin_agent_provider_manifests(),
+            *builtin_capability_manifests(),
+        ]
+        harness_ref = _plugin_ref(
+            KSADK_HARNESS_AGENT_PROVIDER_PLUGIN_ID,
+            BUILTIN_PROVIDER_VERSION,
+        )
+        harness_manifest = self._provider_manifests.get(harness_ref)
+        if runtime.type == "harness":
+            if harness_manifest is None:
+                raise StudioError(
+                    "AGENT_PROVIDER_NOT_REGISTERED",
+                    "KsADK Harness 尚未由受管理 DSH Profile 完成预检与注册",
+                    status_code=503,
+                    field="spec.runtime.type",
+                )
+            manifests.append(harness_manifest)
+        providers: dict[str, RuntimePluginSelection] = {}
+        if runtime.type == "plugin":
+            assert runtime.provider_ref is not None  # RuntimeRef validates this boundary.
+            external = self._registered_provider(runtime.provider_ref, draft)
+            manifests.append(external)
+            providers[runtime.provider_ref] = RuntimePluginSelection(
+                provider_ref=runtime.provider_ref,
+            )
+
+        policy = CompositionPolicy(
+            runtimes={"harness": RuntimePluginSelection(provider_ref=harness_ref)},
+            providers=providers,
+            session_store=_selection(
+                SQLITE_SESSION_STORE_PLUGIN_ID,
+                "session.event-store/v1",
+                "session.events",
+            ),
+            resource_materializations=self._resource_materializations(draft),
+            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 [],
+                        "maxChars": draft.spec.context.max_input_tokens * 4,
+                    },
+                )
+            },
+            renderers=(
+                _selection(
+                    CORE_RENDERER_PLUGIN_ID,
+                    "session.item.renderer/v1",
+                    "renderer.core",
+                ),
+            ),
+            default_runtime="harness",
+        )
+        try:
+            return CompositionCompiler(
+                PluginRegistry(manifests), self._catalog, policy
+            ).compile(draft)
+        except CompositionCompileError as error:
+            raise StudioError(
+                error.code.upper(),
+                str(error),
+                status_code=422,
+                field=error.field,
+            ) from error
+
+    def bind_build(self, composition: ResolvedComposition, *, agent_id: str, build_id: str) -> None:
+        """Keep the API seam while DSH owns package/Profile references."""
+
+        del composition, agent_id, build_id
+
+    def unbind_builds(self, builds: list[object]) -> tuple[tuple[str, str, str], ...]:
+        """Remove exact Bundle bindings before deleting an Agent.
+
+        The returned tokens let the caller restore protection if its filesystem
+        deletion transaction fails after the receipt updates.
+        """
+
+        del builds
+        return ()
+
+    def restore_bindings(self, bindings: tuple[tuple[str, str, str], ...]) -> None:
+        """Best-effort-safe rollback for a failed Agent deletion."""
+
+        del bindings
+
+    @staticmethod
+    def build_reference(agent_id: str, build_id: str) -> str:
+        return f"bundle://{agent_id}@{build_id}"
+
+    def _registered_provider(self, provider_ref: str, draft: AgentDraft) -> PluginManifest:
+        plugin_id, version = provider_ref.removeprefix("plugin://").rsplit("@", 1)
+        if plugin_id == KSADK_HARNESS_AGENT_PROVIDER_PLUGIN_ID:
+            raise StudioError(
+                "AGENT_PROVIDER_REFERENCE_RESERVED",
+                "Harness Runtime 必须选择受管理的默认 Provider 引用",
+                status_code=422,
+                field="spec.runtime.providerRef",
+            )
+        manifest = self._provider_manifests.get(provider_ref)
+        if manifest is None:
+            raise StudioError(
+                "AGENT_PROVIDER_NOT_REGISTERED",
+                "所选 AgentProvider 尚未由当前 DSH Profile 完成预检与注册",
+                status_code=422,
+                field="spec.runtime.providerRef",
+            )
+        if (
+            manifest.metadata.id != plugin_id
+            or manifest.metadata.version != version
+        ):
+            raise StudioError(
+                "AGENT_PROVIDER_REGISTRATION_MISMATCH",
+                "DSH AgentProvider 注册信息与精确引用不一致",
+                status_code=409,
+                field="spec.runtime.providerRef",
+            )
+        offers = [
+            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"
+        ):
+            raise StudioError(
+                "AGENT_PROVIDER_MANIFEST_INVALID",
+                "插件必须唯一提供 agent.provider/v1 的 agent.execution 槽位",
+                status_code=422,
+                field="spec.runtime.providerRef",
+            )
+        if manifest.spec.isolation != "sidecar":
+            raise StudioError(
+                "AGENT_PROVIDER_ISOLATION_INVALID",
+                "DSH AgentProvider 必须使用 sidecar 隔离",
+                status_code=422,
+                field="spec.runtime.providerRef",
+            )
+        missing_permissions = sorted(
+            set(manifest.spec.permissions)
+            - set(draft.spec.security.allowed_permissions)
+        )
+        if missing_permissions:
+            raise StudioError(
+                "AGENT_PROVIDER_PERMISSION_DENIED",
+                "Agent 未批准 Provider 请求的权限",
+                status_code=422,
+                field="spec.security.allowedPermissions",
+                details={"missingPermissions": missing_permissions},
+            )
+        return manifest
+
+    def _resource_materializations(
+        self, draft: AgentDraft
+    ) -> dict[str, ResourcePluginMaterialization]:
+        materializations: dict[str, ResourcePluginMaterialization] = {}
+        groups: tuple[tuple[str, list[CapabilityBinding]], ...] = (
+            ("mcp", draft.spec.bindings.mcp_servers),
+            ("skill", draft.spec.bindings.skills),
+        )
+        for kind, bindings in groups:
+            for binding in bindings:
+                if not binding.enabled:
+                    continue
+                # Catalog lookup is deliberate even though CompositionCompiler
+                # repeats the final kind/readiness check: it makes this product
+                # materializer fail at the authoritative Studio resource seam.
+                descriptor = self._catalog.get(binding.resource_id)
+                if descriptor.kind != kind:
+                    raise StudioError(
+                        "RESOURCE_KIND_INVALID",
+                        f"{kind.upper()} binding 引用了错误类型的资源",
+                        status_code=422,
+                        field=f"spec.bindings.{kind}",
+                        details={"resourceId": binding.resource_id},
+                    )
+                plugin_id = (
+                    WORKSPACE_MCP_PLUGIN_ID if kind == "mcp" else WORKSPACE_SKILL_PLUGIN_ID
+                )
+                materializations[binding.resource_id] = ResourcePluginMaterialization(
+                    kind=kind,  # type: ignore[arg-type]
+                    plugin_ref=_plugin_ref(plugin_id, BUILTIN_PLUGIN_VERSION),
+                    config=deepcopy(binding.config),
+                )
+        return materializations
+
+__all__ = ["StudioPluginCompositionCompiler"]

ksadk/studio/plugin_kernel_adapter.py

@@ -0,0 +1,128 @@
+"""AgentKernel adapter for an immutable Studio PluginHost Build."""
+
+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.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."""
+
+    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,
+        )
+        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"]