okstra 0.163.2 → 0.164.0

package/runtime/python/okstra_ctl/domain/wizard/interaction.py

@@ -0,0 +1,140 @@
+"""Host-neutral wizard prompts, interaction plans, and answer protocols."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass(frozen=True)
+class WizardOption:
+    value: str
+    label: str
+    description: str = ""
+
+
+@dataclass(frozen=True)
+class WizardPrompt:
+    step: str
+    kind: Literal["pick", "text", "pick_group", "done", "aborted"]
+    label: str = ""
+    options: tuple[WizardOption, ...] = ()
+    help: str = ""
+    echo_template: str = ""
+    multi: bool = False
+    questions: tuple["WizardPrompt", ...] = ()
+
+
+@dataclass(frozen=True)
+class AnswerProtocol:
+    kind: Literal["exact-value", "numbered", "group-json", "numbered-group-json"]
+    multi: bool = False
+
+
+@dataclass(frozen=True)
+class InteractionPlan:
+    kind: Literal[
+        "native-single",
+        "native-multi",
+        "native-group",
+        "numbered-single",
+        "numbered-multi",
+        "sequential-group",
+        "plain-text",
+    ]
+    answer_protocol: AnswerProtocol
+
+
+class WizardAnswerError(ValueError):
+    """Raised when an answer violates the interaction plan's protocol."""
+
+
+def _normalize_numbered_item(prompt: WizardPrompt, answer: str) -> str:
+    candidate = (answer or "").strip()
+    exact_values = tuple(
+        option.value for option in prompt.options if option.value == candidate
+    )
+    if exact_values:
+        return exact_values[0]
+    if candidate.isdecimal():
+        number = int(candidate)
+        if 1 <= number <= len(prompt.options):
+            return prompt.options[number - 1].value
+        raise WizardAnswerError(f"numbered-text answer is out of range: {candidate}")
+    label_values = tuple(
+        option.value for option in prompt.options if option.label == candidate
+    )
+    if len(label_values) == 1:
+        return label_values[0]
+    if len(label_values) > 1:
+        raise WizardAnswerError(
+            f"numbered-text answer label is ambiguous: {candidate}"
+        )
+    raise WizardAnswerError(f"numbered-text answer is not an option: {candidate}")
+
+
+def _normalize_numbered_answer(
+    prompt: WizardPrompt,
+    answer: str,
+    *,
+    multi: bool,
+) -> str:
+    if not multi:
+        return _normalize_numbered_item(prompt, answer)
+    if not (answer or "").strip():
+        return ""
+    return ",".join(
+        _normalize_numbered_item(prompt, item)
+        for item in answer.split(",")
+    )
+
+
+def _group_answers(answer: str) -> dict[str, object]:
+    try:
+        answers = json.loads(answer or "{}")
+    except json.JSONDecodeError as exc:
+        raise WizardAnswerError(f"group answer must be a JSON object: {exc}") from exc
+    if not isinstance(answers, dict):
+        raise WizardAnswerError("group answer must be a JSON object")
+    return answers
+
+
+def _normalize_group_answer(
+    prompt: WizardPrompt,
+    answer: str,
+    *,
+    numbered: bool,
+) -> str:
+    answers = _group_answers(answer)
+    if not numbered:
+        return json.dumps(answers, ensure_ascii=False, separators=(",", ":"))
+    questions = {question.step: question for question in prompt.questions}
+    normalized = dict(answers)
+    for step, raw_answer in answers.items():
+        question = questions.get(step)
+        if question is None:
+            continue
+        normalized[step] = _normalize_numbered_answer(
+            question,
+            str(raw_answer or ""),
+            multi=question.multi,
+        )
+    return json.dumps(normalized, ensure_ascii=False, separators=(",", ":"))
+
+
+def normalize_planned_answer(
+    prompt: WizardPrompt,
+    protocol: AnswerProtocol,
+    answer: str,
+) -> str:
+    if protocol.kind == "exact-value":
+        return answer
+    if protocol.kind == "numbered":
+        return _normalize_numbered_answer(prompt, answer, multi=protocol.multi)
+    if protocol.kind in {"group-json", "numbered-group-json"}:
+        return _normalize_group_answer(
+            prompt,
+            answer,
+            numbered=protocol.kind == "numbered-group-json",
+        )
+    raise WizardAnswerError(f"unsupported answer protocol: {protocol.kind}")

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

@@ -0,0 +1 @@
+"""Internal command entrypoints used by Okstra host integrations."""

package/runtime/python/okstra_ctl/entrypoints/hosts.py

@@ -0,0 +1,334 @@
+"""JSON entrypoint for host catalog, resolution, and launch plans."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from contextlib import contextmanager
+from dataclasses import asdict
+from pathlib import Path
+
+from ..application.start_run import start_run
+from ..application.resume_run import resume_run
+from ..domain.host import (
+    HostAdapterContractError,
+    HostCapabilityMismatch,
+    HostNotRegistered,
+    HostResolutionContext,
+    HostSessionContext,
+    HostUnavailable,
+    LeadStartRequest,
+    LeadResumeRequest,
+    ProviderNotRegistered,
+    ProviderUnavailable,
+)
+from ..registry.host_registry import HostAdapterRegistry, default_host_registry
+
+
+_ENTRYPOINT_ERRORS = (
+    HostAdapterContractError,
+    HostCapabilityMismatch,
+    HostNotRegistered,
+    HostUnavailable,
+    ProviderNotRegistered,
+    ProviderUnavailable,
+    ValueError,
+)
+
+
+def catalog_payload(registry: HostAdapterRegistry) -> dict[str, object]:
+    return {
+        "schemaVersion": 1,
+        "hosts": [asdict(descriptor) for descriptor in registry.catalog()],
+    }
+
+
+def resolve_payload(
+    registry: HostAdapterRegistry,
+    requested_host: str,
+    context: HostResolutionContext,
+) -> dict[str, object]:
+    descriptor, host, reason = registry.resolve_request_details(
+        requested_host, context
+    )
+    return {
+        "ok": True,
+        "requestedRuntime": requested_host.strip().lower() or "auto",
+        "resolvedRuntime": descriptor.id,
+        "launchMode": descriptor.launch_mode,
+        "installTargets": sorted(descriptor.install_targets),
+        "host": host,
+        "confidence": "high",
+        "reason": reason,
+        "fallbackFrom": None,
+        "warnings": [],
+    }
+
+
+def main(
+    argv: list[str] | None = None,
+    *,
+    registry: HostAdapterRegistry | None = None,
+) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    try:
+        active_registry = registry or default_host_registry()
+        payload = _command_payload(args, active_registry)
+    except _ENTRYPOINT_ERRORS as exc:
+        sys.stderr.write(f"{exc}\n")
+        return 2
+    if getattr(args, "output_format", "json") == "null":
+        _write_null_launch_plan(payload)
+    else:
+        public_payload = {
+            key: value for key, value in payload.items()
+            if not key.startswith("_")
+        }
+        print(json.dumps(public_payload, default=_json_default, sort_keys=True))
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="okstra-hosts")
+    commands = parser.add_subparsers(dest="command", required=True)
+    catalog = commands.add_parser("catalog")
+    catalog.add_argument("--json", action="store_true")
+    resolve = commands.add_parser("resolve")
+    resolve.add_argument("--requested", required=True)
+    resolve.add_argument("--command", dest="runtime_command", required=True)
+    resolve.add_argument("--context-json", required=True)
+    launch = commands.add_parser("launch-plan")
+    _add_session_plan_args(launch)
+    launch.add_argument("--prepared-launch-json", default="")
+    resume = commands.add_parser("resume-plan")
+    _add_session_plan_args(resume)
+    resume.add_argument("--session-id", required=True)
+    resume.add_argument("--task-type", default="")
+    resume.add_argument("--request-arg", action="append", default=[])
+    probe = commands.add_parser("probe")
+    probe.add_argument("--host", required=True)
+    probe.add_argument(
+        "--entry-mode",
+        required=True,
+        choices=("spawn-process", "current-session"),
+    )
+    probe.add_argument("--project-root", required=True)
+    probe.add_argument("--home-dir", required=True)
+    probe.add_argument("--available-function", action="append", default=[])
+    return parser
+
+
+def _add_session_plan_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--host", required=True)
+    parser.add_argument(
+        "--entry-mode",
+        required=True,
+        choices=("spawn-process", "current-session"),
+    )
+    parser.add_argument(
+        "--format",
+        dest="output_format",
+        choices=("json", "null"),
+        default="json",
+    )
+    parser.add_argument("--project-root", default=str(Path.cwd()))
+
+
+def _command_payload(
+    args: argparse.Namespace, registry: HostAdapterRegistry
+) -> dict[str, object]:
+    if args.command == "catalog":
+        return catalog_payload(registry)
+    if args.command == "resolve":
+        context = _parse_resolution_context(args.context_json)
+        try:
+            return resolve_payload(registry, args.requested, context)
+        except HostUnavailable as exc:
+            raise HostUnavailable(
+                _unclaimed_host_message(registry, args.runtime_command)
+            ) from exc
+        except HostNotRegistered as exc:
+            if args.requested.strip().lower() in {"", "auto"} and context.explicit_env_host:
+                allowed = "|".join(registry.ids())
+                raise HostNotRegistered(
+                    f"invalid OKSTRA_RUNTIME_HOST {context.explicit_env_host!r} "
+                    f"(expected: {allowed})."
+                ) from exc
+            raise
+    if args.command == "probe":
+        return _probe_payload(registry, args)
+    if args.command == "resume-plan":
+        return _resume_plan_payload(registry, args)
+    return _launch_plan_payload(registry, args)
+
+
+def _probe_payload(
+    registry: HostAdapterRegistry,
+    args: argparse.Namespace,
+) -> dict[str, object]:
+    adapter = registry.resolve(args.host)
+    context = HostSessionContext(
+        host_id=adapter.descriptor.id,
+        entry_mode=args.entry_mode,
+        available_functions=frozenset(args.available_function),
+        interaction_surface="preflight",
+    )
+    with _probe_paths(args.project_root, args.home_dir):
+        readiness = adapter.probe(context)
+    statuses = {check.get("status") for check in readiness.checks}
+    status = "unknown" if "unavailable" in statuses else (
+        "ready" if readiness.ok else "blocked"
+    )
+    return {
+        "runtime": adapter.descriptor.id,
+        "status": status,
+        "checks": list(readiness.checks),
+        "relayContract": adapter.descriptor.relay_contract,
+    }
+
+
+@contextmanager
+def _probe_paths(project_root: str, home_dir: str):
+    keys = ("OKSTRA_PROBE_PROJECT_ROOT", "OKSTRA_PROBE_HOME_DIR")
+    previous = {key: os.environ.get(key) for key in keys}
+    os.environ[keys[0]] = project_root
+    os.environ[keys[1]] = home_dir
+    try:
+        yield
+    finally:
+        for key, value in previous.items():
+            if value is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = value
+
+
+def _parse_resolution_context(raw_context: str) -> HostResolutionContext:
+    try:
+        raw = json.loads(raw_context)
+    except json.JSONDecodeError as exc:
+        raise ValueError("invalid host resolution context JSON") from exc
+    if not isinstance(raw, dict):
+        raise ValueError("invalid host resolution context JSON")
+    env = raw.get("env", {})
+    capabilities = raw.get("capabilities", {})
+    if not isinstance(env, dict) or not isinstance(capabilities, dict):
+        raise ValueError("invalid host resolution context JSON")
+    explicit_env_host = env.get("OKSTRA_RUNTIME_HOST", "")
+    if not isinstance(explicit_env_host, str):
+        raise ValueError("invalid host resolution context JSON")
+    signals = frozenset(
+        signal
+        for capability, signal in (
+            ("claudeSkillHandoff", "claude-skill-handoff"),
+            ("tmuxAvailable", "tmux"),
+        )
+        if capabilities.get(capability) is True
+    )
+    return HostResolutionContext(explicit_env_host, signals)
+
+
+def _unclaimed_host_message(registry: HostAdapterRegistry, command: str) -> str:
+    runtime_flag = "--runtime" if command in {
+        "install", "ensure-installed", "doctor"
+    } else "--lead-runtime"
+    allowed = "|".join(registry.ids())
+    return (
+        f"host unknown: set OKSTRA_RUNTIME_HOST={allowed} or pass "
+        f"{runtime_flag} explicitly."
+    )
+
+
+def _launch_plan_payload(
+    registry: HostAdapterRegistry,
+    args: argparse.Namespace,
+) -> dict[str, object]:
+    adapter = registry.resolve(args.host)
+    context = HostSessionContext(
+        host_id=adapter.descriptor.id,
+        entry_mode=args.entry_mode,
+        available_functions=frozenset(),
+        interaction_surface="terminal",
+    )
+    project_root, request_argv = _launch_request(args, adapter.descriptor.id)
+    request = LeadStartRequest(project_root, "", request_argv)
+    plan = start_run(request, context, adapter)
+    return {"ok": True, "_project_root": str(project_root), **asdict(plan)}
+
+
+def _resume_plan_payload(
+    registry: HostAdapterRegistry,
+    args: argparse.Namespace,
+) -> dict[str, object]:
+    adapter = registry.resolve(args.host)
+    context = HostSessionContext(
+        host_id=adapter.descriptor.id,
+        entry_mode=args.entry_mode,
+        available_functions=frozenset(),
+        interaction_surface="terminal",
+    )
+    project_root = Path(args.project_root)
+    request = LeadResumeRequest(
+        project_root,
+        args.task_type,
+        args.session_id,
+        tuple(args.request_arg),
+    )
+    plan = resume_run(request, context, adapter)
+    return {"ok": True, "_project_root": str(project_root), **asdict(plan)}
+
+
+def _launch_request(
+    args: argparse.Namespace,
+    canonical_host_id: str,
+) -> tuple[Path, tuple[str, ...]]:
+    if not args.prepared_launch_json:
+        return Path(args.project_root), ()
+    try:
+        prepared = json.loads(args.prepared_launch_json)
+    except json.JSONDecodeError as exc:
+        raise ValueError("invalid prepared launch JSON") from exc
+    if not isinstance(prepared, dict):
+        raise ValueError("prepared launch JSON must be an object")
+    if prepared.get("leadRuntime") != canonical_host_id:
+        raise ValueError("prepared launch runtime does not match selected host")
+    project_root = prepared.get("projectRoot")
+    request_argv = prepared.get("launchRequestArgv")
+    if not isinstance(project_root, str) or not project_root:
+        raise ValueError("prepared launch is missing projectRoot")
+    if not isinstance(request_argv, list) or not all(
+        isinstance(arg, str) for arg in request_argv
+    ):
+        raise ValueError("prepared launch is missing launchRequestArgv")
+    return Path(project_root), tuple(request_argv)
+
+
+def _write_null_launch_plan(payload: dict[str, object]) -> None:
+    fields = [
+        payload["_project_root"],
+        payload["sandbox_note"],
+        str(len(payload["env"])),
+    ]
+    fields.extend(
+        f"{key}={value}" for key, value in payload["env"].items()
+    )
+    fields.extend(payload["argv"])
+    for field in fields:
+        value = str(field)
+        if "\0" in value:
+            raise ValueError("launch plan field contains a null byte")
+        sys.stdout.write(value + "\0")
+
+
+def _json_default(value: object) -> object:
+    if isinstance(value, (frozenset, set)):
+        return sorted(value)
+    if isinstance(value, Path):
+        return str(value)
+    raise TypeError(f"not JSON serializable: {type(value).__name__}")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())