agentengine-sdk-python 0.8.2__py3-none-any.whl → 0.8.4__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"
@@ -45,9 +45,35 @@ def build_hosted_kernel_requirement(
     entry_point: str | None,
     agent_variable: str | None,
     launch_config: bytes | None,
+    composition_profile_digest: str | None = None,
+    plugin_lock_digest: str | None = None,
+    provider_ref: str | None = None,
 ) -> dict[str, Any]:
     """Build the immutable local requirement embedded into every Studio ZIP."""
 
+    if runtime_type == "plugin":
+        if not composition_profile_digest or not plugin_lock_digest or not provider_ref:
+            raise ValueError("plugin runtime requires a resolved composition launch contract")
+        runtime_requirement = {
+            "type": runtime_type,
+            "launchMode": "plugin-host",
+            "compositionProfile": "composition-profile.json",
+            "compositionProfileDigest": composition_profile_digest,
+            "pluginLock": "plugin-lock.json",
+            "pluginLockDigest": plugin_lock_digest,
+            "providerRef": provider_ref,
+        }
+    else:
+        runtime_requirement = {
+            "type": runtime_type,
+            "entryPoint": entry_point or "",
+            "agentVariable": agent_variable or "",
+            "launchConfig": "runtime/agentengine.yaml" if launch_config is not None else "",
+            "launchConfigSha256": (
+                sha256_digest(launch_config) if launch_config is not None else ""
+            ),
+        }
+
     return {
         "format": HOSTED_KERNEL_REQUIREMENTS_FORMAT,
         "kernelContract": {
@@ -56,13 +82,7 @@ def build_hosted_kernel_requirement(
         },
         "bundleLayout": HOSTED_KERNEL_BUNDLE_FORMAT,
         "runtimeContract": HOSTED_KERNEL_RUNTIME_CONTRACT,
-        "runtime": {
-            "type": runtime_type,
-            "entryPoint": entry_point or "",
-            "agentVariable": agent_variable or "",
-            "launchConfig": "runtime/agentengine.yaml" if launch_config is not None else "",
-            "launchConfigSha256": sha256_digest(launch_config) if launch_config is not None else "",
-        },
+        "runtime": runtime_requirement,
     }
 
 
@@ -207,17 +227,24 @@ def _validate_requirement(
             "Bundle 缺少受支持的 runtime 启动 requirement", reason="missing_runtime"
         )
     runtime_type = str(runtime.get("type") or "").strip().lower()
-    entry_point = str(runtime.get("entryPoint") or "").strip()
-    agent_variable = str(runtime.get("agentVariable") or "").strip()
-    launch_path = str(runtime.get("launchConfig") or "").strip()
-    launch_digest = str(runtime.get("launchConfigSha256") or "").strip()
+    manifest_runtime_type = str(manifest.get("runtimeType") or "").strip().lower()
+    if runtime_type != manifest_runtime_type:
+        raise _incompatible_error(
+            "Bundle runtime requirement 与 manifest 不一致", reason="runtime_type"
+        )
+    if runtime_type == "plugin":
+        _validate_plugin_launch(manifest, runtime, entries)
+        return
     if runtime_type not in _RUNTIME_TYPES:
         raise _incompatible_error(
             "Bundle runtime 类型不受 Hosted Agent Kernel 支持", reason="runtime_type"
         )
+    entry_point = str(runtime.get("entryPoint") or "").strip()
+    agent_variable = str(runtime.get("agentVariable") or "").strip()
+    launch_path = str(runtime.get("launchConfig") or "").strip()
+    launch_digest = str(runtime.get("launchConfigSha256") or "").strip()
     if (
-        runtime_type != str(manifest.get("runtimeType") or "").strip().lower()
-        or not entry_point
+        not entry_point
         or not agent_variable
         or launch_path != "runtime/agentengine.yaml"
         or not launch_digest
@@ -249,6 +276,54 @@ def _validate_requirement(
         )
 
 
+def _validate_plugin_launch(
+    manifest: dict[str, Any],
+    runtime: dict[str, Any],
+    entries: dict[str, bytes],
+) -> None:
+    profile_path = str(runtime.get("compositionProfile") or "").strip()
+    profile_digest = str(runtime.get("compositionProfileDigest") or "").strip()
+    lock_path = str(runtime.get("pluginLock") or "").strip()
+    lock_digest = str(runtime.get("pluginLockDigest") or "").strip()
+    provider_ref = str(runtime.get("providerRef") or "").strip()
+    if (
+        runtime.get("launchMode") != "plugin-host"
+        or manifest.get("compositionMode") != "composed"
+        or profile_path != "composition-profile.json"
+        or lock_path != "plugin-lock.json"
+        or not profile_digest
+        or not lock_digest
+        or not provider_ref
+        or manifest.get("compositionProfileDigest") != profile_digest
+        or manifest.get("pluginLockDigest") != lock_digest
+    ):
+        raise _incompatible_error(
+            "Bundle 缺少可验证的 PluginHost 启动配置", reason="plugin_launch"
+        )
+    profile = _json_object(entries, profile_path)
+    lock = _json_object(entries, lock_path)
+    if sha256_digest(canonical_json(profile)) != profile_digest:
+        raise _incompatible_error(
+            "Bundle composition profile digest 不一致", reason="plugin_profile_digest"
+        )
+    if sha256_digest(canonical_json(lock)) != lock_digest:
+        raise _incompatible_error(
+            "Bundle plugin lock digest 不一致", reason="plugin_lock_digest"
+        )
+    agent_provider = profile.get("agentProvider")
+    if not isinstance(agent_provider, dict) or agent_provider.get("ref") != provider_ref:
+        raise _incompatible_error(
+            "Bundle Agent Provider 与 PluginHost requirement 不一致",
+            reason="plugin_provider",
+        )
+    runtime_lock = _json_object(entries, "runtime-lock.json")
+    if str(runtime_lock.get("type") or "").strip().lower() != "plugin":
+        raise _incompatible_error(
+            "Bundle runtime lock 与 PluginHost requirement 不一致",
+            reason="runtime_lock",
+        )
+
+
 def _validate_content_manifest(manifest: dict[str, Any], entries: dict[str, bytes]) -> None:
     files = manifest.get("files")
     if not isinstance(files, list):

ksadk/studio/mcp_runtime.py

@@ -142,9 +142,11 @@ class MCPRuntimeAdapter:
                 yield read_stream, write_stream
         elif transport in {"http", "streamable-http", "streamable_http"}:
             headers = self._http_headers(server)
-            async with streamablehttp_client(
-                server.endpoint_url or "", headers=headers
-            ) as (read_stream, write_stream, _):
+            async with streamablehttp_client(server.endpoint_url or "", headers=headers) as (
+                read_stream,
+                write_stream,
+                _,
+            ):
                 yield read_stream, write_stream
         elif transport == "sse":
             headers = self._http_headers(server)
@@ -193,6 +195,12 @@ class MCPRuntimeAdapter:
 
     @staticmethod
     def _validate(server: MCPServerRef) -> None:
+        if server.materialization == "dsh-profile":
+            raise StudioError(
+                "DSH_MCP_MANAGED_RESOURCE_REQUIRED",
+                "DSH Profile MCP 必须通过受管理的 PluginHost 租约使用",
+                status_code=422,
+            )
         transport = (server.transport or "stdio").lower()
         if transport == "stdio":
             command = Path(server.command or "").name.lower()

ksadk/studio/model_client.py

@@ -220,9 +220,9 @@ class CredentialResolver:
             "persistence": source,
         }
 
-    def resolve(self, reference: str) -> str:
+    def resolve(self, reference: str, *, allow_aliases: bool = True) -> str:
         name = self._environment_name(reference)
-        fallback = self._fallback_name(name)
+        fallback = self._fallback_name(name) if allow_aliases else None
         aliases = [name, *([fallback] if fallback else [])]
         for candidate in aliases:
             value = self._session_value(candidate)

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)