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

ksadk/runtime/executor.py

@@ -8,6 +8,7 @@
 from __future__ import annotations
 
 import hashlib
+import inspect
 import json
 from contextlib import suppress
 from dataclasses import dataclass
@@ -75,6 +76,7 @@ class RuntimeExecutor:
         self._registry = registry
         self._kernel_store = kernel_store
         self._runs: dict[_HandleKey, _OwnedRun] = {}
+        self._capability_adapters: dict[int, tuple[RuntimeLaunchContext, RuntimeAdapter]] = {}
 
     def create_adapter(self, context: RuntimeLaunchContext) -> RuntimeAdapter:
         """从本 executor 的 registry 创建一个 adapter。
@@ -225,6 +227,18 @@ class RuntimeExecutor:
                     first_error = exc
             finally:
                 self._runs.pop(key, None)
+        for key, (_context, adapter) in list(self._capability_adapters.items()):
+            runner = getattr(adapter, "_runner", None)
+            close_runner = getattr(runner, "close", None)
+            if callable(close_runner):
+                try:
+                    result = close_runner()
+                    if inspect.isawaitable(result):
+                        await result
+                except BaseException as exc:
+                    if first_error is None:
+                        first_error = exc
+            self._capability_adapters.pop(key, None)
         if first_error is not None:
             raise first_error
 
@@ -295,7 +309,7 @@ class RuntimeExecutor:
     def native_capabilities(self, context: RuntimeLaunchContext) -> dict[str, object]:
         """Read the capability declaration from the registered Runtime implementation."""
 
-        adapter = self._registry.create(context)
+        adapter = self.capability_adapter(context)
         return dict(adapter.runtime.native_capabilities())
 
     def capability_matrix(self, context: RuntimeLaunchContext) -> dict[str, object]:
@@ -306,9 +320,25 @@ class RuntimeExecutor:
         modes can be exposed only when the selected runtime declares support.
         """
 
-        adapter = self._registry.create(context)
+        adapter = self.capability_adapter(context)
         return adapter.capabilities().model_dump(mode="json")
 
+    def capability_adapter(self, context: RuntimeLaunchContext) -> RuntimeAdapter:
+        """Return one stable, non-executing adapter for capability discovery."""
+
+        key = id(context)
+        cached = self._capability_adapters.get(key)
+        if cached is None or cached[0] is not context:
+            adapter = self._registry.create(context)
+            self._capability_adapters[key] = (context, adapter)
+            return adapter
+        return cached[1]
+
+    def capability_subject(self, context: RuntimeLaunchContext) -> object | None:
+        """Expose the runner whose async capability hooks feed persistence gating."""
+
+        return getattr(self.capability_adapter(context), "_runner", None)
+
     def registered_runtime_types(self) -> list[str]:
         """Expose Registry membership without leaking or duplicating the Registry."""
 
@@ -375,6 +405,51 @@ def _normalize_runtime_type(runtime_type: str) -> str:
     return runtime_type.strip().lower()
 
 
+def project_legacy_runtime_capabilities(
+    native: dict[str, object],
+    matrix: dict[str, object],
+) -> dict[str, object]:
+    """Fill the legacy PascalCase UI contract from the typed v1 matrix."""
+
+    projected = dict(native)
+
+    def capability(name: str) -> dict[str, object]:
+        value = matrix.get(name)
+        return dict(value) if isinstance(value, dict) else {}
+
+    cancel = capability("cancel")
+    checkpoint = capability("checkpoint")
+    resume = capability("resume")
+    projected.setdefault(
+        "CancelRun",
+        {
+            "Supported": cancel.get("supported") is True,
+            "Reason": str(cancel.get("reason") or ""),
+        },
+    )
+    projected.setdefault(
+        "Checkpoint",
+        {
+            "Supported": checkpoint.get("supported") is True,
+            "Backend": "native" if checkpoint.get("supported") is True else "none",
+            "Scope": "runtime",
+            "Durable": capability("durable_restore").get("supported") is True,
+            "SharedAcrossPods": False,
+            "ResumeMode": str(resume.get("mode") or "none"),
+            "Reason": str(checkpoint.get("reason") or ""),
+        },
+    )
+    projected.setdefault(
+        "ResumeRun",
+        {
+            "Supported": resume.get("supported") is True,
+            "ResumeMode": str(resume.get("mode") or "none"),
+            "Reason": str(resume.get("reason") or ""),
+        },
+    )
+    return projected
+
+
 def _handle_key(handle: RunHandle) -> _HandleKey:
     return (
         _normalize_runtime_type(handle.runtime_type),
@@ -389,4 +464,5 @@ __all__ = [
     "DurableRun",
     "RunNotFoundError",
     "handle_digest",
+    "project_legacy_runtime_capabilities",
 ]

ksadk/runtime/factory.py

@@ -2,17 +2,37 @@
 
 from __future__ import annotations
 
-import dataclasses
-import os
-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 StartRequest
-from ksadk.runtime.adapter import RuntimeAdapter, RuntimeRegistry
+from ksadk.runtime.adapter import RuntimeAdapter, RuntimeRegistry, StartRequest
 from ksadk.runtime.framework_adapters import ADKRuntimeAdapter, LangGraphRuntimeAdapter
 from ksadk.runtime.launch import RuntimeLaunchContext
 
@@ -49,46 +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
-    defaults["config"] = request_config
+    defaults["config"] = codex_request_config(context)
     return defaults
 
 
@@ -112,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
@@ -134,155 +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)
-    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)
-        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,
-    )
-
-
-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 _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

@@ -63,6 +63,24 @@ class LangGraphRuntimeAdapter(RunnerRuntimeAdapter):
     def __init__(self, runner: BaseRunner) -> None:
         super().__init__(runner, runtime_type="langgraph")
 
+    def capabilities(self):  # noqa: ANN201
+        """Advertise checkpoint interaction only when LangGraph can resume it.
+
+        ``RunnerRuntimeAdapter`` is intentionally conservative because a
+        generic checkpoint is not proof of original-interrupt delivery.  The
+        LangGraph adapter owns that mapping, so it is the only runner-family
+        adapter that may publish ``durable_resume``.
+        """
+
+        matrix = super().capabilities()
+        return matrix.model_copy(
+            update={
+                "interaction_mode": (
+                    "durable_resume" if matrix.resume.supported else "unavailable"
+                )
+            }
+        )
+
     async def _resume_native(
         self,
         handle: RunHandle,
@@ -101,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 ""),