hubble-cli 4.0.0__py3-none-any.whl

hubble/prompts.py

@@ -0,0 +1,157 @@
+"""System prompt: persona, tool guidance, environment and project memory files."""
+
+import functools
+import platform
+import subprocess
+import time
+from pathlib import Path
+from typing import List, Tuple
+
+from hubble.settings import HOME_DIR
+
+MEMORY_FILENAMES = ("HUBBLE.md", "AGENTS.md", "CLAUDE.md", "GEMINI.md")
+MAX_MEMORY_CHARS = 20000
+
+PERSONAS = {
+    "code": "You are Hubble, an expert software engineer working directly in the user's repository.",
+    "debug": ("You are Hubble in debug mode. Reproduce the problem, find the root cause before "
+              "changing code, explain it in one or two sentences, apply the minimal fix and verify it."),
+    "review": ("You are Hubble in review mode, a strict senior reviewer. Read the relevant code and "
+               "report findings grouped as Bug, Security, Performance or Style, each with file:line and a "
+               "concrete fix. Do not edit files unless asked."),
+    "architect": ("You are Hubble in architect mode. Explore the codebase structure and produce designs, "
+                  "trade-offs and phased implementation plans. Do not edit files unless asked."),
+    "chat": "You are Hubble, a helpful technical assistant. Use tools only when they help answer.",
+}
+
+GUIDELINES = """\
+# How to work
+- Use the tools to inspect the workspace instead of guessing. Search with grep/glob, then read_file the relevant parts.
+- Always read_file a file before editing it. Prefer edit_file for targeted changes; use write_file for new files.
+- In edit_file, old_string must match the file exactly, without the "N | " line-number prefix from read_file.
+- Keep changes minimal and consistent with the surrounding code style. Do not add unrelated refactors.
+- After changing code, verify it: run the tests, a build, or at least a syntax check with the shell tool.
+- For tasks with three or more steps, track progress with todo_write.
+- If you notice yourself repeating a multi-step procedure this user is likely to need again, offer to
+  save it with write_skill so it is available as a skill next time (ask first; do not save one-off tasks).
+- Use web_search for anything that may have changed since your training (library versions, APIs, error
+  messages), then web_fetch the best result. Cite the URLs you used.
+- If a tool call is denied, do not retry the same call; adjust your approach or ask the user.
+- Never print or exfiltrate secrets (.env files, keys, tokens).
+- Be concise. Lead with the answer or result. Reference code as path:line.
+- When the task is done, reply with a short summary of what changed and how it was verified."""
+
+
+@functools.lru_cache(maxsize=8)
+def _git_summary(root: Path) -> str:
+    try:
+        branch = subprocess.run(["git", "rev-parse", "--abbrev-ref", "HEAD"], cwd=root, capture_output=True,
+                                text=True, timeout=5, stdin=subprocess.DEVNULL)
+        if branch.returncode != 0:
+            return "not a git repository"
+        status = subprocess.run(["git", "status", "--short"], cwd=root, capture_output=True, text=True,
+                                timeout=5, stdin=subprocess.DEVNULL)
+        changed = [l for l in status.stdout.splitlines() if l.strip()]
+        summary = f"branch {branch.stdout.strip()}, {len(changed)} changed file(s)"
+        if changed:
+            summary += "\n" + "\n".join(f"  {l}" for l in changed[:15])
+        return summary
+    except (OSError, subprocess.TimeoutExpired):
+        return "git unavailable"
+
+
+@functools.lru_cache(maxsize=8)
+def workspace_overview(root: Path, limit: int = 80) -> str:
+    """Shallow file tree (depth 2) so the model knows what exists before searching."""
+    from hubble.tools import IGNORED_DIRS
+    lines: List[str] = []
+
+    def entries(d: Path):
+        try:
+            return sorted((e for e in d.iterdir() if e.name not in IGNORED_DIRS and not e.name.startswith(".")),
+                          key=lambda e: (not e.is_dir(), e.name.lower()))
+        except OSError:
+            return []
+
+    for e in entries(root):
+        if len(lines) >= limit:
+            lines.append("  ...")
+            break
+        lines.append(f"  {e.name}/" if e.is_dir() else f"  {e.name}")
+        if e.is_dir():
+            children = entries(e)
+            for c in children[:12]:
+                lines.append(f"    {c.name}/" if c.is_dir() else f"    {c.name}")
+            if len(children) > 12:
+                lines.append(f"    ... {len(children) - 12} more")
+    return "\n".join(lines[: limit + 1]) or "  (empty)"
+
+
+def find_memory_files(root: Path) -> List[Path]:
+    """User-level memory, then files from the filesystem root down to the workspace."""
+    found = [p for p in (HOME_DIR / "HUBBLE.md",) if p.is_file()]
+    chain = [root, *root.parents]
+    stop = next((i for i, d in enumerate(chain) if (d / ".git").exists()), None)
+    dirs = chain[: stop + 1] if stop is not None else [root]
+    for d in reversed(dirs):
+        for name in MEMORY_FILENAMES:
+            p = d / name
+            if p.is_file():
+                found.append(p)
+                break  # one memory file per directory; HUBBLE.md takes priority
+    return found
+
+
+def load_memory(root: Path) -> List[Tuple[Path, str]]:
+    out, budget = [], MAX_MEMORY_CHARS
+    for p in find_memory_files(root):
+        try:
+            text = p.read_text(encoding="utf-8", errors="replace").strip()
+        except OSError:
+            continue
+        if text and budget > 0:
+            out.append((p, text[:budget]))
+            budget -= len(text)
+    return out
+
+
+def build_system_prompt(root: Path, persona: str, shell: str, model: str,
+                        pinned: dict, memory: List[Tuple[Path, str]], mode: str,
+                        skills_block: str = "") -> str:
+    parts = [PERSONAS.get(persona, PERSONAS["code"]), GUIDELINES]
+    parts.append(
+        "# Environment\n"
+        f"- Workspace root: {root}\n"
+        f"- OS: {platform.system()} {platform.release()}\n"
+        f"- Shell used by the shell tool: {shell}"
+        + (" (use PowerShell syntax; `&&` is not supported in 5.1, use `;`)" if "5.1" in shell else "")
+        + f"\n- Date: {time.strftime('%Y-%m-%d')}\n"
+        f"- Model: {model}\n"
+        f"- Git (at session start): {_git_summary(root)}\n"
+        f"- Workspace files (snapshot at session start, depth 2):\n{workspace_overview(root)}"
+    )
+    if mode == "plan":
+        parts.append("# Plan mode\nYou are in read-only plan mode. Explore with read-only tools, then present "
+                     "a concise step-by-step implementation plan. Do not try to edit files or run commands.")
+    for path, text in memory:
+        parts.append(f"# Project instructions from {path}\n{text}")
+    if skills_block:
+        parts.append(skills_block)
+    if pinned:
+        files = "\n\n".join(f"--- {name} ---\n{text}" for name, text in pinned.items())
+        parts.append(f"# Files pinned by the user\n{files}")
+    return "\n\n".join(parts)
+
+
+INIT_PROMPT = """Analyze this codebase and create an HUBBLE.md file in the workspace root with instructions for future \
+coding sessions. Include: a one-paragraph overview, how to install, build, run and test (exact commands), the \
+high-level architecture and the role of the key files, and code style or conventions you observe. Keep it under \
+80 lines, factual, and skip generic advice. If HUBBLE.md already exists, read it and improve it instead."""
+
+COMPACT_PROMPT = """Summarize the conversation so far so the work can continue in a fresh context. Include:
+1. The user's goals and explicit requests, in their words where it matters.
+2. Key decisions and findings.
+3. Files read or modified, with the important details of each change.
+4. Errors hit and how they were fixed.
+5. Pending tasks and the exact next step.
+Be dense and specific; omit pleasantries."""

hubble/provider.py

@@ -0,0 +1,283 @@
+"""OpenAI-compatible streaming client with native tool calling."""
+
+import hashlib
+import json
+import re
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+import httpx
+from urllib.parse import urlparse
+
+RETRY_STATUS = {408, 429, 500, 502, 503, 504}
+
+
+class ProviderError(Exception):
+    def __init__(self, message: str, status: Optional[int] = None):
+        super().__init__(message)
+        self.status = status
+
+    @property
+    def transient(self) -> bool:
+        """Rate limits, overload and outages: another model may still work."""
+        return self.status in RETRY_STATUS or self.status is None
+
+
+@dataclass
+class ToolCall:
+    id: str
+    name: str
+    arguments: str
+
+
+@dataclass
+class TurnResult:
+    text: str = ""
+    reasoning: str = ""
+    tool_calls: List[ToolCall] = field(default_factory=list)
+    usage: Dict[str, int] = field(default_factory=dict)
+    finish_reason: Optional[str] = None
+    ttft_ms: int = 0
+    duration: float = 0.0
+
+
+def normalize_base_url(url: str) -> str:
+    """Append /v1 only to a bare host; keep explicit paths such as /api/v1 or /v1beta/openai."""
+    url = url.strip().rstrip("/")
+    if not re.match(r"^https?://", url):
+        url = "https://" + url
+    if urlparse(url).path in ("", "/"):
+        url += "/v1"
+    return url
+
+
+def _short_id(raw: str) -> str:
+    # Mistral rejects tool_call ids that are not 9 alphanumeric chars; other backends accept any.
+    return hashlib.sha1(raw.encode()).hexdigest()[:9]
+
+
+def normalize_messages(messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Rewrite tool_call ids so a history built with one model stays valid for another."""
+    out = []
+    for m in messages:
+        m = dict(m)
+        if m.get("tool_calls"):
+            m["tool_calls"] = [{**tc, "id": _short_id(tc["id"])} for tc in m["tool_calls"]]
+            if not m.get("content"):
+                m["content"] = ""
+        if m.get("role") == "tool":
+            m["tool_call_id"] = _short_id(m["tool_call_id"])
+        out.append(m)
+    return out
+
+
+def _error_message(body: str) -> str:
+    """Short human message. Gateways often wrap the upstream error as JSON inside the message."""
+    try:
+        err = json.loads(body).get("error", {})
+    except (ValueError, AttributeError):
+        return body.strip()[:200]
+    if not isinstance(err, dict):
+        return str(err)[:200]
+    msg = err.get("message") or json.dumps(err)
+    inner = re.search(r"\{.*\}", msg, re.DOTALL)
+    if inner:
+        try:
+            raw = json.loads(inner.group(0)).get("raw")
+            if raw:
+                msg = raw
+        except (ValueError, AttributeError):
+            pass
+    msg = re.split(r"(?<=\.)\s", msg.strip(), maxsplit=1)[0]  # first sentence is the useful part
+    return msg[:200]
+
+
+def _retry_after(resp: httpx.Response) -> Optional[float]:
+    try:
+        return max(0.0, min(float(resp.headers.get("retry-after", "")), 20.0))
+    except ValueError:
+        return None
+
+
+class OpenAICompatProvider:
+    def __init__(self, base_url: str, api_key: str, client: Optional[httpx.Client] = None,
+                 max_retries: int = 3):
+        self.base_url = normalize_base_url(base_url)
+        self.api_key = api_key
+        self.max_retries = max_retries
+        self.client = client or httpx.Client(
+            timeout=httpx.Timeout(connect=15.0, read=180.0, write=30.0, pool=15.0))
+
+    @property
+    def headers(self) -> Dict[str, str]:
+        return {"Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json"}
+
+    def stream(self, model: str, messages: List[Dict[str, Any]], tools: Optional[List[Dict]] = None,
+               temperature: float = 0.3, max_tokens: int = 8192,
+               on_text: Optional[Callable[[str], None]] = None,
+               on_reasoning: Optional[Callable[[str], None]] = None) -> TurnResult:
+        payload: Dict[str, Any] = {
+            "model": model,
+            "messages": normalize_messages(messages),
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+            "stream": True,
+            "stream_options": {"include_usage": True},
+        }
+        if tools:
+            payload["tools"] = tools
+            payload["tool_choice"] = "auto"
+
+        attempt = 0
+        while True:
+            attempt += 1
+            try:
+                return self._stream_once(payload, on_text, on_reasoning)
+            except _Retryable as e:
+                if attempt > self.max_retries:
+                    raise ProviderError(str(e), e.status) from None
+                time.sleep(e.wait if e.wait is not None else min(2 ** (attempt - 1), 8))
+
+    def _stream_once(self, payload, on_text, on_reasoning) -> TurnResult:
+        result = TurnResult()
+        text_parts: List[str] = []
+        reasoning_parts: List[str] = []
+        calls: Dict[int, Dict[str, str]] = {}
+        start = time.time()
+        got_delta = False
+
+        try:
+            with self.client.stream("POST", f"{self.base_url}/chat/completions",
+                                    headers=self.headers, json=payload) as resp:
+                if resp.status_code != 200:
+                    body = resp.read().decode("utf-8", errors="replace")
+                    msg = f"HTTP {resp.status_code}: {_error_message(body)}"
+                    if resp.status_code in RETRY_STATUS:
+                        raise _Retryable(msg, resp.status_code, _retry_after(resp))
+                    raise ProviderError(msg, resp.status_code)
+
+                for line in resp.iter_lines():
+                    if not line.startswith("data:"):
+                        continue
+                    data = line[5:].strip()
+                    if data == "[DONE]":
+                        break
+                    try:
+                        chunk = json.loads(data)
+                    except ValueError:
+                        continue
+                    if chunk.get("error"):
+                        err = chunk["error"]
+                        raise ProviderError(err.get("message", str(err)) if isinstance(err, dict) else str(err))
+                    if chunk.get("usage"):
+                        result.usage = {k: v for k, v in chunk["usage"].items() if isinstance(v, int)}
+                    for choice in chunk.get("choices") or []:
+                        delta = choice.get("delta") or {}
+                        reasoning = delta.get("reasoning_content") or delta.get("reasoning") or ""
+                        if reasoning:
+                            got_delta = True
+                            reasoning_parts.append(reasoning)
+                            if on_reasoning:
+                                on_reasoning(reasoning)
+                        content = delta.get("content") or ""
+                        if content:
+                            if not result.ttft_ms:
+                                result.ttft_ms = round((time.time() - start) * 1000)
+                            got_delta = True
+                            text_parts.append(content)
+                            if on_text:
+                                on_text(content)
+                        for tc in delta.get("tool_calls") or []:
+                            got_delta = True
+                            slot = calls.setdefault(self._slot_index(calls, tc),
+                                                    {"id": "", "name": "", "arguments": ""})
+                            if tc.get("id"):
+                                slot["id"] = tc["id"]
+                            fn = tc.get("function") or {}
+                            name = fn.get("name")
+                            if name and name != slot["name"]:  # some backends resend the full name
+                                slot["name"] += name
+                            if fn.get("arguments"):
+                                args = fn["arguments"]
+                                slot["arguments"] += args if isinstance(args, str) else json.dumps(args)
+                        if choice.get("finish_reason"):
+                            result.finish_reason = choice["finish_reason"]
+        except (httpx.TimeoutException, httpx.TransportError) as e:
+            if got_delta:
+                raise ProviderError(f"Connection lost mid-stream: {e}") from None
+            raise _Retryable(f"{type(e).__name__}: {e}") from None
+
+        result.text = "".join(text_parts)
+        result.reasoning = "".join(reasoning_parts)
+        for idx in sorted(calls):
+            slot = calls[idx]
+            if slot["name"]:
+                result.tool_calls.append(ToolCall(slot["id"] or f"call_{idx}_{int(start)}",
+                                                  slot["name"], slot["arguments"] or "{}"))
+        result.duration = time.time() - start
+        return result
+
+    @staticmethod
+    def _slot_index(calls: Dict[int, Dict[str, str]], tc: Dict[str, Any]) -> int:
+        if isinstance(tc.get("index"), int):
+            return tc["index"]
+        # No index: a new id starts a new call, otherwise the chunk continues the last one.
+        cid = tc.get("id")
+        for idx, slot in calls.items():
+            if cid and slot["id"] == cid:
+                return idx
+        if cid or not calls:
+            return max(calls, default=-1) + 1
+        return max(calls)
+
+    def complete(self, model: str, messages: List[Dict[str, Any]], max_tokens: int = 2048,
+                 temperature: float = 0.2) -> str:
+        """Non-streaming call used for compaction and summaries."""
+        payload = {"model": model, "messages": normalize_messages(messages),
+                   "max_tokens": max_tokens, "temperature": temperature, "stream": False}
+        try:
+            resp = self.client.post(f"{self.base_url}/chat/completions", headers=self.headers, json=payload)
+        except httpx.HTTPError as e:
+            raise ProviderError(f"{type(e).__name__}: {e}") from None
+        if resp.status_code != 200:
+            raise ProviderError(f"HTTP {resp.status_code}: {_error_message(resp.text)}")
+        choices = resp.json().get("choices") or []
+        if not choices:
+            raise ProviderError("Empty response")
+        return (choices[0].get("message") or {}).get("content") or ""
+
+    def ping(self, model: str) -> Dict[str, Any]:
+        start = time.time()
+        try:
+            text = self.complete(model, [{"role": "user", "content": "Reply OK"}], max_tokens=10)
+            return {"ok": True, "latency_ms": round((time.time() - start) * 1000), "msg": text.strip()[:60]}
+        except ProviderError as e:
+            return {"ok": False, "latency_ms": round((time.time() - start) * 1000), "msg": str(e)[:120]}
+
+
+class _Retryable(Exception):
+    def __init__(self, message: str, status: Optional[int] = None, wait: Optional[float] = None):
+        super().__init__(message)
+        self.status = status
+        self.wait = wait
+
+
+def parse_arguments(raw: str) -> Dict[str, Any]:
+    """Parse tool-call JSON, tolerating code fences and trailing junk from weaker models."""
+    raw = (raw or "").strip() or "{}"
+    candidates = [raw]
+    fenced = re.sub(r"^```(?:json)?\s*|\s*```$", "", raw)
+    if fenced != raw:
+        candidates.append(fenced)
+    start, end = raw.find("{"), raw.rfind("}")
+    if 0 <= start < end:
+        candidates.append(raw[start:end + 1])
+    for cand in candidates:
+        try:
+            val = json.loads(cand)
+        except ValueError:
+            continue
+        if isinstance(val, dict):
+            return val
+    raise ValueError(f"Tool arguments are not a valid JSON object: {raw[:200]}")

hubble/providers.py

@@ -0,0 +1,186 @@
+"""Multiple OpenAI-compatible providers.
+
+The built-in "hubble" provider comes from settings/.env, and connects to the AIHub gateway (or
+another OpenAI-compatible base URL you set) by default. Extra providers added with
+`/provider add` live in ~/.hubble/providers.json (API keys are stored there in plain text,
+like a .env file). Each provider has its own model scan file.
+"""
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+import httpx
+
+from hubble.models import SCAN_FILE, all_models
+from hubble.provider import normalize_base_url
+from hubble.settings import HOME_DIR
+
+DEFAULT_PROVIDER = "hubble"
+# Renamed from "aihub" when this CLI was renamed to Hubble; old session files may still record it.
+LEGACY_DEFAULT_PROVIDER = "aihub"
+PROVIDERS_FILE = HOME_DIR / "providers.json"
+NAME_RX = re.compile(r"^[a-z0-9][a-z0-9_-]{0,30}$")
+
+KNOWN_EXAMPLES = [
+    ("openrouter", "https://openrouter.ai/api/v1"),
+    ("groq", "https://api.groq.com/openai/v1"),
+    ("openai", "https://api.openai.com/v1"),
+    ("mistral", "https://api.mistral.ai/v1"),
+    ("gemini", "https://generativelanguage.googleapis.com/v1beta/openai"),
+    ("ollama", "http://localhost:11434/v1"),
+]
+
+
+@dataclass
+class ProviderConfig:
+    name: str
+    base_url: str
+    api_key: str
+    check_models: bool = True  # probe each model for availability (costs one tiny request per model)
+
+
+def _read_file() -> Dict[str, Any]:
+    try:
+        data = json.loads(PROVIDERS_FILE.read_text(encoding="utf-8"))
+        return data if isinstance(data, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def _write_file(data: Dict[str, Any]):
+    HOME_DIR.mkdir(parents=True, exist_ok=True)
+    tmp = PROVIDERS_FILE.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    tmp.replace(PROVIDERS_FILE)
+
+
+def load_providers(settings: Dict[str, Any]) -> Dict[str, ProviderConfig]:
+    out: Dict[str, ProviderConfig] = {}
+    if settings.get("api_key"):
+        out[DEFAULT_PROVIDER] = ProviderConfig(DEFAULT_PROVIDER, normalize_base_url(settings["base_url"]),
+                                               settings["api_key"], True)
+    for name, entry in _read_file().items():
+        if isinstance(entry, dict) and entry.get("base_url") and entry.get("api_key"):
+            out[name] = ProviderConfig(name, normalize_base_url(entry["base_url"]), entry["api_key"],
+                                       bool(entry.get("check_models", True)))
+    return out
+
+
+def save_provider(cfg: ProviderConfig):
+    data = _read_file()
+    data[cfg.name] = {"base_url": cfg.base_url, "api_key": cfg.api_key, "check_models": cfg.check_models}
+    _write_file(data)
+
+
+def remove_provider(name: str) -> bool:
+    data = _read_file()
+    if name not in data:
+        return False
+    del data[name]
+    _write_file(data)
+    path = scan_file(name)
+    if path.exists():
+        path.unlink()
+    return True
+
+
+def scan_file(name: str) -> Path:
+    return SCAN_FILE if name == DEFAULT_PROVIDER else HOME_DIR / "models" / f"{name}.json"
+
+
+def verify(base_url: str, api_key: str, timeout: float = 20.0) -> Tuple[bool, str, List[str]]:
+    """Check the endpoint and key by listing models. Returns (ok, message, model_ids)."""
+    headers = {"Authorization": f"Bearer {api_key}"}
+    try:
+        resp = httpx.get(f"{base_url}/models", headers=headers, timeout=timeout)
+    except httpx.HTTPError as e:
+        return False, f"could not connect: {type(e).__name__}: {e}"[:200], []
+    if resp.status_code in (401, 403):
+        return False, f"the API key was rejected (HTTP {resp.status_code})", []
+    if resp.status_code == 404:
+        return False, (f"no /models endpoint at {base_url} (HTTP 404). Check the base URL; "
+                       "it usually ends in /v1"), []
+    if resp.status_code != 200:
+        body = resp.text.strip()
+        detail = "" if body.startswith("<") else f": {body[:150]}"
+        return False, f"HTTP {resp.status_code} from {base_url}/models{detail}", []
+    try:
+        data = resp.json()
+    except ValueError:
+        return False, f"{base_url}/models did not return JSON; is this an OpenAI-compatible base URL?", []
+    entries = data.get("data", data) if isinstance(data, dict) else data
+    ids = [m["id"] for m in entries if isinstance(m, dict) and m.get("id")] if isinstance(entries, list) else []
+    if not ids:
+        return False, "connected, but the provider listed no models", []
+    return True, f"connected, {len(ids)} models listed", ids
+
+
+def save_listing(name: str, base_url: str, ids: List[str]):
+    """Record the model list without probing, so the picker can show models right away."""
+    path = scan_file(name)
+    existing: Dict[str, Any] = {}
+    try:
+        existing = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        pass
+    existing.update({"base_url": base_url, "all_ids": ids})
+    existing.setdefault("working_models", [])
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(existing, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+def provider_models(name: str) -> List[Dict[str, Any]]:
+    """Model entries for one provider: model, category, latency_ms, available (None = not checked)."""
+    if name == DEFAULT_PROVIDER:
+        return all_models()
+    try:
+        data = json.loads(scan_file(name).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return []
+    working = {m["model"]: m for m in data.get("working_models", []) if m.get("model")}
+    checked = {r["model"] for r in data.get("all_results", []) if r.get("model")}
+    out = [{"model": m, "category": "Available", "latency_ms": w.get("latency_ms"), "available": True}
+           for m, w in working.items()]
+    for m in data.get("all_ids", []):
+        if m not in working:
+            out.append({"model": m, "category": "Unavailable" if m in checked else "Not checked",
+                        "latency_ms": None, "available": False if m in checked else None})
+    return out
+
+
+def resolve_fallback(settings: Dict[str, Any], providers: Dict[str, "ProviderConfig"], provider: str,
+                     model: str) -> Optional[Tuple[str, str]]:
+    """Pick (provider, model) to retry with when `model` on `provider` is rate limited or down.
+
+    Order: a fallback set for this provider (/fallback), then fallback_model if this provider
+    has it, then the fastest verified model on the same provider, then fallback_model on the
+    built-in hubble provider. Returns None when fallback is off or nothing suitable exists.
+    """
+    per_provider = (settings.get("fallback_models") or {}).get(provider)
+    if per_provider == "off":
+        return None
+    if per_provider and per_provider != model:
+        return provider, per_provider
+    default = settings.get("fallback_model")
+    if not default and not per_provider:
+        return None
+    known = provider_models(provider)
+    names = {m["model"] for m in known if m.get("available") is not False}
+    if default and default != model and default in names:
+        return provider, default
+    verified = sorted((m for m in known if m.get("available") and m["model"] != model and m.get("latency_ms")),
+                      key=lambda m: m["latency_ms"])
+    if verified:
+        return provider, verified[0]["model"]
+    if default and provider != DEFAULT_PROVIDER and DEFAULT_PROVIDER in providers:
+        if default in {m["model"] for m in provider_models(DEFAULT_PROVIDER) if m.get("available") is not False}:
+            return DEFAULT_PROVIDER, default
+    return None
+
+
+def normalize_provider_name(name: Optional[str]) -> str:
+    """Map a possibly-legacy provider slug from an old session file to the current one."""
+    return DEFAULT_PROVIDER if not name or name == LEGACY_DEFAULT_PROVIDER else name