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

ksadk/studio/contracts.py

@@ -3,25 +3,36 @@
 from __future__ import annotations
 
 import re
+import hashlib
+import hmac
+import json
 from datetime import datetime, timezone
 from enum import Enum
 from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
+from ksadk.harness.spec import SubAgentBinding
 
-def _to_camel(value: str) -> str:
-    head, *tail = value.split("_")
-    return head + "".join(part.capitalize() for part in tail)
+from .lifecycle_status import (
+    BuildStatus as BuildStatus,
+)
+from .lifecycle_status import (
+    OperationKind as OperationKind,
+)
+from .lifecycle_status import (
+    OperationStatus as OperationStatus,
+)
+from .lifecycle_status import (
+    RunStatus as RunStatus,
+)
 
+from ksadk.studio.contract_base import ContractModel, _to_camel
 
-class ContractModel(BaseModel):
-    model_config = ConfigDict(
-        alias_generator=_to_camel,
-        populate_by_name=True,
-        extra="forbid",
-        use_enum_values=True,
-    )
+from ksadk.studio.agent_configuration import (ModelParameters, ModelSpec, RetryPolicy, ExecutionSpec, CompactionSpec, ContextContributorsSpec, RolloutSpec, ContextSpec, MemoryRecallSpec, MemoryWriteSpec, MemoryScope, _default_memory_scopes, MemorySpec, NetworkPolicy, SecuritySpec, EvaluationSpec)
+
+#: Anthropic Messages wire 的 API 版本头；探测与运行时必须保持一致。
+ANTHROPIC_VERSION = "2023-06-01"
 
 
 class DiagnosticSeverity(str, Enum):
@@ -65,35 +76,6 @@ class SoulDocument(ContractModel):
         return value
 
 
-class ModelParameters(ContractModel):
-    # 三者 None=未配置：请求 payload 一律不携带该字段，使用服务端默认，
-    # 规避各模型族对 temperature/max_tokens 的硬约束（如 kimi 只接受默认温度）。
-    temperature: float | None = Field(default=None, ge=0, le=2)
-    max_tokens: int | None = Field(default=None, ge=1, le=131072)
-    top_p: float | None = Field(default=None, gt=0, le=1)
-    # 是否允许在 chat 请求中携带 response_format（json_object 结构化输出）。
-    # 关闭后 compose 等结构化调用退回纯文本输出，兼容不支持该字段的网关。
-    allow_json_response_format: bool = Field(default=True)
-
-
-class ModelSpec(ContractModel):
-    provider: str = Field(default="openai-compatible", min_length=1, max_length=64)
-    model: str = Field(min_length=1, max_length=256)
-    endpoint_url: str | None = None
-    base_url: str | None = None
-    wire_api: Literal["chat", "responses"] | None = None
-    credential_ref: str = Field(min_length=1, max_length=512)
-    parameters: ModelParameters = Field(default_factory=ModelParameters)
-    metadata: dict[str, Any] = Field(default_factory=dict)
-    discovery: dict[str, Any] = Field(default_factory=dict)
-
-    @model_validator(mode="after")
-    def validate_address(self) -> "ModelSpec":
-        if bool(self.endpoint_url) == bool(self.base_url):
-            raise ValueError("endpointUrl 和 baseUrl 必须且只能配置一个")
-        return self
-
-
 class CapabilityRef(ContractModel):
     name: str = Field(min_length=1, max_length=128)
     version: str = Field(min_length=1, max_length=64)
@@ -160,6 +142,10 @@ class ToolContract(ContractModel):
     )
     permissions: list[str] = Field(default_factory=list)
     timeout_seconds: int = Field(default=20, ge=1, le=3600)
+    # Optional deterministic per-Run budget. The Managed Harness reserves one
+    # slot immediately before execution, so model retries and process restarts
+    # cannot bypass the limit.
+    max_calls_per_run: int | None = Field(default=None, ge=1, le=100_000)
     side_effect: Literal["none", "read", "write", "external"] = "none"
     approval: Literal["never", "always", "policy"] = "never"
     executor: Literal["builtin", "mcp", "deferred", "python"] = "builtin"
@@ -276,9 +262,109 @@ class NativePluginBinding(ContractModel):
         return self
 
 
+class RemoteAgentBinding(ContractModel):
+    """Immutable, credential-free Studio binding to one A2A version."""
+
+    model_config = ConfigDict(frozen=True)
+
+    binding_id: str = Field(pattern=r"^a2a-binding-[0-9a-f]{32}$")
+    space_id: str
+    target_agent_id: str
+    expected_version_id: str
+    local_name: str = Field(
+        min_length=1,
+        max_length=128,
+        pattern=r"^[A-Za-z_][A-Za-z0-9_]*$",
+    )
+    exposure: Literal["native", "tool", "auto"] = "auto"
+    policy_ref: str = Field(
+        min_length=10,
+        max_length=256,
+        pattern=r"^policy://[A-Za-z0-9][A-Za-z0-9._/-]*$",
+    )
+    digest: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+
+    @field_validator("space_id", "target_agent_id", "expected_version_id")
+    @classmethod
+    def validate_resource_id(cls, value: str, info) -> str:
+        # Studio contracts also load during core discovery startup. Managed
+        # runtime/database extras are needed only when an A2A binding is used.
+        from ksadk.a2a.ids import require_a2a_resource_id
+
+        prefix = {
+            "space_id": "a2a-space-",
+            "target_agent_id": "a2a-agent-",
+            "expected_version_id": "a2a-version-",
+        }[info.field_name]
+        return require_a2a_resource_id(value, prefix, field_name=info.field_name)
+
+    @staticmethod
+    def _canonical(payload: dict[str, Any]) -> bytes:
+        return json.dumps(
+            payload,
+            ensure_ascii=False,
+            sort_keys=True,
+            separators=(",", ":"),
+        ).encode("utf-8")
+
+    @classmethod
+    def freeze(
+        cls,
+        *,
+        space_id: str,
+        target_agent_id: str,
+        expected_version_id: str,
+        local_name: str,
+        exposure: Literal["native", "tool", "auto"] = "auto",
+        policy_ref: str,
+        binding_id: str | None = None,
+    ) -> "RemoteAgentBinding":
+        identity = {
+            "localName": local_name,
+            "spaceId": space_id,
+            "targetAgentId": target_agent_id,
+        }
+        frozen_binding_id = binding_id or (
+            "a2a-binding-" + hashlib.sha256(cls._canonical(identity)).hexdigest()[:32]
+        )
+        payload = {
+            "bindingId": frozen_binding_id,
+            "spaceId": space_id,
+            "targetAgentId": target_agent_id,
+            "expectedVersionId": expected_version_id,
+            "localName": local_name,
+            "exposure": exposure,
+            "policyRef": policy_ref,
+        }
+        return cls(
+            **payload,
+            digest="sha256:" + hashlib.sha256(cls._canonical(payload)).hexdigest(),
+        )
+
+    @model_validator(mode="after")
+    def validate_digest(self) -> "RemoteAgentBinding":
+        payload = self.model_dump(
+            by_alias=True,
+            exclude={"digest"},
+            mode="json",
+        )
+        expected = "sha256:" + hashlib.sha256(self._canonical(payload)).hexdigest()
+        if not hmac.compare_digest(self.digest, expected):
+            raise ValueError("A2A_BINDING_DIGEST_MISMATCH")
+        return self
+
+
 class AgentBindings(ContractModel):
+    remote_agents: list[RemoteAgentBinding] = Field(default_factory=list)
     model_profile_id: str | None = None
     model_profile_ids: list[str] = Field(default_factory=list)
+    # Optional image-capable model for browser observations. This is a
+    # separate locked role, never a fallback for the main Agent model.
+    vision_model_profile_id: str | None = Field(default=None, min_length=1)
+    # ``strict`` preserves the model selected for a turn.  ``automatic``
+    # permits the additional bound profiles to be compiled as an ordered
+    # availability fallback chain.
+    model_failover_mode: Literal["strict", "automatic"] = "strict"
     model_parameters: ModelParameters | None = None
     policy_template: Literal["loose", "strict", "custom"] = "strict"
     tools: list[CapabilityBinding] = Field(default_factory=list)
@@ -298,6 +384,15 @@ class AgentBindings(ContractModel):
             and self.model_profile_id not in self.model_profile_ids
         ):
             raise ValueError("默认 modelProfileId 必须包含在 modelProfileIds 中")
+        names = [binding.local_name for binding in self.remote_agents]
+        if len(names) != len(set(names)):
+            raise ValueError("remoteAgents localName must be unique")
+        targets = [binding.target_agent_id for binding in self.remote_agents]
+        if len(targets) != len(set(targets)):
+            raise ValueError("A2A_EXPOSURE_CONFLICT")
+        ids = [binding.binding_id for binding in self.remote_agents]
+        if len(ids) != len(set(ids)):
+            raise ValueError("remoteAgents bindingId must be unique")
         plugin_refs = [binding.plugin_ref for binding in self.plugins if binding.enabled]
         if len(plugin_refs) != len(set(plugin_refs)):
             raise ValueError("启用的插件绑定不能重复 pluginRef")
@@ -313,126 +408,6 @@ class CapabilitiesSpec(ContractModel):
     tools: list[ToolContract] = Field(default_factory=list)
 
 
-class RetryPolicy(ContractModel):
-    max_attempts: int = Field(default=2, ge=1, le=10)
-    backoff_seconds: float = Field(default=1, ge=0, le=60)
-
-
-class ExecutionSpec(ContractModel):
-    strategy: Literal["direct", "plan-act-observe"] = "direct"
-    max_steps: int = Field(default=12, ge=1, le=100)
-    timeout_seconds: int = Field(default=120, ge=1, le=3600)
-    retry: RetryPolicy = Field(default_factory=RetryPolicy)
-    sandbox: str | None = None
-    approval_mode: str | None = None
-
-
-class CompactionSpec(ContractModel):
-    enabled: bool = True
-    threshold_ratio: float = Field(default=0.8, gt=0, le=1)
-    # PCM：双阈值（方案 §8.2 / §9.1）。soft=主动整理，hard=强制压缩。
-    soft_threshold_ratio: float = Field(default=0.50, gt=0, le=1)
-    hard_threshold_ratio: float = Field(default=0.85, gt=0, le=1)
-    preserve_working_state: bool = True
-    flush_memory_before_compaction: bool = True
-
-    @model_validator(mode="after")
-    def validate_ratios(self) -> "CompactionSpec":
-        if self.soft_threshold_ratio >= self.hard_threshold_ratio:
-            raise ValueError("softThresholdRatio 必须小于 hardThresholdRatio")
-        return self
-
-
-class ContextContributorsSpec(ContractModel):
-    """ContextContributor 开关与预算（方案 §5.1 / §8.7）。默认按 policy，可显式开关。"""
-
-    workspace_rules: bool | None = None
-    skill_manifest: bool | None = None
-    memory_recall: bool | None = None
-
-
-class RolloutSpec(ContractModel):
-    """AgentVersion 级灰度/回退状态（方案 §8.5）。替代环境变量控制正式灰度。"""
-
-    context_engine: Literal["off", "shadow", "enabled"] = "shadow"
-    memory_write: Literal["off", "shadow", "enabled"] = "shadow"
-
-
-class ContextSpec(ContractModel):
-    max_input_tokens: int = Field(default=32000, ge=1024)
-    reserve_output_tokens: int = Field(default=4096, ge=1)
-    compaction: CompactionSpec = Field(default_factory=CompactionSpec)
-    # prompt_ownership：标记本 Agent 的 system prompt 归属。
-    # framework（默认）= 框架自带 SystemMessage，ksadk 不接管 Runner 输入；
-    # ksadk = 由 ksadk 的 PromptCompiler 编译 CompiledPrompt 并接管 instructions。
-    prompt_ownership: Literal["framework", "ksadk"] = "framework"
-    # PCM：ownership 高阶字段（方案 §5.1）。auto=按 capability 推导，向后兼容现有
-    # prompt_ownership；显式 ksadk/framework/native 时覆盖。Studio 据 capability 限制选项。
-    ownership: Literal["auto", "ksadk", "framework", "native"] = "auto"
-    tokenizer: Literal["auto", "heuristic"] = "auto"
-    policy_version: str = Field(default="context-v2", max_length=64)
-    contributors: ContextContributorsSpec = Field(default_factory=ContextContributorsSpec)
-    rollout: RolloutSpec = Field(default_factory=RolloutSpec)
-
-    @model_validator(mode="after")
-    def validate_budget(self) -> "ContextSpec":
-        if self.reserve_output_tokens >= self.max_input_tokens:
-            raise ValueError("reserveOutputTokens 必须小于 maxInputTokens")
-        # ownership 与 prompt_ownership 一致性：显式 ownership 收窄 prompt_ownership（§5.2）。
-        if self.ownership == "ksadk":
-            self.prompt_ownership = "ksadk"
-        elif self.ownership == "framework":
-            self.prompt_ownership = "framework"
-        # native 不收窄 prompt_ownership（native runtime 的 prompt 投影由 Adapter 决定）。
-        return self
-
-
-class MemoryRecallSpec(ContractModel):
-    enabled: bool = True
-    max_tokens: int = Field(default=1600, ge=0)
-    top_k: int = Field(default=8, ge=1, le=64)
-    min_score: float = Field(default=0.45, ge=0, le=1)
-
-
-class MemoryWriteSpec(ContractModel):
-    mode: Literal["off", "explicit_only", "candidate"] = "candidate"
-    flush_before_compaction: bool = True
-
-
-MemoryScope = Literal["tenant", "workspace", "agent", "user"]
-
-
-def _default_memory_scopes() -> list[MemoryScope]:
-    return ["workspace", "agent", "user"]
-
-
-class MemorySpec(ContractModel):
-    """AgentVersion 级 Memory 策略（方案 §5.1 / §10）。Build 只存 providerRef，不存凭证。"""
-
-    enabled: bool = False
-    provider_ref: str = Field(default="local-default", max_length=128)
-    recall: MemoryRecallSpec = Field(default_factory=MemoryRecallSpec)
-    write: MemoryWriteSpec = Field(default_factory=MemoryWriteSpec)
-    scopes: list[MemoryScope] = Field(default_factory=_default_memory_scopes)
-
-
-class NetworkPolicy(ContractModel):
-    mode: Literal["restricted", "open"] = "restricted"
-    allowed_hosts: list[str] = Field(default_factory=list)
-    allow_private_network: bool = False
-
-
-class SecuritySpec(ContractModel):
-    tool_policy: Literal["deny-by-default", "allow-listed"] = "deny-by-default"
-    allowed_permissions: list[str] = Field(default_factory=list)
-    network: NetworkPolicy = Field(default_factory=NetworkPolicy)
-
-
-class EvaluationSpec(ContractModel):
-    suite_refs: list[str] = Field(default_factory=list)
-    minimum_pass_rate: float = Field(default=1, ge=0, le=1)
-
-
 class RuntimeRef(ContractModel):
     """Per-Agent reference to one registered RuntimeAdapter implementation.
 
@@ -527,7 +502,68 @@ def _reject_clear_runtime_secrets(value: Any, *, path: str = "providerConfig") -
             _reject_clear_runtime_secrets(child, path=f"{path}[{index}]")
 
 
+class A2ADesignNode(ContractModel):
+    node_id: str = Field(pattern=r"^[A-Za-z_][A-Za-z0-9_]{0,127}$")
+    kind: Literal["local", "remote"]
+    binding_id: str | None = None
+
+    @model_validator(mode="after")
+    def validate_binding(self):
+        if (self.kind == "remote") != (self.binding_id is not None):
+            raise ValueError("A2A_NODE_BINDING_REQUIRED")
+        return self
+
+
+class A2ADesignEdge(ContractModel):
+    source: str
+    target: str
+    kind: Literal["sequential", "handoff"]
+
+
+class A2AOrchestration(ContractModel):
+    entry_node_id: str
+    nodes: tuple[A2ADesignNode, ...] = Field(min_length=1, max_length=64)
+    edges: tuple[A2ADesignEdge, ...] = Field(default=(), max_length=63)
+
+    @model_validator(mode="after")
+    def validate_graph(self):
+        ids = {node.node_id for node in self.nodes}
+        if len(ids) != len(self.nodes) or self.entry_node_id not in ids:
+            raise ValueError("A2A_NODE_ID_INVALID")
+        incoming: dict[str, int] = {}
+        outgoing: dict[str, list[str]] = {key: [] for key in ids}
+        sequential_sources: set[str] = set()
+        for edge in self.edges:
+            if edge.source not in ids or edge.target not in ids:
+                raise ValueError("A2A_EDGE_NODE_MISSING")
+            incoming[edge.target] = incoming.get(edge.target, 0) + 1
+            if incoming[edge.target] > 1:
+                raise ValueError("A2A_MULTIPLE_INCOMING_UNSUPPORTED")
+            if edge.kind == "sequential":
+                if edge.source in sequential_sources:
+                    raise ValueError("A2A_PARALLEL_UNSUPPORTED")
+                sequential_sources.add(edge.source)
+            outgoing[edge.source].append(edge.target)
+        visited, visiting = set(), set()
+        def visit(node):
+            if node in visiting:
+                raise ValueError("A2A_LOOP_UNSUPPORTED")
+            if node in visited:
+                return
+            visiting.add(node)
+            for target in outgoing[node]:
+                visit(target)
+            visiting.remove(node)
+            visited.add(node)
+        for node in ids:
+            visit(node)
+        if self.entry_node_id in incoming:
+            raise ValueError("A2A_ENTRY_HAS_INCOMING")
+        return self
+
+
 class AgentSpec(ContractModel):
+    a2a_orchestration: A2AOrchestration | None = None
     description: str = Field(default="", max_length=1024)
     runtime: RuntimeRef | None = None
     instructions: Instructions = Field(default_factory=Instructions)
@@ -540,6 +576,31 @@ class AgentSpec(ContractModel):
     memory: MemorySpec = Field(default_factory=MemorySpec)
     security: SecuritySpec = Field(default_factory=SecuritySpec)
     evaluation: EvaluationSpec = Field(default_factory=EvaluationSpec)
+    sub_agents: tuple[SubAgentBinding, ...] = Field(default=(), max_length=32)
+
+    @model_validator(mode="after")
+    def validate_sub_agents(self) -> "AgentSpec":
+        if self.execution.approval_timeout_seconds is not None and (
+            self.runtime is None or self.runtime.type != "harness"
+        ):
+            raise ValueError("approvalTimeoutSeconds 当前仅支持 Harness Runtime")
+        if not self.sub_agents:
+            return self
+        if self.runtime is not None and self.runtime.type != "harness":
+            raise ValueError("subAgents 当前需要 Harness Runtime")
+        names = {sub.name for sub in self.sub_agents}
+        if len(names) != len(self.sub_agents):
+            raise ValueError("subAgents 名称不能重复")
+        dependencies = {sub.name: set(sub.depends_on) for sub in self.sub_agents}
+        if any(deps - names for deps in dependencies.values()):
+            raise ValueError("subAgents dependsOn 引用了未声明的子 Agent")
+        resolved: set[str] = set()
+        while len(resolved) < len(names):
+            ready = {name for name, deps in dependencies.items() if deps <= resolved} - resolved
+            if not ready:
+                raise ValueError("subAgents dependsOn 存在依赖环")
+            resolved.update(ready)
+        return self
 
     @model_validator(mode="after")
     def validate_memory_resource_reference(self) -> "AgentSpec":
@@ -623,8 +684,9 @@ class AgentTemplateComposeRequest(ContractModel):
     mcp_resource_ids: list[str] = Field(default_factory=list)
     policy_template: Literal["loose", "strict", "custom"] = "strict"
     execution_strategy: Literal["direct", "plan-act-observe"] = "direct"
-    max_steps: int = Field(default=12, ge=1, le=100)
-    timeout_seconds: int = Field(default=120, ge=1, le=3600)
+    # Kept wire-compatible with ExecutionSpec; see its compatibility note.
+    max_steps: int = Field(default=25, ge=1)
+    timeout_seconds: int = Field(default=300, ge=1, le=3600)
     auto_bind_tools: bool = True
     auto_bind_mcp: bool = True
 
@@ -671,6 +733,8 @@ class ResolvedModel(ContractModel):
     credential_ref: str
     parameters: ModelParameters
     wire_api: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    discovery: dict[str, Any] = Field(default_factory=dict)
 
 
 class ResolvedCapabilities(ContractModel):
@@ -680,6 +744,8 @@ class ResolvedCapabilities(ContractModel):
 
 
 class ResolvedAgentSpec(ContractModel):
+    a2a_orchestration: dict[str, Any] | None = None
+    remote_agents: list[RemoteAgentBinding] = Field(default_factory=list)
     schema_version: Literal["agentkit.resolved/v1"] = "agentkit.resolved/v1"
     agent_id: str
     source_revision: int
@@ -687,12 +753,19 @@ class ResolvedAgentSpec(ContractModel):
     instructions: Instructions
     soul: SoulDocument | None = None
     model: ResolvedModel
+    vision_model: ResolvedModel | None = None
+    # ``model`` is the selected primary.  Additional bound Model Profiles are
+    # retained for user-initiated switching; they become a runtime failover
+    # chain only when ``model_failover_mode`` explicitly requests it.
+    fallback_models: list[ResolvedModel] = Field(default_factory=list, max_length=4)
+    model_failover_mode: Literal["strict", "automatic"] = "strict"
     capabilities: ResolvedCapabilities
     execution: ExecutionSpec
     context: ContextSpec
     memory: MemorySpec
     security: SecuritySpec
     evaluation: EvaluationSpec
+    sub_agents: tuple[SubAgentBinding, ...] = Field(default=(), max_length=32)
     source_digest: str
     resolved_digest: str = ""
 
@@ -703,18 +776,6 @@ class ValidationResult(ContractModel):
     diagnostics: list[Diagnostic] = Field(default_factory=list)
 
 
-class BuildStatus(str, Enum):
-    QUEUED = "QUEUED"
-    VALIDATING = "VALIDATING"
-    RESOLVING = "RESOLVING"
-    COMPILING = "COMPILING"
-    PACKAGING = "PACKAGING"
-    SUCCEEDED = "SUCCEEDED"
-    FAILED = "FAILED"
-    CANCELLED = "CANCELLED"
-    INTERRUPTED = "INTERRUPTED"
-
-
 class FileEntry(ContractModel):
     path: str
     sha256: str
@@ -779,12 +840,14 @@ class BundleManifest(ContractModel):
 
 
 # ``BundleManifest`` is the existing, installed source type.  The explicit
-# name documents that its ``agentkit.bundle/v2`` branch is the Phase 2
+# name documents that its ``agentkit.bundle/v2`` branch is the Release
 # AgentBundleManifest/v2 contract; it is an alias, not a parallel manifest.
 AgentBundleManifest = BundleManifest
 
 
 class BuildRecord(ContractModel):
+    a2a_orchestration_digest: str | None = Field(default=None, pattern=r"^sha256:[0-9a-f]{64}$")
+    a2a_binding_digest: str | None = Field(default=None, pattern=r"^sha256:[0-9a-f]{64}$")
     id: str
     agent_id: str
     source_revision: int
@@ -808,22 +871,6 @@ class BuildRecord(ContractModel):
     completed_at: datetime | None = None
 
 
-class OperationKind(str, Enum):
-    BUILD = "BUILD"
-    RUN = "RUN"
-    EVALUATION = "EVALUATION"
-    DEPLOYMENT = "DEPLOYMENT"
-
-
-class OperationStatus(str, Enum):
-    QUEUED = "QUEUED"
-    RUNNING = "RUNNING"
-    SUCCEEDED = "SUCCEEDED"
-    FAILED = "FAILED"
-    CANCELLED = "CANCELLED"
-    INTERRUPTED = "INTERRUPTED"
-
-
 class Operation(ContractModel):
     id: str
     kind: OperationKind
@@ -843,18 +890,6 @@ class OperationEvent(ContractModel):
     created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
 
 
-class RunStatus(str, Enum):
-    CREATED = "CREATED"
-    RUNNING = "RUNNING"
-    PAUSED = "PAUSED"
-    WAITING_INPUT = "WAITING_INPUT"
-    COMPLETED = "COMPLETED"
-    FAILED = "FAILED"
-    CANCELLED = "CANCELLED"
-    INTERRUPTED = "INTERRUPTED"
-    TIMED_OUT = "TIMED_OUT"
-
-
 class Usage(ContractModel):
     input_tokens: int = Field(default=0, ge=0)
     output_tokens: int = Field(default=0, ge=0)
@@ -865,19 +900,42 @@ class Usage(ContractModel):
     source: str | None = None
 
 
+class NativeRunOptions(ContractModel):
+    """Host-admitted selections required to rebuild the same Native activation."""
+
+    tool_approval_mode: Literal["ask", "risk", "full"] | None = None
+    reasoning_effort: Literal["low", "medium", "high"] | None = None
+
+
+class RunSubmissionRef(ContractModel):
+    """Transport correlation, validated against the admitted Agent and Session."""
+
+    model_config = ConfigDict(frozen=True)
+
+    client_invocation_id: str = Field(min_length=1, max_length=256)
+    agent_id: str = Field(min_length=1)
+    session_id: str = Field(min_length=1)
+
+
 class RunRecord(ContractModel):
     id: str
     build_id: str
     agent_id: str
     session_id: str
     trace_id: str
+    submission_ref: RunSubmissionRef | None = None
     manifest_sha256: str = ""
     runtime_type: str = ""
     model: str = ""
     collaboration_mode: str = ""
     goal_objective: str = ""
+    presentation_profile: Literal["flat-v1", "agent-block-v1"] = "flat-v1"
     runtime_handle: dict[str, Any] = Field(default_factory=dict)
+    native_runtime_options: NativeRunOptions | None = None
     status: RunStatus = RunStatus.CREATED
+    # Native completion evidence is separate from scheduler termination.
+    # A completed run can still be unverified or only partially accepted.
+    verification_outcome: Literal["verified", "unverified", "partial", "blocked"] | None = None
     input: str
     output: str = ""
     usage: Usage = Field(default_factory=Usage)