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

ksadk/runtime/factory.py

@@ -2,17 +2,35 @@
 
 from __future__ import annotations
 
-import dataclasses
-import hashlib
-import os
-import re
-import shutil
-import tempfile
-from pathlib import Path
 from typing import Any
 
-from ksadk.codex.client import AsyncCodexClient
-from ksadk.codex.runtime import CodexRuntimeAdapter
+from ksadk.plugins.providers.codex_native import (
+    _apply_codex_overrides as _apply_codex_overrides,
+)
+from ksadk.plugins.providers.codex_native import (
+    _codex_home_key as _codex_home_key,
+)
+from ksadk.plugins.providers.codex_native import (
+    _codex_plugin_bootstrap as _codex_plugin_bootstrap,
+)
+from ksadk.plugins.providers.codex_native import (
+    _isolated_codex_home as _isolated_codex_home,
+)
+from ksadk.plugins.providers.codex_native import (
+    _manifest_has_network_mcp as _manifest_has_network_mcp,
+)
+from ksadk.plugins.providers.codex_native import (
+    _manifest_mcp_overrides as _manifest_mcp_overrides,
+)
+from ksadk.plugins.providers.codex_native import (
+    _materialize_bound_codex_skills as _materialize_bound_codex_skills,
+)
+from ksadk.plugins.providers.codex_native import (
+    codex_request_config,
+)
+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.framework_adapters import ADKRuntimeAdapter, LangGraphRuntimeAdapter
@@ -51,59 +69,7 @@ def kernel_start_request_defaults(context: RuntimeLaunchContext) -> dict[str, An
     if context.runtime_type != "codex":
         return defaults
 
-    prompt = str(config.get("prompt") or "").strip()
-    task_prompt = str(config.get("task_prompt") or "").strip()
-    base_instructions = prompt
-    if task_prompt:
-        base_instructions = f"{prompt}\n\n{task_prompt}" if prompt else task_prompt
-
-    raw_sandbox = str(config.get("sandbox") or "read_only").strip().lower()
-    raw_approval = str(config.get("approval_mode") or "").strip().lower()
-    approval_profiles = {
-        "ask": ("workspace-write", "manual"),
-        "risk": ("workspace-write", "auto_review"),
-        "full": ("full-access", "deny_all"),
-    }
-    sandbox_profiles = {
-        "read_only": ("read-only", "deny_all"),
-        "read-only": ("read-only", "deny_all"),
-        "workspace_write": ("workspace-write", "deny_all"),
-        "workspace-write": ("workspace-write", "deny_all"),
-        "workspace_write_auto": ("workspace-write", "auto_review"),
-        "workspace-write-auto": ("workspace-write", "auto_review"),
-        "full_access": ("full-access", "deny_all"),
-        "full-access": ("full-access", "deny_all"),
-    }
-    if raw_approval in approval_profiles:
-        sandbox, approval = approval_profiles[raw_approval]
-    else:
-        sandbox, default_approval = sandbox_profiles.get(raw_sandbox, ("read-only", "deny_all"))
-        approval = raw_approval or default_approval
-
-    request_config: dict[str, Any] = {
-        "sandbox_read_only": sandbox == "read-only",
-        "sandbox": sandbox,
-        "approval_mode": approval,
-        "cwd": str(context.project_dir),
-        "summary": "auto",
-        "ephemeral": False,
-    }
-    if base_instructions:
-        request_config["base_instructions"] = base_instructions
-    collaboration_mode = str(config.get("collaboration_mode") or "").strip().lower()
-    if collaboration_mode:
-        if collaboration_mode not in {"default", "plan"}:
-            raise ValueError("Codex collaboration_mode must be default or plan")
-        request_config["collaboration_mode"] = collaboration_mode
-    goal_objective = str(config.get("goal_objective") or "").strip()
-    if goal_objective:
-        request_config["goal_objective"] = goal_objective
-    raw_skills = config.get("skills")
-    if isinstance(raw_skills, (list, tuple)):
-        request_config["skills"] = [
-            dict(item) for item in raw_skills if isinstance(item, dict)
-        ]
-    defaults["config"] = request_config
+    defaults["config"] = codex_request_config(context)
     return defaults
 
 
@@ -127,9 +93,7 @@ def apply_runtime_start_request_defaults(
     default_model = str(defaults.get("model") or "").strip() or None
     requested_model = str(request.model or "").strip()
     allowed_models = {
-        str(item).strip()
-        for item in (defaults.get("allowed_models") or [])
-        if str(item).strip()
+        str(item).strip() for item in (defaults.get("allowed_models") or []) if str(item).strip()
     }
     selected_model = (
         requested_model
@@ -149,214 +113,6 @@ def apply_runtime_start_request_defaults(
     )
 
 
-def _manifest_mcp_overrides(config: dict[str, Any]) -> list[str]:
-    """Translate declarative MCP bindings into native Codex config keys."""
-
-    overrides: list[str] = []
-    servers = config.get("mcp_servers") or []
-    if not isinstance(servers, (list, tuple)):
-        return overrides
-    for server in servers:
-        if not isinstance(server, dict):
-            continue
-        name = str(server.get("name") or "").strip()
-        url = str(server.get("url") or "").strip()
-        if not name or not url:
-            continue
-        overrides.append(f"mcp_servers.{name}.url={url}")
-        env_key = str(server.get("env_key") or "").strip()
-        if env_key:
-            overrides.append(f"mcp_servers.{name}.bearer_token_env_var={env_key}")
-    return overrides
-
-
-def _create_codex(context: RuntimeLaunchContext) -> RuntimeAdapter:
-    client_factory = context.services.codex_client_factory or AsyncCodexClient
-    config = dict(context.config)
-    bound_skill_paths: dict[str, str] = {}
-    overrides = list(config.get("codex_overrides") or [])
-    manifest_mcp_overrides = _manifest_mcp_overrides(config)
-    overrides.extend(item for item in manifest_mcp_overrides if item not in overrides)
-    projected_config = kernel_start_request_defaults(context).get("config") or {}
-    if manifest_mcp_overrides and projected_config.get("sandbox") == "workspace-write":
-        network_override = "sandbox_workspace_write.network_access=true"
-        if network_override not in overrides:
-            overrides.append(network_override)
-    # Studio's default collaboration mode must expose Codex's structured
-    # request_user_input tool; the upstream feature is intentionally off by
-    # default outside Plan mode.  This stays process-local to the isolated
-    # runtime and does not mutate the user's global Codex configuration.
-    interaction_override = "features.default_mode_request_user_input=true"
-    if interaction_override not in overrides:
-        overrides.append(interaction_override)
-    try:
-        from openai_codex import CodexConfig
-
-        base_cfg = CodexConfig()
-        if overrides:
-            base_cfg = dataclasses.replace(
-                base_cfg,
-                config_overrides=tuple(getattr(base_cfg, "config_overrides", ()) or ())
-                + tuple(str(o) for o in overrides),
-            )
-        env = dict(getattr(base_cfg, "env", None) or {})
-        isolated_home = _isolated_codex_home(context.project_dir)
-        bound_skill_paths = _materialize_bound_codex_skills(
-            isolated_home, config.get("skills")
-        )
-        env.setdefault("CODEX_HOME", str(isolated_home))
-        # HOME 级隔离：codex app-server 还会按约定扫 ~/.agents/skills、
-        # ~/.claude/skills 等宿主目录，仅设 CODEX_HOME 挡不住。隔离 HOME 后这些
-        # 路径全部落在工作区内，宿主 skills/MCP/凭证不再进入 Agent 上下文。
-        # 设 KSADK_CODEX_ISOLATE_HOME=0 可关闭（调试用）。
-        if os.environ.get("KSADK_CODEX_ISOLATE_HOME", "1") != "0":
-            env.setdefault("HOME", str(isolated_home))
-        # 运行期解析出的凭证值（如 MCP bearer_token_env_var 所需）注入子进程环境
-        env.update({str(k): str(v) for k, v in (context.config.get("env") or {}).items()})
-        base_cfg = dataclasses.replace(base_cfg, env=env)
-        try:
-            client: Any = client_factory(config=base_cfg)
-        except TypeError:
-            # 自定义/测试工厂可能不接受 config 参数：退化为无参构造，
-            # config_overrides 事后注入（自定义工厂自行承担 env 隔离）。
-            client = client_factory()
-            if overrides:
-                _apply_codex_overrides(client, overrides)
-    except ImportError:
-        client: Any = client_factory()
-        if overrides:
-            _apply_codex_overrides(client, overrides)
-    timeout = context.config.get("turn_timeout_seconds")
-    request_defaults = kernel_start_request_defaults(context)
-    request_config = request_defaults.get("config") or {}
-    sandbox_read_only = (
-        bool(context.config["sandbox_read_only"])
-        if "sandbox_read_only" in context.config
-        else bool(request_config.get("sandbox_read_only", True))
-    )
-    return CodexRuntimeAdapter(
-        client,
-        sandbox_read_only=sandbox_read_only,
-        turn_timeout_seconds=float(timeout) if timeout is not None else None,
-        bound_skill_paths=bound_skill_paths,
-    )
-
-
-def _isolated_codex_home(project_dir: Any) -> Path:
-    """Studio 运行 Agent 使用工作区级隔离 CODEX_HOME。
-
-    避免 codex app-server 继承宿主环境（~/.codex / ~/.wework/codex）里的
-    skills、MCP 配置、插件与凭证，污染 Agent 上下文甚至泄漏宿主能力。
-    可用 KSADK_CODEX_HOME 显式覆盖。
-    """
-    override = os.environ.get("KSADK_CODEX_HOME")
-    if override:
-        home = Path(override).expanduser()
-        home.mkdir(parents=True, exist_ok=True)
-        return home
-
-    # Source bundles are deliberately mounted read-only in managed runtimes.
-    # Keep the preferred workspace-local isolation for local development, but
-    # never make a Codex turn depend on being able to mutate that bundle.
-    workspace_home = Path(str(project_dir)) / ".agentkit" / "codex-home"
-    try:
-        workspace_home.mkdir(parents=True, exist_ok=True)
-        return workspace_home
-    except OSError:
-        pass
-
-    # The managed runtime already provides a per-workload writable state
-    # volume.  Derive from its explicit directory first, then from the
-    # session-store path for backward-compatible images.  /tmp is a final
-    # process-local fallback for custom read-only launchers.
-    state_dir = os.environ.get("KSADK_RUNTIME_STATE_DIR")
-    session_path = os.environ.get("KSADK_SESSION_PATH")
-    fallback_root = (
-        Path(state_dir)
-        if state_dir
-        else Path(session_path).expanduser().parent
-        if session_path
-        else Path(tempfile.gettempdir()) / "ksadk-runtime-state"
-    )
-    fallback_home = fallback_root / "codex-home"
-    fallback_home.mkdir(parents=True, exist_ok=True)
-    return fallback_home
-
-
-def _materialize_bound_codex_skills(
-    codex_home: Path, value: Any
-) -> dict[str, str]:
-    """Expose immutable Bundle Skills through Codex's native skill catalog.
-
-    Passing an arbitrary ``SkillInput`` path is accepted by the Python SDK but
-    ignored by the real App Server unless the Skill is discoverable by the
-    native host.  Copy each content-addressed Bundle Skill into the isolated
-    CODEX_HOME so the host owns discovery while the Bundle remains read-only.
-    Content-addressed directory names avoid overwriting user-managed Skills
-    when an explicit KSADK_CODEX_HOME is used.
-    """
-
-    if not isinstance(value, (list, tuple)):
-        return {}
-    skills_root = codex_home / "skills"
-    skills_root.mkdir(parents=True, exist_ok=True)
-    installed: dict[str, str] = {}
-    for item in value:
-        if not isinstance(item, dict):
-            continue
-        name = str(item.get("name") or "").strip()
-        raw_path = str(item.get("path") or "").strip()
-        if not name or not raw_path:
-            continue
-        skill_file = Path(raw_path).resolve()
-        if skill_file.name != "SKILL.md" or not skill_file.is_file():
-            continue
-        source_dir = skill_file.parent
-        digest = hashlib.sha256()
-        for source in sorted(path for path in source_dir.rglob("*") if path.is_file()):
-            digest.update(source.relative_to(source_dir).as_posix().encode("utf-8"))
-            digest.update(b"\0")
-            digest.update(source.read_bytes())
-            digest.update(b"\0")
-        safe_name = re.sub(r"[^A-Za-z0-9._-]+", "-", name).strip(".-") or "skill"
-        target = skills_root / f"ksadk-{digest.hexdigest()[:16]}-{safe_name}"
-        if target.is_dir():
-            installed[name] = str(target / "SKILL.md")
-            continue
-        staging = Path(tempfile.mkdtemp(prefix=".ksadk-skill-", dir=skills_root))
-        try:
-            shutil.copytree(source_dir, staging, dirs_exist_ok=True)
-            try:
-                staging.replace(target)
-            except FileExistsError:
-                pass
-        finally:
-            if staging.exists():
-                shutil.rmtree(staging)
-        installed[name] = str(target / "SKILL.md")
-    return installed
-
-
-def _apply_codex_overrides(client: Any, overrides: Any) -> None:
-    """Append MCP server --config overrides to the client's CodexConfig."""
-    try:
-        from openai_codex import CodexConfig
-    except ImportError:
-        return
-    # ksadk AsyncCodexClient -> AsyncCodex -> inner AsyncCodexClient.config
-    inner_codex = getattr(client, "_codex", None)
-    inner_client = getattr(inner_codex, "_client", None) or inner_codex
-    cfg = getattr(inner_client, "config", None)
-    if cfg is None or not isinstance(cfg, CodexConfig):
-        return
-    base_overrides = tuple(getattr(cfg, "config_overrides", ()) or ())
-    new_overrides = tuple(str(o) for o in overrides if o not in base_overrides)
-    if not new_overrides:
-        return
-    new_cfg = dataclasses.replace(cfg, config_overrides=base_overrides + new_overrides)
-    setattr(inner_client, "config", new_cfg)
-
-
 def _create_framework_runner(context: RuntimeLaunchContext, runtime_type: str) -> BaseRunner:
     try:
         from ksadk.runners.patch_langchain import apply_patch

ksadk/runtime/framework_adapters.py

@@ -119,6 +119,29 @@ class LangGraphRuntimeAdapter(RunnerRuntimeAdapter):
 
     def _checkpoint_capability(self) -> CheckpointCapability:
         capability = super()._checkpoint_capability()
+        if not capability.supported:
+            describe = getattr(self._runner, "describe_checkpoint_capability", None)
+            try:
+                raw = dict(describe()) if callable(describe) else {}
+            except Exception:  # noqa: BLE001
+                raw = {}
+            if (
+                str(raw.get("Scope") or "").strip().lower() == "process_local"
+                and str(raw.get("Backend") or "").strip().lower() in {"memory", "sqlite"}
+            ):
+                # The runner correctly refuses to advertise this checkpoint to
+                # hosted callers because it is not durable across a process
+                # restart. This adapter only resumes an attached in-process
+                # handle, for which LangGraph's memory saver is sufficient.
+                capability = capability.model_copy(
+                    update={
+                        "supported": True,
+                        "reason": (
+                            "Checkpoint resume is limited to the current process; "
+                            "it is not durable across restarts or pods"
+                        ),
+                    }
+                )
         if not capability.supported:
             return capability
         return capability.model_copy(

ksadk/runtime/preprocessing.py

@@ -19,6 +19,7 @@ from ksadk.runtime.adapter import (
     StartRequest,
 )
 from ksadk.runtime_context import PlatformInvocationContext
+from ksadk.session_context import split_session_context
 
 
 @dataclass
@@ -58,17 +59,21 @@ async def prepare_runtime_start(request: StartRequest, runner: Any) -> PreparedR
     outer_metadata = {
         key: value
         for key, value in request.metadata.items()
-        if key != CONVERSATION_PREPROCESSING_METADATA_KEY
+        if key not in {CONVERSATION_PREPROCESSING_METADATA_KEY, "session_context"}
     }
     request_metadata = {**outer_metadata, **conversation.request_metadata}
     messages = conversation.messages or _fallback_messages(request.input)
     raw_prepared = (conversation.model_extra or {}).get("prepared_turn")
     if isinstance(raw_prepared, Mapping):
         prepared = PreparedConversationTurn(**dict(raw_prepared))
-        prepared.request_metadata = {
+        merged_metadata = {
             **prepared.request_metadata,
             **request_metadata,
         }
+        snapshot, prepared.request_metadata = split_session_context(merged_metadata)
+        controls = merged_metadata.get("agentengine")
+        if isinstance(controls, Mapping) and "session_context" in controls:
+            prepared.session_context = snapshot.to_payload()
     else:
         prepared = await build_run_input(
             agent_id=str(request.agent_id or "agent"),
@@ -114,7 +119,10 @@ async def prepare_runtime_start(request: StartRequest, runner: Any) -> PreparedR
         ambient_contexts["memory_recall_events"] = list(prepared.memory_recall_events)
     else:
         prepared.memory_recall_events = ambient_contexts.get("memory_recall_events", [])
+    from ksadk.session_context import SessionContext
+
     runtime_context = PlatformInvocationContext(
+        session=SessionContext.from_payload(prepared.session_context),
         agent_id=str(request.agent_id or "agent"),
         user_id=request.user_id,
         account_id=str(conversation.account_id or ""),

ksadk/runtime/runner_adapter.py

@@ -54,6 +54,7 @@ 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
 
 logger = logging.getLogger(__name__)
 
@@ -138,6 +139,10 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
 
     # ---- 框架钩子(子类按需 override) ----
 
+    def _requires_stable_stream_context(self) -> bool:
+        """Whether one Task must own the runner generator for its lifetime."""
+        return self._runtime_type == "adk"
+
     def capabilities(self) -> RuntimeCapabilityMatrix:
         """诚实矩阵:cancel 经 asyncio 任务打断(emulated,过 conformance);
         resume/checkpoint 依赖 runner 声明的原生 checkpoint;attach/durable_restore
@@ -170,8 +175,12 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
             submit_interaction=_unavailable("runtime_no_live_interaction_channel"),
             attach=(
                 RuntimeCapability(supported=True, mode="native")
-                if attach_seam
-                else _unavailable("runner_no_durable_attach_seam")
+                if durable_supported
+                else _unavailable(
+                    "runner_no_durable_attach_seam"
+                    if not attach_seam
+                    else "attach_requires_cross_process_checkpoint"
+                )
             ),
             steer=_unavailable("runtime_no_native_steer"),
             inject=_unavailable("runtime_no_native_inject"),
@@ -272,6 +281,15 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
         self._active_runs[run_id] = _ActiveRun(invocation_id=run_id, session_id=request.session_id)
         # 暂存 start 输入,供 stream() 使用。
         self._active_runs[run_id].__dict__["_start_request"] = request
+        snapshot = request.metadata.get("session_context")
+        if snapshot 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,
+            )
         if prepared_start is not None:
             self._active_runs[run_id].__dict__["_prepared_start"] = prepared_start
         return handle
@@ -307,6 +325,7 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
                 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)
         if inspect.isawaitable(restored):
             restored = await restored
@@ -365,11 +384,14 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
         self._require_native_checkpoint_capability()
         self._known_runs.add(handle.run_id)
         prepared_start: PreparedRuntimeStart | None = None
+        resume_invocation_id = handle.run_id
         raw_start_request = handle.native_ref.pop(RESUME_START_REQUEST_NATIVE_KEY, None)
         if isinstance(raw_start_request, Mapping):
-            prepared_start = await prepare_runtime_start(
-                StartRequest.model_validate(raw_start_request), self._runner
+            resume_request = StartRequest.model_validate(raw_start_request)
+            resume_invocation_id = str(
+                resume_request.metadata.get("invocation_id") or handle.run_id
             )
+            prepared_start = await prepare_runtime_start(resume_request, self._runner)
         # _resume_native 返回的 runner_input 覆盖存到 run 上,下一次 stream() 经
         # _build_runner_input 消费,以框架原生方式真驱动恢复。
         override = await self._resume_native(handle, target, payload)
@@ -392,7 +414,7 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
                 return handle
             if resume_key in self._consumed_resumes:
                 self._active_runs[handle.run_id] = _ActiveRun(
-                    invocation_id=handle.run_id,
+                    invocation_id=resume_invocation_id,
                     session_id=handle.session_id,
                     resume_key=resume_key,
                     resume_fingerprint=resume_fingerprint,
@@ -409,11 +431,19 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
             raise ValueError(f"run {handle.run_id!r} already has an active or pending resume")
 
         run = _ActiveRun(
-            invocation_id=handle.run_id,
+            invocation_id=resume_invocation_id,
             session_id=handle.session_id,
             resume_key=resume_key,
             resume_fingerprint=resume_fingerprint,
         )
+        if payload is not None and payload.session_context is not None:
+            run.__dict__["_tag_context"] = session_invocation_context(
+                payload.session_context,
+                agent_id=str(handle.native_ref.get("agent_id") or ""),
+                user_id=str(handle.native_ref.get("user_id") or ""),
+                session_id=handle.session_id,
+                runner_type=self._runtime_type,
+            )
         if prepared_start is not None:
             run.__dict__["_prepared_start"] = prepared_start
         if override:
@@ -509,23 +539,30 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
         if run is None:
             run = _ActiveRun(invocation_id=handle.run_id, session_id=handle.session_id)
             self._active_runs[handle.run_id] = run
+        event_handle = (
+            handle
+            if run.invocation_id == handle.run_id
+            else handle.model_copy(update={"run_id": run.invocation_id})
+        )
 
         # 消费 pending cancel:start 时若已记 pending,立即中断该 turn。
         if handle.run_id in self._pending_cancels:
             self._pending_cancels.discard(handle.run_id)
-            yield self._make_run_canceled(handle, reason=CancelResult.PENDING_CANCEL_RECORDED.value)
+            yield self._make_run_canceled(
+                event_handle, reason=CancelResult.PENDING_CANCEL_RECORDED.value
+            )
             return
 
         if run.skip_runner:
             run.done = True
             self._active_runs.pop(handle.run_id, None)
-            yield self._make_run_completed(handle)
+            yield self._make_run_completed(event_handle)
             return
 
         if run.resume_key is not None:
             self._consumed_resumes.add(run.resume_key)
 
-        yield self._make_run_started(handle)
+        yield self._make_run_started(event_handle)
 
         request = run.__dict__.get("_start_request")
         runner_input = self._build_runner_input(handle, request)
@@ -533,7 +570,7 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
         terminal_event_seen = False
         approval_interrupted = False
         try:
-            gen = self._map_runner_stream(handle, runner_input)
+            gen = self._map_runner_stream(event_handle, runner_input, active_run=run)
             run.stream = gen
             async for event in gen:
                 yield event
@@ -560,18 +597,38 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
 
             if run.interrupt_event.is_set() and not terminal_event_seen:
                 yield self._make_run_canceled(
-                    handle, reason=CancelResult.INTERRUPTED_ACTIVE_TURN.value
+                    event_handle, reason=CancelResult.INTERRUPTED_ACTIVE_TURN.value
                 )
             elif approval_interrupted and not terminal_event_seen:
-                yield self._make_run_interrupted(handle, reason="input_required")
+                yield self._make_run_interrupted(event_handle, reason="input_required")
             elif not terminal_event_seen:
-                yield self._make_run_completed(handle, run=run, metrics=run.completion_metrics)
+                yield self._make_run_completed(
+                    event_handle, run=run, metrics=run.completion_metrics
+                )
         finally:
             run.stream = None
             run.done = True
             self._active_runs.pop(handle.run_id, None)
 
     def _build_runner_input(self, handle: RunHandle, request: Optional[StartRequest]) -> dict:
+        result = self._build_base_runner_input(handle, request)
+        run = self._active_runs.get(handle.run_id)
+        context = run.__dict__.get("_tag_context") if run is not None else None
+        if context is not None:
+            existing_context = result.get("platform_context")
+            result["platform_context"] = (
+                {**existing_context, "session": context.session.to_payload()}
+                if isinstance(existing_context, dict)
+                else context.to_payload()
+            )
+            result["metadata"] = {
+                key: value
+                for key, value in dict(result.get("metadata") or {}).items()
+                if key != "session_context"
+            }
+        return result
+
+    def _build_base_runner_input(self, handle: RunHandle, request: Optional[StartRequest]) -> dict:
         # resume 覆盖优先:_resume_native 注入的 checkpoint_resume + framework_ref
         # 直接作为 runner 输入,驱动框架原生恢复。
         run = self._active_runs.get(handle.run_id)
@@ -588,7 +645,9 @@ class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
                 {
                     "input": override.get("input"),
                     "session_id": handle.session_id,
-                    "invocation_id": 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_context.py

@@ -3,7 +3,9 @@ from __future__ import annotations
 from contextlib import contextmanager
 from contextvars import ContextVar, Token
 from dataclasses import dataclass, field
-from typing import Any, Iterator
+from typing import Any, Iterator, Mapping
+
+from ksadk.session_context import SessionContext
 
 
 @dataclass
@@ -30,9 +32,10 @@ class PlatformInvocationContext:
     # Request-scoped runtime control. It is intentionally separate from
     # public caller metadata so built-in tools can enforce it consistently.
     tool_approval_mode: str = ""
+    session: SessionContext = field(default_factory=SessionContext)
 
     def to_payload(self) -> dict[str, Any]:
-        return {
+        payload = {
             "agent_id": self.agent_id,
             "user_id": self.user_id,
             "account_id": self.account_id,
@@ -52,6 +55,10 @@ class PlatformInvocationContext:
             "model_options": dict(self.model_options or {}),
         }
 
+        if self.session.tags or self.session.revision:
+            payload["session"] = self.session.to_payload()
+        return payload
+
 
 @dataclass
 class ToolExecutionContext:
@@ -179,3 +186,34 @@ def tool_execution_scope(
         yield context
     finally:
         reset_current_tool_execution_context(token)
+
+
+def get_current_session_context() -> SessionContext:
+    """Read the current immutable snapshot in LangChain, LangGraph or ADK code."""
+    context = get_current_invocation_context()
+    return context.session if context is not None else SessionContext()
+
+
+def get_current_session_tags() -> Mapping[str, str]:
+    """Return read-only business labels; these are not authorization claims."""
+    return get_current_session_context().tags
+
+
+def session_invocation_context(snapshot, *, agent_id="", user_id="", session_id="", runner_type=""):
+    """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,
+        history=[],
+        input_content=[],
+        input_messages=[],
+        input_parts=[],
+        attachments=[],
+        attachment_results=[],
+        current_attachments=[],
+        current_attachment_results=[],
+        has_current_files=False,
+        session=SessionContext.from_payload(snapshot),
+    )