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

ksadk/harness/observability/otel_exporter.py

@@ -0,0 +1,218 @@
+"""RuntimeEvent → OpenTelemetry Span 适配 + OTLP 导出（plan §13 / 方案 P0）。
+
+在 RuntimeEvent 事件流之上加 OTel Span 适配层，不改 RuntimeEvent 契约。
+按 ``KSADK_OTEL_ENDPOINT`` 环境变量开关；无配置时不导出（零侵入）。
+
+Span 层级映射（plan §13.1 事件层级）::
+
+    Run     → root Span
+    Turn    → child Span of Run
+    Model   → child Span of Turn
+    Tool    → child Span of Turn
+    Context → child Span of Turn（compaction/planned）
+    Approval→ child Span of Turn
+    Memory  → child Span of Turn
+
+成对事件（started/completed）由 Span 自动计时；单次事件（delta/usage）记为
+Span 事件（OTel Event，非 Span）。Tool Call begin/end 成对包裹。
+
+配置::
+
+    KSADK_OTEL_ENDPOINT=http://otel-collector:4318/v1/traces
+    KSADK_OTEL_SERVICE_NAME=ksadk-harness  (默认)
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from ksadk.harness.events import EventType, RuntimeEvent
+
+#: 事件 → OTel Span 名映射（started 事件创建 Span，completed/failed 结束）。
+_SPAN_EVENTS: dict[str, str] = {
+    EventType.RUN_STARTED: "harness.run",
+    EventType.TURN_STARTED: "harness.turn",
+    EventType.MODEL_CALL_STARTED: "harness.model_call",
+    EventType.TOOL_CALL_BEGIN: "harness.tool_call",
+    EventType.CONTEXT_COMPACTION_STARTED: "harness.compaction",
+    EventType.CHECKPOINT_CREATED: "harness.checkpoint",
+}
+
+#: started 事件 → 对应的结束事件（completed/failed/end/canceled）。
+_SPAN_END_EVENTS: dict[str, set[str]] = {
+    EventType.RUN_STARTED: {
+        EventType.RUN_COMPLETED,
+        EventType.RUN_FAILED,
+        EventType.RUN_CANCELED,
+    },
+    EventType.TURN_STARTED: {EventType.TURN_COMPLETED},
+    EventType.MODEL_CALL_STARTED: {
+        EventType.MODEL_CALL_COMPLETED,
+        EventType.MODEL_CALL_FAILED,
+    },
+    EventType.TOOL_CALL_BEGIN: {EventType.TOOL_CALL_END},
+    EventType.CONTEXT_COMPACTION_STARTED: {EventType.CONTEXT_COMPACTION_COMPLETED},
+}
+
+
+class OTelSpanAdapter:
+    """把 RuntimeEvent 流适配为 OpenTelemetry Span。
+
+    用法：引擎在 stream 事件时调 :meth:`on_event`；适配器内部维护 Span 栈，
+    started 事件创建 Span，结束事件结束 Span。
+
+    无 ``KSADK_OTEL_ENDPOINT`` 时为 no-op（不创建 TracerProvider）。
+    """
+
+    def __init__(
+        self,
+        *,
+        endpoint: str | None = None,
+        service_name: str = "ksadk-harness",
+    ) -> None:
+        self._endpoint = endpoint or os.getenv("KSADK_OTEL_ENDPOINT", "")
+        self._service_name = os.getenv("KSADK_OTEL_SERVICE_NAME", service_name)
+        self._tracer: Any | None = None
+        self._provider: Any | None = None
+        self._spans: dict[str, Any] = {}  # span_key → Span
+        self._span_counter: int = 0
+        if self._endpoint:
+            self._setup_otel()
+
+    def _setup_otel(self) -> None:
+        """初始化 OTel TracerProvider + OTLP HTTP exporter。"""
+        from opentelemetry import trace
+        from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+        from opentelemetry.sdk.resources import Resource
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+        resource = Resource.create({"service.name": self._service_name})
+        provider = TracerProvider(resource=resource)
+        exporter = OTLPSpanExporter(endpoint=self._endpoint)
+        provider.add_span_processor(BatchSpanProcessor(exporter))
+        trace.set_tracer_provider(provider)
+        self._provider = provider
+        self._tracer = trace.get_tracer("ksadk.harness")
+
+    @property
+    def enabled(self) -> bool:
+        return self._tracer is not None
+
+    def on_event(self, event: RuntimeEvent) -> None:
+        """处理一个 RuntimeEvent——创建/结束对应 OTel Span。"""
+        if not self._tracer:
+            return
+
+        et = event.event_type
+
+        # started 事件 → 创建 Span
+        if et in _SPAN_EVENTS:
+            span_name = _SPAN_EVENTS[et]
+            span_key = self._span_key(event, et)
+            if span_key in self._spans:
+                return  # 已存在（重复 started，不重复创建）
+            parent_key = self._parent_key(event, et)
+            parent_span = self._spans.get(parent_key) if parent_key else None
+            context = parent_span.set_span_on_parent() if parent_span else None
+            span = self._tracer.start_span(
+                span_name,
+                context=context,
+                attributes=self._attributes(event),
+            )
+            self._spans[span_key] = span
+            return
+
+        # 结束事件 → 结束对应 Span
+        for started_et, end_events in _SPAN_END_EVENTS.items():
+            if et in end_events:
+                span_key = self._span_key(event, started_et)
+                span = self._spans.pop(span_key, None)
+                if span:
+                    if et.endswith(".failed") or et.endswith(".canceled"):
+                        span.set_attribute("otel.status_code", "ERROR")
+                        span.set_attribute(
+                            "error.message", str(event.payload.get("error") or "")
+                        )
+                    else:
+                        span.set_attribute("otel.status_code", "OK")
+                    span.end()
+                return
+
+        # 单次事件 → 记为 Span Event（非新 Span）
+        if self._spans:
+            turn_key = self._span_key(event, EventType.TURN_STARTED)
+            span = self._spans.get(turn_key) or self._spans.get(
+                self._span_key(event, EventType.RUN_STARTED)
+            )
+            if span:
+                span.add_event(
+                    et,
+                    attributes={
+                        k: str(v) for k, v in event.payload.items() if v is not None
+                    },
+                )
+
+    def flush(self) -> None:
+        """强制刷新所有待导出的 Span（进程退出前调）。"""
+        if self._provider:
+            try:
+                self._provider.force_flush()
+            except Exception:  # noqa: BLE001 - 导出失败不阻断主流程
+                pass
+
+    def shutdown(self) -> None:
+        """关闭 TracerProvider。"""
+        if self._provider:
+            try:
+                self._provider.shutdown()
+            except Exception:  # noqa: BLE001
+                pass
+            self._provider = None
+            self._tracer = None
+
+    # ---- helpers ----
+
+    def _span_key(self, event: RuntimeEvent, started_et: str) -> str:
+        """Span 唯一键：run_id + started_event_type + call_id/tool_id。"""
+        run_id = event.run_id or event.invocation_id
+        extra = ""
+        if started_et == EventType.TOOL_CALL_BEGIN:
+            extra = f":{event.payload.get('call_id', '')}"
+        elif started_et == EventType.MODEL_CALL_STARTED:
+            extra = f":{event.payload.get('attempt', '')}"
+        return f"{run_id}:{started_et}{extra}"
+
+    def _parent_key(self, event: RuntimeEvent, started_et: str) -> str | None:
+        """Span 父键：Turn/Tool 的父是 Run/Turn。"""
+        run_id = event.run_id or event.invocation_id
+        if started_et == EventType.TURN_STARTED:
+            return f"{run_id}:{EventType.RUN_STARTED}"
+        if started_et in (
+            EventType.MODEL_CALL_STARTED,
+            EventType.TOOL_CALL_BEGIN,
+            EventType.CONTEXT_COMPACTION_STARTED,
+        ):
+            return f"{run_id}:{EventType.TURN_STARTED}"
+        return None
+
+    @staticmethod
+    def _attributes(event: RuntimeEvent) -> dict[str, Any]:
+        """从 RuntimeEvent 提取 OTel Span 属性。"""
+        attrs: dict[str, Any] = {
+            "harness.event_type": event.event_type,
+            "harness.agent_id": event.agent_id,
+            "harness.session_id": event.session_id,
+            "harness.run_id": event.run_id or event.invocation_id,
+            "harness.seq_id": event.seq_id,
+        }
+        if event.phase:
+            attrs["harness.phase"] = event.phase
+        for key, value in event.payload.items():
+            if value is not None and isinstance(value, (str, int, float, bool)):
+                attrs[f"harness.payload.{key}"] = value
+        return attrs
+
+
+__all__ = ["OTelSpanAdapter"]

ksadk/harness/prompt_cache.py

@@ -0,0 +1,70 @@
+"""Prompt Cache 边界诊断（只记录 Hash，不持久化 Prompt 正文）。"""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class PromptCacheDiagnostic:
+    """一次稳定 Prompt 前缀观察结果。"""
+
+    stable_prompt_hash: str
+    previous_stable_prompt_hash: str
+    cache_break: bool
+    reason: str
+
+    def to_payload(self) -> dict[str, str | bool]:
+        return {
+            "stable_prompt_hash": self.stable_prompt_hash,
+            "previous_stable_prompt_hash": self.previous_stable_prompt_hash,
+            "cache_break": self.cache_break,
+            "reason": self.reason,
+        }
+
+
+class PromptCacheTracker:
+    """进程内有界诊断器。
+
+    Provider 的真实缓存命中仍以 ``usage.reported.cached_tokens`` 为准；本类只
+    判断 KsADK 稳定 Prompt 合同是否发生变化。LRU 有界，重启后首个观察记为
+    ``cold_start``，不会把本地缓存状态伪装成云端事实。
+    """
+
+    def __init__(self, *, max_scopes: int = 1024) -> None:
+        if max_scopes < 1:
+            raise ValueError("max_scopes 必须为正整数")
+        self._max_scopes = max_scopes
+        self._hashes: OrderedDict[str, str] = OrderedDict()
+
+    def observe(self, *, scope: str, stable_prompt_hash: str) -> PromptCacheDiagnostic:
+        current = stable_prompt_hash.strip()
+        previous = self._hashes.pop(scope, "")
+        if current:
+            self._hashes[scope] = current
+            while len(self._hashes) > self._max_scopes:
+                self._hashes.popitem(last=False)
+
+        if not current:
+            return PromptCacheDiagnostic(
+                stable_prompt_hash="",
+                previous_stable_prompt_hash=previous,
+                cache_break=False,
+                reason="stable_prompt_unavailable",
+            )
+        if not previous:
+            reason, cache_break = "cold_start", False
+        elif previous == current:
+            reason, cache_break = "stable_prompt_reused", False
+        else:
+            reason, cache_break = "stable_prompt_changed", True
+        return PromptCacheDiagnostic(
+            stable_prompt_hash=current,
+            previous_stable_prompt_hash=previous,
+            cache_break=cache_break,
+            reason=reason,
+        )
+
+
+__all__ = ["PromptCacheDiagnostic", "PromptCacheTracker"]

ksadk/harness/public_activity.py

@@ -0,0 +1,154 @@
+"""Small, display-safe facts about actions, never a copy of tool arguments."""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+import shlex
+from pathlib import PurePosixPath
+from typing import Any
+from urllib.parse import urlsplit, urlunsplit
+
+_SENSITIVE = re.compile(
+    r"(?i)(?:api[_ -]?key|secret|password|passwd|authorization|bearer|token|"
+    r"sk-[a-z0-9]|[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})"
+)
+_SECRET_VALUE = re.compile(
+    r"(?i)(?:\b(?:api[_ -]?key|secret|password|passwd|authorization|access[_ -]?token|"
+    r"refresh[_ -]?token)\b\s*[:=]\s*\S+|\bbearer\s+\S+|\bsk-[a-z0-9_-]{12,})"
+)
+
+
+def _text(value: Any) -> str:
+    # Tool arguments are untrusted payloads.  Keep the deliberately broad
+    # policy here: even a credential-shaped field name or URL path is enough
+    # to omit the action rather than risk displaying it.
+    if not isinstance(value, str) or _SENSITIVE.search(value):
+        return ""
+    # Free-text search requests can embed URLs too; never publish credentials.
+    if re.search(r"https?://[^\s/]*@", value):
+        return ""
+    return " ".join(value.split())[:180]
+
+
+def public_commentary_text(value: Any, *, limit: int = 360) -> str:
+    """Return model-authored text that is safe to show as public progress.
+
+    This accepts only the assistant's public text channel.  Provider reasoning,
+    tool arguments and tool results never call this helper.  Fail closed for
+    credentials and for tool-protocol fragments that some OpenAI-compatible
+    providers accidentally place in ``content`` alongside a tool call.
+    """
+    # Public assistant prose may legitimately discuss concepts such as a
+    # "token budget".  Only reject text that contains a credential value;
+    # unlike tool arguments, this channel has already been separated from
+    # provider reasoning and tool payloads.
+    if not isinstance(value, str) or _SECRET_VALUE.search(value):
+        return ""
+    if re.search(r"https?://[^\s/]*@", value):
+        return ""
+    if re.search(
+        r"(?i)(?:<\|\s*DSML\s*\||</?calls?>|</?invoke\b|<parameter\b|"
+        r"tool_calls?\s*[:=]|function_call\s*[:=])",
+        value,
+    ):
+        return ""
+    # Child conclusions are often Markdown.  The activity feed is prose, so
+    # remove presentation markers while retaining the actual conclusion.
+    text = re.sub(r"(?m)^\s{0,3}(?:#{1,6}\s+|>\s*|[-*+]\s+|\d+[.)]\s+)", "", value)
+    text = text.replace("**", "").replace("__", "").replace("`", "")
+    text = " ".join(text.split()).strip()
+    # Streaming providers can occasionally leave a trailing punctuation-only
+    # content fragment after a tool call.  It conveys no progress and would
+    # otherwise render as a stray activity row such as ``。``.
+    if not re.search(r"[A-Za-z0-9\u3400-\u9fff]", text):
+        return ""
+    # Tool-preface boilerplate is not a useful user-facing checkpoint.  It is
+    # intentionally omitted instead of translated into another canned phrase.
+    if re.fullmatch(
+        r"(?i)(?:let me|i(?:'ll| will)|we(?:'ll| will))\s+"
+        r"(?:delegate|search|look up|check|call|use|run)\b.*",
+        text,
+    ):
+        return ""
+    if len(text) <= limit:
+        return text
+    shortened = text[:limit]
+    boundary = max(shortened.rfind(mark) for mark in "。！？；.!?;")
+    if boundary >= max(40, limit // 2):
+        shortened = shortened[: boundary + 1]
+    return shortened.rstrip() + "…"
+
+
+def tool_public_action(payload: dict[str, Any]) -> dict[str, str] | None:
+    """Allowlist display fields; omit results, command arguments and credentials."""
+    name = str(payload.get("name") or "").lower()
+    args = payload.get("args")
+    if not isinstance(args, dict):
+        return None
+    if name == "web_search":
+        query = _text(args.get("query"))
+        return {"text": f"搜索资料：{query}"} if query else None
+    if name == "web_fetch":
+        try:
+            url = urlsplit(str(args.get("url") or ""))
+            host = url.hostname or ""
+            if url.scheme not in {"https", "http"} or not host:
+                return None
+            if host == "localhost" or "." not in host or host.endswith((".local", ".internal")):
+                return None
+            try:
+                if not ipaddress.ip_address(host).is_global:
+                    return None
+            except ValueError:
+                pass
+            # Queries, fragments and URL credentials never become presentation data.
+            safe = urlunsplit((url.scheme, host, url.path, "", ""))
+            if not _text(safe) or len(safe) > 300:
+                return None
+            return {"text": f"查看网页：{host}{url.path}", "href": safe}
+        except ValueError:
+            return None
+    if name in {
+        "read_workspace_file",
+        "write_workspace_file",
+        "edit_workspace_file",
+        "list_workspace_files",
+    }:
+        target = _text(PurePosixPath(str(args.get("path") or "").replace("\\", "/")).name)
+        if not target or target in {".", "..", ".env"}:
+            return None
+        verb = (
+            "保存文件"
+            if name == "write_workspace_file"
+            else "编辑文件"
+            if name == "edit_workspace_file"
+            else "查看文件"
+            if name == "read_workspace_file"
+            else "查看目录"
+        )
+        return {"text": f"{verb}：{target}"}
+    if name in {"exec_command", "run_command", "execute_command", "run_workspace_command"}:
+        try:
+            words = shlex.split(str(args.get("command") or args.get("cmd") or ""))
+        except ValueError:
+            return None
+        command = PurePosixPath(words[0]).name if words else ""
+        if command in {
+            "rg",
+            "git",
+            "ls",
+            "cat",
+            "sed",
+            "python",
+            "python3",
+            "node",
+            "npm",
+            "uv",
+            "pytest",
+        }:
+            return {"text": f"运行命令：{command}（参数未展示）"}
+    return None
+
+
+__all__ = ["public_commentary_text", "tool_public_action"]

ksadk/harness/readiness.py

@@ -0,0 +1,249 @@
+"""Harness 运行就绪度稳定合同。
+
+把不可变 :class:`HarnessSpec` 与一次 smoke/draft Run 的公开事件合并为
+``ready / warning / blocked``。该投影只消费公开合同，不解析 Engine、MCP、
+Skill 或 Sandbox 私有对象，可直接供生命周期门禁与 Studio 展示。
+
+``unknown`` 不等于故障：渐进披露能力在尚未被模型使用前本来就是 unknown，
+因此只产生 warning；只有已观测到的必需能力故障、模型失败或 Run 失败才阻断。
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from typing import Any, Sequence
+
+from ksadk.harness.events import EventType, RuntimeEvent
+from ksadk.harness.observability import capability_health
+from ksadk.harness.spec import CapabilityBinding, HarnessSpec
+
+_STATUS_ORDER = {"ready": 0, "warning": 1, "blocked": 2}
+
+
+def runtime_readiness(
+    spec: HarnessSpec,
+    events: Sequence[RuntimeEvent] = (),
+) -> dict[str, Any]:
+    """返回 JSON 兼容的运行/部署就绪度快照。
+
+    该函数不执行探测。``events`` 应来自同一 Revision 的 draft/smoke Run；
+    空事件仍可做静态检查，但模型和按需能力会标记为尚未观测。
+    """
+
+    projected = capability_health(events)
+    health_by_ref = {
+        str(item["capability_ref"]): item for item in projected.get("items", ())
+    }
+    checks: list[dict[str, Any]] = [
+        _check(
+            check_id="spec",
+            category="configuration",
+            status="ready",
+            reason_code="spec_valid",
+            resource_ref=spec.agent_revision_ref,
+            required=True,
+        ),
+        _model_check(spec, events),
+    ]
+    checks.extend(
+        _capability_check("mcp", binding, health_by_ref.get(binding.capability_ref))
+        for binding in spec.capabilities.mcp_bindings
+    )
+    checks.extend(
+        _capability_check("skill", binding, health_by_ref.get(binding.capability_ref))
+        for binding in spec.capabilities.skill_bindings
+    )
+
+    # Sandbox 只有在引擎实际声明/使用时才属于该 Agent 的运行依赖；默认
+    # SandboxPolicy 本身不代表 Agent 一定绑定了 Sandbox Tool。
+    checks.extend(
+        _observed_capability_check(item)
+        for item in projected.get("items", ())
+        if item.get("kind") == "sandbox"
+    )
+    checks.append(_approval_check(spec))
+    checks.append(_run_check(events))
+
+    counts = Counter(str(item["status"]) for item in checks)
+    overall = max((str(item["status"]) for item in checks), key=_STATUS_ORDER.__getitem__)
+    run_ids = sorted(
+        {
+            str(event.run_id or event.invocation_id)
+            for event in events
+            if event.run_id or event.invocation_id
+        }
+    )
+    return {
+        "status": overall,
+        "deployable": overall != "blocked",
+        "revision_ref": spec.agent_revision_ref,
+        "spec_hash": spec.content_hash(),
+        "observed_run_ids": run_ids,
+        "counts": {name: counts.get(name, 0) for name in ("ready", "warning", "blocked")},
+        "checks": checks,
+    }
+
+
+def _model_check(spec: HarnessSpec, events: Sequence[RuntimeEvent]) -> dict[str, Any]:
+    observed = [
+        event
+        for event in events
+        if event.event_type
+        in {EventType.MODEL_CALL_COMPLETED, EventType.MODEL_CALL_FAILED}
+    ]
+    if not observed:
+        return _check(
+            check_id="model",
+            category="model",
+            status="warning",
+            reason_code="not_observed",
+            resource_ref=spec.model.profile_ref,
+            required=True,
+        )
+    latest = observed[-1]
+    failed = latest.event_type == EventType.MODEL_CALL_FAILED
+    check = _check(
+        check_id="model",
+        category="model",
+        status="blocked" if failed else "ready",
+        reason_code="model_call_failed" if failed else "model_call_succeeded",
+        resource_ref=str(latest.payload.get("model") or spec.model.profile_ref),
+        required=True,
+    )
+    check["configured_resource_ref"] = spec.model.profile_ref
+    check["fallback_used"] = bool(latest.payload.get("fallback", False))
+    check["attempt"] = int(latest.payload.get("attempt") or 1)
+    return check
+
+
+def _capability_check(
+    kind: str,
+    binding: CapabilityBinding,
+    health: dict[str, Any] | None,
+) -> dict[str, Any]:
+    observed_status = str((health or {}).get("status") or "unknown")
+    if observed_status == "available":
+        status, reason = "ready", "capability_available"
+    elif observed_status == "degraded":
+        status = "blocked" if binding.required else "warning"
+        reason = (
+            "required_capability_degraded"
+            if binding.required
+            else "optional_capability_degraded"
+        )
+    else:
+        # on_demand/explicit 以及尚未调用的 always 能力都不能仅因“未使用”判坏。
+        status, reason = "warning", "capability_not_observed"
+    return _check(
+        check_id=f"{kind}:{binding.capability_ref}",
+        category=kind,
+        status=status,
+        reason_code=reason,
+        resource_ref=binding.capability_ref,
+        required=binding.required,
+        load_policy=binding.load_policy,
+    )
+
+
+def _observed_capability_check(item: dict[str, Any]) -> dict[str, Any]:
+    required = bool(item.get("required", True))
+    observed_status = str(item.get("status") or "unknown")
+    if observed_status == "available":
+        status, reason = "ready", "capability_available"
+    elif observed_status == "degraded":
+        status = "blocked" if required else "warning"
+        reason = "required_capability_degraded" if required else "optional_capability_degraded"
+    else:
+        status, reason = "warning", "capability_not_observed"
+    capability_ref = str(item.get("capability_ref") or "")
+    return _check(
+        check_id=f"{item.get('kind', 'capability')}:{capability_ref}",
+        category=str(item.get("kind") or "capability"),
+        status=status,
+        reason_code=reason,
+        resource_ref=capability_ref,
+        required=required,
+        load_policy=str(item.get("load_policy") or "on_demand"),
+    )
+
+
+def _approval_check(spec: HarnessSpec) -> dict[str, Any]:
+    policy = spec.approval_policy
+    if policy.mode == "never" or policy.approver_roles:
+        status, reason = "ready", "approval_policy_configured"
+    else:
+        # 本地调试可由调用者直接批准，正式平台仍应配置组织审批角色。
+        status, reason = "warning", "approval_roles_not_configured"
+    return _check(
+        check_id="approval-policy",
+        category="policy",
+        status=status,
+        reason_code=reason,
+        resource_ref=None,
+        required=policy.mode != "never",
+    )
+
+
+def _run_check(events: Sequence[RuntimeEvent]) -> dict[str, Any]:
+    terminal = [
+        event
+        for event in events
+        if event.event_type
+        in {
+            EventType.RUN_COMPLETED,
+            EventType.RUN_FAILED,
+            EventType.RUN_CANCELED,
+            EventType.RUN_INTERRUPTED,
+        }
+    ]
+    if not terminal:
+        return _check(
+            check_id="smoke-run",
+            category="runtime",
+            status="warning",
+            reason_code="smoke_run_not_observed",
+            resource_ref=None,
+            required=False,
+        )
+    latest = terminal[-1]
+    if latest.event_type == EventType.RUN_COMPLETED:
+        status, reason = "ready", "smoke_run_succeeded"
+    elif latest.event_type == EventType.RUN_FAILED:
+        status, reason = "blocked", "smoke_run_failed"
+    else:
+        status, reason = "warning", "smoke_run_incomplete"
+    return _check(
+        check_id="smoke-run",
+        category="runtime",
+        status=status,
+        reason_code=reason,
+        resource_ref=None,
+        required=False,
+    )
+
+
+def _check(
+    *,
+    check_id: str,
+    category: str,
+    status: str,
+    reason_code: str,
+    resource_ref: str | None,
+    required: bool,
+    load_policy: str | None = None,
+) -> dict[str, Any]:
+    result: dict[str, Any] = {
+        "id": check_id,
+        "category": category,
+        "status": status,
+        "reason_code": reason_code,
+        "required": required,
+    }
+    if resource_ref:
+        result["resource_ref"] = resource_ref
+    if load_policy:
+        result["load_policy"] = load_policy
+    return result
+
+
+__all__ = ["runtime_readiness"]