okstra 0.163.2 → 0.164.0

package/runtime/python/okstra_ctl/registry/host_discovery.py

@@ -0,0 +1,124 @@
+"""Discover host manifests inside explicitly trusted adapter roots."""
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..domain.host import HostAdapterContractError
+
+
+@dataclass(frozen=True)
+class HostManifest:
+    path: Path
+    host_id: str
+    factory_ref: str
+    native_provider_id: str
+    required_executables: tuple[str, ...]
+    relay_contract: Path
+
+
+def discover_host_manifests(roots: Iterable[Path]) -> tuple[HostManifest, ...]:
+    manifests: list[HostManifest] = []
+    for manifest_path in _manifest_paths(roots):
+        manifests.append(_read_manifest(manifest_path))
+    return tuple(manifests)
+
+
+def _manifest_paths(roots: Iterable[Path]) -> tuple[Path, ...]:
+    manifests: list[Path] = []
+    for root in roots:
+        if root.is_symlink():
+            raise HostAdapterContractError(
+                f"host discovery root is symbolic link: {root}"
+            )
+        if not root.is_dir():
+            continue
+        resolved_root = root.resolve()
+        for manifest_path in sorted(root.glob("*/manifest.json")):
+            resolved_manifest = manifest_path.resolve()
+            if resolved_root not in resolved_manifest.parents:
+                raise HostAdapterContractError(
+                    f"host adapter escapes discovery root: {manifest_path}"
+                )
+            manifests.append(resolved_manifest)
+    return tuple(manifests)
+
+
+def _read_manifest(manifest_path: Path) -> HostManifest:
+    raw = _read_json_object(manifest_path)
+    host_id = _required_id(raw, "id", manifest_path)
+    factory_ref = _required_string(raw, "factory", manifest_path)
+    native_provider_id = _optional_id(raw, "nativeProviderId", manifest_path)
+    required_executables = _string_tuple(raw, "requiredExecutables", manifest_path)
+    relay_ref = _required_string(raw, "relayContract", manifest_path)
+    relay_contract = _resolve_relay_contract(manifest_path, relay_ref)
+    return HostManifest(
+        path=manifest_path,
+        host_id=host_id,
+        factory_ref=factory_ref,
+        native_provider_id=native_provider_id,
+        required_executables=required_executables,
+        relay_contract=relay_contract,
+    )
+
+
+def _read_json_object(manifest_path: Path) -> dict[str, object]:
+    try:
+        raw = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise HostAdapterContractError(
+            f"invalid host manifest: {manifest_path}"
+        ) from exc
+    if not isinstance(raw, dict) or raw.get("schemaVersion") != 1:
+        raise HostAdapterContractError(f"invalid host manifest: {manifest_path}")
+    return raw
+
+
+def _required_id(raw: dict[str, object], key: str, manifest_path: Path) -> str:
+    value = _required_string(raw, key, manifest_path).strip().lower()
+    if not value:
+        raise HostAdapterContractError(f"invalid host manifest: {manifest_path}")
+    return value
+
+
+def _optional_id(raw: dict[str, object], key: str, manifest_path: Path) -> str:
+    value = raw.get(key, "")
+    if not isinstance(value, str):
+        raise HostAdapterContractError(f"invalid host manifest: {manifest_path}")
+    return value.strip().lower()
+
+
+def _required_string(
+    raw: dict[str, object], key: str, manifest_path: Path
+) -> str:
+    value = raw.get(key)
+    if not isinstance(value, str) or not value:
+        raise HostAdapterContractError(f"invalid host manifest: {manifest_path}")
+    return value
+
+
+def _string_tuple(
+    raw: dict[str, object], key: str, manifest_path: Path
+) -> tuple[str, ...]:
+    value = raw.get(key)
+    if not isinstance(value, list) or not all(
+        isinstance(item, str) and item for item in value
+    ):
+        raise HostAdapterContractError(f"invalid host manifest: {manifest_path}")
+    return tuple(value)
+
+
+def _resolve_relay_contract(manifest_path: Path, relay_ref: str) -> Path:
+    adapter_root = manifest_path.parent.resolve()
+    if Path(relay_ref).is_absolute():
+        raise HostAdapterContractError(
+            f"relay contract escapes adapter root: {relay_ref!r}"
+        )
+    relay_contract = (adapter_root / relay_ref).resolve()
+    if adapter_root not in relay_contract.parents or not relay_contract.is_file():
+        raise HostAdapterContractError(
+            f"relay contract escapes adapter root: {relay_ref!r}"
+        )
+    return relay_contract

package/runtime/python/okstra_ctl/registry/host_registry.py

@@ -0,0 +1,365 @@
+"""Register and resolve discovered host adapter strategies."""
+from __future__ import annotations
+
+import inspect
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+
+from okstra_project.dirs import okstra_home
+
+from ..domain.host import (
+    HostAdapterContractError,
+    HostClaim,
+    HostDescriptor,
+    HostNotRegistered,
+    HostResolutionContext,
+    HostUnavailable,
+    ProviderNotRegistered,
+)
+from ..ports import HostAdapter
+from .factory_loader import FactoryLoadError, load_relative_factory
+from .host_discovery import HostManifest, discover_host_manifests
+from .provider_registry import ProviderRegistry, default_provider_registry
+
+
+_ADAPTER_METHODS = (
+    "detect",
+    "probe",
+    "interaction",
+    "lead_session",
+    "worker_dispatch",
+    "usage_accounting",
+)
+_PORT_METHODS = {
+    "interaction": ("plan",),
+    "lead_session": ("build_start", "build_resume"),
+    "worker_dispatch": ("build_plan",),
+    "usage_accounting": ("collect",),
+}
+
+
+class _RegisteredHostAdapter:
+    def __init__(self, descriptor: HostDescriptor, adapter: object) -> None:
+        self.descriptor = descriptor
+        self._adapter = adapter
+
+    def detect(self, context):
+        return self._adapter.detect(context)
+
+    def probe(self, context):
+        return self._adapter.probe(context)
+
+    def interaction(self):
+        return self._adapter.interaction()
+
+    def lead_session(self):
+        return self._adapter.lead_session()
+
+    def worker_dispatch(self):
+        return self._adapter.worker_dispatch()
+
+    def usage_accounting(self):
+        return self._adapter.usage_accounting()
+
+
+class HostAdapterRegistry:
+    def __init__(
+        self,
+        adapters: Mapping[str, HostAdapter],
+        aliases: Mapping[str, HostAdapter],
+    ) -> None:
+        self._adapters = dict(adapters)
+        self._aliases = dict(aliases)
+
+    @classmethod
+    def from_roots(
+        cls,
+        roots: Iterable[Path],
+        provider_registry: ProviderRegistry,
+    ) -> "HostAdapterRegistry":
+        entries = _load_entries(roots, provider_registry)
+        adapters = _index_host_ids(entries)
+        aliases = _index_aliases(entries, adapters)
+        return cls(adapters, aliases)
+
+    def resolve(self, host_id_or_alias: str) -> HostAdapter:
+        normalized = host_id_or_alias.strip().lower()
+        adapter = self._aliases.get(normalized)
+        if adapter is not None:
+            return adapter
+        allowed = ", ".join(self._adapters)
+        raise HostNotRegistered(
+            f"unknown host {host_id_or_alias!r}. Allowed values: {allowed}"
+        )
+
+    def resolve_request(
+        self,
+        requested_host: str,
+        context: HostResolutionContext,
+    ) -> HostDescriptor:
+        descriptor, _, _ = self.resolve_request_details(requested_host, context)
+        return descriptor
+
+    def resolve_request_details(
+        self,
+        requested_host: str,
+        context: HostResolutionContext,
+    ) -> tuple[HostDescriptor, str, str]:
+        normalized = requested_host.strip().lower()
+        if normalized and normalized != "auto":
+            descriptor = self.resolve(normalized).descriptor
+            return descriptor, "explicit", (
+                f"Explicit runtime {descriptor.id!r} requested."
+            )
+        env_host = context.explicit_env_host.strip()
+        if env_host and env_host.lower() != "auto":
+            descriptor = self.resolve(env_host).descriptor
+            return descriptor, descriptor.id, (
+                f"OKSTRA_RUNTIME_HOST={env_host} selected runtime {descriptor.id!r}."
+            )
+        adapter, claim = self._resolve_claim(context)
+        return adapter.descriptor, adapter.descriptor.id, claim.reason
+
+    def ids(self) -> tuple[str, ...]:
+        return tuple(self._adapters)
+
+    def catalog(self) -> tuple[HostDescriptor, ...]:
+        return tuple(adapter.descriptor for adapter in self._adapters.values())
+
+    def _resolve_claim(
+        self, context: HostResolutionContext
+    ) -> tuple[HostAdapter, HostClaim]:
+        claims = tuple(
+            claim
+            for adapter in self._adapters.values()
+            if (claim := _detect_claim(adapter, context)) is not None
+        )
+        if not claims:
+            raise HostUnavailable("no host adapter claimed the current session")
+        highest_priority = max(claim.priority for claim in claims)
+        winners = tuple(
+            claim for claim in claims if claim.priority == highest_priority
+        )
+        if len(winners) != 1:
+            host_ids = ", ".join(sorted(claim.host_id for claim in winners))
+            raise HostUnavailable(f"ambiguous host adapter claims: {host_ids}")
+        winner = winners[0]
+        return self.resolve(winner.host_id), winner
+
+
+def default_host_registry(
+    provider_registry: ProviderRegistry | None = None,
+) -> HostAdapterRegistry:
+    bundled_root = Path(__file__).resolve().parents[1] / "adapters" / "hosts"
+    user_root = okstra_home() / "adapters" / "hosts"
+    providers = provider_registry or default_provider_registry()
+    return HostAdapterRegistry.from_roots((bundled_root, user_root), providers)
+
+
+def _load_entries(
+    roots: Iterable[Path], provider_registry: ProviderRegistry
+) -> tuple[tuple[HostManifest, HostAdapter], ...]:
+    entries: list[tuple[HostManifest, HostAdapter]] = []
+    for manifest in discover_host_manifests(roots):
+        _validate_provider(manifest, provider_registry)
+        entries.append((manifest, _load_host_adapter(manifest, provider_registry)))
+    return tuple(entries)
+
+
+def _validate_provider(
+    manifest: HostManifest, provider_registry: ProviderRegistry
+) -> None:
+    if not manifest.native_provider_id:
+        return
+    if manifest.native_provider_id not in provider_registry.providers:
+        raise ProviderNotRegistered(
+            f"native provider {manifest.native_provider_id!r} is not registered"
+        )
+
+
+def _load_host_adapter(
+    manifest: HostManifest,
+    provider_registry: ProviderRegistry,
+) -> HostAdapter:
+    try:
+        factory = load_relative_factory(manifest.path, manifest.factory_ref)
+        parameters = inspect.signature(factory).parameters.values()
+        accepts_registry = any(
+            parameter.name == "provider_registry"
+            or parameter.kind is inspect.Parameter.VAR_KEYWORD
+            for parameter in parameters
+        )
+        adapter = (
+            factory(provider_registry=provider_registry)
+            if accepts_registry
+            else factory()
+        )
+    except FactoryLoadError as exc:
+        raise HostAdapterContractError(str(exc)) from exc
+    except Exception as exc:
+        raise HostAdapterContractError(
+            f"host factory failed for {manifest.host_id!r}"
+        ) from exc
+    descriptor = _validated_descriptor(adapter, manifest)
+    return _RegisteredHostAdapter(descriptor, adapter)
+
+
+def _validated_descriptor(adapter: object, manifest: HostManifest) -> HostDescriptor:
+    for method_name in _ADAPTER_METHODS:
+        if not callable(getattr(adapter, method_name, None)):
+            raise HostAdapterContractError(
+                f"host factory returned invalid adapter {manifest.host_id!r}"
+            )
+    _validate_ports(adapter, manifest.host_id)
+    descriptor = _copy_descriptor(getattr(adapter, "descriptor", None), manifest.host_id)
+    if descriptor.id != manifest.host_id:
+        raise HostAdapterContractError(f"host id mismatch for {manifest.host_id!r}")
+    if descriptor.native_provider_id != manifest.native_provider_id:
+        raise HostAdapterContractError(
+            f"native provider mismatch for {manifest.host_id!r}"
+        )
+    if descriptor.required_executables != manifest.required_executables:
+        raise HostAdapterContractError(
+            f"required executables mismatch for {manifest.host_id!r}"
+        )
+    if Path(descriptor.relay_contract).resolve() != manifest.relay_contract:
+        raise HostAdapterContractError(
+            f"relay contract mismatch for {manifest.host_id!r}"
+        )
+    return descriptor
+
+
+def _validate_ports(adapter: object, host_id: str) -> None:
+    for accessor, required_methods in _PORT_METHODS.items():
+        try:
+            port = getattr(adapter, accessor)()
+        except Exception as exc:
+            raise HostAdapterContractError(
+                f"host {host_id!r} {accessor} port could not be created"
+            ) from exc
+        missing = tuple(
+            method for method in required_methods
+            if not callable(getattr(port, method, None))
+        )
+        if missing:
+            required = ", ".join(missing)
+            raise HostAdapterContractError(
+                f"host {host_id!r} {accessor} port is missing {required}"
+            )
+
+
+def _copy_descriptor(raw: object, host_id: str) -> HostDescriptor:
+    try:
+        descriptor = HostDescriptor(
+            id=raw.id,
+            aliases=raw.aliases,
+            native_provider_id=raw.native_provider_id,
+            required_executables=raw.required_executables,
+            launch_mode=raw.launch_mode,
+            install_targets=raw.install_targets,
+            agent_id=raw.agent_id,
+            agent_label=raw.agent_label,
+            role=raw.role,
+            dispatch_mode=raw.dispatch_mode,
+            session_accounting=raw.session_accounting,
+            has_claude_session=raw.has_claude_session,
+            relay_contract=raw.relay_contract,
+        )
+    except (AttributeError, TypeError) as exc:
+        raise HostAdapterContractError(
+            f"host factory returned invalid descriptor {host_id!r}"
+        ) from exc
+    if not _descriptor_fields_are_valid(descriptor):
+        raise HostAdapterContractError(
+            f"host factory returned invalid descriptor {host_id!r}"
+        )
+    return descriptor
+
+
+def _descriptor_fields_are_valid(descriptor: HostDescriptor) -> bool:
+    normalized_ids = (descriptor.id, descriptor.native_provider_id)
+    if not all(isinstance(value, str) for value in normalized_ids):
+        return False
+    if not descriptor.id or descriptor.id != descriptor.id.strip().lower():
+        return False
+    if descriptor.native_provider_id != descriptor.native_provider_id.strip().lower():
+        return False
+    if not isinstance(descriptor.aliases, tuple) or not all(
+        isinstance(alias, str) and alias == alias.strip().lower() and alias
+        for alias in descriptor.aliases
+    ):
+        return False
+    if not isinstance(descriptor.required_executables, tuple) or not all(
+        isinstance(executable, str) and executable
+        for executable in descriptor.required_executables
+    ):
+        return False
+    if descriptor.launch_mode not in {"lead", "team"}:
+        return False
+    if not isinstance(descriptor.install_targets, frozenset) or not all(
+        isinstance(target, str) and target for target in descriptor.install_targets
+    ):
+        return False
+    text_fields = (
+        descriptor.agent_id,
+        descriptor.agent_label,
+        descriptor.role,
+        descriptor.dispatch_mode,
+        descriptor.session_accounting,
+        descriptor.relay_contract,
+    )
+    return all(isinstance(value, str) and value for value in text_fields) and isinstance(
+        descriptor.has_claude_session, bool
+    )
+
+
+def _index_host_ids(
+    entries: tuple[tuple[HostManifest, HostAdapter], ...]
+) -> dict[str, HostAdapter]:
+    adapters: dict[str, HostAdapter] = {}
+    for manifest, adapter in entries:
+        if manifest.host_id in adapters:
+            raise HostAdapterContractError(
+                f"duplicate host id {manifest.host_id!r}"
+            )
+        adapters[manifest.host_id] = adapter
+    return adapters
+
+
+def _index_aliases(
+    entries: tuple[tuple[HostManifest, HostAdapter], ...],
+    adapters: Mapping[str, HostAdapter],
+) -> dict[str, HostAdapter]:
+    aliases = dict(adapters)
+    for _, adapter in entries:
+        for raw_alias in adapter.descriptor.aliases:
+            alias = raw_alias.strip().lower()
+            existing = aliases.get(alias)
+            if not alias or (existing is not None and existing is not adapter):
+                raise HostAdapterContractError(f"duplicate host key {alias!r}")
+            aliases[alias] = adapter
+    return aliases
+
+
+def _detect_claim(
+    adapter: HostAdapter, context: HostResolutionContext
+) -> HostClaim | None:
+    try:
+        raw_claim = adapter.detect(context)
+    except Exception as exc:
+        raise HostAdapterContractError(
+            f"host detector failed for {adapter.descriptor.id!r}"
+        ) from exc
+    if raw_claim is None:
+        return None
+    try:
+        claim = HostClaim(raw_claim.host_id, raw_claim.priority, raw_claim.reason)
+    except (AttributeError, TypeError) as exc:
+        raise HostAdapterContractError(
+            f"host detector returned invalid claim for {adapter.descriptor.id!r}"
+        ) from exc
+    if claim.host_id != adapter.descriptor.id or not isinstance(claim.priority, int):
+        raise HostAdapterContractError(
+            f"host detector returned invalid claim for {adapter.descriptor.id!r}"
+        )
+    return claim

package/runtime/python/okstra_ctl/registry/provider_registry.py

@@ -0,0 +1,149 @@
+"""Discover provider adapters from the bundled and Okstra-user locations."""
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Mapping
+from functools import lru_cache
+from pathlib import Path
+
+from okstra_project.dirs import okstra_home
+
+from ..domain.provider import ProviderSpec, UnknownProviderError
+from .factory_loader import FactoryLoadError, load_relative_factory
+
+
+class ProviderAdapterContractError(ValueError):
+    """Raised when a discovered provider adapter violates its contract."""
+
+
+class ProviderRegistry:
+    """Resolved provider specifications, indexed by their normalized id."""
+
+    def __init__(self, providers: Mapping[str, ProviderSpec]) -> None:
+        self._providers = dict(providers)
+
+    @classmethod
+    def from_roots(cls, roots: Iterable[Path]) -> "ProviderRegistry":
+        providers: dict[str, ProviderSpec] = {}
+        for manifest_path, provider_id, factory_ref in _manifest_entries(roots):
+            spec = _load_provider_spec(manifest_path, provider_id, factory_ref)
+            providers[provider_id] = spec
+        return cls(providers)
+
+    def resolve(self, provider_id: str) -> ProviderSpec:
+        normalized = provider_id.strip().lower()
+        try:
+            return self._providers[normalized]
+        except KeyError as exc:
+            allowed = ", ".join(self._providers)
+            raise UnknownProviderError(
+                f"unknown provider {provider_id!r}. Allowed values: {allowed}"
+            ) from exc
+
+    def ids(self, role: str | None = None) -> tuple[str, ...]:
+        if role is None:
+            return tuple(self._providers)
+        return tuple(
+            provider_id
+            for provider_id, spec in self._providers.items()
+            if role in spec.supported_roles
+        )
+
+    @property
+    def providers(self) -> Mapping[str, ProviderSpec]:
+        return dict(self._providers)
+
+
+def default_provider_registry() -> ProviderRegistry:
+    """Load bundled providers plus only adapters owned by the Okstra user home."""
+    bundled_root = Path(__file__).resolve().parents[1] / "adapters" / "providers"
+    user_root = okstra_home() / "adapters" / "providers"
+    if user_root.is_symlink():
+        raise ProviderAdapterContractError(
+            f"provider discovery root is symbolic link: {user_root}"
+        )
+    return _registry_for_roots(bundled_root.resolve(), user_root.resolve())
+
+
+@lru_cache(maxsize=None)
+def _registry_for_roots(
+    bundled_root: Path,
+    user_root: Path,
+) -> ProviderRegistry:
+    discovered = ProviderRegistry.from_roots((bundled_root, user_root)).providers
+    bundled_order = ("claude", "antigravity", "codex", "grok", "kimi")
+    ordered = {provider_id: discovered[provider_id] for provider_id in bundled_order}
+    ordered.update(
+        (provider_id, spec)
+        for provider_id, spec in discovered.items()
+        if provider_id not in ordered
+    )
+    return ProviderRegistry(ordered)
+
+
+def _manifest_entries(roots: Iterable[Path]) -> list[tuple[Path, str, str]]:
+    entries: list[tuple[Path, str, str]] = []
+    provider_paths: dict[str, Path] = {}
+    for manifest_path in _manifest_paths(roots):
+        provider_id, factory_ref = _read_manifest(manifest_path)
+        if provider_id in provider_paths:
+            raise ProviderAdapterContractError(
+                f"duplicate provider id {provider_id!r}"
+            )
+        provider_paths[provider_id] = manifest_path
+        entries.append((manifest_path, provider_id, factory_ref))
+    return entries
+
+
+def _manifest_paths(roots: Iterable[Path]) -> tuple[Path, ...]:
+    manifests: list[Path] = []
+    for root in roots:
+        if root.is_symlink():
+            raise ProviderAdapterContractError(
+                f"provider discovery root is symbolic link: {root}"
+            )
+        if not root.is_dir():
+            continue
+        resolved_root = root.resolve()
+        for manifest_path in sorted(root.glob("*/manifest.json")):
+            resolved_manifest = manifest_path.resolve()
+            if resolved_root not in resolved_manifest.parents:
+                raise ProviderAdapterContractError(
+                    f"provider adapter escapes discovery root: {manifest_path}"
+                )
+            manifests.append(resolved_manifest)
+    return tuple(manifests)
+
+
+def _read_manifest(manifest_path: Path) -> tuple[str, str]:
+    try:
+        raw = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ProviderAdapterContractError(f"invalid provider manifest: {manifest_path}") from exc
+    if not isinstance(raw, dict) or raw.get("schemaVersion") != 1:
+        raise ProviderAdapterContractError(f"invalid provider manifest: {manifest_path}")
+    provider_id = raw.get("id")
+    factory_ref = raw.get("factory")
+    if not isinstance(provider_id, str) or not provider_id.strip():
+        raise ProviderAdapterContractError(f"invalid provider manifest: {manifest_path}")
+    if not isinstance(factory_ref, str) or not factory_ref:
+        raise ProviderAdapterContractError(f"invalid provider manifest: {manifest_path}")
+    return provider_id.strip().lower(), factory_ref
+
+
+def _load_provider_spec(
+    manifest_path: Path, provider_id: str, factory_ref: str,
+) -> ProviderSpec:
+    try:
+        spec = load_relative_factory(manifest_path, factory_ref)()
+    except FactoryLoadError as exc:
+        raise ProviderAdapterContractError(str(exc)) from exc
+    except Exception as exc:
+        raise ProviderAdapterContractError(
+            f"provider factory failed for {provider_id!r}"
+        ) from exc
+    if not isinstance(spec, ProviderSpec) or spec.provider != provider_id:
+        raise ProviderAdapterContractError(
+            f"provider factory returned invalid provider {provider_id!r}"
+        )
+    return spec