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

ksadk/plugins/subagents.py

@@ -0,0 +1,333 @@
+"""Frozen SubagentProvider/v1 seam with explicit lineage and policy bounds.
+
+The Kernel does not know whether a child is implemented by Codex, DSH,
+Claude, another KsADK AgentProvider, or a remote service.  It only routes a
+bounded request to a named provider and retains the returned child identity.
+Provider-private state and event logs remain with that provider; projected
+child events keep their own ids and sequence numbers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Mapping, Sequence
+from datetime import datetime
+from typing import Any, Literal, Protocol, cast, runtime_checkable
+
+from pydantic import Field, field_validator, model_validator
+
+from ksadk.plugins.contracts import PluginContractModel, PluginReference
+
+
+class SubagentPolicy(PluginContractModel):
+    """Parent-owned limits that a child provider may only narrow."""
+
+    max_depth: int = Field(default=1, ge=1, le=16)
+    timeout_seconds: int = Field(default=120, ge=1, le=86_400)
+    max_steps: int = Field(default=12, ge=1, le=10_000)
+    background: bool = False
+    allowed_tools: tuple[str, ...] = ()
+    allowed_permissions: tuple[str, ...] = ()
+
+    @field_validator("allowed_tools", "allowed_permissions")
+    @classmethod
+    def validate_unique_values(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        if any(not item.strip() for item in value):
+            raise ValueError("subagent policy entries must be non-empty")
+        if len(value) != len(set(value)):
+            raise ValueError("subagent policy entries must be unique")
+        return tuple(sorted(value))
+
+
+class SpawnSubagentRequest(PluginContractModel):
+    """One bounded child task requested by an authenticated parent Run."""
+
+    request_format: Literal["ksadk.subagent-spawn/v1"] = "ksadk.subagent-spawn/v1"
+    provider_ref: str
+    parent_session_id: str = Field(min_length=1, max_length=256)
+    parent_run_id: str = Field(min_length=1, max_length=256)
+    task: str = Field(min_length=1, max_length=131_072)
+    depth: int = Field(default=1, ge=1, le=16)
+    policy: SubagentPolicy = Field(default_factory=SubagentPolicy)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("provider_ref")
+    @classmethod
+    def validate_provider_ref(cls, value: str) -> str:
+        return cast(str, PluginReference(ref=value).ref)
+
+    @field_validator("metadata")
+    @classmethod
+    def validate_metadata(cls, value: dict[str, Any]) -> dict[str, Any]:
+        _reject_secret_values(value)
+        return value
+
+    @model_validator(mode="after")
+    def validate_depth(self) -> "SpawnSubagentRequest":
+        if self.depth > self.policy.max_depth:
+            raise ValueError("subagent depth exceeds the parent policy maxDepth")
+        return self
+
+
+class ChildHandle(PluginContractModel):
+    """Stable lineage and recovery descriptor for one provider-owned child."""
+
+    handle_format: Literal["ksadk.child-handle/v1"] = "ksadk.child-handle/v1"
+    handle_id: str = Field(min_length=1, max_length=256)
+    provider_ref: str
+    parent_session_id: str = Field(min_length=1, max_length=256)
+    parent_run_id: str = Field(min_length=1, max_length=256)
+    child_session_id: str | None = Field(default=None, max_length=256)
+    child_run_id: str | None = Field(default=None, max_length=256)
+    depth: int = Field(ge=1, le=16)
+    capabilities: tuple[str, ...] = ()
+    capability_digest: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+    created_at: datetime
+    resumable: bool = False
+    resume_descriptor: dict[str, Any] | None = None
+
+    @field_validator("provider_ref")
+    @classmethod
+    def validate_provider_ref(cls, value: str) -> str:
+        return cast(str, PluginReference(ref=value).ref)
+
+    @field_validator("capabilities")
+    @classmethod
+    def validate_capabilities(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        if any(not item.strip() for item in value):
+            raise ValueError("child capabilities must be non-empty")
+        if len(value) != len(set(value)):
+            raise ValueError("child capabilities must be unique")
+        return tuple(sorted(value))
+
+    @field_validator("created_at")
+    @classmethod
+    def validate_created_at(cls, value: datetime) -> datetime:
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise ValueError("child handle createdAt must include a timezone")
+        return value
+
+    @field_validator("resume_descriptor")
+    @classmethod
+    def validate_resume_descriptor(
+        cls, value: dict[str, Any] | None
+    ) -> dict[str, Any] | None:
+        if value is not None:
+            _reject_secret_values(value)
+        return value
+
+    @model_validator(mode="after")
+    def validate_recovery_shape(self) -> "ChildHandle":
+        if self.resumable and not self.resume_descriptor:
+            raise ValueError("resumable child handle requires a resumeDescriptor")
+        if not self.resumable and self.resume_descriptor is not None:
+            raise ValueError("non-resumable child handle cannot carry a resumeDescriptor")
+        return self
+
+
+class SubagentStatus(PluginContractModel):
+    status_format: Literal["ksadk.subagent-status/v1"] = "ksadk.subagent-status/v1"
+    handle_id: str = Field(min_length=1, max_length=256)
+    state: Literal[
+        "accepted",
+        "running",
+        "waiting_input",
+        "succeeded",
+        "failed",
+        "cancelled",
+        "interrupted",
+        "disposed",
+    ]
+    last_seq: int = Field(default=0, ge=0)
+    updated_at: datetime
+    reason: str | None = Field(default=None, max_length=2048)
+
+    @field_validator("updated_at")
+    @classmethod
+    def validate_updated_at(cls, value: datetime) -> datetime:
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise ValueError("subagent status updatedAt must include a timezone")
+        return value
+
+
+class SubagentEvent(PluginContractModel):
+    """Identity-preserving child event; parent projection must not merge by text."""
+
+    event_format: Literal["ksadk.subagent-event/v1"] = "ksadk.subagent-event/v1"
+    handle_id: str = Field(min_length=1, max_length=256)
+    event_id: str = Field(min_length=1, max_length=256)
+    seq: int = Field(ge=1)
+    kind: Literal["progress", "item", "interaction", "terminal"]
+    payload: dict[str, Any] = Field(default_factory=dict)
+    native_ref: dict[str, str] = Field(default_factory=dict)
+
+    @field_validator("payload")
+    @classmethod
+    def validate_payload(cls, value: dict[str, Any]) -> dict[str, Any]:
+        _reject_secret_values(value)
+        return value
+
+
+class SubagentResult(PluginContractModel):
+    result_format: Literal["ksadk.subagent-result/v1"] = "ksadk.subagent-result/v1"
+    handle_id: str = Field(min_length=1, max_length=256)
+    state: Literal["succeeded", "failed", "cancelled", "interrupted"]
+    output: Any = None
+    output_refs: tuple[str, ...] = ()
+    error_code: str | None = Field(default=None, max_length=256)
+    error_message: str | None = Field(default=None, max_length=2048)
+
+    @field_validator("output_refs")
+    @classmethod
+    def validate_output_refs(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        if any(not item.strip() for item in value):
+            raise ValueError("subagent output references must be non-empty")
+        if len(value) != len(set(value)):
+            raise ValueError("subagent output references must be unique")
+        return tuple(sorted(value))
+
+    @model_validator(mode="after")
+    def validate_terminal_shape(self) -> "SubagentResult":
+        if self.state == "succeeded" and (self.error_code or self.error_message):
+            raise ValueError("successful subagent result cannot carry an error")
+        if self.state == "failed" and not self.error_code:
+            raise ValueError("failed subagent result requires errorCode")
+        return self
+
+
+@runtime_checkable
+class SubagentProvider(Protocol):
+    """Named child execution provider; every method is provider-owned."""
+
+    async def describe(self) -> Mapping[str, Any]: ...
+
+    async def available(self) -> bool: ...
+
+    async def spawn(self, request: SpawnSubagentRequest) -> ChildHandle: ...
+
+    async def followup(self, handle: ChildHandle, input: Any) -> None: ...
+
+    async def status(self, handle: ChildHandle) -> SubagentStatus: ...
+
+    async def interrupt(self, handle: ChildHandle) -> None: ...
+
+    async def cancel(self, handle: ChildHandle) -> None: ...
+
+    def subscribe(
+        self, handle: ChildHandle, *, after_seq: int = 0
+    ) -> AsyncIterator[SubagentEvent]: ...
+
+    async def result(self, handle: ChildHandle) -> SubagentResult: ...
+
+    async def dispose(self, handle: ChildHandle) -> None: ...
+
+
+class SubagentProviderError(RuntimeError):
+    """Stable typed failure at the provider routing boundary."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+class SubagentProviderRouter:
+    """Route child handles to exact providers without interpreting their state."""
+
+    def __init__(self, providers: Mapping[str, SubagentProvider]) -> None:
+        self._providers = dict(providers)
+
+    async def spawn(self, request: SpawnSubagentRequest) -> ChildHandle:
+        provider = self._provider(request.provider_ref)
+        if not await provider.available():
+            raise SubagentProviderError(
+                "subagent_provider_unavailable",
+                f"SubagentProvider {request.provider_ref} is unavailable",
+            )
+        handle = await provider.spawn(request)
+        self._validate_handle(request, handle)
+        return handle
+
+    async def status(self, handle: ChildHandle) -> SubagentStatus:
+        return await self._provider_for_handle(handle).status(handle)
+
+    async def followup(self, handle: ChildHandle, input: Any) -> None:
+        await self._provider_for_handle(handle).followup(handle, input)
+
+    async def interrupt(self, handle: ChildHandle) -> None:
+        await self._provider_for_handle(handle).interrupt(handle)
+
+    async def cancel(self, handle: ChildHandle) -> None:
+        await self._provider_for_handle(handle).cancel(handle)
+
+    def subscribe(
+        self, handle: ChildHandle, *, after_seq: int = 0
+    ) -> AsyncIterator[SubagentEvent]:
+        if after_seq < 0:
+            raise SubagentProviderError(
+                "subagent_cursor_invalid", "subagent after_seq cannot be negative"
+            )
+        return self._provider_for_handle(handle).subscribe(handle, after_seq=after_seq)
+
+    async def result(self, handle: ChildHandle) -> SubagentResult:
+        return await self._provider_for_handle(handle).result(handle)
+
+    async def dispose(self, handle: ChildHandle) -> None:
+        await self._provider_for_handle(handle).dispose(handle)
+
+    def _provider_for_handle(self, handle: ChildHandle) -> SubagentProvider:
+        return self._provider(handle.provider_ref)
+
+    def _provider(self, provider_ref: str) -> SubagentProvider:
+        provider = self._providers.get(provider_ref)
+        if provider is None:
+            raise SubagentProviderError(
+                "subagent_provider_not_found",
+                f"SubagentProvider {provider_ref} is not registered",
+            )
+        return provider
+
+    @staticmethod
+    def _validate_handle(
+        request: SpawnSubagentRequest,
+        handle: ChildHandle,
+    ) -> None:
+        if (
+            handle.provider_ref != request.provider_ref
+            or handle.parent_session_id != request.parent_session_id
+            or handle.parent_run_id != request.parent_run_id
+            or handle.depth != request.depth
+        ):
+            raise SubagentProviderError(
+                "subagent_handle_mismatch",
+                "SubagentProvider returned a child handle outside the requested lineage",
+            )
+
+
+_SECRET_KEY_PARTS = ("secret", "password", "token", "apikey", "api_key")
+_SECRET_REF_PREFIXES = ("secret://", "env://", "credential://", "vault://")
+
+
+def _reject_secret_values(value: Any, *, path: str = "payload") -> None:
+    if isinstance(value, Mapping):
+        for key, child in value.items():
+            key_text = str(key)
+            normalized = key_text.replace("-", "").lower()
+            if any(part in normalized for part in _SECRET_KEY_PARTS) and child is not None:
+                if not isinstance(child, str) or not child.startswith(_SECRET_REF_PREFIXES):
+                    raise ValueError(f"{path}.{key_text} must contain a secret reference")
+            _reject_secret_values(child, path=f"{path}.{key_text}")
+    elif isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        for index, child in enumerate(value):
+            _reject_secret_values(child, path=f"{path}[{index}]")
+
+
+__all__ = [
+    "ChildHandle",
+    "SpawnSubagentRequest",
+    "SubagentEvent",
+    "SubagentPolicy",
+    "SubagentProvider",
+    "SubagentProviderError",
+    "SubagentProviderRouter",
+    "SubagentResult",
+    "SubagentStatus",
+]

ksadk/runtime/_runner_adapter/stream_mapping.py

@@ -69,7 +69,7 @@ def _a2ui_surface_event(
     self: Any,
     handle: RunHandle,
     chunk: Any,
-) -> RuntimeEvent | None:
+) -> tuple[RuntimeEvent, ...]:
     """Recognize a validated A2UI tool envelope and emit a canonical data-item event.
 
     The dynamic ``generate_a2ui`` tool returns official v0.9 operations as a
@@ -83,7 +83,7 @@ def _a2ui_surface_event(
     """
 
     if not isinstance(chunk, dict):
-        return None
+        return ()
     value = chunk.get("tool_output", chunk.get("output"))
     if value is not None and hasattr(value, "content"):
         value = value.content
@@ -91,15 +91,15 @@ def _a2ui_surface_event(
         try:
             value = json.loads(value)
         except (TypeError, ValueError):
-            return None
+            return ()
     if not isinstance(value, Mapping):
-        return None
+        return ()
     operations_raw = value.get("a2ui_operations")
     if not isinstance(operations_raw, list) or not operations_raw:
-        return None
+        return ()
     operations = [dict(operation) for operation in operations_raw if isinstance(operation, Mapping)]
     if not operations:
-        return None
+        return ()
 
     known: list[tuple[str, str]] = []  # (surface_id, lifecycle)
     for operation in operations:
@@ -116,71 +116,75 @@ def _a2ui_surface_event(
                     known.append((surface_id, lifecycle))
                     break
     if not known:
-        return None
+        return ()
     surface_ids = {surface_id for surface_id, _lifecycle in known}
     if len(surface_ids) != 1:
         logger.warning("ignoring A2UI tool result with multiple surfaces")
-        return None
+        return ()
     surface_id = known[0][0]
     lifecycle = "begin" if any(lc == "begin" for _, lc in known) else known[0][1]
 
     framework = self._runtime_type
     run_id = handle.run_id
     scope_id = stable_scope_id(framework, run_id)
-    item_id = stable_item_id(framework, run_id, "a2ui", surface_id)
+    # A dynamic A2UI tool result is a complete, immutable operation batch.  It
+    # must therefore be represented by a closed canonical item.  Reusing one
+    # long-lived item per surface leaves a create/update-only batch open at the
+    # run terminal and makes strict reducers reject the stream.
+    start_seq = self._next_seq()
+    batch_ref = str(chunk.get("call_id") or chunk.get("run_id") or chunk.get("id") or "")
+    if not batch_ref:
+        batch_ref = json.dumps(
+            operations,
+            ensure_ascii=False,
+            sort_keys=True,
+            separators=(",", ":"),
+        )
+    item_id = stable_item_id(framework, run_id, "a2ui-batch", surface_id, batch_ref)
     source = SourceRef(
         framework=framework,
         protocol="a2ui",
         native_run_id=run_id,
-        metadata={"surface_id": surface_id},
+        metadata={
+            "surface_id": surface_id,
+            "operation_batch": True,
+            "surface_lifecycle": lifecycle,
+        },
     )
     # TODO(runtime-event-v2): dict chunk 退化路径,chunk_ordinal 用 seq counter;
     # LangGraph/Codex 切 stream_canonical_events 后清理
-    n = self._next_seq()
     timestamp = time.time()
-    if lifecycle == "begin":
-        return ItemStarted(
+    snapshot = ContentSnapshot(parts=(DataContent(part_id="a2ui-ops", data=operations),))
+    completed_seq = self._next_seq()
+    return (
+        ItemStarted(
             schema_version=2,
             event_id=stable_event_id(
-                framework, scope_id, item_id, "item.started", "a2ui", run_id, n
+                framework, scope_id, item_id, "item.started", "a2ui", run_id, start_seq
             ),
-            seq=n,
+            seq=start_seq,
             timestamp=timestamp,
             run_id=run_id,
             scope_id=scope_id,
             source=source,
             item_id=item_id,
             item_kind="data",
-            initial=ContentSnapshot(parts=(DataContent(part_id="a2ui-ops", data=operations),)),
-        )
-    if lifecycle == "update":
-        return ItemUpdated(
+            initial=snapshot,
+        ),
+        ItemCompleted(
             schema_version=2,
             event_id=stable_event_id(
-                framework, scope_id, item_id, "item.updated", "a2ui", run_id, n
+                framework, scope_id, item_id, "item.completed", "a2ui", run_id, completed_seq
             ),
-            seq=n,
+            seq=completed_seq,
             timestamp=timestamp,
             run_id=run_id,
             scope_id=scope_id,
             source=source,
             item_id=item_id,
             item_kind="data",
-            op="replace",
-            update=DataContent(part_id="a2ui-ops", data=operations),
-        )
-    # lifecycle == "end"
-    return ItemCompleted(
-        schema_version=2,
-        event_id=stable_event_id(framework, scope_id, item_id, "item.completed", "a2ui", run_id, n),
-        seq=n,
-        timestamp=timestamp,
-        run_id=run_id,
-        scope_id=scope_id,
-        source=source,
-        item_id=item_id,
-        item_kind="data",
-        snapshot=ContentSnapshot(parts=()),
+            snapshot=snapshot,
+        ),
     )
 
 
@@ -323,8 +327,7 @@ class _RunnerStreamMappingMixin:
                                 usage.update(raw_usage)
                         for event in self._chunk_to_event(handle, run, chunk):  # type: ignore[attr-defined]
                             yield event
-                        a2ui_surface = _a2ui_surface_event(self, handle, chunk)
-                        if a2ui_surface is not None:
+                        for a2ui_surface in _a2ui_surface_event(self, handle, chunk):
                             yield a2ui_surface
             finally:
                 if accumulated_output:
@@ -708,8 +711,10 @@ class _RunnerStreamMappingMixin:
             if run is not None:
                 run.final_answer_item_id = item_id
             text_content = TextContent(part_id="text-0", text=output)
-            # Auto-close any open commentary/reasoning item before emitting final_answer.
-            # Text/thinking deltas create items that are never ItemCompleted;
+            # Auto-close any open explicit commentary/reasoning item before completing
+            # final_answer. Text deltas already belong to the final-answer item and must
+            # keep that identity through completion.
+            # Commentary/thinking deltas create items that are never ItemCompleted;
             # without this, RunCompleted fails _ensure_no_open_items.
             #
             # Close them *before* allocating the final-answer item.  Event
@@ -764,9 +769,13 @@ class _RunnerStreamMappingMixin:
         text = self._coerce(chunk.get("delta") or chunk.get("output") or chunk.get("data"))  # type: ignore[attr-defined]
         if not text:
             return []
-        item_id = stable_item_id(framework, run_id, "message", "commentary")
+        is_commentary = chunk_type in {"commentary", "commentary_delta"}
+        phase = "commentary" if is_commentary else "final_answer"
+        item_id = stable_item_id(framework, run_id, "message", phase)
+        if run is not None and not is_commentary:
+            run.final_answer_item_id = item_id
         op: str = "replace" if chunk.get("replace") else "append"
-        events = ensure_started(item_id=item_id, item_kind="message", phase="commentary")
+        events = ensure_started(item_id=item_id, item_kind="message", phase=phase)
         events.append(
             ItemUpdated(
                 **self._canonical_kwargs(  # type: ignore[attr-defined]

ksadk/runtime/adapter.py

@@ -417,6 +417,7 @@ class RuntimeAdapter(ABC):
             inject=_unavailable("runtime_no_native_inject"),
             checkpoint=_unavailable(),
             durable_restore=_unavailable(),
+            interaction_mode="unavailable",
         )
 
     def native_capabilities(self) -> dict[str, object]:

ksadk/runtime/factory.py

@@ -3,7 +3,10 @@
 from __future__ import annotations
 
 import dataclasses
+import hashlib
 import os
+import re
+import shutil
 import tempfile
 from pathlib import Path
 from typing import Any
@@ -11,8 +14,7 @@ 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 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
 
@@ -88,6 +90,19 @@ def kernel_start_request_defaults(context: RuntimeLaunchContext) -> dict[str, An
     }
     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
 
@@ -158,6 +173,7 @@ def _manifest_mcp_overrides(config: dict[str, Any]) -> list[str]:
 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)
@@ -185,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 后这些
@@ -219,6 +238,7 @@ def _create_codex(context: RuntimeLaunchContext) -> RuntimeAdapter:
         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,
     )
 
 
@@ -263,6 +283,60 @@ def _isolated_codex_home(project_dir: Any) -> Path:
     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:

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,