okstra 0.163.2 → 0.164.0

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

@@ -0,0 +1,63 @@
+"""Bundled Kimi host strategy."""
+from __future__ import annotations
+
+import shutil
+from collections.abc import Callable
+from pathlib import Path
+
+from okstra_ctl.adapters.accounting import UnavailableUsageAccountingPort
+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="kimi",
+    aliases=("kimi",),
+    native_provider_id="kimi",
+    required_executables=("kimi",),
+    launch_mode="lead",
+    install_targets=frozenset({"agents"}),
+    agent_id="kimi",
+    agent_label="Kimi CLI",
+    role="Kimi 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=UnavailableUsageAccountingPort(
+        "Kimi host usage accounting is unavailable because no session "
+        "transcript or CLI usage artifact contract is registered."
+    ),
+    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/kimi/manifest.json

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

package/runtime/python/okstra_ctl/adapters/hosts/kimi/relay.md

@@ -0,0 +1,90 @@
+# Kimi Lead Runtime Adapter
+
+## Scope
+
+This adapter maps neutral Okstra lead operations to the Kimi CLI. Read it only when the rendered launch prompt selects `leadRuntime=kimi`.
+
+## Capability declaration
+
+| Field | Value |
+|---|---|
+| `runtime` | `kimi` |
+| `leadRoleLabel` | `Kimi lead` |
+| `userPromptMode` | `host-text` |
+| `workerDispatchBackend` | `mixed` |
+| `initialPromptDeliveryMode` | `eager-include` |
+| `sessionAccounting` | `artifact-only` |
+| `resumeMode` | `native-session-id` |
+| `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": "kimi",
+  "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. Submit the next user message unchanged. For `sequential-group`, collect one raw reply per question in order and build one compact JSON object keyed by the corresponding `questions[].step`.
+
+## Semantic operation mapping
+
+| Operation | Mapping |
+|---|---|
+| `read_artifacts` | Read the manifest-provided paths through the current Kimi host file interface. |
+| `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
+| `prompt_user` | Ask through the current host text interface and wait for an explicit answer. |
+| `dispatch_worker` | Follow each persisted assignment's `runner` and use the common host dispatch boundary. |
+| `await_workers` | Await through the selected common dispatch backend, then verify terminal state and Result Paths. |
+| `redispatch_worker` | Start a fresh attempt from the persisted assignment and record the supplied dispatch kind. |
+| `shutdown_workers` | Clean up only host or process resources owned by this run. |
+| `record_lead_event` | Append the required structured event to `leadEventsPath` and emit the matching progress line. |
+| `collect_usage` | Return explicit unavailable lead usage until Kimi registers a session transcript or CLI usage artifact contract. |
+
+## Completion, cleanup, and resume
+
+- Do not infer the current host from an installed `kimi` executable. The runtime must come from an explicit request or current-session declaration.
+- Keep persisted provider, model, runner, and dispatch-kind assignments unchanged.
+- Resume with the persisted Kimi session ID when one exists; otherwise resume from Okstra run artifacts.

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

@@ -0,0 +1,35 @@
+"""Bundled Antigravity provider catalog."""
+from okstra_ctl.domain.provider import LeadLaunchSpec, ModelSpec, ProviderSpec
+
+
+# `agy` needs a tier suffix at dispatch time; model_discovery owns that host
+# specific normalization so catalog display values never reach the CLI.
+ANTIGRAVITY = {
+    "gemini-3.1-pro": ModelSpec("Gemini 3.1 Pro", "gemini-3.1-pro", in_picker=True),
+    "gemini 3.1 pro": ModelSpec("Gemini 3.1 Pro", "gemini-3.1-pro"),
+    "gemini-3.6-flash": ModelSpec(
+        "Gemini 3.6 Flash", "gemini-3.6-flash", in_picker=True
+    ),
+    "gemini 3.6 flash": ModelSpec("Gemini 3.6 Flash", "gemini-3.6-flash"),
+    "gemini-3.5-flash": ModelSpec(
+        "Gemini 3.5 Flash", "gemini-3.5-flash", in_picker=True
+    ),
+    "gemini 3.5 flash": ModelSpec("Gemini 3.5 Flash", "gemini-3.5-flash"),
+}
+
+
+def create_provider() -> ProviderSpec:
+    return ProviderSpec(
+        provider="antigravity",
+        display_label="Antigravity",
+        models=ANTIGRAVITY,
+        default_models={
+            role: "gemini-3.1-pro"
+            for role in ("lead", "analyser", "critic", "executor", "verifier")
+        },
+        wrapper="okstra-antigravity-exec.sh",
+        supported_roles=frozenset({"lead", "analyser", "critic", "executor", "verifier"}),
+        lead_launch=LeadLaunchSpec(
+            executable="agy", model_flag="--model", prompt_flag="--prompt-interactive"
+        ),
+    )

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

@@ -0,0 +1 @@
+{"schemaVersion": 1, "id": "antigravity", "factory": "adapter.py:create_provider"}

package/runtime/python/okstra_ctl/adapters/providers/claude/adapter.py

@@ -0,0 +1,55 @@
+"""Bundled Claude provider catalog."""
+from okstra_ctl.domain.provider import LeadLaunchSpec, ModelSpec, ProviderSpec
+
+
+CLAUDE = {
+    "fable": ModelSpec("fable", "fable", in_picker=True),
+    "fable-5": ModelSpec("fable-5", "claude-fable-5"),
+    "claude-fable-5": ModelSpec("fable-5", "claude-fable-5"),
+    "opus": ModelSpec("opus", "opus", in_picker=True),
+    "opus-5": ModelSpec("opus-5", "claude-opus-5"),
+    "claude-opus-5": ModelSpec("opus-5", "claude-opus-5"),
+    "opus-4-8": ModelSpec("opus-4-8", "claude-opus-4-8"),
+    "claude-opus-4-8": ModelSpec("opus-4-8", "claude-opus-4-8"),
+    "opus-4-7": ModelSpec("opus-4-7", "claude-opus-4-7"),
+    "claude-opus-4-7": ModelSpec("opus-4-7", "claude-opus-4-7"),
+    "opus-4-6": ModelSpec("opus-4-6", "claude-opus-4-6"),
+    "claude-opus-4-6": ModelSpec("opus-4-6", "claude-opus-4-6"),
+    "sonnet": ModelSpec("sonnet", "sonnet", in_picker=True),
+    "sonnet-5": ModelSpec("sonnet-5", "claude-sonnet-5", in_picker=True),
+    "claude-sonnet-5": ModelSpec("sonnet-5", "claude-sonnet-5"),
+    "sonnet-4-6": ModelSpec("sonnet-4-6", "claude-sonnet-4-6"),
+    "claude-sonnet-4-6": ModelSpec("sonnet-4-6", "claude-sonnet-4-6"),
+    "haiku": ModelSpec("haiku", "haiku", in_picker=True),
+    "haiku-4-5": ModelSpec("haiku-4-5", "claude-haiku-4-5"),
+    "claude-haiku-4-5": ModelSpec("haiku-4-5", "claude-haiku-4-5"),
+    "claude-haiku-4-5-20251001": ModelSpec(
+        "haiku-4-5", "claude-haiku-4-5-20251001"
+    ),
+}
+
+
+def create_provider() -> ProviderSpec:
+    return ProviderSpec(
+        provider="claude",
+        display_label="Claude",
+        models=CLAUDE,
+        default_models={
+            "lead": "opus",
+            "analyser": "opus",
+            "critic": "opus",
+            "executor": "opus",
+            "verifier": "opus",
+            "report-writer": "sonnet",
+        },
+        wrapper="okstra-claude-exec.sh",
+        supported_roles=frozenset(
+            {"lead", "analyser", "critic", "executor", "verifier", "report-writer"}
+        ),
+        lead_launch=LeadLaunchSpec(
+            executable="claude",
+            model_flag="--model",
+            start_session_id_flag="--session-id",
+            resume_session_id_flag="--resume",
+        ),
+    )

package/runtime/python/okstra_ctl/adapters/providers/claude/manifest.json

@@ -0,0 +1 @@
+{"schemaVersion": 1, "id": "claude", "factory": "adapter.py:create_provider"}

package/runtime/python/okstra_ctl/adapters/providers/codex/adapter.py

@@ -0,0 +1,43 @@
+"""Bundled Codex provider catalog."""
+from okstra_ctl.domain.provider import LeadLaunchSpec, ModelSpec, ProviderSpec
+
+
+CODEX = {
+    # ChatGPT-account hosts serve this model without per-token billing.
+    "gpt-5.6-sol": ModelSpec("gpt-5.6-sol", "gpt-5.6-sol", None, in_picker=True),
+    "gpt-5.6": ModelSpec("gpt-5.6", "gpt-5.6", (5.00, 0.50, 30.0), in_picker=True),
+    "gpt-5.5": ModelSpec("gpt-5.5", "gpt-5.5", (5.00, 0.50, 30.0), in_picker=True),
+    "gpt-5.4": ModelSpec("gpt-5.4", "gpt-5.4", (2.50, 0.25, 15.00), in_picker=True),
+    "gpt-5.4-mini": ModelSpec(
+        "gpt-5.4-mini", "gpt-5.4-mini", (0.75, 0.075, 4.50), in_picker=True
+    ),
+    "gpt-5.3-codex": ModelSpec("gpt-5.4", "gpt-5.4"),
+    "gpt-5.2": ModelSpec("gpt-5.2", "gpt-5.2", (1.75, 0.175, 14.0)),
+    "codex-auto-review": ModelSpec("codex-auto-review", "codex-auto-review"),
+}
+
+
+def create_provider() -> ProviderSpec:
+    return ProviderSpec(
+        provider="codex",
+        display_label="Codex",
+        models=CODEX,
+        default_models={
+            role: "gpt-5.6-sol"
+            for role in ("lead", "analyser", "critic", "executor", "verifier", "report-writer")
+        },
+        wrapper="okstra-codex-exec.sh",
+        supported_roles=frozenset(
+            {"lead", "analyser", "critic", "executor", "verifier", "report-writer"}
+        ),
+        lead_launch=LeadLaunchSpec(
+            executable="codex",
+            model_flag="-m",
+            # A sandboxed lead cannot reach cmux or write its worker CLI config.
+            sandbox_waiver=("-s", "danger-full-access"),
+            sandbox_waiver_note=(
+                "codex will start without its filesystem and network sandbox, "
+                "which okstra needs so the lead can reach cmux and start worker CLIs."
+            ),
+        ),
+    )

package/runtime/python/okstra_ctl/adapters/providers/codex/manifest.json

@@ -0,0 +1 @@
+{"schemaVersion": 1, "id": "codex", "factory": "adapter.py:create_provider"}

package/runtime/python/okstra_ctl/adapters/providers/grok/adapter.py

@@ -0,0 +1,32 @@
+"""Bundled Grok provider catalog."""
+from okstra_ctl.domain.provider import LeadLaunchSpec, ModelSpec, ProviderSpec
+
+
+GROK = {
+    "grok-build-0.1": ModelSpec(
+        "grok-build-0.1", "grok-build-0.1", (1.00, 0.20, 2.00), in_picker=True
+    ),
+    "grok-4.5": ModelSpec("grok-4.5", "grok-4.5", (2.00, 0.30, 6.00), in_picker=True),
+}
+
+GROK_LEAD_LAUNCH = LeadLaunchSpec(
+    executable="grok",
+    model_flag="--model",
+    resume_session_id_flag="--resume",
+)
+
+
+def create_provider() -> ProviderSpec:
+    return ProviderSpec(
+        provider="grok",
+        display_label="Grok",
+        models=GROK,
+        default_models={
+            "lead": "grok-build-0.1",
+            "analyser": "grok-build-0.1",
+            "critic": "grok-4.5",
+        },
+        wrapper="okstra-grok-exec.sh",
+        supported_roles=frozenset({"lead", "analyser", "critic"}),
+        lead_launch=GROK_LEAD_LAUNCH,
+    )

package/runtime/python/okstra_ctl/adapters/providers/grok/manifest.json

@@ -0,0 +1 @@
+{"schemaVersion": 1, "id": "grok", "factory": "adapter.py:create_provider"}

package/runtime/python/okstra_ctl/adapters/providers/kimi/adapter.py

@@ -0,0 +1,38 @@
+"""Bundled Kimi provider catalog."""
+from okstra_ctl.domain.provider import LeadLaunchSpec, ModelSpec, ProviderSpec
+
+
+KIMI = {
+    "kimi-k2.7-code": ModelSpec(
+        "Kimi K2.7 Code", "kimi-k2.7-code", (0.95, 0.19, 4.00), in_picker=True
+    ),
+    "kimi k2.7 code": ModelSpec("Kimi K2.7 Code", "kimi-k2.7-code"),
+    "kimi-for-coding": ModelSpec("Kimi K2.7 Code", "kimi-for-coding", in_picker=True),
+    "kimi-k3": ModelSpec("Kimi K3", "kimi-k3", (3.00, 0.30, 15.00), in_picker=True),
+    "kimi k3": ModelSpec("Kimi K3", "kimi-k3"),
+    "k3": ModelSpec("Kimi K3", "k3", in_picker=True),
+    "k3-256k": ModelSpec("Kimi K3 256K", "k3-256k", in_picker=True),
+    "kimi k3 256k": ModelSpec("Kimi K3 256K", "k3-256k"),
+}
+
+KIMI_LEAD_LAUNCH = LeadLaunchSpec(
+    executable="kimi",
+    model_flag="--model",
+    resume_session_id_flag="--session",
+)
+
+
+def create_provider() -> ProviderSpec:
+    return ProviderSpec(
+        provider="kimi",
+        display_label="Kimi",
+        models=KIMI,
+        default_models={
+            "lead": "kimi-k2.7-code",
+            "analyser": "kimi-k2.7-code",
+            "critic": "kimi-k3",
+        },
+        wrapper="okstra-kimi-exec.sh",
+        supported_roles=frozenset({"lead", "analyser", "critic"}),
+        lead_launch=KIMI_LEAD_LAUNCH,
+    )

package/runtime/python/okstra_ctl/adapters/providers/kimi/manifest.json

@@ -0,0 +1 @@
+{"schemaVersion": 1, "id": "kimi", "factory": "adapter.py:create_provider"}

package/runtime/python/okstra_ctl/application/__init__.py

@@ -0,0 +1 @@
+"""Host-neutral application services."""

package/runtime/python/okstra_ctl/application/advance_wizard.py

@@ -0,0 +1,25 @@
+"""Plan a wizard prompt through the selected host interaction boundary."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from okstra_ctl.domain.host import HostSessionContext
+from okstra_ctl.domain.wizard.interaction import InteractionPlan, WizardPrompt
+from okstra_ctl.ports import InteractionPort
+
+
+@dataclass(frozen=True)
+class PlannedWizardPrompt:
+    prompt: WizardPrompt
+    interaction: InteractionPlan
+
+
+def plan_prompt(
+    prompt: WizardPrompt,
+    context: HostSessionContext,
+    interaction_port: InteractionPort,
+) -> PlannedWizardPrompt:
+    return PlannedWizardPrompt(
+        prompt=prompt,
+        interaction=interaction_port.plan(prompt, context),
+    )

package/runtime/python/okstra_ctl/application/collect_usage.py

@@ -0,0 +1,15 @@
+"""Collect a usage snapshot through the selected host boundary."""
+from __future__ import annotations
+
+from okstra_ctl.ports.usage_accounting import (
+    UsageAccountingPort,
+    UsageRequest,
+    UsageSnapshot,
+)
+
+
+def collect_usage(
+    request: UsageRequest,
+    port: UsageAccountingPort,
+) -> UsageSnapshot:
+    return port.collect(request)

package/runtime/python/okstra_ctl/application/dispatch_assignments.py

@@ -0,0 +1,15 @@
+"""Route one normalized worker-dispatch request through its host port."""
+from __future__ import annotations
+
+from ..ports.worker_dispatch import (
+    WorkerDispatchPlan,
+    WorkerDispatchPort,
+    WorkerDispatchRequest,
+)
+
+
+def dispatch_assignments(
+    request: WorkerDispatchRequest,
+    port: WorkerDispatchPort,
+) -> WorkerDispatchPlan:
+    return port.build_plan(request)

package/runtime/python/okstra_ctl/application/resolve_assignment.py

@@ -0,0 +1,93 @@
+"""Resolve provider assignments from host and provider capabilities."""
+from __future__ import annotations
+
+from okstra_ctl.domain.host import (
+    HostCapabilityMismatch,
+    HostDescriptor,
+    ProviderUnavailable,
+)
+from okstra_ctl.domain.provider import (
+    LeadProviderAssignment,
+    ProviderSpec,
+    RunnerResolution,
+)
+
+
+NATIVE_SESSION = "native-session"
+CLI_WRAPPER = "cli-wrapper"
+RUNNER_VALUES = frozenset({NATIVE_SESSION, CLI_WRAPPER})
+
+
+def resolve_assignment_runner(
+    *,
+    host: HostDescriptor,
+    provider: ProviderSpec,
+    role: str,
+    requested_runner: str = "",
+) -> RunnerResolution:
+    if role not in provider.supported_roles:
+        raise ProviderUnavailable(
+            f"provider {provider.provider!r} does not support role {role!r}"
+        )
+    requested = (requested_runner or "").strip()
+    if requested and requested not in RUNNER_VALUES:
+        allowed = ", ".join(sorted(RUNNER_VALUES))
+        raise HostCapabilityMismatch(
+            f"unknown runner {requested!r}. Allowed values: {allowed}"
+        )
+    is_native = provider.provider == host.native_provider_id
+    if requested == NATIVE_SESSION and not is_native:
+        raise HostCapabilityMismatch(
+            f"host {host.id!r} does not provide native "
+            f"{provider.provider!r} execution"
+        )
+    if requested == NATIVE_SESSION or (not requested and is_native):
+        return RunnerResolution(
+            NATIVE_SESSION,
+            "",
+            f"{host.id} provides native {provider.provider} execution",
+        )
+    if not provider.wrapper:
+        raise ProviderUnavailable(
+            f"provider {provider.provider!r} has no CLI wrapper for role {role!r}"
+        )
+    return RunnerResolution(
+        CLI_WRAPPER,
+        provider.wrapper,
+        f"{host.id} uses the registered {provider.provider} CLI wrapper",
+    )
+
+
+def resolve_lead_provider(
+    *,
+    host_id: str,
+    requested_provider: str,
+    host_registry,
+    provider_registry,
+) -> LeadProviderAssignment:
+    host = host_registry.resolve(host_id).descriptor
+    requested = (requested_provider or "").strip().lower()
+    if not requested and not host.native_provider_id:
+        raise HostCapabilityMismatch(
+            f"host {host.id!r} has no native lead provider; select an explicit "
+            "provider with lead capability"
+        )
+    if host.native_provider_id and requested not in {"", host.native_provider_id}:
+        raise HostCapabilityMismatch(
+            f"{host.agent_label.removesuffix(' CLI')} host requires provider "
+            f"{host.native_provider_id!r} for the in-session lead; provider "
+            f"{requested!r} must be selected as a worker instead"
+        )
+    provider_id = requested or host.native_provider_id
+    provider = provider_registry.resolve(provider_id)
+    resolution = resolve_assignment_runner(
+        host=host,
+        provider=provider,
+        role="lead",
+    )
+    return LeadProviderAssignment(
+        provider=provider.provider,
+        runner=resolution.runner,
+        wrapper=resolution.wrapper,
+        reason=resolution.reason,
+    )

package/runtime/python/okstra_ctl/application/resume_run.py

@@ -0,0 +1,21 @@
+"""Prepare a lead resume plan through a ready host adapter."""
+from __future__ import annotations
+
+from okstra_ctl.domain.host import (
+    HostSessionContext,
+    HostUnavailable,
+    LeadResumeRequest,
+    LeadSessionPlan,
+)
+from okstra_ctl.ports import HostAdapter
+
+
+def resume_run(
+    request: LeadResumeRequest,
+    context: HostSessionContext,
+    adapter: HostAdapter,
+) -> LeadSessionPlan:
+    readiness = adapter.probe(context)
+    if not readiness.ok:
+        raise HostUnavailable(readiness.reason)
+    return adapter.lead_session().build_resume(request, context)

package/runtime/python/okstra_ctl/application/start_run.py

@@ -0,0 +1,21 @@
+"""Prepare a lead start plan through a ready host adapter."""
+from __future__ import annotations
+
+from okstra_ctl.domain.host import (
+    HostSessionContext,
+    HostUnavailable,
+    LeadSessionPlan,
+    LeadStartRequest,
+)
+from okstra_ctl.ports import HostAdapter
+
+
+def start_run(
+    request: LeadStartRequest,
+    context: HostSessionContext,
+    adapter: HostAdapter,
+) -> LeadSessionPlan:
+    readiness = adapter.probe(context)
+    if not readiness.ok:
+        raise HostUnavailable(readiness.reason)
+    return adapter.lead_session().build_start(request, context)