okstra 0.163.2 → 0.165.0

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())

package/runtime/python/okstra_ctl/incremental_scope.py

@@ -293,20 +293,32 @@ def decide_scope(
     if not prev_base_sha or prev_base_sha != cur_base_sha:
         return IncrementalDecision(
             "full", [], [],
-            f"base-ref changed ({prev_base_sha!r} -> {cur_base_sha!r}); prior analysis invalid",
+            "the branch this plan was written against has moved on "
+            f"({prev_base_sha or 'unrecorded'} -> {cur_base_sha or 'unrecorded'}), "
+            "so none of the prior stages can be reused as they stand",
         )
     if not impacted_stages:
-        return IncrementalDecision("full", [], [], "no impacted stages resolved; falling back to full")
+        return IncrementalDecision(
+            "full", [], [],
+            "no stage of the prior plan could be tied to the answers, so there is "
+            "nothing to narrow the rework down to",
+        )
     all_stages = {num for num, _ in stages}
     closure = downstream_stage_closure(stages, set(impacted_stages))
     if len(closure) * 2 > len(all_stages):
         return IncrementalDecision(
             "full", [], [],
-            f"closure {len(closure)}/{len(all_stages)} exceeds {int(cutoff_ratio * 100)}% cutoff",
+            f"the answers reach {len(closure)} of the plan's {len(all_stages)} stages — "
+            f"past the {int(cutoff_ratio * 100)}% mark where replanning outright costs "
+            "less than tracking what carried over",
         )
     reverify = sorted(closure)
     carry = sorted(all_stages - closure)
-    return IncrementalDecision("incremental", reverify, carry, f"closure {reverify} within cutoff")
+    return IncrementalDecision(
+        "incremental", reverify, carry,
+        f"the answers reach {len(reverify)} of the plan's {len(all_stages)} stages; "
+        "the rest is reused as written",
+    )
 
 
 def _preview_result(args) -> dict: