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

ksadk/runtime/executor.py

@@ -11,9 +11,10 @@ import hashlib
 import inspect
 import json
 from contextlib import suppress
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from typing import TYPE_CHECKING
 
+from ksadk.kernel.contracts import RuntimeCapabilityMatrix, SteerPayload
 from ksadk.runtime.adapter import (
     CancelResult,
     CheckpointDescriptor,
@@ -75,6 +76,7 @@ class RuntimeExecutor:
     ) -> None:
         self._registry = registry
         self._kernel_store = kernel_store
+        self._managed_a2a_bootstrap = None
         self._runs: dict[_HandleKey, _OwnedRun] = {}
         self._capability_adapters: dict[int, tuple[RuntimeLaunchContext, RuntimeAdapter]] = {}
 
@@ -86,7 +88,28 @@ class RuntimeExecutor:
         从而让普通执行、worker 与恢复走同一套 runtime-type 注册表。
         """
 
-        return self._registry.create(context)
+        if self._managed_a2a_bootstrap is not None:
+            declared = context.services.managed_a2a_bootstrap
+            if declared is not None and declared is not self._managed_a2a_bootstrap:
+                raise ValueError("A2A_BOOTSTRAP_IDENTITY_CONFLICT")
+            context = replace(context, services=replace(context.services,
+                managed_a2a_bootstrap=self._managed_a2a_bootstrap))
+        adapter = self._registry.create(context)
+        self._configure_managed_adapter(adapter)
+        return adapter
+
+    def configure_managed_a2a(self, bootstrap) -> None:
+        if self._runs:
+            raise RuntimeError("cannot configure managed A2A during active execution")
+        self._managed_a2a_bootstrap = bootstrap
+        for _, adapter in self._capability_adapters.values():
+            self._configure_managed_adapter(adapter)
+
+    def _configure_managed_adapter(self, adapter) -> None:
+        if self._managed_a2a_bootstrap is not None:
+            configure = getattr(adapter, "configure_managed_a2a", None)
+            if callable(configure):
+                configure(self._managed_a2a_bootstrap)
 
     async def resolve_run(self, run_id: str) -> DurableRun:
         """以 durable Store 为真相解析 Run；cache 只是 live handle 提示。"""
@@ -129,7 +152,7 @@ class RuntimeExecutor:
         agent initialization twice.
         """
 
-        adapter = self._registry.create(context)
+        adapter = self.create_adapter(context)
         await adapter.preflight()
         return RuntimeStartPreparation(context=context, adapter=adapter)
 
@@ -176,10 +199,49 @@ class RuntimeExecutor:
         owned = self._resolve(handle)
         return await owned.adapter.pause(owned.handle)
 
+    async def steer(self, handle: RunHandle, payload: SteerPayload) -> object | None:
+        """Deliver a live user correction to the adapter that owns this handle."""
+        if not isinstance(payload, SteerPayload) or payload.run_id not in {None, handle.run_id}:
+            raise ValueError("steering must target this attached run")
+        owned = self._resolve(handle)
+        return await owned.adapter.steer(owned.handle, payload)
+
+    async def guide(self, handle: RunHandle, payload: SteerPayload) -> object | None:
+        if not isinstance(payload, SteerPayload) or payload.run_id not in {None, handle.run_id}:
+            raise ValueError("guidance must target this attached run")
+        owned = self._resolve(handle)
+        return await owned.adapter.guide(owned.handle, payload)
+
+    async def child_tasks(self, handle: RunHandle) -> tuple[dict, ...]:
+        owned = self._resolve(handle)
+        return await owned.adapter.child_tasks(owned.handle)
+
+    async def child_execution_view(self, handle: RunHandle, child_run_id: str) -> dict:
+        owned = self._resolve(handle)
+        return await owned.adapter.child_execution_view(owned.handle, child_run_id)
+
+    async def cancel_child(self, handle: RunHandle, *, child_run_id: str, command_id: str):
+        owned = self._resolve(handle)
+        return await owned.adapter.cancel_child(owned.handle, child_run_id=child_run_id,
+                                               command_id=command_id)
+
+    async def promote_child(self, handle: RunHandle, *, child_run_id: str, command_id: str):
+        owned = self._resolve(handle)
+        return await owned.adapter.promote_child(owned.handle, child_run_id=child_run_id,
+                                                command_id=command_id)
+
     async def submit(self, handle: RunHandle, payload: ResumePayload) -> None:
         owned = self._resolve(handle)
         await owned.adapter.submit(owned.handle, payload)
 
+    async def send_child_input(self, handle: RunHandle, *, child_run_id: str, text: str,
+                               command_id: str, expected_goal_revision: int):
+        owned = self._resolve(handle)
+        return await owned.adapter.send_child_input(
+            owned.handle, child_run_id=child_run_id, text=text, command_id=command_id,
+            expected_goal_revision=expected_goal_revision,
+        )
+
     async def resume(
         self,
         handle: RunHandle,
@@ -246,6 +308,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 +317,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.create_adapter(context)
         restored = await adapter.attach(handle)
         if restored != handle:
             with suppress(Exception):
@@ -283,12 +353,40 @@ class RuntimeExecutor:
         handle = RunHandle.model_validate(handle_dump)
         if handle_digest(handle) != digest:
             raise ValueError(f"handle digest mismatch for run {run.run_id!r}")
-        return await self.attach(context, handle)
+        if self.is_attached(handle):
+            return handle
+        adapter = self.create_adapter(context)
+        prepare_record = getattr(adapter, "prepare_attach_record", None)
+        if callable(prepare_record):
+            # Some native runtimes need the scoped private checkpoint before
+            # attach can resolve a thread. Validate it before any native I/O.
+            await prepare_record(handle, run)
+        restored = await self.attach(
+            context, handle,
+            preparation=RuntimeStartPreparation(context=context, adapter=adapter),
+        )
+        adapter = self.adapter_for_handle(restored)
+        restore_record = getattr(adapter, "restore_run_record", None)
+        if callable(restore_record):
+            try:
+                await restore_record(restored, run)
+            except Exception:
+                await self.close(restored)
+                raise
+        return restored
 
     def is_attached(self, handle: RunHandle) -> bool:
         owned = self._runs.get(_handle_key(handle))
         return owned is not None and owned.handle == handle
 
+    def attached_capabilities(self, handle: RunHandle) -> RuntimeCapabilityMatrix:
+        """Read the actual attached adapter, without constructing a probe runtime."""
+        return self._resolve(handle).adapter.capabilities()
+
+    def adapter_for_handle(self, handle: RunHandle) -> RuntimeAdapter:
+        """Return the exact attached owner for subsequent control delivery."""
+        return self._resolve(handle).adapter
+
     def find_handle(
         self,
         runtime_type: str,
@@ -329,7 +427,7 @@ class RuntimeExecutor:
         key = id(context)
         cached = self._capability_adapters.get(key)
         if cached is None or cached[0] is not context:
-            adapter = self._registry.create(context)
+            adapter = self.create_adapter(context)
             self._capability_adapters[key] = (context, adapter)
             return adapter
         return cached[1]
@@ -366,7 +464,7 @@ class RuntimeExecutor:
         preparation: RuntimeStartPreparation | None,
     ) -> RuntimeAdapter:
         if preparation is None:
-            return self._registry.create(context)
+            return self.create_adapter(context)
         if preparation.consumed:
             raise RuntimeError("runtime start preparation was already consumed")
         if preparation.context != context:

ksadk/runtime/factory.py

@@ -32,11 +32,50 @@ from ksadk.plugins.providers.codex_native import (
     create_codex_adapter as _create_codex,
 )
 from ksadk.runners.base_runner import BaseRunner
-from ksadk.runtime.adapter import RuntimeAdapter, RuntimeRegistry, StartRequest
+from ksadk.runtime.adapter import (
+    RuntimeAdapter,
+    RuntimeAdapterFactory,
+    RuntimeRegistry,
+    StartRequest,
+)
 from ksadk.runtime.framework_adapters import ADKRuntimeAdapter, LangGraphRuntimeAdapter
 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 ModelGatewayHarnessReasoner
+    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=ModelGatewayHarnessReasoner(
+            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.
 
@@ -148,11 +187,14 @@ def _create_langgraph(context: RuntimeLaunchContext) -> RuntimeAdapter:
     return LangGraphRuntimeAdapter(_create_framework_runner(context, "langgraph"))
 
 
-def build_default_runtime_registry() -> RuntimeRegistry:
-    """注册内置 Codex、ADK 和 LangGraph Runtime Factory。"""
+def build_default_runtime_registry(
+    *, harness_factory: RuntimeAdapterFactory | None = None
+) -> RuntimeRegistry:
+    """注册内置 Runtime；宿主可为 Harness 注入已授权的 opt-in factory。"""
 
     registry = RuntimeRegistry()
     registry.register("codex", _create_codex)
+    registry.register("harness", harness_factory or _create_harness)
     registry.register("adk", _create_adk)
     registry.register("langgraph", _create_langgraph)
     return registry

ksadk/runtime/framework_adapters.py

@@ -11,7 +11,7 @@
 
 from __future__ import annotations
 
-from typing import Optional
+from typing import TYPE_CHECKING, Optional
 
 from ksadk.runners.base_runner import BaseRunner
 from ksadk.runtime.adapter import (
@@ -19,16 +19,100 @@ from ksadk.runtime.adapter import (
     ResumePayload,
     ResumeTarget,
     RunHandle,
+    RuntimeCapability,
+    StartRequest,
 )
-from ksadk.runtime.runner_adapter import RunnerRuntimeAdapter
+from ksadk.runtime.preprocessing import prepare_runtime_start
+from ksadk.runtime.runner_adapter import RunnerRuntimeAdapter, _ActiveRun
+from ksadk.runtime_context import TRUSTED_IDENTITY_METADATA_KEY, session_invocation_context
+
+if TYPE_CHECKING:
+    from ksadk.kernel.store import RunRecord
 
 
 class ADKRuntimeAdapter(RunnerRuntimeAdapter):
     """ADK 框架 adapter(forward-only resume)。"""
 
+    # Native resume must re-enter the graph to reconstruct live managed A2A
+    # waiters. Merely attaching a WAITING handle cannot accept their replies.
+    recovery_requires_stream = True
+
     def __init__(self, runner: BaseRunner) -> None:
         super().__init__(runner, runtime_type="adk")
 
+    async def restore_run_record(self, handle: RunHandle, record: "RunRecord") -> None:
+        """Rebuild private request context after native attachment has succeeded.
+
+        A handle alone cannot reconstruct the original identity or distinguish
+        native resume from a new user turn. Legacy records without a snapshot
+        must fail closed instead of silently starting another invocation.
+        """
+        if not self.is_handle_attached(handle):
+            raise ValueError("ADK request restoration requires native attachment")
+        raw = record.metadata.get("start_request")
+        if not isinstance(raw, dict):
+            raise ValueError("ADK durable run has no original start request")
+        request = StartRequest.model_validate(raw)
+        if (
+            request.session_id != record.session_id
+            or handle.session_id != record.session_id
+            or request.metadata.get("run_id") != record.run_id
+            or not record.metadata.get("command_id")
+            or request.metadata.get("command_id") != record.metadata.get("command_id")
+            or handle.run_id != record.metadata.get("runtime_run_id", record.run_id)
+        ):
+            raise ValueError("ADK original start request does not match durable run")
+        for key in ("user_id", "agent_id"):
+            if key in handle.native_ref and handle.native_ref[key] != getattr(request, key):
+                raise ValueError("ADK original identity does not match native handle")
+        if handle.run_id in self._active_runs:
+            raise ValueError("ADK durable restoration cannot replace a live invocation")
+        prepared = await prepare_runtime_start(request, self._runner)
+        run = _ActiveRun(invocation_id=handle.run_id, session_id=handle.session_id)
+        run.__dict__["_restored_from_record"] = True
+        run.__dict__["_start_request"] = request
+        if prepared is not None:
+            run.__dict__["_prepared_start"] = prepared
+        run.__dict__["_resume_input_override"] = {
+            **request.config,
+            "metadata": dict(request.metadata),
+            "checkpoint_resume": True,
+            "run_id": handle.run_id,
+            "invocation_id": handle.run_id,
+            "framework_ref": {},
+            "input": None,
+        }
+        snapshot = request.metadata.get("session_context")
+        identity = request.metadata.get(TRUSTED_IDENTITY_METADATA_KEY)
+        if snapshot is not None or identity is not None or request.metadata.get("tool_approval_mode"):
+            run.__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="adk",
+                identity=identity,
+                tool_approval_mode=str(request.metadata.get("tool_approval_mode") or ""),
+            )
+        self._active_runs[handle.run_id] = run
+
+    def capabilities(self):
+        matrix = super().capabilities()
+        bootstrap = getattr(self._runner, "_managed_a2a_bootstrap", None)
+        if bootstrap is None or not bootstrap.outbound_enabled:
+            return matrix
+        # The Kernel owns this live approval channel. Native ADK interaction
+        # delivery remains unavailable; admission is restricted to its ledger
+        # records, and Worker requires the original live invocation waiter.
+        return matrix.model_copy(
+            update={
+                "submit_interaction": RuntimeCapability(
+                    supported=True, mode="emulated", reason="managed_a2a_live_interaction_only"
+                ),
+                "interaction_mode": "live_submit",
+            }
+        )
+
     async def _resume_native(
         self,
         handle: RunHandle,
@@ -37,12 +121,16 @@ class ADKRuntimeAdapter(RunnerRuntimeAdapter):
     ) -> Optional[dict]:
         # ADK forward-only:恢复目标 = invocation_id。注入 adk_runner 真消费的
         # ``checkpoint_resume`` + ``framework_ref.adk.invocation_id`` → run_async(invocation_id)。
-        return {
+        runner_input = {
             "checkpoint_resume": True,
             "run_id": target.id,
             "framework_ref": {"adk": {"invocation_id": target.id}},
             "input": payload.data if payload else None,
         }
+        if payload is not None:
+            runner_input["resume_payload_kind"] = payload.kind
+            runner_input["resume_call_id"] = payload.call_id
+        return runner_input
 
     def _checkpoint_capability(self) -> CheckpointCapability:
         capability = super()._checkpoint_capability()
@@ -63,6 +151,86 @@ class LangGraphRuntimeAdapter(RunnerRuntimeAdapter):
     def __init__(self, runner: BaseRunner) -> None:
         super().__init__(runner, runtime_type="langgraph")
 
+    def requires_recovery_stream(self, handle: RunHandle) -> bool:
+        """A shared adapter only restarts the restored managed invocation."""
+        run = self._active_runs.get(handle.run_id)
+        return bool(
+            run is not None
+            and run.session_id == handle.session_id
+            and run.__dict__.get("_restored_from_record")
+            and handle.native_ref.get("managed_a2a_takeover") is True
+        )
+
+    @property
+    def requires_durable_start_request(self):
+        bootstrap = getattr(self._runner, "_managed_a2a_bootstrap", None)
+        return bootstrap is not None and bootstrap.outbound_enabled
+
+    def remember_managed_checkpoint(self, handle, event):
+        from ksadk.events.canonical import ContinuationCreated
+
+        bootstrap = getattr(self._runner, "_managed_a2a_bootstrap", None)
+        if (
+            bootstrap is None or not bootstrap.outbound_enabled
+            or not isinstance(event, ContinuationCreated)
+            or event.source.framework != "langgraph"
+            or event.source.metadata.get("managed_a2a_takeover") is not True
+            or event.continuation_kind != "graph_checkpoint" or not event.resumable
+        ):
+            return False
+        if not event.ref.get("checkpoint_id") or not event.ref.get("thread_id"):
+            raise ValueError("A2A_NATIVE_RECOVERY_CHECKPOINT_REQUIRED")
+        ref = {key: str(event.ref.get(key) or "")
+               for key in ("checkpoint_id", "thread_id", "checkpoint_ns")}
+        handle.native_ref.update(ref)
+        handle.native_ref["framework_ref"] = {"langgraph": ref}
+        handle.native_ref["managed_a2a_takeover"] = True
+        return True
+
+    async def restore_run_record(self, handle: RunHandle, record: "RunRecord") -> None:
+        if handle.native_ref.get("managed_a2a_takeover") is not True:
+            return
+        bootstrap = getattr(self._runner, "_managed_a2a_bootstrap", None)
+        if bootstrap is None or not bootstrap.outbound_enabled or not self.is_handle_attached(handle):
+            raise ValueError("LangGraph managed restoration requires native attachment")
+        raw = record.metadata.get("start_request")
+        if not isinstance(raw, dict):
+            raise ValueError("LangGraph durable run has no original start request")
+        request = StartRequest.model_validate(raw)
+        if (
+            request.session_id != record.session_id or handle.session_id != record.session_id
+            or request.metadata.get("run_id") != record.run_id
+            or not record.metadata.get("command_id")
+            or request.metadata.get("command_id") != record.metadata.get("command_id")
+            or handle.run_id != record.metadata.get("runtime_run_id", record.run_id)
+        ):
+            raise ValueError("LangGraph original start request does not match durable run")
+        for key in ("user_id", "agent_id"):
+            if key in handle.native_ref and handle.native_ref[key] != getattr(request, key):
+                raise ValueError("LangGraph original identity does not match native handle")
+        if handle.run_id in self._active_runs:
+            raise ValueError("LangGraph restoration cannot replace a live invocation")
+        prepared = await prepare_runtime_start(request, self._runner)
+        run = _ActiveRun(invocation_id=handle.run_id, session_id=handle.session_id)
+        run.__dict__.update(_restored_from_record=True, _start_request=request)
+        if prepared is not None:
+            run.__dict__["_prepared_start"] = prepared
+        run.__dict__["_resume_input_override"] = {
+            **request.config, "metadata": dict(request.metadata),
+            "checkpoint_resume": True, "_ksadk_managed_takeover": True,
+            "run_id": handle.run_id, "invocation_id": handle.run_id,
+            "framework_ref": handle.native_ref["framework_ref"], "input": None,
+        }
+        snapshot = request.metadata.get("session_context")
+        identity = request.metadata.get(TRUSTED_IDENTITY_METADATA_KEY)
+        if snapshot is not None or identity is not None or request.metadata.get("tool_approval_mode"):
+            run.__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="langgraph", identity=identity,
+                tool_approval_mode=str(request.metadata.get("tool_approval_mode") or ""),
+            )
+        self._active_runs[handle.run_id] = run
+
     def capabilities(self):  # noqa: ANN201
         """Advertise checkpoint interaction only when LangGraph can resume it.
 
@@ -73,13 +241,17 @@ class LangGraphRuntimeAdapter(RunnerRuntimeAdapter):
         """
 
         matrix = super().capabilities()
-        return matrix.model_copy(
-            update={
-                "interaction_mode": (
-                    "durable_resume" if matrix.resume.supported else "unavailable"
-                )
-            }
-        )
+        updates = {
+            "interaction_mode": "durable_resume" if matrix.resume.supported else "unavailable"
+        }
+        bootstrap = getattr(self._runner, "_managed_a2a_bootstrap", None)
+        if bootstrap is not None and bootstrap.outbound_enabled:
+            # Managed waiters are delivered by Kernel, independently of the
+            # native checkpoint provider. Keep native interrupt/resume intact.
+            updates["submit_interaction"] = RuntimeCapability(
+                supported=True, mode="emulated", reason="managed_a2a_live_interaction_only"
+            )
+        return matrix.model_copy(update=updates)
 
     async def _resume_native(
         self,
@@ -112,6 +284,8 @@ class LangGraphRuntimeAdapter(RunnerRuntimeAdapter):
                 "langgraph": {
                     "checkpoint_id": target.id,
                     "thread_id": str(handle.native_ref.get("thread_id") or handle.session_id),
+                    **({"checkpoint_ns": str(handle.native_ref["checkpoint_ns"])}
+                       if "checkpoint_ns" in handle.native_ref else {}),
                 }
             },
             "input": payload.data if payload else None,

ksadk/runtime/hosted_finalizer.py

@@ -1,15 +1,13 @@
-"""HostedTurnFinalizer —— 统一 Studio 与 canonical Runtime 的 turn 收尾（方案 §11.1 / P0）。
+"""HostedTurnFinalizer —— 可显式调用的 hosted turn 收尾组件（方案 §11.1 / P0）。
 
-之前 Studio `StudioRunService` 和 canonical `conversation_execution._finalize_hosted_turn`
-各自维护一套收尾逻辑（usage 回填、Context evidence、Memory Candidate、Trace），导致两条路径
-漂移（如 scope_id 硬编码 local-user、Memory 重复写）。本组件统一负责：
+本组件提供以下共用策略，但当前 Studio 和 canonical Runtime 尚未自动调用它：
 
 - actual usage 回填进 ContextPlan（planned vs actual 偏差可观测）。
 - capability mismatch 证据检测（方案 §6.1）。
-- Memory Candidate 抽取 + flush（据 MemoryPolicy，同一 Turn 不重复写）。
+- Memory Candidate 抽取 + flush（据 MemoryPolicy）。
 - 失败降级（best-effort，绝不阻断主链路，方案 §10.8）。
 
-Studio 与 canonical Runtime 都调用本组件，不再各自实现收尾。
+组件测试通过不能证明产品接线或跨调用幂等；调用方仍须负责运行时事实与写入回执。
 """
 
 from __future__ import annotations

ksadk/runtime/launch.py

@@ -24,6 +24,8 @@ class RuntimeServices:
 
     codex_client_factory: Callable[[], Any] | None = None
     runner_factory: Callable[[Any, str], Any] | None = None
+    # Process-owned dependency; never serialized into user/runtime config.
+    managed_a2a_bootstrap: Any | None = None
 
 
 @dataclass(frozen=True)

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,