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

ksadk/deployment/providers/serverless.py

@@ -40,23 +40,9 @@ from ksadk.deployment.env_forward import should_forward_process_env
 from ksadk.deployment.registry import DeployProviderRegistry
 from ksadk.deployment.ui_config import resolve_ui_config, ui_config_to_state_fields
 
-logger = logging.getLogger(__name__)
-
-# CodeBuilder archives put the runnable application below ``runtime/``.  The
-# command and checksum travel together: sending the command for an arbitrary
-# legacy ``--ks3-path`` archive could change its launch semantics, while a
-# fresh locally built archive can be attested and safely admitted as v1.
-_HOSTED_CODE_COMMAND = (
-    "ksadk",
-    "web",
-    "/app/code",
-    "--port",
-    "8080",
-    "--host",
-    "0.0.0.0",
-    "--no-open",
-)
+from ksadk.deployment.providers.serverless_payloads import _ServerlessPayloadMixin
 
+logger = logging.getLogger(__name__)
 
 # 转发规则已迁移至 ksadk.deployment.env_forward（hermes/openclaw deploy 共用）；
 # 保留私有别名以兼容既有调用与测试。
@@ -81,7 +67,7 @@ _CONTROL_PLANE_ONLY_ENV_KEYS = frozenset(
 @DeployProviderRegistry.register("serverless")
 @DeployProviderRegistry.register("kcf")
 @DeployProviderRegistry.register("kce")
-class ServerlessProvider(BaseDeployProvider):
+class ServerlessProvider(_ServerlessPayloadMixin, BaseDeployProvider):
     """金山云 Serverless 计算引擎 (AgentEngine Server 托管)
 
     重构后直接继承 BaseDeployProvider，不再依赖 DockerProvider。
@@ -99,68 +85,6 @@ class ServerlessProvider(BaseDeployProvider):
     def __init__(self, config: Optional[Dict[str, Any]] = None):
         self.config = config or {}
 
-    @staticmethod
-    def _image_credential_from_env(image_ref: str) -> Optional[Dict[str, str]]:
-        username, password, registry_kind = resolve_registry_credentials(image_ref)
-        if username and password:
-            return {
-                "endpoint": image_ref.split("/", 1)[0],
-                "username": username,
-                "password": password,
-            }
-
-        if password and not username and registry_kind != "personal_kcr":
-            click.secho(
-                f"   ⚠️  检测到 KCR_PASSWORD 但缺少 KCR_USERNAME，"
-                f"已忽略{registry_kind_label(registry_kind)}镜像凭证；"
-                "企业版 KCR 和第三方镜像仓库必须配置 KCR_USERNAME + KCR_PASSWORD",
-                fg="yellow",
-            )
-        elif registry_kind == "personal_kcr":
-            click.secho(
-                "   ⚠️  未配置个人版 KCR 镜像凭证 "
-                "(KSYUN_ACCOUNT_ID/KCR_PASSWORD)，私有镜像可能无法拉取",
-                fg="yellow",
-            )
-        else:
-            click.secho(
-                f"   ⚠️  未配置{registry_kind_label(registry_kind)}镜像凭证 "
-                "(KCR_USERNAME/KCR_PASSWORD)，私有镜像可能无法拉取",
-                fg="yellow",
-            )
-        return None
-
-    @staticmethod
-    def _parse_code_artifact_path(artifact_path: str) -> tuple[Optional[str], Optional[str]]:
-        """解析代码包路径，返回 (bucket, object_key)。"""
-        if not artifact_path:
-            return None, None
-
-        path = artifact_path.strip()
-        if not path:
-            return None, None
-
-        if path.startswith("ks3://"):
-            raw = path[6:]
-            parts = raw.split("/", 1)
-            bucket = parts[0].strip() if parts else ""
-            object_key = parts[1].strip() if len(parts) > 1 else ""
-            return bucket or None, object_key or None
-
-        if path.startswith("http://") or path.startswith("https://"):
-            from urllib.parse import urlparse
-
-            parsed = urlparse(path)
-            bucket = (parsed.netloc.split(".", 1)[0] if parsed.netloc else "").strip()
-            object_key = parsed.path.lstrip("/").strip()
-            return bucket or None, object_key or None
-
-        if "/" in path:
-            bucket, object_key = path.split("/", 1)
-            return bucket.strip() or None, object_key.strip() or None
-
-        return None, None
-
     @staticmethod
     def _load_project_env_vars(env_file: Path) -> Dict[str, str]:
         """读取项目 .env，并修正 UTF-8 BOM 导致的脏 key。"""
@@ -301,54 +225,6 @@ class ServerlessProvider(BaseDeployProvider):
     def _is_sha256_digest(value: str) -> bool:
         return len(value) == 64 and all(char in "0123456789abcdef" for char in value.lower())
 
-    @staticmethod
-    def _serialize_network_config(
-        target: DeployTarget, *, is_update: bool = False
-    ) -> Optional[Dict[str, Any]]:
-        network = getattr(target, "network", None)
-        if network is None:
-            return None
-
-        public_access = getattr(network, "enable_public_access", None)
-        # 三态：None=未指定。create 默认开公网；update 未指定则不发 network 字段。
-        if public_access is None:
-            public_value: Optional[bool] = None if is_update else True
-        else:
-            public_value = bool(public_access)
-
-        payload: Dict[str, Any] = {}
-        if public_value is not None:
-            payload["enable_public_access"] = public_value
-        if bool(getattr(network, "enable_vpc_access", False)):
-            payload["enable_vpc_access"] = True
-
-        for field in ("vpc_id", "subnet_id", "security_group_id", "availability_zone"):
-            value = str(getattr(network, field, "") or "").strip()
-            if value:
-                payload[field] = value
-
-        if not payload:
-            return None
-        return payload
-
-    @staticmethod
-    def _serialize_storage_config(target: DeployTarget) -> Optional[Dict[str, Any]]:
-        storage = getattr(target, "storage", None)
-        if storage is None:
-            return None
-
-        mount_path = str(getattr(storage, "mount_path", "") or "").strip()
-        size_gi = getattr(storage, "size_gi", None)
-        if not mount_path and size_gi is None:
-            return None
-
-        payload: Dict[str, Any] = {}
-        if mount_path:
-            payload["mount_path"] = mount_path
-        if size_gi is not None:
-            payload["size_gi"] = int(size_gi)
-        return payload
-
     @staticmethod
     def _format_elapsed(started_at: float) -> str:
         elapsed = max(0.0, time.monotonic() - started_at)
@@ -446,6 +322,10 @@ class ServerlessProvider(BaseDeployProvider):
             # 如果显式传入了 ks3-path，直接使用
             if cli_ks3_path:
                 package_info.metadata["ks3_path"] = cli_ks3_path
+                # A caller-provided URI may point at an old SDK ZIP.  Cached
+                # metadata belongs to the previous locally built object.
+                for field in ("code_checksum", "code_command", "code_kernel_contract_digest"):
+                    package_info.metadata.pop(field, None)
                 return package_info
 
             # 如果没有 no_cache 且有缓存，才使用缓存
@@ -498,6 +378,15 @@ class ServerlessProvider(BaseDeployProvider):
                 raise RuntimeError("代码构建成功但未生成 artifact_path")
             package_info.metadata.update(build_result.metadata)
             package_info.metadata["code_checksum"] = self._sha256_file(zip_path)
+            from ksadk.builders.code_builder import read_code_deployment_contract
+
+            declaration = read_code_deployment_contract(zip_path)
+            if declaration and declaration.get("schema") == "ksadk-code-deployment/v1":
+                package_info.metadata["code_command"] = declaration.get("command")
+                package_info.metadata["code_kernel_contract_digest"] = declaration.get("agentKernelContractDigest")
+            else:
+                package_info.metadata.pop("code_command", None)
+                package_info.metadata.pop("code_kernel_contract_digest", None)
             if build_result.metadata.get("manifest_sha256"):
                 target.extra["manifest_sha256"] = build_result.metadata["manifest_sha256"]
             # click.echo(f"   ✅ ZIP 已生成: {zip_path}")
@@ -753,7 +642,10 @@ class ServerlessProvider(BaseDeployProvider):
         code_checksum = str(package_info.metadata.get("code_checksum") or "").strip()
         if not self._is_sha256_digest(code_checksum):
             code_checksum = ""
-        code_command = list(_HOSTED_CODE_COMMAND) if code_backed and code_checksum else None
+        code_command = package_info.metadata.get("code_command") if code_backed and code_checksum else None
+        code_kernel_contract_digest = (
+            package_info.metadata.get("code_kernel_contract_digest") if code_backed and code_checksum else None
+        )
 
         try:
             # 获取 dry_run 标识
@@ -891,6 +783,8 @@ class ServerlessProvider(BaseDeployProvider):
                         if code_checksum:
                             update_data["code_checksum"] = code_checksum
                             update_data["code_command"] = code_command
+                            if code_kernel_contract_digest:
+                                update_data["agent_kernel_contract_digest"] = code_kernel_contract_digest
                         elif artifact_type == "Container":
                             image_credential = self._image_credential_from_env(artifact_path)
                             if image_credential:
@@ -901,6 +795,13 @@ class ServerlessProvider(BaseDeployProvider):
                                 )
                                 click.echo(f"   🔑 镜像凭证: {credential_target}")
 
+                        if target.extra.get("a2a_space_id"):
+                            update_data["component_config"] = {
+                                "A2ASpace": {"Id": target.extra["a2a_space_id"],
+                                    **({"RuntimeProfile": target.extra["a2a_runtime_profile"]}
+                                       if target.extra.get("a2a_runtime_profile") else {})}
+                            }
+
                         # 加载全局配置 + 本地 .env，并通过部署参数注入到运行时环境变量。
                         env_vars, env_file_exists, project_env_count = self._load_deploy_env_vars(
                             project_dir,
@@ -913,6 +814,12 @@ class ServerlessProvider(BaseDeployProvider):
                         env_vars = self._inject_ui_runtime_env(env_vars, ui_state, local_state)
                         if env_vars:
                             update_data["env_vars"] = env_vars
+                            # Hot updates must not replace platform-managed runtime
+                            # settings (for example durable session/A2A database
+                            # bindings) that are intentionally absent from the local
+                            # project environment.  The public client translates this
+                            # marker to UpdateAgent.EnvironmentVariablePatch.
+                            update_data["environment_variables_is_patch"] = True
                             if env_file_exists:
                                 click.echo(
                                     f"   📦 更新环境变量: {len(env_vars)} 项 "
@@ -980,7 +887,9 @@ class ServerlessProvider(BaseDeployProvider):
                             agent_id=existing_agent_id,
                             agent_name=res.get("name"),
                             endpoint=res.get("endpoint"),
-                            message=f"✅ Agent 已更新: {existing_agent_id}",
+                            message=(f"Agent 更新请求已提交，服务端将在后台执行: {existing_agent_id}"
+                                     if code_backed else f"✅ Agent 已更新: {existing_agent_id}"),
+                            metadata={"update_accepted": True} if code_backed else {},
                         )
                     # else: agent_exists = False，继续执行创建逻辑
 
@@ -1021,6 +930,8 @@ class ServerlessProvider(BaseDeployProvider):
                     if code_checksum:
                         request_data["code_checksum"] = code_checksum
                         request_data["code_command"] = code_command
+                        if code_kernel_contract_digest:
+                            request_data["agent_kernel_contract_digest"] = code_kernel_contract_digest
 
                     # Container 模式: 传递镜像凭证
                     if artifact_type == "Container":
@@ -1054,6 +965,13 @@ class ServerlessProvider(BaseDeployProvider):
                     if env_vars:
                         request_data["env_vars"] = env_vars
 
+                    if target.extra.get("a2a_space_id"):
+                        request_data["component_config"] = {
+                            "A2ASpace": {"Id": target.extra["a2a_space_id"],
+                                    **({"RuntimeProfile": target.extra["a2a_runtime_profile"]}
+                                       if target.extra.get("a2a_runtime_profile") else {})}
+                        }
+
                     network_config = self._serialize_network_config(target, is_update=False)
                     if network_config:
                         request_data["network"] = network_config
@@ -1181,8 +1099,16 @@ class ServerlessProvider(BaseDeployProvider):
         except Exception as e:
             logger.error(f"Deploy failed: {e}")
 
-            # 检测名称冲突
             err_msg = str(e)
+            # UpdateAgent also uses 409 when another update holds the Agent lock.
+            # Keep that response visible instead of suggesting a name change.
+            if "该 Agent 正在更新，请稍后重试" in err_msg:
+                return DeployResult(
+                    status=DeployStatus.FAILED,
+                    message="❌ 部署失败: 该 Agent 正在更新，请稍后重试",
+                )
+
+            # 检测名称冲突
             if "Conflict" in err_msg or "409" in err_msg or "already exists" in err_msg:
                 return DeployResult(
                     status=DeployStatus.FAILED,
@@ -1200,6 +1126,10 @@ class ServerlessProvider(BaseDeployProvider):
         try:
             async with AgentEngineClient(region=target.region, dry_run=dry_run) as client:
                 res = await client.get_agent(agent_id)
+                basic = res.get("basic") if isinstance(res.get("basic"), dict) else res
+                deployment = (
+                    res.get("deployment") if isinstance(res.get("deployment"), dict) else {}
+                )
 
                 status_map = {
                     "running": DeployStatus.RUNNING,
@@ -1214,13 +1144,23 @@ class ServerlessProvider(BaseDeployProvider):
                 }
 
                 # 使状态匹配不区分大小写，以兼容服务端的改动 (Creating -> CREATING)
-                current_status = (res.get("status") or "").lower()
+                current_status = (basic.get("status") or "").lower()
+                status = status_map.get(current_status, DeployStatus.UNKNOWN)
+                kernel_phase = deployment.get("deployment_phase")
+                if (
+                    status == DeployStatus.RUNNING
+                    and kernel_phase
+                    and deployment.get("agent_kernel_ready") is not True
+                ):
+                    status = DeployStatus.DEPLOYING
                 return DeployResult(
-                    status=status_map.get(current_status, DeployStatus.UNKNOWN),
-                    agent_id=res.get("agent_id"),
-                    agent_name=res.get("name"),
-                    endpoint=res.get("endpoint"),
-                    message=f"Status: {res.get('status')} ({res.get('phase')})",
+                    status=status,
+                    agent_id=basic.get("agent_id"),
+                    agent_name=basic.get("name"),
+                    endpoint=(res.get("quick_access") or {}).get("public_endpoint")
+                    or (res.get("quick_access") or {}).get("private_endpoint")
+                    or res.get("endpoint"),
+                    message=f"Status: {basic.get('status')} ({kernel_phase or basic.get('phase')})",
                 )
         except DryRunExit:
             return DeployResult(status=DeployStatus.SKIPPED, message="Dry Run executed.")

ksadk/deployment/providers/serverless_payloads.py

@@ -0,0 +1,122 @@
+"""Build serverless artifact, network, storage, and credential payloads."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import click
+
+from ksadk.builders.container_builder import registry_kind_label, resolve_registry_credentials
+from ksadk.deployment.base import DeployTarget
+
+
+class _ServerlessPayloadMixin:
+    @staticmethod
+    def _image_credential_from_env(image_ref: str) -> Optional[Dict[str, str]]:
+        username, password, registry_kind = resolve_registry_credentials(image_ref)
+        if username and password:
+            return {
+                "endpoint": image_ref.split("/", 1)[0],
+                "username": username,
+                "password": password,
+            }
+
+        if password and not username and registry_kind != "personal_kcr":
+            click.secho(
+                f"   ⚠️  检测到 KCR_PASSWORD 但缺少 KCR_USERNAME，"
+                f"已忽略{registry_kind_label(registry_kind)}镜像凭证；"
+                "企业版 KCR 和第三方镜像仓库必须配置 KCR_USERNAME + KCR_PASSWORD",
+                fg="yellow",
+            )
+        elif registry_kind == "personal_kcr":
+            click.secho(
+                "   ⚠️  未配置个人版 KCR 镜像凭证 "
+                "(KSYUN_ACCOUNT_ID/KCR_PASSWORD)，私有镜像可能无法拉取",
+                fg="yellow",
+            )
+        else:
+            click.secho(
+                f"   ⚠️  未配置{registry_kind_label(registry_kind)}镜像凭证 "
+                "(KCR_USERNAME/KCR_PASSWORD)，私有镜像可能无法拉取",
+                fg="yellow",
+            )
+        return None
+
+    @staticmethod
+    def _parse_code_artifact_path(artifact_path: str) -> tuple[Optional[str], Optional[str]]:
+        """解析代码包路径，返回 (bucket, object_key)。"""
+        if not artifact_path:
+            return None, None
+
+        path = artifact_path.strip()
+        if not path:
+            return None, None
+
+        if path.startswith("ks3://"):
+            raw = path[6:]
+            parts = raw.split("/", 1)
+            bucket = parts[0].strip() if parts else ""
+            object_key = parts[1].strip() if len(parts) > 1 else ""
+            return bucket or None, object_key or None
+
+        if path.startswith("http://") or path.startswith("https://"):
+            from urllib.parse import urlparse
+
+            parsed = urlparse(path)
+            bucket = (parsed.netloc.split(".", 1)[0] if parsed.netloc else "").strip()
+            object_key = parsed.path.lstrip("/").strip()
+            return bucket or None, object_key or None
+
+        if "/" in path:
+            bucket, object_key = path.split("/", 1)
+            return bucket.strip() or None, object_key.strip() or None
+
+        return None, None
+
+    @staticmethod
+    def _serialize_network_config(
+        target: DeployTarget, *, is_update: bool = False
+    ) -> Optional[Dict[str, Any]]:
+        network = getattr(target, "network", None)
+        if network is None:
+            return None
+
+        public_access = getattr(network, "enable_public_access", None)
+        # 三态：None=未指定。create 默认开公网；update 未指定则不发 network 字段。
+        if public_access is None:
+            public_value: Optional[bool] = None if is_update else True
+        else:
+            public_value = bool(public_access)
+
+        payload: Dict[str, Any] = {}
+        if public_value is not None:
+            payload["enable_public_access"] = public_value
+        if bool(getattr(network, "enable_vpc_access", False)):
+            payload["enable_vpc_access"] = True
+
+        for field in ("vpc_id", "subnet_id", "security_group_id", "availability_zone"):
+            value = str(getattr(network, field, "") or "").strip()
+            if value:
+                payload[field] = value
+
+        if not payload:
+            return None
+        return payload
+
+    @staticmethod
+    def _serialize_storage_config(target: DeployTarget) -> Optional[Dict[str, Any]]:
+        storage = getattr(target, "storage", None)
+        if storage is None:
+            return None
+
+        mount_path = str(getattr(storage, "mount_path", "") or "").strip()
+        size_gi = getattr(storage, "size_gi", None)
+        if not mount_path and size_gi is None:
+            return None
+
+        payload: Dict[str, Any] = {}
+        if mount_path:
+            payload["mount_path"] = mount_path
+        if size_gi is not None:
+            payload["size_gi"] = int(size_gi)
+        return payload

ksadk/evaluation/agent_eval_client.py

@@ -9,6 +9,7 @@ from typing import Any, Protocol
 
 import httpx
 
+from ksadk.common.cloud_headers import build_cloud_headers
 from ksadk.common.kop_client import KOPClient, KOPError
 
 from .cloud_converter import CloudDatasetColumn, CloudDatasetRow, CloudDatasetSnapshot
@@ -317,7 +318,7 @@ class AgentEvalCloudDatasetClient:
                 )
             return data
 
-        headers = {"Content-Type": "application/json"}
+        headers = build_cloud_headers({"Content-Type": "application/json"})
         if self._api_token:
             headers["Authorization"] = f"Bearer {self._api_token}"
         if self._account_id:

ksadk/evaluation/contracts.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from datetime import datetime, timezone
 from enum import Enum
+from pathlib import PurePosixPath
 from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field, model_validator
@@ -59,6 +60,24 @@ class AssertionType(str, Enum):
     RUNTIME_MAX_INPUT_TOKENS = "runtime.maxInputTokens"
     RUNTIME_MAX_OUTPUT_TOKENS = "runtime.maxOutputTokens"
     RUNTIME_MAX_TOTAL_TOKENS = "runtime.maxTotalTokens"
+    RUNTIME_MAX_TERMINAL_EVENTS_PER_SCOPE = "runtime.maxTerminalEventsPerScope"
+    RUNTIME_MAX_RETRIES = "runtime.maxRetries"
+    RUNTIME_MAX_COMPACTIONS = "runtime.maxCompactions"
+    RUNTIME_MAX_SUBAGENTS = "runtime.maxSubagents"
+    RUNTIME_MAX_TOOL_CALLS = "runtime.maxToolCalls"
+    RUNTIME_MAX_SKILL_DISCLOSURES = "runtime.maxSkillDisclosures"
+    RUNTIME_MAX_MCP_DISCLOSURES = "runtime.maxMcpDisclosures"
+    RUNTIME_MIN_RETRIES = "runtime.minRetries"
+    RUNTIME_MIN_COMPACTIONS = "runtime.minCompactions"
+    RUNTIME_MIN_SUBAGENTS = "runtime.minSubagents"
+    RUNTIME_MIN_MEMORY_RECALLS = "runtime.minMemoryRecalls"
+    RUNTIME_MIN_MEMORY_WRITES = "runtime.minMemoryWrites"
+    RUNTIME_MIN_SKILL_DISCLOSURES = "runtime.minSkillDisclosures"
+    RUNTIME_MIN_MCP_DISCLOSURES = "runtime.minMcpDisclosures"
+    ARTIFACT_FILE_EXISTS = "artifact.fileExists"
+    ARTIFACT_FILE_EQUALS = "artifact.fileEquals"
+    ARTIFACT_FILE_CONTAINS = "artifact.fileContains"
+    SESSION_SAME_ACROSS_TURNS = "session.sameAcrossTurns"
     TOOL_CALLED = "tool.called"
     TOOL_NOT_CALLED = "tool.notCalled"
     TOOL_SUCCEEDED = "tool.succeeded"
@@ -132,6 +151,21 @@ class AssertionSpec(EvaluationModel):
         if self.type is AssertionType.RESPONSE_JSON_SCHEMA:
             if not isinstance(self.value, dict):
                 raise ValueError("response.jsonSchema 的 value 必须是对象")
+        elif self.type is AssertionType.ARTIFACT_FILE_EXISTS:
+            _validate_workspace_path(self.value, assertion_type=self.type.value)
+        elif self.type in {
+            AssertionType.ARTIFACT_FILE_EQUALS,
+            AssertionType.ARTIFACT_FILE_CONTAINS,
+        }:
+            if not isinstance(self.value, dict) or set(self.value) != {"path", "content"}:
+                raise ValueError(f"{self.type.value} 的 value 必须只包含 path 和 content")
+            _validate_workspace_path(self.value.get("path"), assertion_type=self.type.value)
+            content = self.value.get("content")
+            if not isinstance(content, str) or len(content) > 1_048_576:
+                raise ValueError(f"{self.type.value} 的 content 必须是不超过 1 MiB 的字符串")
+        elif self.type is AssertionType.SESSION_SAME_ACROSS_TURNS:
+            if self.value is not True:
+                raise ValueError("session.sameAcrossTurns 的 value 必须是 true")
         elif self.type.value.startswith("runtime."):
             if isinstance(self.value, bool) or not isinstance(self.value, (int, float)):
                 raise ValueError(f"{self.type} 的 value 必须是非负数字")
@@ -149,6 +183,23 @@ class AssertionSpec(EvaluationModel):
         return self
 
 
+def _validate_workspace_path(value: Any, *, assertion_type: str) -> str:
+    if not isinstance(value, str) or not value.strip() or len(value) > 1024:
+        raise ValueError(f"{assertion_type} 的路径必须是 1..1024 字符的字符串")
+    path = value
+    parsed = PurePosixPath(path)
+    if (
+        path != path.strip()
+        or "\\" in path
+        or "\x00" in path
+        or parsed.is_absolute()
+        or parsed.as_posix() != path
+        or any(part in {"", ".", ".."} for part in parsed.parts)
+    ):
+        raise ValueError(f"{assertion_type} 的路径必须是工作区内的规范相对路径")
+    return path
+
+
 class EvalCase(EvaluationModel):
     """One evaluation case: ordered turns plus assertions to check."""
 
@@ -280,6 +331,7 @@ class EvaluationConfig(EvaluationModel):
     fail_fast: bool = False
     evaluators: list[str] = Field(default_factory=list)
     data_policy: DataPolicy = DataPolicy.LOCAL_ONLY
+    tool_approval_mode: Literal["ask", "risk", "full"] = "risk"
     judge_model: str | None = Field(default=None, min_length=1, max_length=256)
     judge_api_base: str | None = Field(default=None, min_length=1, max_length=2048)
     judge_api_key_env: str = Field(
@@ -366,6 +418,30 @@ class ToolCallEvidence(EvaluationModel):
     seq_end: int | None = Field(default=None, ge=1)
 
 
+class FileCheckEvidence(EvaluationModel):
+    """Content-free result of checking one declared workspace file assertion."""
+
+    assertion_type: Literal[
+        "artifact.fileExists",
+        "artifact.fileEquals",
+        "artifact.fileContains",
+    ]
+    path: str = Field(min_length=1, max_length=1024)
+    expected_digest: str | None = Field(default=None, pattern=r"^sha256:[0-9a-f]{64}$")
+    status: Literal[
+        "PRESENT",
+        "MATCH",
+        "MISMATCH",
+        "MISSING",
+        "NOT_FILE",
+        "TOO_LARGE",
+        "UNAVAILABLE",
+        "ERROR",
+    ]
+    actual_sha256: str | None = Field(default=None, pattern=r"^sha256:[0-9a-f]{64}$")
+    size_bytes: int | None = Field(default=None, ge=0)
+
+
 class TargetRun(EvaluationModel):
     """Normalized result returned by a target adapter for one case."""
 
@@ -378,6 +454,7 @@ class TargetRun(EvaluationModel):
     trace_ref: TraceRef | None = None
     trace_refs: list[TraceRef] = Field(default_factory=list)
     tool_calls: list[ToolCallEvidence] = Field(default_factory=list)
+    file_checks: list[FileCheckEvidence] = Field(default_factory=list)
     metadata: dict[str, Any] = Field(default_factory=dict)
 
 
@@ -439,9 +516,7 @@ class EvalRunReport(EvaluationModel):
         self.summary = self._summarize_cases()
         expected = self.compute_digest()
         if self.report_digest and self.report_digest != expected:
-            legacy_payload = self.model_dump(
-                mode="json", by_alias=False, exclude={"report_digest"}
-            )
+            legacy_payload = self.model_dump(mode="json", by_alias=False, exclude={"report_digest"})
             legacy_payload["spec"].pop("cloud_dataset", None)
             if self.spec.cloud_dataset is not None or self.report_digest != _content_digest(
                 legacy_payload