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

ksadk/studio/event_store.py

@@ -1,4 +1,4 @@
-"""Persistent local Run and Event store."""
+"""Persistent local Run record store and derived trace access."""
 
 from __future__ import annotations
 
@@ -6,11 +6,11 @@ import json
 import shutil
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import List
+from typing import Any
 
 from pydantic import ValidationError
 
-from ksadk.studio.contracts import RunEvent, RunRecord, RunStatus
+from ksadk.studio.contracts import RunEvent, RunRecord
 from ksadk.studio.errors import StudioError, not_found
 from ksadk.studio.otel_trace import OtlpTraceStore
 from ksadk.studio.workspace import Workspace
@@ -28,40 +28,94 @@ class RunEventStore:
         path = self._path(record.id)
         if path.exists():
             raise StudioError("RUN_ALREADY_EXISTS", "Run 已存在", status_code=409)
-        self._write(record, [])
+        self._write(record)
         return record
 
     def save(self, record: RunRecord) -> RunRecord:
         _, events = self._read(record.id)
-        self._write(record, events)
+        self._write(record, events or None)
         return record
 
     def append(self, run_id: str, event_type: str, data: dict) -> RunEvent:
+        """Persist a Studio lifecycle RunEvent (run.created, memory.recall.projected, …).
+
+        These Studio-level events (as opposed to RuntimeEvents) are durably
+        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
-
-    def get(self, run_id: str) -> RunRecord:
-        record, _ = self._read(run_id)
-        return record
+        return resolved, action, receipt
 
     def events(self, run_id: str, *, after: int = 0) -> list[RunEvent]:
         _, events = self._read(run_id)
         return [event for event in events if event.id > after]
 
+    def get(self, run_id: str) -> RunRecord:
+        record, _ = self._read(run_id)
+        return record
+
     def list_runs(
         self,
         *,
         session_id: str | None = None,
         agent_id: str | None = None,
-    ) -> List[RunRecord]:
+    ) -> list[RunRecord]:
         records: list[RunRecord] = []
         directory = self.workspace.resolve(".agentkit/runs")
         for path in sorted(directory.glob("run_*.json")):
@@ -126,82 +180,6 @@ class RunEventStore:
             deleted += 1
         return deleted
 
-    def recover_interrupted(self) -> int:
-        """Reconcile non-terminal records left behind by a stopped Studio.
-
-        Events are persisted before the final RunRecord update.  A browser
-        disconnect or process stop can therefore leave a terminal event next
-        to a stale ``RUNNING`` record.  On startup the event log wins; a run
-        without any terminal event is explicitly marked interrupted because
-        its in-memory runtime task cannot survive a Studio restart.
-        """
-
-        recovered = 0
-        for record in self.list_runs():
-            if record.status not in {
-                RunStatus.CREATED,
-                RunStatus.RUNNING,
-                RunStatus.PAUSED,
-                RunStatus.WAITING_INPUT,
-            }:
-                continue
-            events = self.events(record.id)
-            terminal = next(
-                (
-                    event
-                    for event in reversed(events)
-                    if event.type
-                    in {
-                        "run.completed",
-                        "run.failed",
-                        "run.cancelled",
-                        "run.interrupted",
-                    }
-                ),
-                None,
-            )
-            if terminal is None:
-                terminal = self.append(
-                    record.id,
-                    "run.interrupted",
-                    {
-                        "status": "interrupted",
-                        "reason": "studio_restarted",
-                    },
-                )
-
-            if terminal.type == "run.completed":
-                record.status = RunStatus.COMPLETED
-                record.error = None
-            elif terminal.type == "run.failed":
-                record.status = RunStatus.FAILED
-                record.error = {
-                    "code": "RUNTIME_RUN_FAILED",
-                    "message": str(
-                        terminal.data.get("error")
-                        or terminal.data.get("message")
-                        or "Agent 运行失败"
-                    ),
-                }
-            elif terminal.type == "run.cancelled":
-                record.status = RunStatus.CANCELLED
-                record.error = {"code": "RUN_CANCELLED", "message": "运行已取消"}
-            else:
-                record.status = RunStatus.INTERRUPTED
-                record.error = {
-                    "code": "RUN_INTERRUPTED",
-                    "message": "Studio 重启后无法重新 attach 上一次本地运行",
-                }
-            record.completed_at = terminal.created_at
-            if record.started_at is not None:
-                record.duration_ms = max(
-                    0,
-                    int((record.completed_at - record.started_at).total_seconds() * 1000),
-                )
-            self.save(record)
-            recovered += 1
-        return recovered
-
     def trace(self, trace_id: str) -> dict:
         return self.trace_store.get_trace_view(trace_id)
 
@@ -253,14 +231,14 @@ class RunEventStore:
             status=status,
         )
 
-    def _read(self, run_id: str) -> tuple[RunRecord, List[RunEvent]]:
+    def _read(self, run_id: str) -> tuple[RunRecord, list[RunEvent]]:
         path = self._path(run_id)
         if not path.is_file():
             raise not_found("run", run_id)
         try:
             payload = json.loads(path.read_text(encoding="utf-8"))
             record = RunRecord.model_validate(payload["record"])
-            events = [RunEvent.model_validate(item) for item in payload["events"]]
+            events = [RunEvent.model_validate(item) for item in payload.get("events", [])]
             return record, events
         except (OSError, ValueError, KeyError, ValidationError) as exc:
             raise StudioError(
@@ -270,15 +248,15 @@ class RunEventStore:
                 details={"id": run_id},
             ) from exc
 
-    def _write(self, record: RunRecord, events: List[RunEvent]) -> None:
-        payload = {
-            "record": record.model_dump(by_alias=True, exclude_none=True, mode="json"),
-            "events": [
-                event.model_dump(by_alias=True, exclude_none=True, mode="json") for event in events
-            ],
+    def _write(self, record: RunRecord, events: list[RunEvent] | None = None) -> None:
+        payload: dict[str, Any] = {
+            "record": record.model_dump(by_alias=True, exclude_none=True, mode="json")
         }
+        if events is not None:
+            payload["events"] = [
+                event.model_dump(by_alias=True, exclude_none=True, mode="json") for event in events
+            ]
         self.workspace.atomic_write_text(
             self._path(record.id),
             json.dumps(payload, ensure_ascii=False, sort_keys=True, indent=2) + "\n",
         )
-        self.trace_store.sync(record, events)

ksadk/studio/framework_run.py

@@ -2,10 +2,16 @@
 
 from __future__ import annotations
 
+import hashlib
 import json
+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
 from ksadk.studio.errors import StudioError
 from ksadk.studio.repository import BuildRepository
 from ksadk.studio.run_service import StudioRunSpec
@@ -13,7 +19,79 @@ from ksadk.studio.workspace import Workspace
 from ksadk.tools.gateway import normalize_tool_approval_mode
 
 
+def _resolved_prompt_ownership(resolved: Any) -> str:
+    """从 resolved-agent-spec.json 的 context 块读 prompt_ownership。
+
+    resolved spec 由 ContractModel 以 ``by_alias=True`` 序列化，alias_generator 为
+    camelCase，故字段名为 ``promptOwnership``；``populate_by_name`` 仅作用于输入，JSON
+    输出仍为 alias。此处 camelCase 与 snake 两种写法都查，稳妥兼容。非 dict / 缺失时
+    返回空串（== framework 默认，不接管 Runner 输入）。
+    """
+    if not isinstance(resolved, dict):
+        return ""
+    context = resolved.get("context")
+    if not isinstance(context, dict):
+        return ""
+    return str(
+        context.get("promptOwnership")
+        or context.get("prompt_ownership")
+        or context.get("ownership")
+        or ""
+    )
+
+
+def _resolved_context_engine_rollout(resolved: Any) -> str:
+    """读取 AgentVersion 固化的 Context Engine rollout。"""
+    if not isinstance(resolved, dict):
+        return ""
+    context = resolved.get("context")
+    if not isinstance(context, dict):
+        return ""
+    rollout = context.get("rollout")
+    if not isinstance(rollout, dict):
+        return ""
+    return str(rollout.get("contextEngine") or rollout.get("context_engine") or "")
+
+
+def _resolved_memory_recall_enabled(resolved: Any) -> bool | None:
+    """读取 AgentVersion 的 Memory 召回开关；缺失时保留旧环境策略。"""
+    if not isinstance(resolved, dict):
+        return None
+    memory = resolved.get("memory")
+    if not isinstance(memory, dict) or "enabled" not in memory:
+        return None
+    enabled = bool(memory.get("enabled"))
+    recall = memory.get("recall")
+    if isinstance(recall, dict) and "enabled" in recall:
+        enabled = enabled and bool(recall.get("enabled"))
+    context = resolved.get("context")
+    contributors = context.get("contributors") if isinstance(context, dict) else None
+    if isinstance(contributors, dict):
+        explicit = contributors.get("memoryRecall", contributors.get("memory_recall"))
+        if explicit is not None:
+            enabled = enabled and bool(explicit)
+    return enabled
+
+
+def _resolved_memory_write_rollout(resolved: Any) -> str:
+    """读取 AgentVersion 固化的 Memory 写入 rollout。"""
+    if not isinstance(resolved, dict):
+        return ""
+    context = resolved.get("context")
+    if not isinstance(context, dict):
+        return ""
+    rollout = context.get("rollout")
+    if not isinstance(rollout, dict):
+        return ""
+    return str(rollout.get("memoryWrite") or rollout.get("memory_write") or "")
+
+
 class FrameworkRunSpecResolver:
+    # manifest.json 是 bundle 自身的描述文件，不进入 manifest.files 清单
+    # （builder 在扫描文件列表之后才写它），校验时排除。checksums.txt 在本仓
+    # bundle 格式中是 manifest 声明的普通成员，参与校验。
+    _BUNDLE_META_FILES = frozenset({"manifest.json"})
+
     def __init__(
         self,
         workspace: Workspace,
@@ -43,6 +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)
+        # 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(
@@ -67,13 +150,38 @@ class FrameworkRunSpecResolver:
         instructions = resolved.get("instructions") if isinstance(resolved, dict) else {}
         request_config = {
             "base_instructions": str((instructions or {}).get("system") or ""),
+            # Preserve system/task as separate PCM sources while keeping the
+            # framework runner's existing base_instructions projection.
+            "agent_system": str((instructions or {}).get("system") or ""),
+            "agent_task": str((instructions or {}).get("task") or ""),
+            **(
+                {"prompt_integration_mode": "ksadk_hosted"}
+                if _resolved_prompt_ownership(resolved) == "ksadk"
+                else {}
+            ),
+            "context_engine_rollout": _resolved_context_engine_rollout(resolved),
+            "memory_recall_enabled": _resolved_memory_recall_enabled(resolved),
+            "memory_write_rollout": _resolved_memory_write_rollout(resolved),
+            "memory_enabled": _resolved_memory_enabled(resolved),
+            "memory_write_mode": _resolved_memory_write_mode(resolved),
+            "flush_before_compaction": _resolved_memory_flush_before_compaction(resolved),
+            "provider_ref": _resolved_memory_provider_ref(resolved),
             "entry_point": detection.entry_point,
             "agent_variable": detection.agent_variable,
         }
-        if approval_mode:
-            request_config["tool_approval_mode"] = normalize_tool_approval_mode(
-                approval_mode
+        # AgentVersion 的 ContextSpec 预算传到 Planner（方案 §8.2）
+        context_spec = resolved.get("context") if isinstance(resolved, dict) else {}
+        if isinstance(context_spec, dict):
+            max_input = context_spec.get("maxInputTokens") or context_spec.get("max_input_tokens")
+            reserve_output = context_spec.get("reserveOutputTokens") or context_spec.get(
+                "reserve_output_tokens"
             )
+            if max_input is not None:
+                request_config["max_input_tokens"] = int(max_input)
+            if reserve_output is not None:
+                request_config["reserve_output_tokens"] = int(reserve_output)
+        if approval_mode:
+            request_config["tool_approval_mode"] = normalize_tool_approval_mode(approval_mode)
         return StudioRunSpec(
             launch_context=RuntimeLaunchContext(
                 runtime_type=runtime_type,
@@ -110,5 +218,158 @@ class FrameworkRunSpecResolver:
             )
         return selected
 
+    def _verify_bundle_integrity(
+        self,
+        bundle_dir: Path,
+        *,
+        expected_bundle_digest: str = "",
+    ) -> None:
+        """加载前校验 bundle 未被篡改：manifest 自身摘要、与 Build 记录一致、
+        文件清单无增删、每个文件 sha256/size 匹配。"""
+        try:
+            manifest = BundleManifest.model_validate_json(
+                (bundle_dir / "manifest.json").read_text(encoding="utf-8")
+            )
+        except (OSError, ValueError) as exc:
+            raise StudioError(
+                "BUILD_ARTIFACT_INVALID",
+                "Build 缺少有效的 Bundle Manifest",
+                status_code=500,
+            ) from exc
+        if manifest.bundle_digest != compute_bundle_digest(manifest):
+            raise StudioError(
+                "BUILD_ARTIFACT_INVALID",
+                "Bundle Manifest 摘要不匹配，Bundle 可能已被篡改",
+                status_code=500,
+                details={"bundleDigest": manifest.bundle_digest},
+            )
+        if expected_bundle_digest and manifest.bundle_digest != expected_bundle_digest:
+            raise StudioError(
+                "BUILD_ARTIFACT_INVALID",
+                "Bundle 与 Build 记录的摘要不一致，Bundle 可能已被篡改",
+                status_code=500,
+                details={
+                    "expected": expected_bundle_digest,
+                    "actual": manifest.bundle_digest,
+                },
+            )
+        declared = {entry.path for entry in manifest.files}
+        actual: dict[str, Path] = {}
+        for path in bundle_dir.rglob("*"):
+            if not path.is_file():
+                continue
+            relative = path.relative_to(bundle_dir).as_posix()
+            if relative in self._BUNDLE_META_FILES:
+                continue
+            actual[relative] = path
+        extra = sorted(set(actual) - declared)
+        if extra:
+            raise StudioError(
+                "BUILD_ARTIFACT_INVALID",
+                "Bundle 含未在 Manifest 中声明的文件",
+                status_code=500,
+                details={"extraFiles": extra},
+            )
+        for entry in manifest.files:
+            file_path = actual.get(entry.path)
+            if file_path is None:
+                raise StudioError(
+                    "BUILD_ARTIFACT_INVALID",
+                    "Bundle 缺少 Manifest 声明的文件",
+                    status_code=500,
+                    details={"missingFile": entry.path},
+                )
+            content = file_path.read_bytes()
+            actual_sha = f"sha256:{hashlib.sha256(content).hexdigest()}"
+            if actual_sha != entry.sha256:
+                raise StudioError(
+                    "BUILD_ARTIFACT_INVALID",
+                    "Bundle 文件摘要不匹配",
+                    status_code=500,
+                    details={
+                        "path": entry.path,
+                        "expected": entry.sha256,
+                        "actual": actual_sha,
+                    },
+                )
+            if len(content) != entry.size:
+                raise StudioError(
+                    "BUILD_ARTIFACT_INVALID",
+                    "Bundle 文件大小不匹配",
+                    status_code=500,
+                    details={
+                        "path": entry.path,
+                        "expected": entry.size,
+                        "actual": len(content),
+                    },
+                )
+
+    @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"]
+
+
+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
+    recall = memory.get("recall", {})
+    return bool(recall.get("enabled", True)) if isinstance(recall, dict) else True
+
+
+def _resolved_memory_write_mode(resolved: Any) -> str:
+    memory = resolved.get("memory") if isinstance(resolved, dict) else {}
+    write = memory.get("write", {}) if isinstance(memory, dict) else {}
+    return (
+        str(write.get("mode", "candidate") or "candidate")
+        if isinstance(write, dict)
+        else "candidate"
+    )
+
+
+def _resolved_memory_flush_before_compaction(resolved: Any) -> bool:
+    memory = resolved.get("memory") if isinstance(resolved, dict) else {}
+    write = memory.get("write", {}) if isinstance(memory, dict) else {}
+    return bool(write.get("flushBeforeCompaction", True)) if isinstance(write, dict) else True
+
+
+def _resolved_memory_provider_ref(resolved: Any) -> str:
+    memory = resolved.get("memory") if isinstance(resolved, dict) else {}
+    return (
+        str(memory.get("providerRef", "local-default") or "local-default")
+        if isinstance(memory, dict)
+        else "local-default"
+    )