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

ksadk/plugins/providers/shipped_dsh.py

@@ -0,0 +1,370 @@
+"""Shared implementation for wheel-owned DSH AgentProvider bundles.
+
+Provider-specific modules declare identity and select an execution factory.
+This module owns the repeated package validation, fixed host command,
+registration fences, and bridge lifecycle.  It does not own an agent loop.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Protocol
+
+from ksadk.plugins.bundle import ResolvedPluginBundle
+from ksadk.plugins.contracts import CompositionProfile, PluginManifest
+from ksadk.plugins.host import PluginExecutionContext, PluginHostError
+from ksadk.plugins.providers.dsh import (
+    DshAgentProviderHost,
+    DshAgentProviderRegistration,
+    dsh_agent_provider_manifest,
+)
+
+
+@dataclass(frozen=True)
+class ShippedDshProviderSpec:
+    key: str
+    display_name: str
+    package_name: str
+    provider_id: str
+    version: str
+    bundle_directory: str
+    bridge_required_code: str
+    bridge_required_message: str
+
+    @property
+    def provider_ref(self) -> str:
+        return f"plugin://{self.provider_id}@{self.version}"
+
+    def error_code(self, suffix: str) -> str:
+        return f"{self.key}_dsh_{suffix}"
+
+
+CODEX_DSH_SPEC = ShippedDshProviderSpec(
+    key="codex",
+    display_name="Codex",
+    package_name="@kingsoftcloud/ksadk-codex-provider",
+    provider_id="io.ksadk.codex-provider",
+    version="1.0.0",
+    bundle_directory="ksadk-codex",
+    bridge_required_code="codex_provider_bridge_required",
+    bridge_required_message=(
+        "Codex execution requires the registration-gated RuntimeAdapter bridge"
+    ),
+)
+
+HARNESS_DSH_SPEC = ShippedDshProviderSpec(
+    key="harness",
+    display_name="KsADK Harness",
+    package_name="@kingsoftcloud/ksadk-harness-provider",
+    provider_id="io.ksadk.harness-provider",
+    version="1.0.0",
+    bundle_directory="ksadk-harness",
+    bridge_required_code="harness_legacy_bridge_required",
+    bridge_required_message=(
+        "Harness execution requires the registration-gated RuntimeAdapter bridge"
+    ),
+)
+
+SHIPPED_DSH_PROVIDER_SPECS = {
+    CODEX_DSH_SPEC.key: CODEX_DSH_SPEC,
+    HARNESS_DSH_SPEC.key: HARNESS_DSH_SPEC,
+}
+
+
+@dataclass(frozen=True)
+class ShippedDshBundle:
+    package_name: str
+    version: str
+    root: Path
+    patch: Path
+
+
+def load_shipped_dsh_bundle(spec: ShippedDshProviderSpec) -> ShippedDshBundle:
+    """Locate and validate one immutable DSH bundle shipped in the wheel."""
+
+    root = Path(__file__).with_name("bundles") / spec.bundle_directory
+    package_path = root / "package.json"
+    try:
+        payload = json.loads(package_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        raise PluginHostError(
+            spec.error_code("bundle_invalid"),
+            f"shipped {spec.display_name} DSH Bundle package.json is unavailable",
+        ) from error
+    if not isinstance(payload, dict):
+        raise PluginHostError(
+            spec.error_code("bundle_invalid"),
+            f"shipped {spec.display_name} DSH Bundle package.json must be an object",
+        )
+    dsh = payload.get("dsh")
+    bundle = dsh.get("bundle") if isinstance(dsh, dict) else None
+    patch_value = bundle.get("patch") if isinstance(bundle, dict) else None
+    if (
+        payload.get("name") != spec.package_name
+        or payload.get("version") != spec.version
+        or patch_value != "./cordis.patch.yml"
+        or "ksadk" in payload
+    ):
+        raise PluginHostError(
+            spec.error_code("bundle_invalid"),
+            f"shipped {spec.display_name} provider is not a standard pinned DSH Bundle",
+        )
+    patch = (root / str(patch_value)).resolve()
+    try:
+        patch.relative_to(root.resolve())
+    except ValueError as error:
+        raise PluginHostError(
+            spec.error_code("bundle_invalid"),
+            "DSH Bundle patch escapes its package root",
+        ) from error
+    if not patch.is_file() or not (root / "index.mjs").is_file():
+        raise PluginHostError(
+            spec.error_code("bundle_invalid"),
+            "DSH Bundle contribution files are missing",
+        )
+    return ShippedDshBundle(
+        package_name=spec.package_name,
+        version=spec.version,
+        root=root.resolve(),
+        patch=patch,
+    )
+
+
+def shipped_dsh_host_command(
+    spec: ShippedDshProviderSpec,
+    *,
+    python_executable: str | None = None,
+) -> tuple[str, ...]:
+    """Return fixed argv; bundle content never controls the executable."""
+
+    load_shipped_dsh_bundle(spec)
+    executable = str(python_executable or sys.executable).strip()
+    if not executable or "\x00" in executable:
+        raise PluginHostError(spec.error_code("host_invalid"), "Python host executable is invalid")
+    return executable, "-m", "ksadk.plugins.providers.dsh_descriptor_host", spec.key
+
+
+class _ExecutionRuntime(Protocol):
+    async def start(self) -> None: ...
+
+    async def health(self) -> bool: ...
+
+    async def prepare(
+        self,
+        bundle: ResolvedPluginBundle,
+        *,
+        capabilities: PluginExecutionContext,
+    ) -> Any: ...
+
+    async def drain(self) -> None: ...
+
+    async def dispose(self) -> None: ...
+
+
+class _ExecutionFactory(Protocol):
+    async def stage(
+        self,
+        manifest: PluginManifest,
+        *,
+        profile: CompositionProfile,
+        services: Mapping[str, Any],
+    ) -> _ExecutionRuntime: ...
+
+
+class ShippedDshBridgeRuntime:
+    """DSH registration lifecycle delegating execution to the owning runtime."""
+
+    def __init__(
+        self,
+        *,
+        spec: ShippedDshProviderSpec,
+        host: DshAgentProviderHost,
+        registration: DshAgentProviderRegistration,
+        execution_runtime: _ExecutionRuntime,
+        owns_host: bool,
+    ) -> None:
+        self._spec = spec
+        self._host = host
+        self._registration = registration
+        self._execution_runtime = execution_runtime
+        self._owns_host = owns_host
+        self._started = False
+        self._disposed = False
+
+    async def start(self) -> None:
+        if self._disposed:
+            raise PluginHostError(
+                self._spec.error_code("bridge_disposed"),
+                f"{self._spec.display_name} DSH bridge is disposed",
+            )
+        current = await self._host.registration()
+        require_same_registration(self._spec, current, self._registration)
+        await self._execution_runtime.start()
+        self._started = True
+
+    async def health(self) -> bool:
+        if not self._started or self._disposed:
+            return False
+        return await self._host.health() and await self._execution_runtime.health()
+
+    async def prepare(
+        self,
+        bundle: ResolvedPluginBundle,
+        *,
+        capabilities: PluginExecutionContext,
+    ) -> Any:
+        if not await self.health():
+            raise PluginHostError(
+                self._spec.error_code("bridge_unavailable"),
+                f"{self._spec.display_name} DSH provider is not ready",
+            )
+        if bundle.composition.profile.agent_provider.ref != self._spec.provider_ref:
+            raise PluginHostError(
+                self._spec.error_code("profile_mismatch"),
+                "Agent Bundle does not select the registered "
+                f"{self._spec.display_name} DSH provider",
+            )
+        return await self._execution_runtime.prepare(bundle, capabilities=capabilities)
+
+    async def drain(self) -> None:
+        if self._disposed:
+            return
+        await self._execution_runtime.drain()
+        if self._owns_host and self._host.pid is not None:
+            await self._host.drain()
+        self._started = False
+
+    async def dispose(self) -> None:
+        if self._disposed:
+            return
+        self._disposed = True
+        self._started = False
+        first_error: BaseException | None = None
+        try:
+            await self._execution_runtime.dispose()
+        except BaseException as error:  # cleanup must continue
+            first_error = error
+        if self._owns_host:
+            try:
+                await self._host.dispose()
+            except BaseException as error:  # cleanup must continue
+                if first_error is None:
+                    first_error = error
+        if first_error is not None:
+            raise first_error
+
+
+class ShippedDshBridgeFactory:
+    """Admit one exact DSH registration and create its execution bridge."""
+
+    runtime_class = ShippedDshBridgeRuntime
+
+    def __init__(
+        self,
+        *,
+        spec: ShippedDshProviderSpec,
+        host: DshAgentProviderHost,
+        registration: DshAgentProviderRegistration,
+        execution_factory: _ExecutionFactory,
+        owns_host: bool = True,
+    ) -> None:
+        validate_registration(spec, registration)
+        self._spec = spec
+        self._host = host
+        self._registration = registration
+        self._execution_factory = execution_factory
+        self._owns_host = owns_host
+        self.runtime: ShippedDshBridgeRuntime | None = None
+
+    async def stage(
+        self,
+        manifest: PluginManifest,
+        *,
+        profile: CompositionProfile,
+        services: Mapping[str, Any],
+    ) -> ShippedDshBridgeRuntime:
+        expected_manifest = dsh_agent_provider_manifest(
+            self._registration.descriptor,
+            preflight=self._registration.preflight,
+        )
+        if manifest != expected_manifest:
+            raise PluginHostError(
+                self._spec.error_code("manifest_mismatch"),
+                f"{self._spec.display_name} provider manifest did not come from "
+                "the ready DSH registration",
+            )
+        if profile.agent_provider.ref != self._spec.provider_ref:
+            raise PluginHostError(
+                self._spec.error_code("profile_mismatch"),
+                "composition profile does not select the shipped "
+                f"{self._spec.display_name} DSH provider",
+            )
+        current = await self._host.registration()
+        require_same_registration(self._spec, current, self._registration)
+        execution_runtime = await self._execution_factory.stage(
+            manifest, profile=profile, services=services
+        )
+        self.runtime = self.runtime_class(
+            spec=self._spec,
+            host=self._host,
+            registration=self._registration,
+            execution_runtime=execution_runtime,
+            owns_host=self._owns_host,
+        )
+        return self.runtime
+
+
+def validate_registration(
+    spec: ShippedDshProviderSpec,
+    registration: DshAgentProviderRegistration,
+) -> None:
+    descriptor = registration.descriptor
+    preflight = registration.preflight
+    if (
+        descriptor.provider_id != spec.provider_id
+        or descriptor.provider_version != spec.version
+        or descriptor.plugin_name != spec.package_name
+        or not preflight.ready
+        or preflight.profile_digest != descriptor.profile_digest
+        or preflight.descriptor_digest != descriptor.descriptor_digest
+    ):
+        raise PluginHostError(
+            spec.error_code("registration_invalid"),
+            f"{spec.display_name} DSH registration does not match the shipped provider fences",
+        )
+
+
+def require_same_registration(
+    spec: ShippedDshProviderSpec,
+    current: DshAgentProviderRegistration,
+    expected: DshAgentProviderRegistration,
+) -> None:
+    validate_registration(spec, current)
+    if (
+        current.descriptor != expected.descriptor
+        or current.preflight != expected.preflight
+        or current.manifest != expected.manifest
+    ):
+        raise PluginHostError(
+            spec.error_code("registration_changed"),
+            f"{spec.display_name} DSH provider changed after admission",
+        )
+
+
+__all__ = [
+    "CODEX_DSH_SPEC",
+    "HARNESS_DSH_SPEC",
+    "SHIPPED_DSH_PROVIDER_SPECS",
+    "ShippedDshBridgeFactory",
+    "ShippedDshBridgeRuntime",
+    "ShippedDshBundle",
+    "ShippedDshProviderSpec",
+    "load_shipped_dsh_bundle",
+    "require_same_registration",
+    "shipped_dsh_host_command",
+    "validate_registration",
+]

ksadk/plugins/resolver.py

@@ -0,0 +1,338 @@
+"""Pure, deterministic Profile -> PluginLock resolver.
+
+This module is intentionally side-effect free: it resolves only supplied
+manifests and never imports their entrypoints.  PluginHost will later own
+admission, staging, start, health, and disposal.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Iterable
+
+from ksadk.plugins.contracts import (
+    CompositionProfile,
+    LockedCapability,
+    PluginDependency,
+    PluginLock,
+    PluginLockEntry,
+    PluginManifest,
+    PluginReference,
+    plugin_lock_digest,
+)
+
+
+class PluginResolutionError(ValueError):
+    """Stable, typed rejection from the pure composition resolver."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+@dataclass(frozen=True)
+class ResolvedComposition:
+    profile: CompositionProfile
+    profile_digest: str
+    plugin_lock: PluginLock
+    plugin_lock_digest: str
+    # Build-time audit facts from the exact manifests that produced the lock.
+    # This is an internal immutable projection, not another wire manifest: the
+    # public Bundle continues to bind only CompositionProfile and PluginLock.
+    manifests: tuple[PluginManifest, ...] = ()
+    # Studio stamps the exact AgentDraft snapshot used to select resources.
+    # Generic resolver callers leave this empty; a composed Studio build must
+    # require it so a composition from another revision cannot be paired with
+    # a newly compiled resolved-agent-spec.
+    source_digest: str = field(default="", compare=False, repr=False)
+
+
+def canonical_composition_profile(profile: CompositionProfile) -> bytes:
+    return json.dumps(
+        profile.model_dump(by_alias=True, exclude_none=True, mode="json"),
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+
+
+def composition_profile_digest(profile: CompositionProfile) -> str:
+    return f"sha256:{hashlib.sha256(canonical_composition_profile(profile)).hexdigest()}"
+
+
+class PluginRegistry:
+    """Immutable in-memory manifest catalog used by build-time resolution."""
+
+    def __init__(self, manifests: Iterable[PluginManifest]) -> None:
+        indexed: dict[tuple[str, str], PluginManifest] = {}
+        for manifest in manifests:
+            key = (manifest.metadata.id, manifest.metadata.version)
+            if key in indexed:
+                raise PluginResolutionError(
+                    "plugin_manifest_duplicate",
+                    f"duplicate plugin manifest {manifest.metadata.id}@{manifest.metadata.version}",
+                )
+            indexed[key] = manifest
+        self._manifests = indexed
+
+    def resolve(self, profile: CompositionProfile) -> ResolvedComposition:
+        """Resolve the requested graph without running any plugin code."""
+
+        selected: dict[str, PluginManifest] = {}
+        dependencies: dict[str, set[str]] = {}
+
+        def select_reference(reference: PluginReference) -> PluginManifest:
+            plugin_id, version = _parse_plugin_reference(reference.ref)
+            manifest = self._manifests.get((plugin_id, version))
+            if manifest is None:
+                raise PluginResolutionError(
+                    "plugin_manifest_unresolved",
+                    f"plugin {plugin_id}@{version} is not in the selected catalog",
+                )
+            select_manifest(manifest)
+            return manifest
+
+        def select_manifest(manifest: PluginManifest) -> None:
+            plugin_id = manifest.metadata.id
+            if plugin_id in selected:
+                if selected[plugin_id].metadata.version != manifest.metadata.version:
+                    raise PluginResolutionError(
+                        "plugin_version_conflict",
+                        f"profile requires conflicting versions of plugin {plugin_id}",
+                    )
+                return
+            selected[plugin_id] = manifest
+            dependencies.setdefault(plugin_id, set())
+            for requirement in manifest.spec.requires:
+                provider = self._resolve_requirement(requirement.definition, requirement.version)
+                if provider.metadata.id == plugin_id:
+                    raise PluginResolutionError(
+                        "plugin_dependency_cycle",
+                        f"plugin {plugin_id} cannot provide its own required capability",
+                    )
+                dependencies[plugin_id].add(provider.metadata.id)
+                select_manifest(provider)
+
+        provider = select_reference(profile.agent_provider)
+        self._require_agent_provider(provider)
+        for capability in profile.capabilities:
+            if capability.ref.startswith("plugin://"):
+                # A capability entry uses the same pinning grammar as the
+                # agent provider, but it has no special agent-provider role.
+                plugin_id, version = _parse_plugin_reference(capability.ref)
+                manifest = self._manifests.get((plugin_id, version))
+                if manifest is None:
+                    raise PluginResolutionError(
+                        "plugin_manifest_unresolved",
+                        f"plugin {plugin_id}@{version} is not in the selected catalog",
+                    )
+                select_manifest(manifest)
+
+        self._validate_unique_slots(selected.values())
+        lock = self._build_lock(selected, dependencies)
+        return ResolvedComposition(
+            profile=profile,
+            profile_digest=composition_profile_digest(profile),
+            plugin_lock=lock,
+            plugin_lock_digest=plugin_lock_digest(lock),
+            manifests=tuple(
+                sorted(
+                    selected.values(),
+                    key=lambda item: (item.metadata.id, item.metadata.version),
+                )
+            ),
+        )
+
+    def manifest_for(self, plugin_id: str, version: str) -> PluginManifest:
+        """Return an exact manifest already admitted to this local catalog."""
+
+        manifest = self._manifests.get((plugin_id, version))
+        if manifest is None:
+            raise PluginResolutionError(
+                "plugin_manifest_unresolved",
+                f"plugin {plugin_id}@{version} is not in the selected catalog",
+            )
+        return manifest
+
+    def _resolve_requirement(self, definition: str, constraint: str) -> PluginManifest:
+        candidates = [
+            manifest
+            for manifest in self._manifests.values()
+            if any(offer.definition == definition for offer in manifest.spec.provides)
+            and _version_satisfies(manifest.metadata.version, constraint)
+        ]
+        if not candidates:
+            raise PluginResolutionError(
+                "plugin_requirement_unresolved",
+                f"no plugin provides {definition!r} matching {constraint!r}",
+            )
+        if len(candidates) > 1:
+            names = ", ".join(
+                f"{item.metadata.id}@{item.metadata.version}"
+                for item in sorted(
+                    candidates,
+                    key=lambda item: (item.metadata.id, item.metadata.version),
+                )
+            )
+            raise PluginResolutionError(
+                "plugin_requirement_ambiguous",
+                f"multiple plugins provide {definition!r}: {names}",
+            )
+        return candidates[0]
+
+    @staticmethod
+    def _require_agent_provider(manifest: PluginManifest) -> None:
+        if any(
+            offer.definition == "agent.provider/v1"
+            and offer.slot == "agent.execution"
+            and offer.mode == "unique"
+            for offer in manifest.spec.provides
+        ):
+            return
+        raise PluginResolutionError(
+            "agent_provider_invalid",
+            f"plugin {manifest.metadata.id}@{manifest.metadata.version} "
+            "does not own agent.execution",
+        )
+
+    @staticmethod
+    def _validate_unique_slots(manifests: Iterable[PluginManifest]) -> None:
+        owners: dict[str, str] = {}
+        for manifest in manifests:
+            for offer in manifest.spec.provides:
+                if offer.mode != "unique":
+                    continue
+                existing = owners.get(offer.slot)
+                if existing and existing != manifest.metadata.id:
+                    raise PluginResolutionError(
+                        "plugin_slot_conflict",
+                        f"unique slot {offer.slot!r} is owned by both {existing} "
+                        f"and {manifest.metadata.id}",
+                    )
+                owners[offer.slot] = manifest.metadata.id
+
+    @staticmethod
+    def _build_lock(
+        selected: dict[str, PluginManifest], dependencies: dict[str, set[str]]
+    ) -> PluginLock:
+        entries: list[PluginLockEntry] = []
+        for plugin_id, manifest in selected.items():
+            entries.append(
+                PluginLockEntry(
+                    id=plugin_id,
+                    version=manifest.metadata.version,
+                    digest=manifest.spec.provenance.digest,
+                    source=manifest.spec.provenance.source,
+                    signature_ref=manifest.spec.provenance.signature_ref,
+                    license=manifest.spec.provenance.license,
+                    upstream=manifest.spec.provenance.upstream,
+                    components=manifest.spec.provenance.components,
+                    provides=[
+                        LockedCapability(
+                            definition=offer.definition,
+                            slot=offer.slot,
+                            owner=plugin_id,
+                        )
+                        for offer in manifest.spec.provides
+                    ],
+                    dependencies=[
+                        PluginDependency(
+                            id=dependency_id,
+                            version=selected[dependency_id].metadata.version,
+                            digest=selected[dependency_id].spec.provenance.digest,
+                        )
+                        for dependency_id in sorted(dependencies.get(plugin_id, set()))
+                    ],
+                )
+            )
+        return PluginLock(plugins=entries)
+
+
+def _parse_plugin_reference(value: str) -> tuple[str, str]:
+    # The Pydantic type validates this at the public boundary.  Keeping the
+    # parser defensive makes this pure resolver safe for values reconstructed
+    # by other language consumers.
+    if not value.startswith("plugin://") or "@" not in value:
+        raise PluginResolutionError(
+            "plugin_reference_invalid", f"invalid plugin reference {value!r}"
+        )
+    plugin_id, version = value.removeprefix("plugin://").rsplit("@", 1)
+    return plugin_id, version
+
+
+_COMPARATOR = re.compile(r"^(>=|<=|>|<|=)?(\d+)\.(\d+)\.(\d+)$")
+
+
+def _version_satisfies(version: str, constraint: str) -> bool:
+    """Small exact-range evaluator for manifest capability requirements.
+
+    The manifest accepts a SemVer range string rather than an unbounded
+    dependency resolver.  P2-00A supports the explicit comparator form used
+    by the contract examples (for example ``>=1,<2``); unsupported forms are
+    rejected instead of silently accepting a possibly incompatible plugin.
+    """
+
+    parsed_version = _parse_release(version, field="plugin version")
+    comparators = [part.strip() for part in constraint.split(",") if part.strip()]
+    if not comparators:
+        raise PluginResolutionError("plugin_constraint_invalid", "empty plugin requirement version")
+    for comparator in comparators:
+        match = _COMPARATOR.fullmatch(comparator)
+        if match is None:
+            # ``>=1,<2`` is a concise allowed major range in the published
+            # manifest.  Expand it deterministically rather than treating it
+            # as a lax string comparison.
+            major_range = re.fullmatch(r"(>=|>|<=|<)(\d+)", comparator)
+            if major_range is None:
+                raise PluginResolutionError(
+                    "plugin_constraint_invalid",
+                    f"unsupported plugin requirement version {constraint!r}",
+                )
+            operator, major = major_range.groups()
+            target = (int(major), 0, 0)
+        else:
+            operator = match.group(1) or "="
+            target = (
+                int(match.group(2)),
+                int(match.group(3)),
+                int(match.group(4)),
+            )
+        if not _compare(parsed_version, target, operator):
+            return False
+    return True
+
+
+def version_satisfies(version: str, constraint: str) -> bool:
+    """Evaluate the exact compatibility-range grammar used by plugin manifests."""
+
+    return _version_satisfies(version, constraint)
+
+
+def _parse_release(value: str, *, field: str) -> tuple[int, int, int]:
+    match = re.match(r"^(\d+)\.(\d+)\.(\d+)", value)
+    if match is None:
+        raise PluginResolutionError("plugin_constraint_invalid", f"invalid {field} {value!r}")
+    return int(match.group(1)), int(match.group(2)), int(match.group(3))
+
+
+def _compare(left: tuple[int, int, int], right: tuple[int, int, int], operator: str) -> bool:
+    return {
+        ">": left > right,
+        ">=": left >= right,
+        "<": left < right,
+        "<=": left <= right,
+        "=": left == right,
+    }[operator]
+
+
+__all__ = [
+    "PluginRegistry",
+    "PluginResolutionError",
+    "ResolvedComposition",
+    "canonical_composition_profile",
+    "composition_profile_digest",
+    "version_satisfies",
+]