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

ksadk/plugins/providers/harness.py

@@ -10,21 +10,36 @@ not create another event stream or transcript store.
 from __future__ import annotations
 
 import asyncio
+import inspect
 import json
-from collections.abc import Awaitable, Mapping, Sequence
+from collections.abc import Awaitable, Callable, Mapping, Sequence
 from contextlib import AsyncExitStack
 from dataclasses import dataclass, replace
 from pathlib import Path
-from typing import Any, Protocol, cast, runtime_checkable
+from typing import Any, Literal, Protocol, cast, runtime_checkable
 
 from ksadk.harness.config import HarnessConfig, McpToolSpec, SandboxPolicy
-from ksadk.harness.reasoner import HarnessReasoner, LiteLLMHarnessReasoner
+from ksadk.harness.reasoner import HarnessReasoner, ModelGatewayHarnessReasoner
 from ksadk.harness.runtime import HarnessRuntimeAdapter
 from ksadk.plugins.bundle import ResolvedPluginBundle
 from ksadk.plugins.contracts import CompositionProfile, PluginManifest
 from ksadk.plugins.host import PluginExecutionContext, PluginHostError
-from ksadk.plugins.providers.mcp_projection import project_mcp_capabilities
-from ksadk.runtime import RuntimeExecutor, RuntimeLaunchContext, RuntimeRegistry, StartRequest
+from ksadk.plugins.memory_provider import MemoryProviderBinding
+from ksadk.plugins.providers.harness_context import HarnessContextContributorSource
+from ksadk.plugins.providers.harness_hooks import HarnessHookBinding, project_harness_hooks
+from ksadk.plugins.providers.mcp_projection import (
+    MCPResourcePin,
+    MCPRuntimeCredential,
+    project_mcp_capabilities,
+)
+from ksadk.runtime import (
+    CONVERSATION_PREPROCESSING_METADATA_KEY,
+    RuntimeAdapter,
+    RuntimeExecutor,
+    RuntimeLaunchContext,
+    RuntimeRegistry,
+    StartRequest,
+)
 from ksadk.runtime.conversation_execution import invoke_runtime_conversation_once
 from ksadk.sessions import create_session_service
 from ksadk.sessions.base import BaseSessionService
@@ -36,6 +51,11 @@ _HISTORY_ENVELOPE_PREFIX = "agentkit.conversation-history/v1:"
 class HarnessSkillContribution:
     name: str
     instructions: str
+    resource_root: Path | None = None
+    # Built-in Bundle Skills carry their locked resource identity into Native.
+    # External sources may omit these until they offer an equivalent binding.
+    source_ref: str | None = None
+    content_digest: str | None = None
 
 
 @dataclass(frozen=True)
@@ -49,6 +69,44 @@ class HarnessProviderInventory:
     context_contributors: tuple[str, ...]
 
 
+@dataclass(frozen=True)
+class HarnessEngineActivationContext:
+    """Locked DSH inputs presented to a host-owned Native adapter builder.
+
+    The Bundle is already resolved by PluginHost; the builder must still bind
+    its own authenticated scope, model, tools and verifier for this activation.
+    Selection is never inferred from bundle text or a model response.
+    """
+
+    bundle: ResolvedPluginBundle
+    config: HarnessConfig
+    agent_name: str
+    workspace_root: Path
+    user_workspace_root: Path | None
+    skills: tuple[HarnessSkillContribution, ...]
+    profile_digest: str
+    plugin_lock_digest: str
+    activation_key: str
+    activation_claims: tuple[tuple[str, str], ...] = ()
+    activation_generation: str = ""
+    activation_available: Callable[[], bool] | None = None
+    mcp_available: Callable[[], Awaitable[bool]] | None = None
+    mcp_resource_pins: tuple[MCPResourcePin, ...] = ()
+    mcp_runtime_credentials: tuple[MCPRuntimeCredential, ...] = ()
+    context_sources: tuple[HarnessContextBinding, ...] = ()
+    hook_sources: tuple[HarnessHookBinding, ...] = ()
+    memory_sources: tuple[MemoryProviderBinding, ...] = ()
+
+
+HarnessEngineSelector = Callable[
+    [HarnessEngineActivationContext],
+    Literal["legacy", "native"] | Awaitable[Literal["legacy", "native"]],
+]
+HarnessNativeAdapterBuilder = Callable[
+    [HarnessEngineActivationContext], RuntimeAdapter | Awaitable[RuntimeAdapter]
+]
+
+
 @dataclass(frozen=True)
 class HarnessTurnRequest:
     user_id: str
@@ -132,6 +190,13 @@ class HarnessSkillSource(Protocol):
     def harness_skill(self, bundle: ResolvedPluginBundle) -> HarnessSkillContribution: ...
 
 
+@runtime_checkable
+class HarnessSkillSetSource(Protocol):
+    def harness_skills(
+        self, bundle: ResolvedPluginBundle
+    ) -> Sequence[HarnessSkillContribution]: ...
+
+
 @runtime_checkable
 class HarnessContextSource(Protocol):
     async def harness_context(
@@ -139,6 +204,19 @@ class HarnessContextSource(Protocol):
     ) -> str: ...
 
 
+@dataclass(frozen=True)
+class HarnessContextBinding:
+    """Host-selected source identity; text returned by it grants no authority."""
+
+    plugin_id: str
+    plugin_version: str
+    runtime: HarnessContextSource | HarnessContextContributorSource
+    # Preserve positional SDK callers. A missing slot is admissible only when
+    # the locked graph has exactly one Context offer for this owner.
+    slot: str | None = None
+    contributor: bool = False
+
+
 class _ConversationHistoryReasoner:
     """Restore canonical message roles before calling the Harness reasoner.
 
@@ -150,6 +228,34 @@ class _ConversationHistoryReasoner:
 
     def __init__(self, delegate: HarnessReasoner) -> None:
         self._delegate = delegate
+        # graph_builder 以 engine._reasoner._streaming 决定是否走增量推理；
+        # 包装器必须透传该声明，否则 managed Harness 静默回退到整段
+        # complete()，前端看不到任何 TEXT_DELTA。
+        self._streaming = getattr(delegate, "_streaming", None) is True
+
+    @staticmethod
+    def _expand_messages(messages: Sequence[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Restore the canonical history envelope for either reasoner path.
+
+        The wrapper used to expand only ``complete``.  That made the managed
+        Harness graph silently fall back to a buffered model call whenever
+        Studio enabled streaming, because the wrapper no longer exposed the
+        delegate's ``stream_complete`` method.
+        """
+        expanded = list(messages)
+        if len(expanded) < 2:
+            return expanded
+        content = expanded[1].get("content")
+        if not isinstance(content, str) or not content.startswith(_HISTORY_ENVELOPE_PREFIX):
+            return expanded
+        raw = content.removeprefix(_HISTORY_ENVELOPE_PREFIX)
+        try:
+            history = json.loads(raw)
+        except json.JSONDecodeError as error:
+            raise RuntimeError("invalid canonical Harness history envelope") from error
+        if not isinstance(history, list) or not all(isinstance(item, dict) for item in history):
+            raise RuntimeError("invalid canonical Harness history payload")
+        return [expanded[0], *_chat_history(history), *expanded[2:]]
 
     async def complete(
         self,
@@ -158,27 +264,63 @@ class _ConversationHistoryReasoner:
         prompt: str,
         messages: Sequence[dict[str, Any]],
         tools: Sequence[Any],
+        max_output_tokens: int | None = None,
+        reasoning_effort: str | None = None,
     ) -> Any:
-        expanded = list(messages)
-        if len(expanded) >= 2:
-            content = expanded[1].get("content")
-            if isinstance(content, str) and content.startswith(_HISTORY_ENVELOPE_PREFIX):
-                raw = content.removeprefix(_HISTORY_ENVELOPE_PREFIX)
-                try:
-                    history = json.loads(raw)
-                except json.JSONDecodeError as error:
-                    raise RuntimeError("invalid canonical Harness history envelope") from error
-                if not isinstance(history, list) or not all(
-                    isinstance(item, dict) for item in history
-                ):
-                    raise RuntimeError("invalid canonical Harness history payload")
-                expanded = [expanded[0], *_chat_history(history), *expanded[2:]]
-        return await self._delegate.complete(
-            model=model,
-            prompt=prompt,
-            messages=expanded,
-            tools=tools,
-        )
+        expanded = self._expand_messages(messages)
+        kwargs: dict[str, Any] = {
+            "model": model,
+            "prompt": prompt,
+            "messages": expanded,
+            "tools": tools,
+        }
+        if max_output_tokens is not None:
+            kwargs["max_output_tokens"] = max_output_tokens
+        if reasoning_effort:
+            kwargs["reasoning_effort"] = reasoning_effort
+        return await self._delegate.complete(**kwargs)
+
+    async def stream_complete(
+        self,
+        *,
+        model: str,
+        prompt: str,
+        messages: Sequence[dict[str, Any]],
+        tools: Sequence[Any],
+        max_output_tokens: int | None = None,
+        reasoning_effort: str | None = None,
+    ):
+        """Forward incremental model events while preserving canonical history."""
+        stream = getattr(self._delegate, "stream_complete", None)
+        if stream is None:
+            # Keep compatibility with custom reasoners that only implement
+            # ``complete``; callers still receive one terminal turn.
+            turn = await self.complete(
+                model=model,
+                prompt=prompt,
+                messages=messages,
+                tools=tools,
+                **(
+                    {"max_output_tokens": max_output_tokens}
+                    if max_output_tokens is not None
+                    else {}
+                ),
+                **({"reasoning_effort": reasoning_effort} if reasoning_effort else {}),
+            )
+            yield {"turn": turn}
+            return
+        kwargs = {
+            "model": model,
+            "prompt": prompt,
+            "messages": self._expand_messages(messages),
+            "tools": tools,
+        }
+        if max_output_tokens is not None:
+            kwargs["max_output_tokens"] = max_output_tokens
+        if reasoning_effort:
+            kwargs["reasoning_effort"] = reasoning_effort
+        async for item in stream(**kwargs):
+            yield item
 
 
 class _ConversationHistoryHarnessAdapter(HarnessRuntimeAdapter):
@@ -187,6 +329,11 @@ class _ConversationHistoryHarnessAdapter(HarnessRuntimeAdapter):
     async def start(self, request: StartRequest):  # type: ignore[no-untyped-def]
         preprocessing = request.conversation_preprocessing()
         if preprocessing is not None and preprocessing.messages:
+            metadata = {
+                key: value
+                for key, value in request.metadata.items()
+                if key != CONVERSATION_PREPROCESSING_METADATA_KEY
+            }
             request = request.model_copy(
                 update={
                     "input": _HISTORY_ENVELOPE_PREFIX
@@ -195,7 +342,8 @@ class _ConversationHistoryHarnessAdapter(HarnessRuntimeAdapter):
                         ensure_ascii=False,
                         sort_keys=True,
                         separators=(",", ":"),
-                    )
+                    ),
+                    "metadata": metadata,
                 }
             )
         return await super().start(request)
@@ -224,10 +372,22 @@ class KsADKHarnessProviderRuntime:
         plugin_id: str,
         session_service: BaseSessionService,
         reasoner: HarnessReasoner,
+        state_dir: str | None = None,
+        checkpoint_dsn: str | None = None,
+        execution_policy_resolver: Any | None = None,
+        user_workspace_root: Path | None = None,
+        engine_selector: HarnessEngineSelector | None = None,
+        native_adapter_builder: HarnessNativeAdapterBuilder | None = None,
     ) -> None:
         self._plugin_id = plugin_id
         self._session_service = session_service
         self._reasoner = reasoner
+        self._state_dir = state_dir
+        self._checkpoint_dsn = checkpoint_dsn
+        self._execution_policy_resolver = execution_policy_resolver
+        self._user_workspace_root = user_workspace_root
+        self._engine_selector = engine_selector
+        self._native_adapter_builder = native_adapter_builder
         self._ready = False
         self._disposed = False
         self._last_inventory: HarnessProviderInventory | None = None
@@ -265,6 +425,7 @@ class KsADKHarnessProviderRuntime:
             raise PluginHostError("harness_provider_unavailable", "Harness provider is not ready")
 
         async with AsyncExitStack() as mcp_cleanup:
+            hook_bindings = project_harness_hooks(bundle, capabilities)
             projection = await project_mcp_capabilities(capabilities, bundle)
             mcp_cleanup.push_async_callback(projection.aclose)
             mcp_specs = list(projection.specs)
@@ -273,30 +434,59 @@ class KsADKHarnessProviderRuntime:
             skills: list[HarnessSkillContribution] = []
             skill_owners: list[str] = []
             for binding in capabilities.all("skill.source/v1"):
-                if not isinstance(binding.runtime, HarnessSkillSource):
+                plural = isinstance(binding.runtime, HarnessSkillSetSource)
+                if not plural and not isinstance(binding.runtime, HarnessSkillSource):
                     raise PluginHostError(
                         "harness_skill_incompatible",
                         f"plugin {binding.plugin_id} cannot project Harness instructions",
                     )
-                contribution = binding.runtime.harness_skill(bundle)
-                if not contribution.name.strip() or not contribution.instructions.strip():
+                contributions = (
+                    tuple(binding.runtime.harness_skills(bundle))
+                    if plural
+                    else (binding.runtime.harness_skill(bundle),)
+                )
+                if not contributions:
                     raise PluginHostError(
                         "harness_skill_invalid",
-                        f"plugin {binding.plugin_id} returned an empty Skill contribution",
+                        f"plugin {binding.plugin_id} returned no Skill contributions",
                     )
-                skills.append(contribution)
-                skill_owners.append(binding.plugin_id)
+                for contribution in contributions:
+                    if (
+                        not isinstance(contribution, HarnessSkillContribution)
+                        or not contribution.name.strip()
+                        or not contribution.instructions.strip()
+                    ):
+                        raise PluginHostError(
+                            "harness_skill_invalid",
+                            f"plugin {binding.plugin_id} returned an invalid Skill contribution",
+                        )
+                    skills.append(contribution)
+                    skill_owners.append(binding.plugin_id)
 
             context_sources: list[HarnessContextSource] = []
             context_owners: list[str] = []
+            context_bindings: list[HarnessContextBinding] = []
             for binding in capabilities.all("context.contributor/v1"):
-                if not isinstance(binding.runtime, HarnessContextSource):
+                declarations = [item for item in bundle.composition.profile.capabilities
+                                if item.ref == f"plugin://{binding.plugin_id}@{binding.plugin_version}"]
+                richer = bool(len(declarations) == 1 and declarations[0].config.get(
+                    "schema_version",
+                ) == "ksadk.harness-context-contributor-binding/v1")
+                required_protocol = (HarnessContextContributorSource if richer
+                                     else HarnessContextSource)
+                if not isinstance(binding.runtime, required_protocol):
                     raise PluginHostError(
                         "harness_context_incompatible",
                         f"plugin {binding.plugin_id} cannot contribute Harness context",
                     )
-                context_sources.append(binding.runtime)
+                if not richer:
+                    context_sources.append(binding.runtime)
                 context_owners.append(binding.plugin_id)
+                context_bindings.append(HarnessContextBinding(
+                    binding.plugin_id, binding.plugin_version, binding.runtime,
+                    slot=binding.slot,
+                    contributor=richer,
+                ))
 
             execution = bundle.resolved_agent_spec.get("execution")
             strategy = (
@@ -304,18 +494,13 @@ class KsADKHarnessProviderRuntime:
                 if isinstance(execution, Mapping)
                 else "direct"
             )
-            if strategy != "direct":
+            if strategy not in {"direct", "plan-act-observe"}:
                 raise PluginHostError(
                     "harness_execution_strategy_unsupported",
                     f"KsADK Harness Provider does not support {strategy!r}",
                 )
 
             model, prompt = _bundle_model_and_prompt(bundle)
-            if skills:
-                prompt = _append_prompt_sections(
-                    prompt,
-                    [f"Skill {item.name}:\n{item.instructions}" for item in skills],
-                )
             config = HarnessConfig(
                 model=model,
                 prompt=prompt,
@@ -332,20 +517,81 @@ class KsADKHarnessProviderRuntime:
                 skills=tuple(item.name for item in skills),
                 context_contributors=tuple(context_owners),
             )
-            self._last_inventory = inventory
             workspace_root = bundle.root / "runtime"
             if not workspace_root.is_dir():
                 workspace_root = bundle.root
+            engine_context = HarnessEngineActivationContext(
+                bundle=bundle,
+                config=config,
+                agent_name=bundle.manifest.agent_id,
+                workspace_root=workspace_root,
+                user_workspace_root=self._user_workspace_root,
+                skills=tuple(skills),
+                profile_digest=capabilities.profile_digest,
+                plugin_lock_digest=capabilities.plugin_lock_digest,
+                activation_key=capabilities.activation_key,
+                activation_claims=capabilities.activation_claims,
+                activation_generation=capabilities.activation_generation,
+                activation_available=capabilities.activation_available,
+                mcp_available=projection.available,
+                mcp_resource_pins=projection.resource_pins,
+                context_sources=tuple(context_bindings),
+                hook_sources=hook_bindings,
+                memory_sources=tuple(
+                    MemoryProviderBinding(binding.plugin_id, binding.plugin_version,
+                                          binding.slot, binding.runtime)
+                    for binding in capabilities.all("memory.provider/v1")
+                ),
+            )
+            engine_kind: Literal["legacy", "native"] = "legacy"
+            if self._engine_selector is not None:
+                selected = self._engine_selector(engine_context)
+                if inspect.isawaitable(selected):
+                    selected = await selected
+                if selected not in {"legacy", "native"}:
+                    raise PluginHostError(
+                        "harness_engine_selection_invalid",
+                        "Harness engine selection must be legacy or native",
+                    )
+                engine_kind = selected
+            if hook_bindings and engine_kind != "native":
+                raise PluginHostError(
+                    "harness_hooks_native_required",
+                    "selected harness.hook/v1 capabilities require Native execution",
+                )
+            if any(binding.contributor for binding in context_bindings) and engine_kind != "native":
+                raise PluginHostError(
+                    "harness_context_native_required",
+                    "typed Context Contributors require the selected Native execution path",
+                )
+            if engine_kind == "native":
+                inventory = replace(inventory, history_owner="native_run_ledger")
+                # Only clients consuming the ephemeral callbacks may use the
+                # renewable probe. Legacy/static clients retain token expiry.
+                engine_context = replace(
+                    engine_context,
+                    mcp_available=projection.runtime_available,
+                    mcp_runtime_credentials=projection.runtime_credentials,
+                )
+            self._last_inventory = inventory
             return KsADKHarnessActivation(
                 bundle=bundle,
                 config=config,
                 agent_name=bundle.manifest.agent_id,
                 workspace_root=workspace_root,
                 reasoner=self._reasoner,
+                skills=tuple(skills),
                 context_sources=tuple(context_sources),
                 session_service=self._session_service,
                 inventory=inventory,
                 mcp_cleanup=mcp_cleanup.pop_all(),
+                state_dir=self._state_dir,
+                checkpoint_dsn=self._checkpoint_dsn,
+                execution_policy_resolver=self._execution_policy_resolver,
+                user_workspace_root=self._user_workspace_root,
+                engine_context=engine_context,
+                engine_kind=engine_kind,
+                native_adapter_builder=self._native_adapter_builder,
             )
 
 
@@ -378,11 +624,30 @@ class KsADKHarnessProviderFactory:
             )
         reasoner = self._reasoner or services.get("harness_reasoner")
         if reasoner is None:
-            reasoner = LiteLLMHarnessReasoner()
+            reasoner = ModelGatewayHarnessReasoner()
+        state_dir = services.get("harness_state_dir")
+        checkpoint_dsn = services.get("checkpoint_dsn")
+        user_workspace_root = services.get("harness_workspace_root")
+        engine_selector = services.get("harness_engine_selector")
+        native_adapter_builder = services.get("harness_native_adapter_builder")
+        if (engine_selector is None) != (native_adapter_builder is None) or (
+            engine_selector is not None
+            and (not callable(engine_selector) or not callable(native_adapter_builder))
+        ):
+            raise PluginHostError(
+                "harness_native_binding_invalid",
+                "Native Harness selection requires a host selector and adapter builder",
+            )
         self.runtime = KsADKHarnessProviderRuntime(
             plugin_id=manifest.metadata.id,
             session_service=service,
             reasoner=reasoner,
+            state_dir=str(state_dir) if state_dir else None,
+            checkpoint_dsn=str(checkpoint_dsn) if checkpoint_dsn else None,
+            execution_policy_resolver=services.get("execution_policy_resolver"),
+            user_workspace_root=(Path(user_workspace_root) if user_workspace_root else None),
+            engine_selector=engine_selector,
+            native_adapter_builder=native_adapter_builder,
         )
         return self.runtime
 
@@ -396,30 +661,62 @@ class KsADKHarnessActivation:
         agent_name: str,
         workspace_root: Path,
         reasoner: HarnessReasoner,
+        skills: tuple[HarnessSkillContribution, ...],
         context_sources: tuple[HarnessContextSource, ...],
         session_service: BaseSessionService,
         inventory: HarnessProviderInventory,
+        state_dir: str | None = None,
+        checkpoint_dsn: str | None = None,
         mcp_cleanup: AsyncExitStack | None = None,
+        execution_policy_resolver: Any | None = None,
+        user_workspace_root: Path | None = None,
+        engine_context: HarnessEngineActivationContext | None = None,
+        engine_kind: Literal["legacy", "native"] = "legacy",
+        native_adapter_builder: HarnessNativeAdapterBuilder | None = None,
     ) -> None:
         self._bundle = bundle
         self._config = config
         self._agent_name = agent_name
         self._workspace_root = workspace_root
+        # 用户当前选择的 Studio 工作区（bundle 之外）；文件工具落盘目标。
+        self._user_workspace_root = user_workspace_root
+        self._engine_context = engine_context
+        self._engine_kind = engine_kind
+        self._native_adapter_builder = native_adapter_builder
         self._reasoner = reasoner
+        self._skills = skills
         self._context_sources = context_sources
         self._session_service = session_service
         self._inventory = inventory
+        self._state_dir = state_dir
+        self._checkpoint_dsn = checkpoint_dsn
+        self._checkpoint_stack: Any | None = None
+        self._execution_policy_resolver = execution_policy_resolver
         self._mcp_cleanup = mcp_cleanup
         self._mcp_cleanup_lock = asyncio.Lock()
         self._ready = False
         self._disposed = False
         self._executors: list[RuntimeExecutor] = []
-        self._kernel_adapter: HarnessRuntimeAdapter | None = None
+        self._kernel_adapter: RuntimeAdapter | None = None
+        self._warmup_task: asyncio.Task[Any] | None = None
+        self._warmup_error: BaseException | None = None
 
     async def start(self) -> None:
         if self._disposed:
             raise RuntimeError("Harness activation is disposed")
         self._ready = True
+        # Compilation and MCP/tool discovery are independent of the first
+        # user turn.  Start them in the background so Studio can finish
+        # opening immediately; the first turn awaits the same task if needed.
+        self._warmup_task = asyncio.create_task(self._warmup_kernel())
+
+    async def _warmup_kernel(self) -> None:
+        try:
+            await self.runtime_adapter()
+        except asyncio.CancelledError:
+            raise
+        except BaseException as error:  # retain the error for the first turn
+            self._warmup_error = error
 
     async def health(self) -> bool:
         return self._ready and not self._disposed
@@ -429,6 +726,14 @@ class KsADKHarnessActivation:
             raise PluginHostError(
                 "harness_activation_unavailable", "Harness activation is not ready"
             )
+        if self._engine_kind == "native":
+            # The direct provider path owns separate Session/transcript state.
+            # Until it has a Native projection, only Scheduler's runtime_adapter
+            # path may execute this pinned Native activation.
+            raise PluginHostError(
+                "harness_native_direct_path_unavailable",
+                "Native Harness activation requires the Scheduler runtime adapter path",
+            )
         turn = HarnessTurnRequest.parse(request)
         context_sections = [
             text.strip()
@@ -437,7 +742,13 @@ class KsADKHarnessActivation:
         ]
         config = replace(
             self._config,
-            prompt=_append_prompt_sections(self._config.prompt, context_sections),
+            prompt=_append_prompt_sections(
+                self._config.prompt,
+                [
+                    *[f"Skill {item.name}:\n{item.instructions}" for item in self._skills],
+                    *context_sections,
+                ],
+            ),
         )
         executor, launch_context = _build_direct_backend(
             config,
@@ -469,7 +780,7 @@ class KsADKHarnessActivation:
             inventory=self._inventory,
         )
 
-    def runtime_adapter(self) -> HarnessRuntimeAdapter:
+    async def runtime_adapter(self) -> RuntimeAdapter:
         """Return the activation-owned adapter used by AgentKernel Scheduler.
 
         The immutable profile has already assembled model instructions, MCP,
@@ -482,13 +793,49 @@ class KsADKHarnessActivation:
             raise PluginHostError(
                 "harness_activation_unavailable", "Harness activation is not ready"
             )
+        current = asyncio.current_task()
+        if self._warmup_task is not None and self._warmup_task is not current:
+            await asyncio.shield(self._warmup_task)
+            if self._warmup_error is not None:
+                error, self._warmup_error = self._warmup_error, None
+                raise error
         if self._kernel_adapter is None:
-            self._kernel_adapter = HarnessRuntimeAdapter(
-                self._config,
-                agent_name=self._agent_name,
-                reasoner=self._reasoner,
-                workspace_root=self._workspace_root,
-            )
+            if self._engine_kind == "native":
+                from ksadk.harness.native_runtime import NativeRuntimeAdapter
+
+                if self._engine_context is None or self._native_adapter_builder is None:
+                    raise PluginHostError(
+                        "harness_native_binding_unavailable",
+                        "Native Harness host bindings are unavailable",
+                    )
+                adapter = self._native_adapter_builder(self._engine_context)
+                if inspect.isawaitable(adapter):
+                    adapter = await adapter
+                if not isinstance(adapter, NativeRuntimeAdapter):
+                    raise PluginHostError(
+                        "harness_native_adapter_invalid",
+                        "Native Harness host builder did not return a NativeRuntimeAdapter",
+                    )
+                self._kernel_adapter = adapter
+            else:
+                from ksadk.plugins.providers.harness_managed import (
+                    build_managed_provider_adapter,
+                )
+
+                self._kernel_adapter = await build_managed_provider_adapter(
+                    self._config,
+                    agent_name=self._agent_name,
+                    reasoner=self._reasoner,
+                    workspace_root=self._workspace_root,
+                    user_workspace_root=self._user_workspace_root,
+                    skills=self._skills,
+                    tool_contracts=dict(self._bundle.resolved_agent_spec),
+                    bundle_root=self._bundle.root,
+                    state_dir=self._state_dir,
+                    checkpoint_dsn=self._checkpoint_dsn,
+                    execution_policy_resolver=self._execution_policy_resolver,
+                )
+                self._checkpoint_stack = getattr(self._kernel_adapter, "_checkpoint_stack", None)
         return self._kernel_adapter
 
     async def drain(self) -> None:
@@ -501,7 +848,17 @@ class KsADKHarnessActivation:
 
     async def dispose(self) -> None:
         self._ready = False
+        if self._warmup_task is not None and not self._warmup_task.done():
+            self._warmup_task.cancel()
+            await asyncio.gather(self._warmup_task, return_exceptions=True)
+        self._warmup_task = None
         first_error: BaseException | None = None
+        if self._checkpoint_stack is not None:
+            try:
+                await self._checkpoint_stack.aclose()
+            except BaseException as error:  # cleanup must continue
+                first_error = error
+            self._checkpoint_stack = None
         try:
             await self._release_mcp_credentials()
         except BaseException as error:  # cleanup must continue
@@ -538,7 +895,7 @@ def _build_direct_backend(
     workspace_root: Path,
     reasoner: HarnessReasoner,
 ) -> tuple[RuntimeExecutor, RuntimeLaunchContext]:
-    """Internal execution seam; Phase 2 does not expose strategy as a plugin."""
+    """Internal execution seam; Release does not expose strategy as a plugin."""
 
     history_reasoner = _ConversationHistoryReasoner(reasoner)
     registry = RuntimeRegistry()
@@ -620,8 +977,12 @@ def _chat_history(history: Sequence[Mapping[str, Any]]) -> list[dict[str, Any]]:
 
 __all__ = [
     "HarnessContextSource",
+    "HarnessContextBinding",
+    "HarnessEngineActivationContext",
+    "HarnessEngineSelector",
     "HarnessMCPSource",
     "HarnessMCPActivationSource",
+    "HarnessNativeAdapterBuilder",
     "HarnessProviderInventory",
     "HarnessSkillContribution",
     "HarnessSkillSource",