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

ksadk/runtime/_runner_adapter/stream_mapping.py

@@ -26,6 +26,7 @@ from ksadk.conversations.runtime_observability import (
     _set_conversation_output_attributes,
     _set_conversation_span_attributes,
     _set_conversation_usage_attributes,
+    _set_skill_eval_result_attributes,
 )
 from ksadk.events.canonical import (
     ApprovalRequest,
@@ -37,6 +38,7 @@ from ksadk.events.canonical import (
     ItemCompleted,
     ItemStarted,
     ItemUpdated,
+    RunCompleted,
     RunFailed,
     RunProgress,
     RuntimeEvent,
@@ -47,6 +49,9 @@ from ksadk.events.content import DataContent, TextContent, ToolCallContent, Tool
 from ksadk.events.identity import stable_event_id, stable_item_id, stable_scope_id
 from ksadk.runtime.adapter import RunHandle
 from ksadk.runtime.preprocessing import PreparedRuntimeStart
+from ksadk.runtime.skill_eval_result import extract_skill_eval_result
+from ksadk.runtime.timing import extract_timing
+from ksadk.runtime.usage import canonical_usage_payload
 from ksadk.runtime_context import platform_invocation_scope
 from ksadk.tools.gateway import approval_interrupt_info_from_result
 
@@ -283,7 +288,9 @@ class _RunnerStreamMappingMixin:
                     # _chunk_to_events 的 tool_result 分支,canonical 快速路径
                     # (stream_canonical_events)不覆盖该语义。
                     if getattr(
-                        self._runner, "supports_gateway_approval_semantic_resume", False  # type: ignore[attr-defined]
+                        self._runner,
+                        "supports_gateway_approval_semantic_resume",
+                        False,  # type: ignore[attr-defined]
                     ):
                         canonical_stream = None
                     stream_result = (
@@ -357,6 +364,10 @@ class _RunnerStreamMappingMixin:
                         if isinstance(chunk, EventEnvelope):
                             # canonical 事件(来自 stream_canonical_events):直接转发,
                             # 追踪 output/usage 供 span 属性。
+                            if isinstance(chunk, RunCompleted):
+                                evidence = extract_skill_eval_result(chunk.source.metadata.get("metrics"))
+                                if evidence:
+                                    _set_skill_eval_result_attributes(span, evidence)
                             if isinstance(chunk, ItemCompleted) and chunk.item_kind == "message":
                                 accumulated_output = "".join(
                                     part.text
@@ -376,6 +387,11 @@ class _RunnerStreamMappingMixin:
                         if isinstance(chunk, dict):
                             chunk_type = str(chunk.get("type") or "")
                             if chunk_type == "final" and run is not None:
+                                if evidence := extract_skill_eval_result(chunk):
+                                    run.completion_metrics["skill_eval_result"] = evidence
+                                    _set_skill_eval_result_attributes(span, evidence)
+                                if timing := extract_timing(chunk):
+                                    run.completion_metrics["timing"] = timing
                                 for source_key, target_key in (
                                     ("duration_ms", "duration_ms"),
                                     ("started_at", "started_at"),
@@ -786,7 +802,11 @@ class _RunnerStreamMappingMixin:
         # ---- usage ----
         if chunk_type == "usage":
             raw_usage = chunk.get("usage")
-            usage_dict: dict[str, Any] = raw_usage if isinstance(raw_usage, dict) else {}
+            usage_dict = (
+                canonical_usage_payload(raw_usage, runtime_type=framework)
+                if isinstance(raw_usage, Mapping)
+                else {}
+            )
             item_id = stable_item_id(framework, run_id, "$run")
             return [
                 UsageReported(
@@ -873,6 +893,36 @@ class _RunnerStreamMappingMixin:
             events.extend(
                 ensure_started(item_id=item_id, item_kind="message", phase="final_answer")
             )
+            # The dict-chunk path is still required for gateway approval flows.
+            # It must project runner-final usage into the canonical stream too;
+            # otherwise non-streaming Runs aggregate zero even when the runner
+            # returned provider token accounting.
+            raw_usage = chunk.get("usage")
+            if isinstance(raw_usage, Mapping):
+                usage_dict = canonical_usage_payload(
+                    raw_usage,
+                    runtime_type=framework,
+                )
+                input_tokens = usage_dict["input_tokens"]
+                output_tokens = usage_dict["output_tokens"]
+                total_tokens = usage_dict["total_tokens"]
+                if input_tokens or output_tokens or total_tokens:
+                    events.append(
+                        UsageReported(
+                            **self._canonical_kwargs(  # type: ignore[attr-defined]
+                                handle,
+                                scope_id=scope_id,
+                                item_id=stable_item_id(framework, run_id, "$run"),
+                                event_type="usage.reported",
+                                part_id="usage",
+                            ),
+                            input_tokens=input_tokens,
+                            output_tokens=output_tokens,
+                            total_tokens=total_tokens,
+                            cached_tokens=usage_dict["cached_tokens"],
+                            reasoning_tokens=usage_dict["reasoning_tokens"],
+                        )
+                    )
             events.append(
                 ItemCompleted(
                     **self._canonical_kwargs(  # type: ignore[attr-defined]

ksadk/runtime/conversation_execution.py

@@ -48,6 +48,8 @@ from ksadk.runtime.adapter import (
 from ksadk.runtime.executor import RuntimeExecutor, RuntimeStartPreparation
 from ksadk.runtime.factory import apply_runtime_start_request_defaults
 from ksadk.runtime.launch import RuntimeLaunchContext
+from ksadk.runtime.skill_eval_result import skill_eval_response_fields
+from ksadk.runtime.timing import normalize_timing
 from ksadk.sessions import resolve_session_service
 
 _TERMINAL_EVENTS = frozenset(
@@ -647,20 +649,31 @@ async def iter_runtime_conversation_semantic_events(
                 "session_id": execution_context.get("session_id", ""),
             }
         elif isinstance(event, RunFailed):
+            metrics = event.source.metadata.get("metrics")
+            timing = normalize_timing(metrics.get("timing")) if isinstance(metrics, Mapping) else {}
             yield {
                 "type": "error",
                 "message": event.error.message or "Agent 运行失败",
                 "session_id": execution_context.get("session_id", ""),
                 "usage": projection.usage.model_dump(),
+                **({"timing": timing} if timing else {}),
+                **skill_eval_response_fields(metrics),
             }
         elif isinstance(event, RunCanceled):
+            metrics = event.source.metadata.get("metrics")
+            timing = normalize_timing(metrics.get("timing")) if isinstance(metrics, Mapping) else {}
             yield {
                 "type": "cancelled",
                 "session_id": execution_context.get("session_id", ""),
                 "usage": projection.usage.model_dump(),
+                **({"timing": timing} if timing else {}),
+                **skill_eval_response_fields(metrics),
             }
         elif isinstance(event, RunCompleted):
             completion_metadata = dict(event.source.metadata)
+            metrics = completion_metadata.get("metrics")
+            metrics = metrics if isinstance(metrics, Mapping) else {}
+            timing = normalize_timing(metrics.get("timing"))
             request_metadata = kwargs.get("request_metadata")
             requested_agentengine = (
                 request_metadata.get("agentengine")
@@ -674,7 +687,10 @@ async def iter_runtime_conversation_semantic_events(
                     if key != "session_context"
                 }
             completion_metadata["runtime"] = {
-                "duration_ms": event.source.metadata.get("duration_ms"),
+                "duration_ms": timing.get(
+                    "agent_duration_ms",
+                    metrics.get("duration_ms", event.source.metadata.get("duration_ms")),
+                ),
                 "runtime_type": kwargs["launch_context"].runtime_type,
             }
             yield {
@@ -683,6 +699,8 @@ async def iter_runtime_conversation_semantic_events(
                 "session_id": execution_context.get("session_id", ""),
                 "usage": projection.usage.model_dump(),
                 "metadata": completion_metadata,
+                **({"timing": timing} if timing else {}),
+                **skill_eval_response_fields(metrics),
             }
 
 
@@ -728,6 +746,8 @@ async def invoke_runtime_conversation_once(
     usage: dict[str, Any] = {}
     metadata: dict[str, Any] = {}
     completed = False
+    timing: dict[str, Any] = {}
+    result_fields: dict[str, Any] = {}
     async for event in iter_runtime_conversation_semantic_events(**kwargs):
         event_type = event.get("type")
         if event_type == "started":
@@ -741,6 +761,8 @@ async def invoke_runtime_conversation_once(
             output_text = str(event.get("output_text") or output_text)
             usage = dict(event.get("usage") or {})
             metadata = dict(event.get("metadata") or {})
+            timing = normalize_timing(event.get("timing"))
+            result_fields = skill_eval_response_fields(event)
         elif event_type == "error":
             raise RuntimeError(str(event.get("message") or "Agent 运行失败"))
         elif event_type == "cancelled":
@@ -751,8 +773,10 @@ async def invoke_runtime_conversation_once(
         raise RuntimeError("runtime did not produce a completed result")
     return session_id, {
         "output_text": output_text,
+        **result_fields,
         "usage": usage,
         "metadata": metadata,
+        **({"timing": timing} if timing else {}),
     }
 
 

ksadk/runtime/executor.py

@@ -246,6 +246,8 @@ class RuntimeExecutor:
         self,
         context: RuntimeLaunchContext,
         handle: RunHandle,
+        *,
+        preparation: RuntimeStartPreparation | None = None,
     ) -> RunHandle:
         expected_type = _normalize_runtime_type(context.runtime_type)
         if _normalize_runtime_type(handle.runtime_type) != expected_type:
@@ -253,7 +255,13 @@ class RuntimeExecutor:
         if self.is_attached(handle):
             return handle
 
-        adapter = self._registry.create(context)
+        if preparation is not None:
+            if preparation.context != context or preparation.consumed:
+                raise ValueError("attach preparation must be unused and match launch context")
+            preparation.consumed = True
+            adapter = preparation.adapter
+        else:
+            adapter = self._registry.create(context)
         restored = await adapter.attach(handle)
         if restored != handle:
             with suppress(Exception):

ksadk/runtime/factory.py

@@ -37,6 +37,40 @@ from ksadk.runtime.framework_adapters import ADKRuntimeAdapter, LangGraphRuntime
 from ksadk.runtime.launch import RuntimeLaunchContext
 
 
+def _create_harness(context: RuntimeLaunchContext) -> RuntimeAdapter:
+    """Create the managed KsADK Harness adapter from an immutable launch manifest."""
+
+    import re
+
+    from ksadk.harness.managed_runtime import ManagedHarnessRuntimeAdapter
+    from ksadk.harness.reasoner import LiteLLMHarnessReasoner
+    from ksadk.harness.spec import HarnessSpec, ModelBinding, PromptSpec
+
+    config = dict(context.config)
+    prompt = str(config.get("prompt") or config.get("base_instructions") or "").strip()
+    model = str(config.get("model") or "").strip()
+    if not prompt:
+        raise ValueError("harness runtime requires prompt/base_instructions")
+    if not model:
+        raise ValueError("harness runtime requires model")
+    model_ref_name = re.sub(r"[^A-Za-z0-9._-]+", "-", model).strip("-") or "studio-model"
+    agent_ref_name = re.sub(
+        r"[^A-Za-z0-9._-]+", "-", str(config.get("agent_id") or "studio-agent")
+    ).strip("-") or "studio-agent"
+    spec = HarnessSpec(
+        agent_revision_ref=f"agent-revision://{agent_ref_name}@1",
+        model=ModelBinding(profile_ref=f"model-profile://{model_ref_name}@1"),
+        prompt=PromptSpec(instructions=prompt),
+    )
+    return ManagedHarnessRuntimeAdapter(
+        spec,
+        reasoner=LiteLLMHarnessReasoner(
+            base_url=str(config.get("base_url") or ""),
+        ),
+        workspace_root=context.project_dir,
+    )
+
+
 def kernel_start_request_defaults(context: RuntimeLaunchContext) -> dict[str, Any]:
     """Project an admitted launch manifest into immutable Kernel turn defaults.
 
@@ -149,10 +183,11 @@ def _create_langgraph(context: RuntimeLaunchContext) -> RuntimeAdapter:
 
 
 def build_default_runtime_registry() -> RuntimeRegistry:
-    """注册内置 Codex、ADK 和 LangGraph Runtime Factory。"""
+    """注册内置 KsADK Harness、Codex、ADK 和 LangGraph Runtime Factory。"""
 
     registry = RuntimeRegistry()
     registry.register("codex", _create_codex)
+    registry.register("harness", _create_harness)
     registry.register("adk", _create_adk)
     registry.register("langgraph", _create_langgraph)
     return registry

ksadk/runtime/preprocessing.py

@@ -18,7 +18,11 @@ from ksadk.runtime.adapter import (
     CONVERSATION_PREPROCESSING_METADATA_KEY,
     StartRequest,
 )
-from ksadk.runtime_context import PlatformInvocationContext
+from ksadk.runtime_context import (
+    TRUSTED_IDENTITY_METADATA_KEY,
+    PlatformIdentityContext,
+    PlatformInvocationContext,
+)
 from ksadk.session_context import split_session_context
 
 
@@ -62,6 +66,7 @@ async def prepare_runtime_start(request: StartRequest, runner: Any) -> PreparedR
         if key not in {CONVERSATION_PREPROCESSING_METADATA_KEY, "session_context"}
     }
     request_metadata = {**outer_metadata, **conversation.request_metadata}
+    identity_payload: Any = request_metadata.get(TRUSTED_IDENTITY_METADATA_KEY)
     messages = conversation.messages or _fallback_messages(request.input)
     raw_prepared = (conversation.model_extra or {}).get("prepared_turn")
     if isinstance(raw_prepared, Mapping):
@@ -70,6 +75,7 @@ async def prepare_runtime_start(request: StartRequest, runner: Any) -> PreparedR
             **prepared.request_metadata,
             **request_metadata,
         }
+        identity_payload = merged_metadata.pop(TRUSTED_IDENTITY_METADATA_KEY, identity_payload)
         snapshot, prepared.request_metadata = split_session_context(merged_metadata)
         controls = merged_metadata.get("agentengine")
         if isinstance(controls, Mapping) and "session_context" in controls:
@@ -105,10 +111,11 @@ async def prepare_runtime_start(request: StartRequest, runner: Any) -> PreparedR
             flush_before_compaction=bool(request.config.get("flush_before_compaction", True)),
             provider_ref=str(request.config.get("provider_ref") or "local-default"),
         )
+        request_metadata.pop(TRUSTED_IDENTITY_METADATA_KEY, None)
     _inject_runner_deferred_tools_for_request(runner, prepared)
     ambient_contexts = _build_runner_ambient_contexts(
         runner=runner,
-        user_id=request.user_id,
+        user_id=prepared.user_id or request.user_id,
         user_input=prepared.user_input,
     )
     # Studio/平台控制面可以按 AgentVersion 的 providerRef 提前完成召回；它比仅依赖
@@ -124,7 +131,7 @@ async def prepare_runtime_start(request: StartRequest, runner: Any) -> PreparedR
     runtime_context = PlatformInvocationContext(
         session=SessionContext.from_payload(prepared.session_context),
         agent_id=str(request.agent_id or "agent"),
-        user_id=request.user_id,
+        user_id=prepared.user_id or request.user_id,
         account_id=str(conversation.account_id or ""),
         session_id=prepared.session_id,
         history=list(prepared.history),
@@ -143,6 +150,7 @@ async def prepare_runtime_start(request: StartRequest, runner: Any) -> PreparedR
         kb_context=ambient_contexts.get("kb_context"),
         memory_context=ambient_contexts.get("memory_context"),
         tool_approval_mode=str(prepared.request_metadata.get("tool_approval_mode") or ""),
+        identity=PlatformIdentityContext.from_payload(identity_payload),
     )
     canonical_payload = _build_runner_request_payload(
         prepared=prepared,

ksadk/runtime/runner_adapter.py

@@ -54,7 +54,11 @@ from ksadk.runtime.adapter import (
 )
 from ksadk.runtime.preprocessing import PreparedRuntimeStart, prepare_runtime_start
 from ksadk.runtime.runner_loading import ensure_runner_loaded
-from ksadk.runtime_context import session_invocation_context
+from ksadk.runtime.timing import normalize_timing
+from ksadk.runtime_context import (
+    TRUSTED_IDENTITY_METADATA_KEY,
+    session_invocation_context,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -282,13 +286,15 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
         # 暂存 start 输入,供 stream() 使用。
         self._active_runs[run_id].__dict__["_start_request"] = request
         snapshot = request.metadata.get("session_context")
-        if snapshot is not None:
+        invocation_identity = request.metadata.get(TRUSTED_IDENTITY_METADATA_KEY)
+        if snapshot is not None or invocation_identity is not None:
             self._active_runs[run_id].__dict__["_tag_context"] = session_invocation_context(
                 snapshot,
                 agent_id=request.agent_id or "",
                 user_id=request.user_id,
                 session_id=request.session_id,
                 runner_type=self._runtime_type,
+                identity=invocation_identity,
             )
         if prepared_start is not None:
             self._active_runs[run_id].__dict__["_prepared_start"] = prepared_start
@@ -322,8 +328,7 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
         attach = getattr(self._runner, "attach_runtime_handle", None)
         if not callable(attach):
             raise UnsupportedControlError(
-                f"runner for {self._runtime_type!r} has no durable "
-                "attach_runtime_handle capability"
+                f"runner for {self._runtime_type!r} has no durable attach_runtime_handle capability"
             )
         ensure_runner_loaded(self._runner, runtime_type=self._runtime_type)
         restored = attach(handle)
@@ -457,8 +462,7 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
         checkpoint_id = str(handle.native_ref.get("checkpoint_id") or "").strip()
         if not checkpoint_id:
             raise UnsupportedControlError(
-                f"{self._runtime_type} runner has no native checkpoint for run "
-                f"{handle.run_id!r}"
+                f"{self._runtime_type} runner has no native checkpoint for run {handle.run_id!r}"
             )
         return CheckpointDescriptor(
             checkpoint_id=checkpoint_id,
@@ -566,6 +570,14 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
 
         request = run.__dict__.get("_start_request")
         runner_input = self._build_runner_input(handle, request)
+        runner_started = time.perf_counter()
+
+        def record_timing() -> None:
+            timing = normalize_timing(run.completion_metrics.get("timing"))
+            timing["agent_duration_ms"] = round((time.perf_counter() - runner_started) * 1000, 3)
+            timing["phase_status"] = {**timing.get("phase_status", {}), "agent": "measured"}
+            run.completion_metrics["timing"] = timing
+
         gen: Optional[AsyncIterator[RuntimeEvent]] = None
         terminal_event_seen = False
         approval_interrupted = False
@@ -573,6 +585,24 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
             gen = self._map_runner_stream(event_handle, runner_input, active_run=run)
             run.stream = gen
             async for event in gen:
+                if event.event_type in {
+                    "run.completed",
+                    "run.failed",
+                    "run.canceled",
+                    "run.interrupted",
+                }:
+                    source_metrics = event.source.metadata.get("metrics")
+                    if isinstance(source_metrics, Mapping):
+                        run.completion_metrics.update(source_metrics)
+                    record_timing()
+                    metrics = dict(run.completion_metrics)
+                    event = event.model_copy(
+                        update={
+                            "source": event.source.model_copy(
+                                update={"metadata": {**event.source.metadata, "metrics": metrics}}
+                            )
+                        }
+                    )
                 yield event
                 if event.event_type == "interaction.requested":
                     approval_interrupted = True
@@ -595,6 +625,7 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
                 if event.event_type in {"run.failed", "run.canceled"}:
                     return
 
+            record_timing()
             if run.interrupt_event.is_set() and not terminal_event_seen:
                 yield self._make_run_canceled(
                     event_handle, reason=CancelResult.INTERRUPTED_ACTIVE_TURN.value
@@ -645,9 +676,7 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
                 {
                     "input": override.get("input"),
                     "session_id": handle.session_id,
-                    "invocation_id": str(
-                        merged.get("invocation_id") or handle.run_id
-                    ),
+                    "invocation_id": str(merged.get("invocation_id") or handle.run_id),
                     "metadata": {
                         **(dict(base_metadata) if isinstance(base_metadata, Mapping) else {}),
                         **dict(override.get("metadata") or {}),

ksadk/runtime/skill_eval_result.py

@@ -0,0 +1,36 @@
+"""Opt-in Skill evaluation evidence, carried separately from assistant text."""
+
+import json
+import re
+from collections.abc import Mapping
+from typing import Any
+
+
+def extract_skill_eval_result(value: Any) -> dict[str, Any]:
+    """Read only an explicit state/result field; never parse model messages."""
+    result = value.get("skill_eval_result") if isinstance(value, Mapping) else None
+    if (
+        not isinstance(result, Mapping)
+        or result.get("schema_version") != "base_agent.skill_eval_result.v2"
+    ):
+        return {}
+    try:
+        return json.loads(json.dumps(dict(result), ensure_ascii=False, allow_nan=False))
+    except (TypeError, ValueError, RecursionError):
+        return {}
+
+
+def skill_eval_response_fields(value: Any) -> dict[str, Any]:
+    result = extract_skill_eval_result(value)
+    if not result:
+        return {}
+    fields: dict[str, Any] = {"skill_eval_result": result}
+    run = result.get("run")
+    trace_id = run.get("trace_id") if isinstance(run, Mapping) else None
+    if (
+        isinstance(trace_id, str)
+        and re.fullmatch(r"[0-9a-fA-F]{32}", trace_id)
+        and int(trace_id, 16)
+    ):
+        fields["trace_id"] = trace_id.lower()
+    return fields

ksadk/runtime/timing.py

@@ -0,0 +1,46 @@
+"""Response timing contract. Durations use milliseconds, never model content."""
+
+import math
+from collections.abc import Mapping
+from typing import Any
+
+PHASES = ("agent", "selection", "answer", "skill_load", "skill_execution")
+
+
+def normalize_timing(value: Any) -> dict[str, Any]:
+    if not isinstance(value, Mapping):
+        return {}
+    result: dict[str, Any] = {}
+    statuses: dict[str, str] = {}
+    raw_statuses = value.get("phase_status")
+    raw_statuses = raw_statuses if isinstance(raw_statuses, Mapping) else {}
+    for phase in PHASES:
+        key = f"{phase}_duration_ms"
+        if key not in value:
+            continue
+        duration = value[key]
+        try:
+            valid = (
+                isinstance(duration, (int, float))
+                and not isinstance(duration, bool)
+                and math.isfinite(duration)
+                and duration >= 0
+            )
+        except OverflowError:
+            valid = False
+        result[key] = duration if valid else None
+        statuses[phase] = (
+            "measured"
+            if valid
+            else "skipped"
+            if duration is None and raw_statuses.get(phase) == "skipped"
+            else "unavailable"
+        )
+    if result:
+        result["phase_status"] = statuses
+    return result
+
+
+def extract_timing(result: Any) -> dict[str, Any]:
+    """Only opt-in graph/runner state fields are eligible; don't inspect messages."""
+    return normalize_timing(result.get("timing")) if isinstance(result, Mapping) else {}

ksadk/runtime/usage.py

@@ -5,29 +5,60 @@ from __future__ import annotations
 from typing import Any, Mapping
 
 
-def canonical_usage_payload(
-    usage: Mapping[str, Any], *, runtime_type: str
-) -> dict[str, Any]:
+def _usage_int(value: Any) -> int:
+    try:
+        return int(value or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
+def _details(usage: Mapping[str, Any], *keys: str) -> Mapping[str, Any]:
+    for key in keys:
+        value = usage.get(key)
+        if isinstance(value, Mapping):
+            return value
+    return {}
+
+
+def _first_present_int(*values: Any) -> int:
+    for value in values:
+        if value is not None:
+            return _usage_int(value)
+    return 0
+
+
+def canonical_usage_payload(usage: Mapping[str, Any], *, runtime_type: str) -> dict[str, Any]:
     """Normalize provider usage, including nested cache/reasoning details."""
-    input_details = usage.get("input_token_details")
-    output_details = usage.get("output_token_details")
-    cached = (
-        input_details.get("cached")
-        if isinstance(input_details, Mapping)
-        else usage.get("cached_tokens")
+    input_details = _details(
+        usage,
+        "input_token_details",
+        "input_tokens_details",
+        "prompt_tokens_details",
+    )
+    output_details = _details(
+        usage,
+        "output_token_details",
+        "output_tokens_details",
+        "completion_tokens_details",
+    )
+    cached = _first_present_int(
+        input_details.get("cached_tokens"),
+        input_details.get("cached"),
+        input_details.get("cache_read"),
+        usage.get("cached_tokens"),
     )
-    reasoning = (
-        output_details.get("reasoning")
-        if isinstance(output_details, Mapping)
-        else usage.get("reasoning_tokens")
+    reasoning = _first_present_int(
+        output_details.get("reasoning_tokens"),
+        output_details.get("reasoning"),
+        usage.get("reasoning_tokens"),
     )
-    input_tokens = int(usage.get("input_tokens") or 0)
-    output_tokens = int(usage.get("output_tokens") or 0)
+    input_tokens = _first_present_int(usage.get("input_tokens"), usage.get("prompt_tokens"))
+    output_tokens = _first_present_int(usage.get("output_tokens"), usage.get("completion_tokens"))
     return {
         "input_tokens": input_tokens,
         "output_tokens": output_tokens,
-        "total_tokens": int(usage.get("total_tokens") or input_tokens + output_tokens),
-        "cached_tokens": int(cached or 0),
-        "reasoning_tokens": int(reasoning or 0),
+        "total_tokens": _first_present_int(usage.get("total_tokens"), input_tokens + output_tokens),
+        "cached_tokens": cached,
+        "reasoning_tokens": reasoning,
         "source": str(usage.get("source") or runtime_type),
     }