okstra 0.163.2 → 0.165.0

package/runtime/python/okstra_ctl/adapters/dispatch/__init__.py

@@ -0,0 +1,92 @@
+"""Host worker-dispatch strategies and host-port decoration."""
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from ... import dispatch_core
+from ...domain.host import HostDescriptor
+from ...registry.provider_registry import ProviderRegistry
+from ...ports.worker_dispatch import WorkerDispatchPort
+from .cli_wrapper import CliWrapperDispatchPort
+from .native_team import NativeTeamDispatchPort
+
+
+def provider_worker_wrappers(
+    registry: ProviderRegistry,
+    report_writer_provider: str = "claude",
+) -> Mapping[str, str]:
+    wrappers = {
+        provider_id: registry.resolve(provider_id).wrapper
+        for provider_id in registry.ids("analyser")
+        if registry.resolve(provider_id).wrapper
+    }
+    report_writer = registry.resolve(report_writer_provider)
+    if "report-writer" not in report_writer.supported_roles:
+        raise dispatch_core.DispatchError(
+            f"provider {report_writer_provider!r} does not support report-writer"
+        )
+    return {**wrappers, "report-writer": report_writer.wrapper}
+
+
+def default_worker_dispatch_port(
+    descriptor: HostDescriptor,
+    provider_registry: ProviderRegistry | None = None,
+) -> WorkerDispatchPort:
+    if descriptor.dispatch_mode == "team":
+        return NativeTeamDispatchPort()
+    wrappers = (
+        provider_worker_wrappers(provider_registry)
+        if provider_registry is not None
+        else None
+    )
+    default_backend = (
+        dispatch_core.BACKEND_TMUX_PANE
+        if descriptor.launch_mode == "team"
+        else dispatch_core.BACKEND_CLI_WRAPPER
+    )
+    return CliWrapperDispatchPort(
+        supported_worker_wrappers=wrappers,
+        unsupported_worker_label=f"{descriptor.id} lead",
+        required_lead_runtime=descriptor.id,
+        default_backend=default_backend,
+    )
+
+
+class WorkerDispatchHostAdapter:
+    def __init__(self, host_adapter, worker_dispatch_port: WorkerDispatchPort) -> None:
+        self._host_adapter = host_adapter
+        self._worker_dispatch_port = worker_dispatch_port
+        self.descriptor = host_adapter.descriptor
+
+    def detect(self, context):
+        return self._host_adapter.detect(context)
+
+    def probe(self, context):
+        return self._host_adapter.probe(context)
+
+    def interaction(self):
+        return self._host_adapter.interaction()
+
+    def lead_session(self):
+        return self._host_adapter.lead_session()
+
+    def worker_dispatch(self) -> WorkerDispatchPort:
+        return self._worker_dispatch_port
+
+    def usage_accounting(self):
+        return self._host_adapter.usage_accounting()
+
+
+def with_worker_dispatch(
+    host_adapter,
+    worker_dispatch_port: WorkerDispatchPort,
+) -> WorkerDispatchHostAdapter:
+    return WorkerDispatchHostAdapter(host_adapter, worker_dispatch_port)
+
+
+__all__ = (
+    "WorkerDispatchHostAdapter",
+    "default_worker_dispatch_port",
+    "provider_worker_wrappers",
+    "with_worker_dispatch",
+)

package/runtime/python/okstra_ctl/adapters/dispatch/cli_wrapper.py

@@ -0,0 +1,54 @@
+"""CLI-wrapper dispatch planning backed by the shared dispatch core."""
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from ... import dispatch_core
+from ...ports.worker_dispatch import WorkerDispatchPlan, WorkerDispatchRequest
+
+
+class CliWrapperDispatchPort:
+    def __init__(
+        self,
+        *,
+        supported_worker_wrappers: Mapping[str, str] | None = None,
+        unsupported_worker_label: str = "host",
+        required_lead_runtime: str | None = None,
+        default_backend: str = dispatch_core.BACKEND_CLI_WRAPPER,
+        cli_wrapper_assignments_only: bool = False,
+        default_provider_by_worker_id: Mapping[str, str] | None = None,
+    ) -> None:
+        self._supported_worker_wrappers = supported_worker_wrappers or {}
+        self._unsupported_worker_label = unsupported_worker_label
+        self._required_lead_runtime = required_lead_runtime
+        self._default_backend = default_backend
+        self._cli_wrapper_assignments_only = cli_wrapper_assignments_only
+        self._default_provider_by_worker_id = dict(
+            default_provider_by_worker_id or {}
+        )
+
+    def build_plan(self, request: WorkerDispatchRequest) -> WorkerDispatchPlan:
+        backend_plan = None
+        if request.workspace_root is not None:
+            backend_plan = dispatch_core.build_dispatch_plan(
+                project_root=request.project_root,
+                run_manifest_path=request.run_manifest,
+                workspace_root=request.workspace_root,
+                okstra_bin=request.okstra_bin,
+                requested_workers=request.requested_workers,
+                idle_timeout_seconds=request.idle_timeout_seconds,
+                required_lead_runtime=self._required_lead_runtime,
+                default_backend=self._default_backend,
+                supported_worker_wrappers=self._supported_worker_wrappers,
+                unsupported_worker_label=self._unsupported_worker_label,
+                dispatch_kind=request.dispatch_kind,
+                jobs_file=request.jobs_file,
+                cli_wrapper_assignments_only=self._cli_wrapper_assignments_only,
+                default_provider_by_worker_id=self._default_provider_by_worker_id,
+            )
+        return WorkerDispatchPlan(
+            mode="cli-wrapper",
+            request=request,
+            backend_plan=backend_plan,
+            dispatch_mode="render-only",
+        )

package/runtime/python/okstra_ctl/adapters/dispatch/cmux.py

@@ -0,0 +1,68 @@
+"""cmux pane dispatch planning and lead-adapter metadata override."""
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from ... import dispatch_core
+from ...ports.worker_dispatch import (
+    WorkerDispatchPlan,
+    WorkerDispatchPort,
+    WorkerDispatchRequest,
+)
+from .cli_wrapper import CliWrapperDispatchPort
+
+
+CMUX_ADAPTER_NAME = "cmux"
+CMUX_RELAY_CONTRACT = "lead/adapters/cmux.md"
+
+
+class CmuxDispatchPort:
+    def __init__(
+        self,
+        *,
+        supported_worker_wrappers: Mapping[str, str] | None = None,
+        unsupported_worker_label: str = "host",
+        required_lead_runtime: str | None = None,
+        cli_wrapper_assignments_only: bool = False,
+        default_provider_by_worker_id: Mapping[str, str] | None = None,
+    ) -> None:
+        self._backend_port = CliWrapperDispatchPort(
+            supported_worker_wrappers=supported_worker_wrappers,
+            unsupported_worker_label=unsupported_worker_label,
+            required_lead_runtime=required_lead_runtime,
+            default_backend=dispatch_core.BACKEND_CMUX_PANE,
+            cli_wrapper_assignments_only=cli_wrapper_assignments_only,
+            default_provider_by_worker_id=default_provider_by_worker_id,
+        )
+
+    def build_plan(self, request: WorkerDispatchRequest) -> WorkerDispatchPlan:
+        backend_plan = self._backend_port.build_plan(request).backend_plan
+        return WorkerDispatchPlan(
+            mode="cmux-pane",
+            request=request,
+            backend_plan=backend_plan,
+            adapter_name=CMUX_ADAPTER_NAME,
+            dispatch_mode="team",
+            relay_contract=CMUX_RELAY_CONTRACT,
+        )
+
+
+def dispatch_port_for_terminal_backend(
+    terminal_backend: str,
+    fallback_port: WorkerDispatchPort,
+    *,
+    supported_worker_wrappers: Mapping[str, str] | None = None,
+    unsupported_worker_label: str = "host",
+    required_lead_runtime: str | None = None,
+    cli_wrapper_assignments_only: bool = False,
+    default_provider_by_worker_id: Mapping[str, str] | None = None,
+) -> WorkerDispatchPort:
+    if terminal_backend != dispatch_core.BACKEND_CMUX_PANE:
+        return fallback_port
+    return CmuxDispatchPort(
+        supported_worker_wrappers=supported_worker_wrappers,
+        unsupported_worker_label=unsupported_worker_label,
+        required_lead_runtime=required_lead_runtime,
+        cli_wrapper_assignments_only=cli_wrapper_assignments_only,
+        default_provider_by_worker_id=default_provider_by_worker_id,
+    )

package/runtime/python/okstra_ctl/adapters/dispatch/native_team.py

@@ -0,0 +1,13 @@
+"""Native host-team dispatch planning."""
+from __future__ import annotations
+
+from ...ports.worker_dispatch import WorkerDispatchPlan, WorkerDispatchRequest
+
+
+class NativeTeamDispatchPort:
+    def build_plan(self, request: WorkerDispatchRequest) -> WorkerDispatchPlan:
+        return WorkerDispatchPlan(
+            mode="native-team",
+            request=request,
+            dispatch_mode="team",
+        )

package/runtime/python/okstra_ctl/adapters/hosts/antigravity/adapter.py

@@ -0,0 +1,60 @@
+"""Bundled Antigravity host strategy."""
+from __future__ import annotations
+
+import shutil
+from collections.abc import Callable
+from pathlib import Path
+
+from okstra_ctl.adapters.accounting import CliArtifactUsageAccountingPort
+from okstra_ctl.adapters.hosts.capability_adapter import (
+    INTERACTION_FUNCTIONS,
+    PENDING_HOST_PORT,
+    CapabilityHostAdapter,
+    no_automatic_claim,
+    numbered_interaction_port,
+)
+from okstra_ctl.domain.host import HostDescriptor
+from okstra_ctl.registry.provider_registry import ProviderRegistry
+
+
+DESCRIPTOR = HostDescriptor(
+    id="antigravity",
+    aliases=("avg", "agy"),
+    native_provider_id="antigravity",
+    required_executables=("agy",),
+    launch_mode="lead",
+    install_targets=frozenset({"agents"}),
+    agent_id="antigravity",
+    agent_label="Antigravity CLI",
+    role="Antigravity lead",
+    dispatch_mode="render-only",
+    session_accounting="artifact-only",
+    has_claude_session=False,
+    relay_contract=str(Path(__file__).with_name("relay.md").resolve()),
+)
+
+
+def create_adapter(
+    *,
+    executable_finder: Callable[[str], str | None] = shutil.which,
+    interaction_port=None,
+    lead_session_port=PENDING_HOST_PORT,
+    worker_dispatch_port=PENDING_HOST_PORT,
+    usage_accounting_port=CliArtifactUsageAccountingPort(),
+    provider_registry: ProviderRegistry | None = None,
+) -> CapabilityHostAdapter:
+    return CapabilityHostAdapter(
+        DESCRIPTOR,
+        executable_finder=executable_finder,
+        interaction_port=(
+            interaction_port
+            if interaction_port is not None
+            else numbered_interaction_port()
+        ),
+        lead_session_port=lead_session_port,
+        worker_dispatch_port=worker_dispatch_port,
+        usage_accounting_port=usage_accounting_port,
+        supported_functions=INTERACTION_FUNCTIONS,
+        detector=no_automatic_claim,
+        provider_registry=provider_registry,
+    )

package/runtime/python/okstra_ctl/adapters/hosts/antigravity/manifest.json

@@ -0,0 +1 @@
+{"schemaVersion": 1, "id": "antigravity", "factory": "adapter.py:create_adapter", "nativeProviderId": "antigravity", "requiredExecutables": ["agy"], "relayContract": "relay.md"}

package/runtime/{prompts/lead/adapters/antigravity.md → python/okstra_ctl/adapters/hosts/antigravity/relay.md}

@@ -18,6 +18,58 @@ This adapter maps the neutral Okstra lead operations to the current Antigravity
 | `teardownMode` | `process-cleanup` |
 | `leadEventSource` | `lead-events-jsonl` |
 
+## Wizard interaction relay
+
+Read this contract when `okstra preflight` returns this file as `runtimeReadiness.relayContract`. The JSON is the complete interaction mapping for this host. This relay exposes only text input; do not invent a native picker function.
+
+```json
+{
+  "schemaVersion": 1,
+  "runtime": "antigravity",
+  "semanticFunctions": ["plain_text_input"],
+  "interactions": {
+    "numbered-single": {
+      "function": "host-text",
+      "input": {
+        "questions": "one",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": { "source": "next-message", "submit": "raw" }
+    },
+    "numbered-multi": {
+      "function": "host-text",
+      "input": {
+        "questions": "one",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": { "source": "next-message", "submit": "raw" }
+    },
+    "sequential-group": {
+      "function": "host-text",
+      "input": {
+        "questions": "all-one-at-a-time-in-original-order",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": {
+        "source": "next-message-by-question-position",
+        "submit": "compact-step-json-raw"
+      }
+    },
+    "plain-text": {
+      "function": "host-text",
+      "input": { "questions": "one", "question": "label-with-progress" },
+      "response": { "source": "next-message", "submit": "raw" }
+    }
+  }
+}
+```
+
+Render every numbered item as its option label followed by its description verbatim, preserving every item and its original order. The next user message is the raw answer: do not translate a number such as `1`, a CSV reply such as `1, 3`, an option label, or an option value before `okstra wizard step`. For `sequential-group`, collect one raw reply per question in order and build one compact JSON object keyed by the corresponding `questions[].step`; the wizard owns all normalization.
+
+
 ## Semantic operation mapping
 
 | Operation | Mapping |

package/runtime/python/okstra_ctl/adapters/hosts/capability_adapter.py

@@ -0,0 +1,292 @@
+"""Capability-based strategy shared by bundled host adapters."""
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+
+from okstra_ctl.adapters.dispatch import default_worker_dispatch_port
+from okstra_ctl.domain.host import (
+    HostClaim,
+    HostDescriptor,
+    HostReadiness,
+    HostResolutionContext,
+    HostSessionContext,
+    LeadResumeRequest,
+    LeadSessionPlan,
+    LeadStartRequest,
+    ProviderUnavailable,
+)
+from okstra_ctl.domain.provider import LeadLaunchSpec
+from okstra_ctl.domain.wizard.interaction import (
+    AnswerProtocol,
+    InteractionPlan,
+    WizardPrompt,
+)
+from okstra_ctl.ports import (
+    InteractionPort,
+    LeadSessionPort,
+    UsageAccountingPort,
+    WorkerDispatchPort,
+)
+from okstra_ctl.registry.provider_registry import (
+    ProviderRegistry,
+    default_provider_registry,
+)
+
+
+@dataclass(frozen=True)
+class HostPorts:
+    interaction: InteractionPort
+    lead_session: LeadSessionPort
+    worker_dispatch: WorkerDispatchPort
+    usage_accounting: UsageAccountingPort
+
+
+class PendingHostPort:
+    """Placeholder replaced as each concrete port migrates behind the adapter."""
+
+
+PENDING_HOST_PORT = PendingHostPort()
+PLAIN_TEXT_FUNCTIONS = frozenset({"plain_text_input"})
+INTERACTION_FUNCTIONS = PLAIN_TEXT_FUNCTIONS | frozenset({
+    "plain_text_input",
+    "native_single_select",
+    "native_multi_select",
+    "native_question_group",
+})
+_NATIVE_QUESTION_LIMIT = 4
+_NATIVE_OPTION_RANGE = range(2, 5)
+
+
+def _native_options_fit(prompt: WizardPrompt) -> bool:
+    labels = tuple(option.label for option in prompt.options)
+    return (
+        len(labels) in _NATIVE_OPTION_RANGE
+        and len(set(labels)) == len(labels)
+        and (not prompt.multi or all(", " not in label for label in labels))
+    )
+
+
+def _native_group_fits(prompt: WizardPrompt) -> bool:
+    return (
+        1 <= len(prompt.questions) <= _NATIVE_QUESTION_LIMIT
+        and all(_native_options_fit(question) for question in prompt.questions)
+    )
+
+
+class CapabilityInteractionPort:
+    def plan(
+        self,
+        prompt: WizardPrompt,
+        context: HostSessionContext,
+    ) -> InteractionPlan:
+        functions = context.available_functions & INTERACTION_FUNCTIONS
+        if prompt.kind == "pick_group":
+            if (
+                "native_question_group" in functions
+                and _native_group_fits(prompt)
+            ):
+                return InteractionPlan("native-group", AnswerProtocol("group-json"))
+            return InteractionPlan(
+                "sequential-group",
+                AnswerProtocol("numbered-group-json"),
+            )
+        if prompt.kind != "pick":
+            return InteractionPlan("plain-text", AnswerProtocol("exact-value"))
+        native_options_fit = _native_options_fit(prompt)
+        if (
+            prompt.multi
+            and "native_multi_select" in functions
+            and native_options_fit
+        ):
+            return InteractionPlan(
+                "native-multi",
+                AnswerProtocol("exact-value", multi=True),
+            )
+        if (
+            not prompt.multi
+            and "native_single_select" in functions
+            and native_options_fit
+        ):
+            return InteractionPlan("native-single", AnswerProtocol("exact-value"))
+        kind = "numbered-multi" if prompt.multi else "numbered-single"
+        return InteractionPlan(kind, AnswerProtocol("numbered", multi=prompt.multi))
+
+
+def numbered_interaction_port() -> CapabilityInteractionPort:
+    return CapabilityInteractionPort()
+
+
+class ProviderLeadSessionPort:
+    def __init__(
+        self,
+        *,
+        host_id: str,
+        native_provider_id: str,
+        provider_registry: ProviderRegistry,
+    ) -> None:
+        self._host_id = host_id
+        self._native_provider_id = native_provider_id
+        self._provider_registry = provider_registry
+
+    def build_start(
+        self,
+        request: LeadStartRequest,
+        context: HostSessionContext,
+    ) -> LeadSessionPlan:
+        if context.entry_mode == "current-session":
+            return self._current_session_plan()
+        launch = self._lead_launch()
+        argv = (launch.executable, *launch.sandbox_waiver, *request.argv)
+        return self._spawn_plan(argv, launch.sandbox_waiver_note)
+
+    def build_resume(
+        self,
+        request: LeadResumeRequest,
+        context: HostSessionContext,
+    ) -> LeadSessionPlan:
+        if context.entry_mode == "current-session":
+            return self._current_session_plan()
+        launch = self._lead_launch()
+        session_args = (
+            (launch.resume_session_id_flag, request.session_id)
+            if launch.resume_session_id_flag and request.session_id
+            else ()
+        )
+        argv = (
+            launch.executable,
+            *launch.sandbox_waiver,
+            *session_args,
+            *request.argv,
+        )
+        return self._spawn_plan(argv, launch.sandbox_waiver_note)
+
+    def _lead_launch(self) -> LeadLaunchSpec:
+        if not self._native_provider_id:
+            raise ProviderUnavailable(
+                f"host {self._host_id!r} has no native lead provider"
+            )
+        provider = self._provider_registry.resolve(self._native_provider_id)
+        if provider.lead_launch is None:
+            raise ProviderUnavailable(
+                f"provider {self._native_provider_id!r} cannot lead"
+            )
+        return provider.lead_launch
+
+    def _current_session_plan(self) -> LeadSessionPlan:
+        return LeadSessionPlan("current-session", (), {}, "")
+
+    def _spawn_plan(
+        self, argv: tuple[str, ...], sandbox_note: str
+    ) -> LeadSessionPlan:
+        return LeadSessionPlan(
+            "spawn-process",
+            argv,
+            {"OKSTRA_RUNTIME_HOST": self._host_id},
+            sandbox_note,
+        )
+
+
+class CapabilityHostAdapter:
+    def __init__(
+        self,
+        descriptor: HostDescriptor,
+        *,
+        executable_finder: Callable[[str], str | None],
+        interaction_port: InteractionPort,
+        lead_session_port: LeadSessionPort,
+        worker_dispatch_port: WorkerDispatchPort,
+        usage_accounting_port: UsageAccountingPort,
+        supported_functions: frozenset[str],
+        detector: Callable[[HostResolutionContext], HostClaim | None],
+        provider_registry: ProviderRegistry | None = None,
+        readiness_probe: Callable[
+            [HostSessionContext], tuple[Mapping[str, object], ...]
+        ] | None = None,
+    ) -> None:
+        self.descriptor = descriptor
+        self._executable_finder = executable_finder
+        resolved_provider_registry = provider_registry or default_provider_registry()
+        resolved_lead_session = lead_session_port
+        if lead_session_port is PENDING_HOST_PORT:
+            resolved_lead_session = ProviderLeadSessionPort(
+                host_id=descriptor.id,
+                native_provider_id=descriptor.native_provider_id,
+                provider_registry=resolved_provider_registry,
+            )
+        resolved_worker_dispatch = worker_dispatch_port
+        if worker_dispatch_port is PENDING_HOST_PORT:
+            resolved_worker_dispatch = default_worker_dispatch_port(
+                descriptor,
+                resolved_provider_registry,
+            )
+        self._ports = HostPorts(
+            interaction_port,
+            resolved_lead_session,
+            resolved_worker_dispatch,
+            usage_accounting_port,
+        )
+        self._supported_functions = supported_functions
+        self._detector = detector
+        self._readiness_probe = readiness_probe or (lambda context: ())
+
+    def detect(self, context: HostResolutionContext) -> HostClaim | None:
+        return self._detector(context)
+
+    def probe(self, context: HostSessionContext) -> HostReadiness:
+        effective_functions = self._effective_functions(context)
+        if context.host_id != self.descriptor.id:
+            reason = (
+                f"host mismatch: expected {self.descriptor.id!r}, "
+                f"received {context.host_id!r}"
+            )
+            return HostReadiness(False, effective_functions, (), (), reason)
+        if context.entry_mode == "current-session":
+            return self._readiness(context, effective_functions)
+        missing = tuple(
+            executable
+            for executable in self.descriptor.required_executables
+            if self._executable_finder(executable) is None
+        )
+        if missing:
+            reason = f"missing required executables: {', '.join(missing)}"
+            return HostReadiness(False, effective_functions, missing, (), reason)
+        return self._readiness(context, effective_functions)
+
+    def interaction(self) -> InteractionPort:
+        return self._ports.interaction
+
+    def lead_session(self) -> LeadSessionPort:
+        return self._ports.lead_session
+
+    def worker_dispatch(self) -> WorkerDispatchPort:
+        return self._ports.worker_dispatch
+
+    def usage_accounting(self) -> UsageAccountingPort:
+        return self._ports.usage_accounting
+
+    def _effective_functions(
+        self, context: HostSessionContext
+    ) -> frozenset[str]:
+        return self._supported_functions & context.available_functions
+
+    def _readiness(
+        self,
+        context: HostSessionContext,
+        effective_functions: frozenset[str],
+    ) -> HostReadiness:
+        checks = self._readiness_probe(context)
+        blockers = tuple(
+            check for check in checks
+            if check.get("status") in {"required", "unavailable"}
+        )
+        if blockers:
+            return HostReadiness(
+                False, effective_functions, (), checks, "host not ready"
+            )
+        return HostReadiness(True, effective_functions, (), checks, "ready")
+
+
+def no_automatic_claim(context: HostResolutionContext) -> HostClaim | None:
+    """Require an explicit host instead of inferring one from installed CLIs."""
+    return None