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

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__)
 
@@ -126,6 +130,8 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
     def __init__(self, runner: BaseRunner, *, runtime_type: str) -> None:
         super().__init__(_RunnerAsBaseRuntime(runner, runtime_type))
         self._runner = runner
+        self._runner_owned_by_app = False
+        self._app_resources_closed = False
         self._runtime_type = runtime_type
         self._active_runs: dict[str, _ActiveRun] = {}
         self._known_runs: set[str] = set()
@@ -139,9 +145,31 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
 
     # ---- 框架钩子(子类按需 override) ----
 
+    def adopt_app_lifetime(self) -> None:
+        """A composition root sharing this adapter owns the runner's lifetime."""
+        self._runner_owned_by_app = True
+
+    async def close_app_resources(self) -> None:
+        if self._runner_owned_by_app and not self._app_resources_closed:
+            self._app_resources_closed = True
+            close = getattr(self._runner, "close", None)
+            if callable(close):
+                result = close()
+                if inspect.isawaitable(result):
+                    await result
+
+    def configure_managed_a2a(self, bootstrap) -> None:
+        if self._active_runs:
+            raise RuntimeError("cannot configure managed A2A during an active run")
+        if self._runtime_type in {"adk", "langgraph"}:
+            self._runner._managed_a2a_bootstrap = bootstrap
+
     def _requires_stable_stream_context(self) -> bool:
         """Whether one Task must own the runner generator for its lifetime."""
-        return self._runtime_type == "adk"
+        return self._runtime_type == "adk" or (
+            self._runtime_type == "langgraph"
+            and getattr(self._runner, "_managed_a2a_bootstrap", None) is not None
+        )
 
     def capabilities(self) -> RuntimeCapabilityMatrix:
         """诚实矩阵:cancel 经 asyncio 任务打断(emulated,过 conformance);
@@ -160,7 +188,13 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
             and checkpoint_capability.shared_across_pods
             and attach_seam
         )
+        bootstrap = getattr(self._runner, "_managed_a2a_bootstrap", None)
+        scoped_cancel = bool(
+            bootstrap is not None and getattr(bootstrap, "scoped_cancel_available", False)
+        )
         return RuntimeCapabilityMatrix(
+            scoped_cancel=(RuntimeCapability(supported=True, mode="emulated")
+                           if scoped_cancel else None),
             cancel=RuntimeCapability(
                 supported=True,
                 mode="emulated",
@@ -265,6 +299,11 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
         """Load the framework agent before a streaming HTTP response commits."""
 
         ensure_runner_loaded(self._runner, runtime_type=self._runtime_type)
+        # Hosted Kernel pins capabilities immediately after preflight. A graph
+        # loaded with MemorySaver must finish its managed checkpoint setup first.
+        prepare = getattr(self._runner, "prepare_runtime_capabilities", None)
+        if callable(prepare):
+            await prepare()
 
     async def start(self, request: StartRequest) -> RunHandle:
         ensure_runner_loaded(self._runner, runtime_type=self._runtime_type)
@@ -282,13 +321,16 @@ 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 or request.metadata.get("tool_approval_mode"):
             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,
+                tool_approval_mode=str(request.metadata.get("tool_approval_mode") or ""),
             )
         if prepared_start is not None:
             self._active_runs[run_id].__dict__["_prepared_start"] = prepared_start
@@ -322,8 +364,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 +498,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,
@@ -493,6 +533,8 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
         self._pending_cancels.discard(handle.run_id)
         self._known_runs.discard(handle.run_id)
         self._run_sessions.pop(handle.run_id, None)
+        if self._runner_owned_by_app:
+            return
         close = getattr(self._runner, "close", None)
         if callable(close):
             result = close()
@@ -520,8 +562,9 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
         if run.stream is None:
             run.cancellation_ack.set()
             return
-        if run.chunk_task is not None:
-            run.chunk_task.cancel()
+        # The stream owner cancels and joins the in-flight task. Cancelling it
+        # here as well interrupts async cleanup (including durable A2A cancel
+        # facts) when the stream owner delivers the second cancellation.
         await asyncio.wait_for(run.cancellation_ack.wait(), timeout=2)
 
     # ---- 内部:stream → RuntimeEvent ----
@@ -545,6 +588,42 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
             else handle.model_copy(update={"run_id": run.invocation_id})
         )
 
+        authority = None
+        existing_start = None
+        if self._runtime_type == "adk" or (
+            self._runtime_type == "langgraph"
+            and getattr(self._runner, "_managed_a2a_bootstrap", None) is not None
+        ):
+            from ksadk.events.run_authority import current_run_event_authority
+
+            authority = current_run_event_authority()
+            if authority is not None:
+                authority.require_session(handle.session_id)
+                # Adapter start/cancel and canonical Runner completion must
+                # describe the same public root, while native input keeps its
+                # private invocation identity for framework checkpoints.
+                if self._runtime_type == "langgraph":
+                    # Keep the shared native_ref: canonical checkpoint mapping
+                    # records resume targets on the original opaque handle.
+                    event_handle.native_ref["invocation_id"] = run.invocation_id
+                    for existing in await authority.list(handle.session_id):
+                        if (
+                            isinstance(existing, RunStarted)
+                            and existing.run_id == authority.run_id
+                            and existing.parent_scope_id is None
+                            and existing.source.framework == "langgraph"
+                        ):
+                            existing_start = existing
+                            break
+                    # Bind before early cancel/skip paths as well as resume.
+                    # Only the active authority can supply this public owner.
+                    event_handle.native_ref["_ksadk_public_root"] = {
+                        "run_id": authority.run_id,
+                        "scope_id": existing_start.scope_id if existing_start else
+                        stable_scope_id("langgraph", authority.run_id, "$run"),
+                    }
+                event_handle = event_handle.model_copy(update={"run_id": authority.run_id})
+
         # 消费 pending cancel:start 时若已记 pending,立即中断该 turn。
         if handle.run_id in self._pending_cancels:
             self._pending_cancels.discard(handle.run_id)
@@ -562,10 +641,36 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
         if run.resume_key is not None:
             self._consumed_resumes.add(run.resume_key)
 
-        yield self._make_run_started(event_handle)
+        # Reuse the original fact across producer upgrades and fenced takeover.
+        started = existing_start or self._make_run_started(event_handle)
+        if run.__dict__.get("_restored_from_record"):
+            if authority is None:
+                raise RuntimeError("ADK restored stream requires Kernel run authority")
+            for existing in await authority.list(handle.session_id):
+                if existing.event_id == started.event_id:
+                    # Reuse the original fact's timestamp; guarded append
+                    # still checks the full payload and current fencing token.
+                    started = started.model_copy(update={"timestamp": existing.timestamp})
+                    break
+        if authority is not None and run.resume_key is not None:
+            for existing in await authority.list(handle.session_id):
+                if existing.event_id == started.event_id:
+                    # Resuming an interaction continues the same public run.
+                    # Its initial start fact must not acquire a new timestamp.
+                    started = existing
+                    break
+        yield started
 
         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,7 +678,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:
-                yield event
+                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}}
+                            )
+                        }
+                    )
                 if event.event_type == "interaction.requested":
                     approval_interrupted = True
                     # Track pending approval for canonical streams that bypass
@@ -585,6 +707,9 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
                             pending_ids = handle.native_ref.setdefault("pending_approval_ids", [])
                             if call_id not in pending_ids:
                                 pending_ids.append(call_id)
+                # Consumers may persist the handle as soon as they receive the
+                # interaction. Include its identity before yielding that event.
+                yield event
                 if event.event_type in {
                     "run.completed",
                     "run.failed",
@@ -595,6 +720,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 +771,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 {}),
@@ -730,15 +854,18 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
         framework = self._runtime_type
         if framework not in {"adk", "langgraph", "codex", "a2a", "ksadk"}:
             framework = "ksadk"
+        native_invocation_id = handle.run_id
+        if framework == "langgraph":
+            native_invocation_id = str(handle.native_ref.get("invocation_id") or handle.run_id)
         return SourceRef(
             framework=framework,
             protocol=protocol,
-            native_run_id=handle.run_id,
+            native_run_id=native_invocation_id,
             metadata={
                 "agent_id": str(handle.native_ref.get("agent_id") or "agent"),
                 "user_id": str(handle.native_ref.get("user_id") or "user"),
                 "session_id": handle.session_id,
-                "invocation_id": handle.run_id,
+                "invocation_id": native_invocation_id,
             },
         )
 
@@ -754,6 +881,8 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
         """Build common EventEnvelope kwargs for the dict-chunk degraded path."""
         framework = self._runtime_type
         run_id = handle.run_id
+        if framework == "langgraph" and event_type.startswith("run."):
+            scope_id = self._root_lifecycle_scope(handle)
         # TODO(runtime-event-v2): dict chunk 退化路径,chunk_ordinal 用 seq counter;
         # LangGraph/Codex 切 stream_canonical_events 后清理
         n = self._next_seq()
@@ -769,10 +898,20 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
             "source": self._make_source(handle),
         }
 
+    def _root_lifecycle_scope(self, handle: RunHandle) -> str:
+        if self._runtime_type != "langgraph":
+            return stable_scope_id(self._runtime_type, handle.run_id)
+        bound = handle.native_ref.get("_ksadk_public_root")
+        if isinstance(bound, Mapping) and bound.get("run_id") == handle.run_id:
+            scope_id = bound.get("scope_id")
+            if isinstance(scope_id, str) and scope_id:
+                return scope_id
+        return stable_scope_id("langgraph", handle.run_id, "$run")
+
     def _make_run_started(self, handle: RunHandle) -> RunStarted:
         framework = self._runtime_type
         run_id = handle.run_id
-        scope_id = stable_scope_id(framework, run_id)
+        scope_id = self._root_lifecycle_scope(handle)
         item_id = stable_item_id(framework, run_id, "$run")
         return RunStarted(
             schema_version=2,
@@ -794,13 +933,13 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
     ) -> RunCompleted:
         framework = self._runtime_type
         run_id = handle.run_id
-        scope_id = stable_scope_id(framework, run_id)
+        scope_id = self._root_lifecycle_scope(handle)
         item_id = stable_item_id(framework, run_id, "$run")
         output_refs: tuple[OutputRef, ...] = ()
         if run is not None and run.final_answer_item_id:
             output_refs = (
                 OutputRef(
-                    scope_id=scope_id,
+                    scope_id=stable_scope_id(framework, run_id),
                     item_id=run.final_answer_item_id,
                     part_id="text-0",
                 ),
@@ -827,7 +966,7 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
     def _make_run_canceled(self, handle: RunHandle, *, reason: str | None = None) -> RunCanceled:
         framework = self._runtime_type
         run_id = handle.run_id
-        scope_id = stable_scope_id(framework, run_id)
+        scope_id = self._root_lifecycle_scope(handle)
         item_id = stable_item_id(framework, run_id, "$run")
         return RunCanceled(
             schema_version=2,
@@ -848,7 +987,7 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
     ) -> RunInterrupted:
         framework = self._runtime_type
         run_id = handle.run_id
-        scope_id = stable_scope_id(framework, run_id)
+        scope_id = self._root_lifecycle_scope(handle)
         item_id = stable_item_id(framework, run_id, "$run")
         return RunInterrupted(
             schema_version=2,

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),
     }

ksadk/runtime_context.py

@@ -7,6 +7,79 @@ from typing import Any, Iterator, Mapping
 
 from ksadk.session_context import SessionContext
 
+TRUSTED_IDENTITY_METADATA_KEY = "_agentengine_verified_identity"
+
+
+def _identity_value(value: Any) -> str:
+    return value.strip() if isinstance(value, str) else ""
+
+
+@dataclass(frozen=True)
+class PlatformIdentityContext:
+    """Verified application identity carried through one runtime invocation.
+
+    Authentication adapters create this value after validating credentials and
+    tenant membership.  It is deliberately separate from caller metadata and
+    from the cloud ``account_id``/``user_id`` compatibility fields.
+    """
+
+    identity_namespace: str = ""
+    tenant_id: str = ""
+    subject_type: str = ""
+    subject_id: str = ""
+    actor_type: str = ""
+    actor_id: str = ""
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, Any] | None) -> "PlatformIdentityContext":
+        if not isinstance(payload, Mapping):
+            return cls()
+        return cls(
+            identity_namespace=_identity_value(payload.get("identity_namespace")),
+            tenant_id=_identity_value(payload.get("tenant_id")),
+            subject_type=_identity_value(payload.get("subject_type")),
+            subject_id=_identity_value(payload.get("subject_id")),
+            actor_type=_identity_value(payload.get("actor_type")),
+            actor_id=_identity_value(payload.get("actor_id")),
+        )
+
+    @property
+    def is_empty(self) -> bool:
+        return not any(self.to_payload().values())
+
+    @property
+    def is_complete(self) -> bool:
+        """Whether the four authorization-scoping fields are all present."""
+
+        return all(self.user_scope)
+
+    @property
+    def tenant_scope(self) -> tuple[str, str]:
+        return self.identity_namespace, self.tenant_id
+
+    @property
+    def user_scope(self) -> tuple[str, str, str, str]:
+        return (
+            self.identity_namespace,
+            self.tenant_id,
+            self.subject_type,
+            self.subject_id,
+        )
+
+    def to_payload(self) -> dict[str, str]:
+        return {
+            key: value
+            for key, value in {
+                "identity_namespace": self.identity_namespace,
+                "tenant_id": self.tenant_id,
+                "subject_type": self.subject_type,
+                "subject_id": self.subject_id,
+                "actor_type": self.actor_type,
+                "actor_id": self.actor_id,
+            }.items()
+            if value
+        }
+
 
 @dataclass
 class PlatformInvocationContext:
@@ -24,6 +97,7 @@ class PlatformInvocationContext:
     has_current_files: bool
     runner_type: str
     account_id: str = ""
+    identity: PlatformIdentityContext = field(default_factory=PlatformIdentityContext)
     metadata: dict[str, Any] = field(default_factory=dict)
     model: str | None = None
     model_options: dict[str, Any] | None = None
@@ -57,6 +131,8 @@ class PlatformInvocationContext:
 
         if self.session.tags or self.session.revision:
             payload["session"] = self.session.to_payload()
+        if not self.identity.is_empty:
+            payload["identity"] = self.identity.to_payload()
         return payload
 
 
@@ -125,6 +201,19 @@ def get_current_account_id(default: str = "") -> str:
     return str(context.account_id or default)
 
 
+def get_current_identity_context() -> PlatformIdentityContext:
+    context = get_current_invocation_context()
+    return context.identity if context is not None else PlatformIdentityContext()
+
+
+def get_current_tenant_id(default: str = "") -> str:
+    return str(get_current_identity_context().tenant_id or default)
+
+
+def get_current_subject_id(default: str = "") -> str:
+    return str(get_current_identity_context().subject_id or default)
+
+
 def set_current_invocation_context(
     context: PlatformInvocationContext | None,
 ) -> Token[PlatformInvocationContext | None]:
@@ -199,13 +288,23 @@ def get_current_session_tags() -> Mapping[str, str]:
     return get_current_session_context().tags
 
 
-def session_invocation_context(snapshot, *, agent_id="", user_id="", session_id="", runner_type=""):
+def session_invocation_context(
+    snapshot,
+    *,
+    agent_id="",
+    user_id="",
+    session_id="",
+    runner_type="",
+    tool_approval_mode="",
+    identity: PlatformIdentityContext | Mapping[str, Any] | None = None,
+):
     """Build the narrow context for kernel starts without conversation preprocessing."""
     return PlatformInvocationContext(
         agent_id=agent_id,
         user_id=user_id,
         session_id=session_id,
         runner_type=runner_type,
+        tool_approval_mode=tool_approval_mode,
         history=[],
         input_content=[],
         input_messages=[],
@@ -216,4 +315,9 @@ def session_invocation_context(snapshot, *, agent_id="", user_id="", session_id=
         current_attachment_results=[],
         has_current_files=False,
         session=SessionContext.from_payload(snapshot),
+        identity=(
+            identity
+            if isinstance(identity, PlatformIdentityContext)
+            else PlatformIdentityContext.from_payload(identity)
+        ),
     )