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

ksadk/plugins/providers/harness_dsh.py

@@ -0,0 +1,91 @@
+"""KsADK Harness AgentProvider packaged as a standard DSH Bundle.
+
+DSH owns installation and discovery. The shared bridge validates the exact
+registration, then delegates execution to the optional in-process KsADK
+Harness implementation so credentials and runtime services stay in KsADK.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any
+
+from ksadk.plugins.contracts import CompositionProfile, PluginManifest
+from ksadk.plugins.providers.dsh import DshAgentProviderHost, DshAgentProviderRegistration
+from ksadk.plugins.providers.shipped_dsh import (
+    HARNESS_DSH_SPEC,
+    ShippedDshBridgeFactory,
+    ShippedDshBridgeRuntime,
+    ShippedDshBundle,
+    load_shipped_dsh_bundle,
+    shipped_dsh_host_command,
+)
+
+if TYPE_CHECKING:
+    from ksadk.plugins.providers.harness import KsADKHarnessProviderFactory
+
+SHIPPED_HARNESS_DSH_PACKAGE = HARNESS_DSH_SPEC.package_name
+SHIPPED_HARNESS_PROVIDER_ID = HARNESS_DSH_SPEC.provider_id
+SHIPPED_HARNESS_PROVIDER_VERSION = HARNESS_DSH_SPEC.version
+ShippedHarnessDshBundle = ShippedDshBundle
+
+
+def shipped_harness_dsh_bundle() -> ShippedHarnessDshBundle:
+    return load_shipped_dsh_bundle(HARNESS_DSH_SPEC)
+
+
+def shipped_harness_dsh_host_command(*, python_executable: str | None = None) -> tuple[str, ...]:
+    return shipped_dsh_host_command(HARNESS_DSH_SPEC, python_executable=python_executable)
+
+
+class KsADKHarnessDshBridgeRuntime(ShippedDshBridgeRuntime):
+    """Named Harness bridge type retained for inventory and public typing."""
+
+
+class KsADKHarnessDshBridgeFactory(ShippedDshBridgeFactory):
+    runtime_class = KsADKHarnessDshBridgeRuntime
+
+    def __init__(
+        self,
+        host: DshAgentProviderHost,
+        registration: DshAgentProviderRegistration,
+        *,
+        execution_factory: KsADKHarnessProviderFactory | None = None,
+        owns_host: bool = True,
+    ) -> None:
+        if execution_factory is None:
+            # Keep the Harness/ADK dependency optional until this provider is
+            # selected; listing Codex or DSH plugins must stay cheap.
+            from ksadk.plugins.providers.harness import KsADKHarnessProviderFactory
+
+            execution_factory = KsADKHarnessProviderFactory()
+        super().__init__(
+            spec=HARNESS_DSH_SPEC,
+            host=host,
+            registration=registration,
+            execution_factory=execution_factory,
+            owns_host=owns_host,
+        )
+
+    async def stage(
+        self,
+        manifest: PluginManifest,
+        *,
+        profile: CompositionProfile,
+        services: Mapping[str, Any],
+    ) -> KsADKHarnessDshBridgeRuntime:
+        runtime = await super().stage(manifest, profile=profile, services=services)
+        assert isinstance(runtime, KsADKHarnessDshBridgeRuntime)
+        return runtime
+
+
+__all__ = [
+    "KsADKHarnessDshBridgeFactory",
+    "KsADKHarnessDshBridgeRuntime",
+    "SHIPPED_HARNESS_DSH_PACKAGE",
+    "SHIPPED_HARNESS_PROVIDER_ID",
+    "SHIPPED_HARNESS_PROVIDER_VERSION",
+    "ShippedHarnessDshBundle",
+    "shipped_harness_dsh_bundle",
+    "shipped_harness_dsh_host_command",
+]

ksadk/plugins/providers/legacy.py

@@ -0,0 +1,215 @@
+"""Central compatibility boundary for pre-DSH Harness AgentBundles.
+
+Reading an old Bundle and selecting the in-process Harness provider are two
+different decisions.  Existing ADK, LangGraph and Codex artifacts continue to
+use their established adapters.  The Harness compatibility adapter is only
+available for an immutable Bundle v1 digest that a release/migration owner has
+explicitly registered as a historical Harness artifact.
+
+Bundle v2 is never eligible for this bridge.  It must resolve the Harness
+provider from the active DSH registration and its deterministic PluginLock.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Iterable, Literal
+
+from pydantic import ValidationError
+
+from ksadk.plugins.contracts import PluginManifest
+from ksadk.plugins.providers.legacy_catalog import (
+    KSADK_HARNESS_AGENT_PROVIDER_PLUGIN_ID,
+    legacy_harness_agent_provider_manifest,
+)
+from ksadk.studio.capabilities import compute_bundle_digest
+from ksadk.studio.contracts import BundleManifest
+
+
+class LegacyBundleCompatibilityError(ValueError):
+    """Stable fail-closed result from the legacy Bundle normalizer."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+@dataclass(frozen=True)
+class LegacyHarnessSource:
+    """Immutable identity approved by a release or migration process."""
+
+    bundle_digest: str
+    resolved_digest: str
+    source_revision: int
+
+    @classmethod
+    def from_verified_manifest(cls, manifest: BundleManifest) -> "LegacyHarnessSource":
+        """Capture an already-verified historical Bundle v1 identity."""
+
+        if manifest.bundle_format != "agentkit.bundle/v1":
+            raise LegacyBundleCompatibilityError(
+                "legacy_harness_bundle_version_unsupported",
+                "Only an AgentBundle v1 can be registered as a legacy Harness source",
+            )
+        _require_self_consistent_digest(manifest)
+        return cls(
+            bundle_digest=manifest.bundle_digest,
+            resolved_digest=manifest.resolved_digest,
+            source_revision=manifest.source_revision,
+        )
+
+
+@dataclass(frozen=True)
+class HarnessProviderSelection:
+    """Normalized provider choice; execution stays with the owning runtime."""
+
+    route: Literal["dsh", "legacy"]
+    manifest: PluginManifest | None = None
+
+
+class LegacyBundleAdapter:
+    """Select Harness compatibility without broad version-based fallback."""
+
+    def __init__(self, sources: Iterable[LegacyHarnessSource] = ()) -> None:
+        source_by_digest: dict[str, LegacyHarnessSource] = {}
+        for source in sources:
+            previous = source_by_digest.setdefault(source.bundle_digest, source)
+            if previous != source:
+                raise ValueError("conflicting legacy Harness identities use the same bundle digest")
+        self._sources = source_by_digest
+
+    def select_from_bundle(
+        self,
+        root: str | Path,
+        *,
+        registered_provider_ids: Iterable[str] = (),
+    ) -> tuple[BundleManifest, HarnessProviderSelection | None]:
+        """Verify one immutable Bundle before applying the compatibility rule."""
+
+        bundle_root = Path(root).resolve()
+        try:
+            payload = json.loads((bundle_root / "manifest.json").read_text(encoding="utf-8"))
+            manifest = BundleManifest.model_validate(payload)
+        except (OSError, UnicodeError, json.JSONDecodeError, ValidationError) as error:
+            raise LegacyBundleCompatibilityError(
+                "bundle_manifest_invalid", "AgentBundle manifest is invalid"
+            ) from error
+        _require_self_consistent_digest(manifest)
+        declared: set[str] = set()
+        for entry in manifest.files:
+            relative = PurePosixPath(entry.path)
+            if relative.is_absolute() or ".." in relative.parts:
+                raise LegacyBundleCompatibilityError(
+                    "bundle_path_invalid", "AgentBundle contains an unsafe file path"
+                )
+            path = (bundle_root / Path(*relative.parts)).resolve()
+            if not path.is_relative_to(bundle_root):
+                raise LegacyBundleCompatibilityError(
+                    "bundle_path_invalid", "AgentBundle file path escapes its root"
+                )
+            try:
+                content = path.read_bytes()
+            except OSError as error:
+                raise LegacyBundleCompatibilityError(
+                    "bundle_file_missing", f"AgentBundle file is missing: {entry.path}"
+                ) from error
+            digest = f"sha256:{hashlib.sha256(content).hexdigest()}"
+            if len(content) != entry.size or digest != entry.sha256:
+                raise LegacyBundleCompatibilityError(
+                    "bundle_file_digest_mismatch",
+                    f"AgentBundle file failed integrity verification: {entry.path}",
+                )
+            declared.add(entry.path)
+        actual = {
+            path.relative_to(bundle_root).as_posix()
+            for path in bundle_root.rglob("*")
+            if path.is_file() and path.name != "manifest.json"
+        }
+        if actual != declared:
+            raise LegacyBundleCompatibilityError(
+                "bundle_membership_mismatch",
+                "AgentBundle contains missing or undeclared files",
+            )
+        return manifest, self.select_harness_provider(
+            manifest,
+            registered_provider_ids=registered_provider_ids,
+        )
+
+    def select_harness_provider(
+        self,
+        manifest: BundleManifest,
+        *,
+        registered_provider_ids: Iterable[str] = (),
+    ) -> HarnessProviderSelection | None:
+        """Return the exact Harness route, or ``None`` for non-Harness Bundles.
+
+        For Bundle v1, a matching approved digest is the Harness discriminator;
+        this also supports historical manifests that predate ``runtimeType``.
+        For Bundle v2, ``runtimeType=harness`` always requires a ready DSH
+        provider registration.  No v1 allowlist entry can change that rule.
+        """
+
+        runtime_type = manifest.runtime_type.strip().lower()
+        registered = frozenset(registered_provider_ids)
+
+        if manifest.bundle_format == "agentkit.bundle/v2":
+            if runtime_type != "harness":
+                return None
+            if KSADK_HARNESS_AGENT_PROVIDER_PLUGIN_ID not in registered:
+                raise LegacyBundleCompatibilityError(
+                    "agent_provider_not_registered",
+                    "Harness Bundle v2 requires a ready DSH provider registration",
+                )
+            return HarnessProviderSelection(route="dsh")
+
+        source = self._sources.get(manifest.bundle_digest)
+        if source is None:
+            if runtime_type == "harness":
+                raise LegacyBundleCompatibilityError(
+                    "legacy_harness_source_unrecognized",
+                    "Bundle v1 is not an explicitly registered historical Harness artifact",
+                )
+            return None
+
+        _require_self_consistent_digest(manifest)
+        if (
+            manifest.resolved_digest != source.resolved_digest
+            or manifest.source_revision != source.source_revision
+        ):
+            raise LegacyBundleCompatibilityError(
+                "legacy_harness_source_mismatch",
+                "Bundle v1 metadata does not match its registered historical identity",
+            )
+        if runtime_type not in {"", "harness"}:
+            raise LegacyBundleCompatibilityError(
+                "legacy_harness_runtime_mismatch",
+                "Registered historical Harness Bundle declares another runtime type",
+            )
+        if manifest.plugin_lock_digest or manifest.composition_profile_digest:
+            raise LegacyBundleCompatibilityError(
+                "legacy_harness_composition_forbidden",
+                "A legacy Harness Bundle cannot carry partial Bundle v2 composition state",
+            )
+        return HarnessProviderSelection(
+            route="legacy",
+            manifest=legacy_harness_agent_provider_manifest(),
+        )
+
+
+def _require_self_consistent_digest(manifest: BundleManifest) -> None:
+    if not manifest.bundle_digest or manifest.bundle_digest != compute_bundle_digest(manifest):
+        raise LegacyBundleCompatibilityError(
+            "legacy_harness_bundle_digest_mismatch",
+            "Historical Harness manifest does not match its declared bundle digest",
+        )
+
+
+__all__ = [
+    "HarnessProviderSelection",
+    "LegacyBundleAdapter",
+    "LegacyBundleCompatibilityError",
+    "LegacyHarnessSource",
+]

ksadk/plugins/providers/legacy_catalog.py

@@ -0,0 +1,100 @@
+"""Explicit compatibility catalog for pre-DSH AgentProvider manifests.
+
+All new AgentProviders, including the official Codex and KsADK Harness
+Bundles, enter Bundle v2 composition only through a ready DSH registration.
+The old in-process Harness manifest remains an explicit compatibility artifact
+for already-built Agents; callers must never add it to new resolution silently.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+from ksadk.plugins.contracts import PluginManifest
+
+BUILTIN_PROVIDER_VERSION = "1.0.0"
+CODEX_AGENT_PROVIDER_PLUGIN_ID = "io.ksadk.codex-provider"
+KSADK_HARNESS_AGENT_PROVIDER_PLUGIN_ID = "io.ksadk.harness-provider"
+
+
+def _digest(plugin_id: str) -> str:
+    payload = f"{plugin_id}@{BUILTIN_PROVIDER_VERSION}:builtin-provider-v1".encode()
+    return f"sha256:{hashlib.sha256(payload).hexdigest()}"
+
+
+def _provider_manifest(
+    plugin_id: str,
+    *,
+    domain: str,
+    runtime: str,
+    isolation: str,
+    source: str,
+    entrypoint: str | None = None,
+) -> PluginManifest:
+    spec: dict[str, object] = {
+        "domain": domain,
+        "runtime": runtime,
+        "provides": [
+            {
+                "definition": "agent.provider/v1",
+                "slot": "agent.execution",
+                "mode": "unique",
+            }
+        ],
+        "permissions": [],
+        "isolation": isolation,
+        "compatibility": {
+            "kernelApi": ">=1,<2",
+            "runtimeProtocols": ["agentkit.runtime/v1"],
+            "python": ">=3.10,<3.15" if runtime == "python" else None,
+        },
+        "healthContract": "plugin.health/v1",
+        "provenance": {
+            "source": source,
+            "digest": _digest(plugin_id),
+            "license": "Apache-2.0",
+        },
+    }
+    if entrypoint is not None:
+        spec["entrypoint"] = entrypoint
+    compatibility = spec["compatibility"]
+    assert isinstance(compatibility, dict)
+    if compatibility["python"] is None:
+        del compatibility["python"]
+    manifest = PluginManifest.model_validate(
+        {
+            "metadata": {"id": plugin_id, "version": BUILTIN_PROVIDER_VERSION},
+            "spec": spec,
+        }
+    )
+    if not isinstance(manifest, PluginManifest):  # pragma: no cover - Pydantic invariant
+        raise TypeError("built-in provider manifest validation returned an invalid type")
+    return manifest
+
+
+def builtin_agent_provider_manifests() -> tuple[PluginManifest, ...]:
+    """Return no Bundle v2 providers; DSH registration is authoritative."""
+
+    return ()
+
+
+def legacy_harness_agent_provider_manifest() -> PluginManifest:
+    """Return the old manifest only for an explicitly detected legacy Agent."""
+
+    return _provider_manifest(
+        KSADK_HARNESS_AGENT_PROVIDER_PLUGIN_ID,
+        domain="ksadk-platform",
+        runtime="python",
+        isolation="in-process",
+        source="builtin",
+        entrypoint="ksadk.plugins.providers.harness:KsADKHarnessProviderFactory",
+    )
+
+
+__all__ = [
+    "BUILTIN_PROVIDER_VERSION",
+    "CODEX_AGENT_PROVIDER_PLUGIN_ID",
+    "KSADK_HARNESS_AGENT_PROVIDER_PLUGIN_ID",
+    "builtin_agent_provider_manifests",
+    "legacy_harness_agent_provider_manifest",
+]

ksadk/plugins/providers/mcp_projection.py

@@ -0,0 +1,150 @@
+"""Provider-neutral projection of PluginHost MCP connector capabilities."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Sequence
+from contextlib import AsyncExitStack
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+from ksadk.harness.config import McpToolSpec
+from ksadk.plugins.bundle import ResolvedPluginBundle
+from ksadk.plugins.host import PluginExecutionContext, PluginHostError
+
+
+@runtime_checkable
+class ActivationMCPSource(Protocol):
+    """MCP source whose lease is bound to one PluginHost activation."""
+
+    def activation_mcp_specs(
+        self,
+        bundle: ResolvedPluginBundle,
+        *,
+        activation_key: str,
+    ) -> Sequence[McpToolSpec] | Awaitable[Sequence[McpToolSpec]]: ...
+
+    async def release_activation_mcp_specs(
+        self,
+        activation_key: str,
+        specs: Sequence[McpToolSpec],
+    ) -> None: ...
+
+
+@runtime_checkable
+class StaticMCPSource(Protocol):
+    """Compatibility seam implemented by existing MCP capability plugins."""
+
+    def harness_mcp_specs(
+        self,
+        bundle: ResolvedPluginBundle,
+    ) -> Sequence[McpToolSpec] | Awaitable[Sequence[McpToolSpec]]: ...
+
+
+@runtime_checkable
+class ReleasableStaticMCPSource(Protocol):
+    async def release_harness_mcp_specs(self, specs: Sequence[McpToolSpec]) -> None: ...
+
+
+@dataclass
+class MCPProjectionLease:
+    """Projected connector specs and their activation-owned cleanup."""
+
+    specs: tuple[McpToolSpec, ...]
+    owners: tuple[str, ...]
+    _cleanup: AsyncExitStack
+    _close_task: asyncio.Task[None] | None = None
+
+    async def aclose(self) -> None:
+        if self._close_task is None:
+            self._close_task = asyncio.create_task(self._cleanup.aclose())
+        await _finish_owned_task(self._close_task)
+
+
+async def _finish_owned_task(task: asyncio.Task[None]) -> None:
+    """Finish a security cleanup before propagating caller cancellation."""
+
+    interrupted = False
+    while not task.done():
+        try:
+            await asyncio.shield(task)
+        except asyncio.CancelledError:
+            interrupted = True
+    task.result()
+    if interrupted:
+        raise asyncio.CancelledError
+
+
+async def project_mcp_capabilities(
+    capabilities: PluginExecutionContext,
+    bundle: ResolvedPluginBundle,
+    *,
+    activation_only: bool = False,
+) -> MCPProjectionLease:
+    """Activate every MCP capability and retain cleanup for the provider."""
+
+    cleanup = AsyncExitStack()
+    specs: list[McpToolSpec] = []
+    owners: list[str] = []
+    names: set[str] = set()
+    try:
+        for binding in capabilities.all("mcp.connector/v1"):
+            runtime = binding.runtime
+            if isinstance(runtime, ActivationMCPSource):
+                projected = runtime.activation_mcp_specs(
+                    bundle,
+                    activation_key=capabilities.activation_key,
+                )
+                if isinstance(projected, Awaitable):
+                    projected = await projected
+                projected_specs = tuple(projected)
+                cleanup.push_async_callback(
+                    runtime.release_activation_mcp_specs,
+                    capabilities.activation_key,
+                    projected_specs,
+                )
+            elif isinstance(runtime, StaticMCPSource):
+                if activation_only:
+                    continue
+                projected = runtime.harness_mcp_specs(bundle)
+                if isinstance(projected, Awaitable):
+                    projected = await projected
+                projected_specs = tuple(projected)
+                if isinstance(runtime, ReleasableStaticMCPSource):
+                    cleanup.push_async_callback(
+                        runtime.release_harness_mcp_specs,
+                        projected_specs,
+                    )
+            else:
+                raise PluginHostError(
+                    "mcp_capability_incompatible",
+                    f"plugin {binding.plugin_id} cannot project MCP connector config",
+                )
+            for spec in projected_specs:
+                if not isinstance(spec, McpToolSpec) or not spec.name.strip():
+                    raise PluginHostError(
+                        "mcp_capability_invalid",
+                        f"plugin {binding.plugin_id} returned an invalid MCP connector",
+                    )
+                if spec.name in names:
+                    raise PluginHostError(
+                        "mcp_capability_ambiguous",
+                        f"more than one MCP connector is named {spec.name!r}",
+                    )
+                names.add(spec.name)
+                specs.append(spec)
+            owners.append(binding.plugin_id)
+    except BaseException:
+        close = asyncio.create_task(cleanup.aclose())
+        await _finish_owned_task(close)
+        raise
+    return MCPProjectionLease(tuple(specs), tuple(owners), cleanup)
+
+
+__all__ = [
+    "ActivationMCPSource",
+    "MCPProjectionLease",
+    "ReleasableStaticMCPSource",
+    "StaticMCPSource",
+    "project_mcp_capabilities",
+]