okstra 0.174.0 → 0.176.0

package/runtime/python/okstra_ctl/model_cli.py

@@ -0,0 +1,278 @@
+"""List models and atomically write role defaults. No inference calls."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from okstra_project import project_json_path, resolve_project_root
+from okstra_project.dirs import okstra_home
+
+from .domain.provider import UnknownModelError
+from .domain.role import RoleCatalogError, normalize_role
+from .model_pool import ModelPool, ModelPoolValidationError
+from .ports.host_model import HostModelBindingError, HostModelBindingRequest
+from .registry.host_registry import default_host_registry
+from .registry.provider_registry import default_provider_registry
+
+
+class ModelCliError(ValueError):
+    """Raised when a model list or default write cannot be completed."""
+
+
+def list_models(
+    *,
+    role: str | None,
+    host_runtime: str,
+    as_json: bool,
+) -> int:
+    wanted = normalize_role(role) if role else None
+    pool, adapter = _pool_and_host(host_runtime)
+    rows = [
+        _catalog_row(model, adapter, wanted)
+        for model in pool.list_catalog(role=wanted)
+    ]
+    if as_json:
+        print(json.dumps({"models": rows}, ensure_ascii=False))
+        return 0
+    for row in rows:
+        mark = "yes" if row["selectable"] else "no"
+        print(f"{row['modelRef']}\t{mark}\t{row['reason']}")
+    return 0
+
+
+def set_model_default(
+    *,
+    role: str,
+    refs: tuple[str, ...],
+    scope: str,
+    cwd: Path,
+) -> int:
+    canonical = normalize_role(role)
+    if not refs or len(refs) != len(set(refs)):
+        raise ModelCliError("model defaults must be a unique non-empty list")
+    pool, _adapter = _pool_and_host("claude-code")
+    for ref in refs:
+        try:
+            availability = pool.availability(ref, canonical)
+        except UnknownModelError as exc:
+            raise ModelCliError(str(exc)) from exc
+        if not availability.available:
+            raise ModelCliError(
+                f"model {ref!r} cannot default role {canonical}: "
+                f"{availability.reason}"
+            )
+    path = _config_path(scope, cwd)
+    payload = _read_json(path)
+    defaults = dict(payload.get("modelDefaults") or {})
+    defaults[canonical] = list(refs)
+    payload["modelDefaults"] = defaults
+    _write_json_atomic(path, payload)
+    return 0
+
+
+def unset_model_default(*, role: str, scope: str, cwd: Path) -> int:
+    canonical = normalize_role(role)
+    path = _config_path(scope, cwd)
+    payload = _read_json(path)
+    defaults = dict(payload.get("modelDefaults") or {})
+    defaults.pop(canonical, None)
+    payload["modelDefaults"] = defaults
+    _write_json_atomic(path, payload)
+    return 0
+
+
+def model_diagnostics(
+    *,
+    host_runtime: str = "claude-code",
+    cwd: Path | None = None,
+) -> dict[str, Any]:
+    """Report pool and default issues without making an inference call."""
+    root = Path(cwd) if cwd is not None else Path.cwd()
+    try:
+        pool, adapter = _pool_and_host(host_runtime)
+        pool_errors: list[str] = []
+    except ModelPoolValidationError as exc:
+        return {
+            "poolErrors": [str(exc)],
+            "defaultErrors": [],
+            "bindingPrecision": "unknown",
+            "observedModel": None,
+            "maxWriteBoundary": "none",
+            "invocationDowngradeReason": None,
+            "inferenceCall": False,
+        }
+    default_errors = [
+        *_default_errors(pool, _try_project_json(root), "project"),
+        *_default_errors(pool, okstra_home() / "config.json", "global"),
+    ]
+    capability = adapter.worker_dispatch().worker_write_capability()
+    max_boundary = (
+        capability.max_boundary_precision if capability is not None else "none"
+    )
+    return {
+        "poolErrors": pool_errors,
+        "defaultErrors": default_errors,
+        "bindingPrecision": "channel" if host_runtime == "claude-code" else "exact",
+        "observedModel": None,
+        "maxWriteBoundary": max_boundary,
+        "invocationDowngradeReason": None,
+        "inferenceCall": False,
+    }
+
+
+def _pool_and_host(host_runtime: str):
+    registry = default_provider_registry()
+    return ModelPool.from_registry(registry), default_host_registry(registry).resolve(
+        host_runtime
+    )
+
+
+def _catalog_row(model, adapter, role: str | None) -> dict[str, Any]:
+    row = {
+        "modelRef": str(model.model_ref),
+        "provider": model.provider_id,
+        "displayName": model.display_name,
+        "selectable": bool(model.selectable),
+        "reason": "",
+    }
+    if not model.selectable:
+        row["reason"] = "not selectable"
+        return row
+    if role != "leader":
+        return row
+    if model.provider_id != adapter.descriptor.native_provider_id:
+        return row
+    try:
+        adapter.host_model().resolve(
+            HostModelBindingRequest(
+                host_runtime=adapter.descriptor.id,
+                provider=model.provider_id,
+                model_ref=str(model.model_ref),
+                version_kind=model.version_kind,
+                model_execution_value=model.execution_value,
+                runner="native-session",
+            )
+        )
+    except HostModelBindingError as exc:
+        row["selectable"] = False
+        row["reason"] = str(exc)
+    return row
+
+
+def _default_errors(pool: ModelPool, path: Path, scope: str) -> list[str]:
+    if not path.is_file():
+        return []
+    payload = _read_json(path)
+    defaults = payload.get("modelDefaults")
+    if defaults is None:
+        return []
+    if not isinstance(defaults, dict):
+        return [f"{scope} modelDefaults must be an object"]
+    errors: list[str] = []
+    for role, refs in defaults.items():
+        try:
+            canonical = normalize_role(str(role))
+        except RoleCatalogError as exc:
+            errors.append(str(exc))
+            continue
+        if not isinstance(refs, list) or not refs:
+            errors.append(f"{scope} model defaults for {canonical!r} are empty")
+            continue
+        seen: set[str] = set()
+        for ref in refs:
+            token = str(ref)
+            if token in seen:
+                errors.append(f"{scope} duplicate model default {token}")
+            seen.add(token)
+            try:
+                availability = pool.availability(token, canonical)
+            except UnknownModelError as exc:
+                errors.append(str(exc))
+                continue
+            if not availability.available:
+                errors.append(
+                    f"{scope} model {token!r} cannot default role {canonical}: "
+                    f"{availability.reason}"
+                )
+    return errors
+
+
+def _try_project_json(cwd: Path) -> Path:
+    try:
+        return project_json_path(resolve_project_root(cwd=str(cwd)))
+    except Exception:
+        return cwd / ".okstra" / "project.json"
+
+
+def _config_path(scope: str, cwd: Path) -> Path:
+    if scope == "global":
+        return okstra_home() / "config.json"
+    return project_json_path(resolve_project_root(cwd=str(cwd)))
+
+
+def _read_json(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    return payload if isinstance(payload, dict) else {}
+
+
+def _write_json_atomic(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    handle = tempfile.NamedTemporaryFile(
+        "w", encoding="utf-8", delete=False, dir=path.parent
+    )
+    try:
+        json.dump(payload, handle, ensure_ascii=False, indent=2)
+        handle.write("\n")
+        handle.close()
+        os.replace(handle.name, path)
+    except Exception:
+        handle.close()
+        Path(handle.name).unlink(missing_ok=True)
+        raise
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="okstra model")
+    sub = parser.add_subparsers(dest="command", required=True)
+    listed = sub.add_parser("list")
+    listed.add_argument("--role")
+    listed.add_argument("--host", default="claude-code")
+    listed.add_argument("--json", action="store_true")
+    default = sub.add_parser("default")
+    default_sub = default.add_subparsers(dest="default_command", required=True)
+    setter = default_sub.add_parser("set")
+    setter.add_argument("role")
+    setter.add_argument("refs")
+    setter.add_argument("--scope", choices=("project", "global"), required=True)
+    setter.add_argument("--cwd", default=".")
+    unsetter = default_sub.add_parser("unset")
+    unsetter.add_argument("role")
+    unsetter.add_argument("--scope", choices=("project", "global"), required=True)
+    unsetter.add_argument("--cwd", default=".")
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "list":
+            return list_models(
+                role=args.role, host_runtime=args.host, as_json=args.json
+            )
+        if args.default_command == "set":
+            refs = tuple(part for part in args.refs.split(",") if part)
+            return set_model_default(
+                role=args.role, refs=refs, scope=args.scope, cwd=Path(args.cwd)
+            )
+        return unset_model_default(
+            role=args.role, scope=args.scope, cwd=Path(args.cwd)
+        )
+    except (ModelCliError, RoleCatalogError, UnknownModelError, OSError, ValueError) as exc:
+        print(f"error: {exc}", flush=True)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/python/okstra_ctl/model_defaults.py

@@ -0,0 +1,46 @@
+"""Pure role-model default scope replacement."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Mapping
+
+
+class ModelDefaultError(ValueError):
+    """Raised when the selected default scope cannot supply candidates."""
+
+
+@dataclass(frozen=True)
+class ModelDefaultScopes:
+    project: Mapping[str, tuple[str, ...]]
+    global_: Mapping[str, tuple[str, ...]]
+    bundled: Mapping[str, tuple[str, ...]]
+
+
+def default_candidates(role: str, scopes: ModelDefaultScopes) -> tuple[str, ...]:
+    """Return the first scope containing ``role`` without merging arrays."""
+    for scope_name, values in (
+        ("project", scopes.project),
+        ("global", scopes.global_),
+        ("bundled", scopes.bundled),
+    ):
+        if role not in values:
+            continue
+        candidates = tuple(values[role])
+        if not candidates:
+            raise ModelDefaultError(
+                f"{scope_name} model defaults for {role!r} are empty"
+            )
+        return candidates
+    return ()
+
+
+def default_scope(role: str, scopes: ModelDefaultScopes) -> str | None:
+    """Name the selected scope for resolver validation and diagnostics."""
+    for scope_name, values in (
+        ("project", scopes.project),
+        ("global", scopes.global_),
+        ("bundled", scopes.bundled),
+    ):
+        if role in values:
+            return scope_name
+    return None

package/runtime/python/okstra_ctl/model_discovery.py

@@ -105,21 +105,40 @@ def normalize_execution_for_dispatch(
     blocking. Raise ModelUnavailableError when the identity is definitely not
     offered (never substitute a different model)."""
     if provider == "codex":
-        available = codex_availability()
-        if not available or execution in available:
-            return execution  # no NUX list → pass through; listed → accepted
-        raise ModelUnavailableError(
-            f"codex model {execution!r} is not available for this account. "
-            f"Available: {', '.join(available)} (no auto-rename — update the catalog)"
+        return normalize_codex_execution(
+            execution=execution,
+            available=codex_availability(),
         )
     if provider != "antigravity":
         return execution  # claude runs via the Agent tool
+    return normalize_antigravity_execution(
+        execution=execution,
+        role=role,
+        available=agy_models(),
+    )
+
+
+def normalize_codex_execution(
+    *, execution: str, available: tuple[str, ...]
+) -> str:
+    """Normalize one Codex value against a previously captured config list."""
+    if not available or execution in available:
+        return execution
+    raise ModelUnavailableError(
+        f"codex model {execution!r} is not available for this account. "
+        f"Available: {', '.join(available)} (no auto-rename — update the catalog)"
+    )
+
+
+def normalize_antigravity_execution(
+    *, execution: str, role: str, available: tuple[str, ...]
+) -> str:
+    """Normalize one agy value against a previously captured model list."""
     # agy bakes the tier into the model identity as a slug suffix
     # (`gemini-3.1-pro-high`) and rejects the bare slug with "requires --effort"
     # — a flag the wrapper never sends. So the suffixed form is the only
     # dispatchable spelling, including on the un-verified fallback below.
     tiered = f"{execution}-{_dispatch_effort(execution, role)}"
-    available = agy_models()
     if not available:
         return tiered  # discovery unavailable → dispatch anyway, wrapper still guards
     if execution in available: