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

ksadk/runtime/executor.py

@@ -1,9 +1,17 @@
-"""RuntimeAdapter 的统一生命周期路由与 Handle 所有权。"""
+"""RuntimeAdapter 的统一生命周期路由与 Handle 所有权。
+
+``_runs`` 只是当前进程的 handle cache：status、幂等、恢复资格和 owner 判断的
+真相在 ``AgentKernelStore`` 的 durable Run 行；cache miss 不能等价于 Run 不
+存在（见 :meth:`RuntimeExecutor.resolve_run`）。
+"""
 
 from __future__ import annotations
 
+import hashlib
+import json
 from contextlib import suppress
 from dataclasses import dataclass
+from typing import TYPE_CHECKING
 
 from ksadk.runtime.adapter import (
     CancelResult,
@@ -18,9 +26,28 @@ from ksadk.runtime.adapter import (
 )
 from ksadk.runtime.launch import RuntimeLaunchContext
 
+if TYPE_CHECKING:  # pragma: no cover - import cycle guard
+    from ksadk.kernel.store import AgentKernelStore, RunRecord
+
 _HandleKey = tuple[str, str, str]
 
 
+class RunNotFoundError(LookupError):
+    """durable Store 中不存在该 Run；cache miss 不是证据，必须查 Store。"""
+
+    def __init__(self, run_id: str) -> None:
+        super().__init__(f"durable run not found: {run_id!r}")
+        self.run_id = run_id
+
+
+@dataclass
+class DurableRun:
+    """Store 中的 Run 真相 + 本进程 live handle（可能未 attach）。"""
+
+    run: "RunRecord"
+    live_handle: RunHandle | None = None
+
+
 @dataclass
 class _OwnedRun:
     adapter: RuntimeAdapter
@@ -39,10 +66,58 @@ class RuntimeStartPreparation:
 class RuntimeExecutor:
     """让每个 Handle 始终回到创建或恢复它的 Adapter 实例。"""
 
-    def __init__(self, registry: RuntimeRegistry) -> None:
+    def __init__(
+        self,
+        registry: RuntimeRegistry,
+        *,
+        kernel_store: "AgentKernelStore | None" = None,
+    ) -> None:
         self._registry = registry
+        self._kernel_store = kernel_store
         self._runs: dict[_HandleKey, _OwnedRun] = {}
 
+    def create_adapter(self, context: RuntimeLaunchContext) -> RuntimeAdapter:
+        """从本 executor 的 registry 创建一个 adapter。
+
+        生产 composition root 需要为 AgentKernelWorker 提供 adapter factory。
+        暴露这个窄入口可避免其绕过当前 RuntimeExecutor、另建默认 registry，
+        从而让普通执行、worker 与恢复走同一套 runtime-type 注册表。
+        """
+
+        return self._registry.create(context)
+
+    async def resolve_run(self, run_id: str) -> DurableRun:
+        """以 durable Store 为真相解析 Run；cache 只是 live handle 提示。"""
+
+        durable = None
+        if self._kernel_store is not None:
+            durable = await self._kernel_store.load_run(run_id)
+        if durable is None:
+            # 没有 Store 时只能退回 cache；cache miss 不等价于 Run 不存在，
+            # 因此未配置 kernel_store 的旧调用方仍需显式处理缺失。
+            if self._kernel_store is not None:
+                raise RunNotFoundError(run_id)
+            cached = next(
+                (
+                    owned.handle
+                    for (_, rid, _), owned in self._runs.items()
+                    if rid == run_id
+                ),
+                None,
+            )
+            if cached is None:
+                raise RunNotFoundError(run_id)
+            return DurableRun(run=_cache_only_record(cached), live_handle=cached)
+        live = next(
+            (
+                owned.handle
+                for (_, rid, _), owned in self._runs.items()
+                if rid == run_id
+            ),
+            None,
+        )
+        return DurableRun(run=durable, live_handle=live)
+
     async def prepare_start(self, context: RuntimeLaunchContext) -> RuntimeStartPreparation:
         """Preflight a fresh adapter and retain it for the matching ``start``.
 
@@ -173,6 +248,29 @@ class RuntimeExecutor:
         self._record_owner(adapter, restored)
         return restored
 
+    async def attach_record(
+        self,
+        run: "RunRecord",
+        context: RuntimeLaunchContext,
+    ) -> RunHandle:
+        """Attach a run from its durable record (cross-process recovery path).
+
+        一个新进程没有任何 ``_runs`` 缓存；durable Run 行的 ``handle`` +
+        ``handle_digest`` 是唯一恢复线索。digest 不匹配即拒绝——被篡改或
+        版本漂移的 handle 绝不能接回 live 执行。
+        """
+
+        handle_dump = run.metadata.get("handle")
+        digest = run.metadata.get("handle_digest")
+        if not isinstance(handle_dump, dict) or not isinstance(digest, str):
+            raise ValueError(
+                f"durable run {run.run_id!r} has no durably attachable handle"
+            )
+        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)
+
     def is_attached(self, handle: RunHandle) -> bool:
         owned = self._runs.get(_handle_key(handle))
         return owned is not None and owned.handle == handle
@@ -200,6 +298,17 @@ class RuntimeExecutor:
         adapter = self._registry.create(context)
         return dict(adapter.runtime.native_capabilities())
 
+    def capability_matrix(self, context: RuntimeLaunchContext) -> dict[str, object]:
+        """Return the canonical typed RuntimeCapabilityMatrix/v1 projection.
+
+        ``native_capabilities`` is a compatibility view whose shape varies by
+        framework. UI clients need the versioned matrix so optional execution
+        modes can be exposed only when the selected runtime declares support.
+        """
+
+        adapter = self._registry.create(context)
+        return adapter.capabilities().model_dump(mode="json")
+
     def registered_runtime_types(self) -> list[str]:
         """Expose Registry membership without leaking or duplicating the Registry."""
 
@@ -236,6 +345,32 @@ class RuntimeExecutor:
         return preparation.adapter
 
 
+def handle_digest(handle: RunHandle) -> str:
+    """Stable digest of one durable handle (cross-process recovery evidence)."""
+
+    payload = json.dumps(
+        handle.model_dump(mode="json"),
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+    ).encode("utf-8")
+    return hashlib.sha256(payload).hexdigest()
+
+
+def _cache_only_record(handle: RunHandle) -> "RunRecord":
+    from ksadk.kernel.state import RunState
+    from ksadk.kernel.store import RunRecord
+
+    # 无 kernel_store 的旧调用方路径：state 只能标记 pending，真相以 Store 为准。
+    return RunRecord(
+        run_id=handle.run_id,
+        agent_instance_id="",
+        session_id=handle.session_id,
+        state=RunState.PENDING,
+        metadata={"source": "process_cache", "runtime_type": handle.runtime_type},
+    )
+
+
 def _normalize_runtime_type(runtime_type: str) -> str:
     return runtime_type.strip().lower()
 
@@ -248,4 +383,10 @@ def _handle_key(handle: RunHandle) -> _HandleKey:
     )
 
 
-__all__ = ["RuntimeExecutor", "RuntimeStartPreparation"]
+__all__ = [
+    "RuntimeExecutor",
+    "RuntimeStartPreparation",
+    "DurableRun",
+    "RunNotFoundError",
+    "handle_digest",
+]

ksadk/runtime/factory.py

@@ -3,21 +3,185 @@
 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.runners.base_runner import BaseRunner
-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
 
 
+def kernel_start_request_defaults(context: RuntimeLaunchContext) -> dict[str, Any]:
+    """Project an admitted launch manifest into immutable Kernel turn defaults.
+
+    The durable Kernel owns enqueue ordering, while the deployment manifest
+    owns model, instructions, sandbox and approval policy.  Keeping this
+    projection beside the RuntimeAdapter factory prevents the Kernel ingress
+    from trusting caller-supplied execution policy.
+    """
+
+    config = dict(context.config)
+    defaults: dict[str, Any] = {}
+    detection_name = str(getattr(context.detection, "name", "") or "").strip()
+    if detection_name:
+        defaults["agent_id"] = detection_name
+    model = str(config.get("model") or "").strip()
+    if model:
+        defaults["model"] = model
+    raw_allowed_models = (
+        config.get("models") or config.get("allowed_models") or config.get("allowedModels") or []
+    )
+    allowed_models = (
+        {str(item).strip() for item in raw_allowed_models if str(item).strip()}
+        if isinstance(raw_allowed_models, (list, tuple, set))
+        else set()
+    )
+    # 不把默认 model 自动加进白名单:白名单只在显式声明 models/allowedModels
+    # 时才存在(显式声明 = 收紧;只配默认 = 不限制 run 级覆盖)。
+    if allowed_models:
+        defaults["allowed_models"] = sorted(allowed_models)
+    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
+    return defaults
+
+
+def apply_runtime_start_request_defaults(
+    context: RuntimeLaunchContext,
+    request: StartRequest,
+) -> StartRequest:
+    """Apply deployment-owned launch policy to a direct runtime start.
+
+    AgentKernelWorker already projects these defaults before ``adapter.start``.
+    Foreground RunAgent, ``/run_sse`` and OpenAI-compatible routes also create
+    ``StartRequest`` objects directly, so they must use the same projection or
+    a deployed Codex agent silently falls back to the generic Codex role.
+
+    Request-local config is internal runtime state, not caller-owned policy;
+    retain it for local Studio builds while using the manifest model as the
+    fallback (and as the fail-closed fallback for an explicit allow-list).
+    """
+
+    defaults = kernel_start_request_defaults(context)
+    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()
+    }
+    selected_model = (
+        requested_model
+        if requested_model and (not allowed_models or requested_model in allowed_models)
+        else default_model
+    )
+    config = {
+        **dict(defaults.get("config") or {}),
+        **dict(request.config or {}),
+    }
+    return request.model_copy(
+        update={
+            "agent_id": request.agent_id or defaults.get("agent_id"),
+            "model": selected_model,
+            "config": config,
+        }
+    )
+
+
+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
-    overrides = list(context.config.get("codex_overrides") or [])
+    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
@@ -37,6 +201,9 @@ def _create_codex(context: RuntimeLaunchContext) -> RuntimeAdapter:
             )
         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 后这些
@@ -60,10 +227,18 @@ def _create_codex(context: RuntimeLaunchContext) -> RuntimeAdapter:
         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=bool(context.config.get("sandbox_read_only", True)),
+        sandbox_read_only=sandbox_read_only,
         turn_timeout_seconds=float(timeout) if timeout is not None else None,
+        bound_skill_paths=bound_skill_paths,
     )
 
 
@@ -76,10 +251,90 @@ def _isolated_codex_home(project_dir: Any) -> Path:
     """
     override = os.environ.get("KSADK_CODEX_HOME")
     if override:
-        return Path(override).expanduser()
-    home = Path(str(project_dir)) / ".agentkit" / "codex-home"
-    home.mkdir(parents=True, exist_ok=True)
-    return home
+        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:
@@ -153,4 +408,9 @@ def create_runtime_adapter(context: RuntimeLaunchContext) -> RuntimeAdapter:
     return build_default_runtime_registry().create(context)
 
 
-__all__ = ["build_default_runtime_registry", "create_runtime_adapter"]
+__all__ = [
+    "apply_runtime_start_request_defaults",
+    "build_default_runtime_registry",
+    "create_runtime_adapter",
+    "kernel_start_request_defaults",
+]

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,