hexcli 2.8.0__py3-none-any.whl

hexcli/distribution.py

@@ -0,0 +1,237 @@
+"""hexcli.distribution — Self-update and uninstall helpers for Hex CLI.
+
+Called from hexcli.agent via --update and --uninstall flags.
+All logic is stdlib only.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+# The npurun binary comes from the fork's own releases, not Hex CLI's.
+_GITHUB_API = "https://api.github.com/repos/NathanL15/npurun/releases/latest"
+_NPURUN_ASSET = "npurun-arm64.exe"
+_SHORTCUT_NAME = "Hex CLI.lnk"
+_START_MENU = Path.home() / "AppData" / "Roaming" / "Microsoft" / "Windows" / "Start Menu" / "Programs"
+# The Windows Terminal profile install.ps1 registers (a fragment, so it never
+# edits the user's settings.json). Removed on uninstall.
+_WT_FRAGMENT = Path.home() / "AppData" / "Local" / "Microsoft" / "Windows Terminal" / "Fragments" / "Hex CLI" / "hexcli.json"
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _print(msg: str) -> None:
+    print(f"  {msg}", flush=True)
+
+
+def _fetch_latest_release() -> dict[str, Any]:
+    req = urllib.request.Request(
+        _GITHUB_API,
+        headers={"Accept": "application/vnd.github+json", "User-Agent": "hexcli"},
+    )
+    with urllib.request.urlopen(req, timeout=15) as resp:
+        return json.loads(resp.read().decode())
+
+
+def _find_asset_url(release: dict[str, Any], asset_name: str) -> str | None:
+    for asset in release.get("assets", []):
+        if asset.get("name") == asset_name:
+            return str(asset["browser_download_url"])
+    return None
+
+
+def _download(url: str, dest: Path) -> None:
+    req = urllib.request.Request(url, headers={"User-Agent": "hexcli"})
+    with urllib.request.urlopen(req, timeout=120) as resp, dest.open("wb") as fh:
+        shutil.copyfileobj(resp, fh)
+
+
+def _launcher():
+    try:
+        from . import launcher
+        return launcher
+    except Exception:
+        return None
+
+
+def _parse_version(tag: str) -> tuple[int, ...]:
+    import re
+    m = re.search(r"(\d+)\.(\d+)\.(\d+)", tag or "")
+    return tuple(int(x) for x in m.groups()) if m else ()
+
+
+def _git_pull(install_dir: Path) -> bool:
+    """Return True if git pull succeeds, False on any failure."""
+    git = shutil.which("git")
+    if not git:
+        _print("git not found; source update skipped.")
+        return False
+    try:
+        result = subprocess.run(
+            [git, "pull", "--ff-only"],
+            cwd=str(install_dir),
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+    except subprocess.TimeoutExpired:
+        _print("git pull timed out; source update skipped.")
+        return False
+    if result.returncode == 0:
+        _print(result.stdout.strip() or "Already up to date.")
+        return True
+    _print(f"git pull failed: {result.stderr.strip()}")
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Public entry points
+# ---------------------------------------------------------------------------
+
+def update(install_dir: Path | None = None) -> int:
+    """Pull the latest source and refresh the npurun binary.
+
+    Returns an exit code (0 = success, 1 = partial failure, 2 = hard failure).
+    """
+    from . import paths
+    print("\n  Hex CLI update\n")
+
+    # 1. Update the Python source: git in a checkout, pip for an installed package.
+    install_dir = install_dir or paths.CHECKOUT_DIR
+    if install_dir is not None and (install_dir / ".git").exists():
+        _print("Pulling source...")
+        _git_pull(install_dir)
+    else:
+        _print("Installed as a package; update the code with:\n"
+               "    pip install --upgrade git+https://github.com/NathanL15/Hex-CLI")
+
+    # 2. Fetch the fork's latest release metadata from GitHub.
+    _print("Checking the latest npurun release...")
+    try:
+        release = _fetch_latest_release()
+    except Exception as exc:
+        _print(f"GitHub API error: {exc}")
+        _print("Source updated. npurun not checked: no network.")
+        return 1
+
+    tag = release.get("tag_name", "unknown")
+    _print(f"Latest npurun: {tag}")
+
+    # Nothing to do when the binary the launcher will run is already there.
+    ln = _launcher()
+    if ln is not None:
+        have = ln.find_npurun_exe()
+        have_version = ln._npurun_version(have) if have else ()
+        want = _parse_version(tag)
+        if have_version and want and tuple(have_version) >= want:
+            _print(f"npurun {ln.version_str(have_version)} at {have} is current.")
+            return 0
+
+    # 3. Download the npurun binary if a matching asset exists.
+    url = _find_asset_url(release, _NPURUN_ASSET)
+    if not url:
+        _print(f"{tag} has no {_NPURUN_ASSET} asset; binary update skipped.")
+        return 0
+
+    bin_dir = paths.npurun_bin_dir()
+    bin_dir.mkdir(parents=True, exist_ok=True)
+    existing = bin_dir / _NPURUN_ASSET
+    dest_tmp = bin_dir / f"{_NPURUN_ASSET}.tmp"
+    _print(f"Downloading {_NPURUN_ASSET}...")
+    try:
+        _download(url, dest_tmp)
+        dest_tmp.replace(existing)
+    except Exception as exc:
+        dest_tmp.unlink(missing_ok=True)
+        _print(f"Download failed: {exc}")
+        return 1
+
+    _print(f"npurun updated: {existing}")
+    _print("Update complete.")
+    return 0
+
+
+def uninstall(install_dir: Path | None = None) -> int:
+    """Remove the Start Menu shortcut and optionally purge user data."""
+    from . import paths
+    print("\n  Hex CLI uninstall\n")
+
+    # 1. Remove Start Menu shortcut.
+    shortcut = _START_MENU / _SHORTCUT_NAME
+    if shortcut.exists():
+        try:
+            shortcut.unlink()
+            _print(f"Removed shortcut: {shortcut}")
+        except OSError as exc:
+            _print(f"Could not remove shortcut: {exc}")
+    else:
+        _print("Start Menu shortcut not found.")
+    if _WT_FRAGMENT.exists():
+        try:
+            _WT_FRAGMENT.unlink()
+            try:
+                _WT_FRAGMENT.parent.rmdir()   # the fragment folder, if nothing else is in it
+            except OSError:
+                pass
+            _print("Removed Windows Terminal profile: Hex CLI")
+        except OSError as exc:
+            _print(f"Could not remove the Windows Terminal profile: {exc}")
+
+    # 2. Ask whether to purge per-user data (~/.shellai: sessions, memory,
+    #    chat logs, the runtime config, the embedding model).
+    shellai_dir = paths.data_dir(create=False)
+    if shellai_dir.exists():
+        try:
+            answer = input(
+                f"\n  Remove {shellai_dir} with its sessions and memory? [y/N] "
+            ).strip().lower()
+        except (EOFError, KeyboardInterrupt):
+            answer = "n"
+        if answer in ("y", "yes"):
+            try:
+                shutil.rmtree(shellai_dir)
+                _print(f"Removed: {shellai_dir}")
+            except OSError as exc:
+                _print(f"Could not remove {shellai_dir}: {exc}")
+        else:
+            _print(f"{shellai_dir} kept.")
+
+    # 3. The code itself.
+    checkout = install_dir or paths.CHECKOUT_DIR
+    _print("\nTo complete uninstall:  pip uninstall hexcli")
+    if checkout is not None:
+        _print(f"and delete the checkout:  Remove-Item -Recurse \"{checkout}\"")
+
+    return 0
+
+
+def first_run_check(install_dir: Path | None = None) -> None:
+    """Print first-run setup hints when critical dependencies are missing.
+
+    Runs once per process on every `hexcli` invocation, but prints nothing
+    when everything looks healthy — zero noise for existing installs.
+    """
+    from . import paths
+    hints: list[str] = []
+
+    # npurun: the launcher's own search (source build, downloaded binary, PATH).
+    ln = _launcher()
+    found = ln.find_npurun_exe() if ln is not None else None
+    if found is None and not (shutil.which("npurun") or shutil.which("npurun.exe")):
+        hints.append("  npurun not found. Run:  hexcli --update")
+
+    # ONNX embedding model for memory.
+    if not paths.embedding_model_path().exists():
+        hints.append("  Embedding model missing; memory is off. hexcli --doctor prints the download commands.")
+
+    if hints:
+        print("\n  First-run setup", flush=True)
+        for h in hints:
+            print(h, flush=True)
+        print(flush=True)

hexcli/doctor.py

@@ -0,0 +1,265 @@
+#!/usr/bin/env python3
+"""hexcli.doctor — diagnose an installation and say exactly how to fix it.
+
+The QAIRT SDK cannot be redistributed and the NPU bundles are multi-GB, so
+this project can never be a one-click install. The honest response is to
+diagnose perfectly: every check prints PASS/WARN/FAIL plus the exact command
+that fixes it.
+
+This exists because of a real failure: the ONNX embedding model was never
+installed on the development machine, so semantic memory silently no-opped
+for months (docs/V2_PLAN.md §14.1). `first_run_check` printed a hint that
+scrolled past. Checks that only whisper are checks that don't work.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .ui import C, cprint
+
+PASS, WARN, FAIL = "PASS", "WARN", "FAIL"
+_NPURUN_RELEASES = "https://github.com/NathanL15/npurun/releases"
+
+
+@dataclass
+class Check:
+    name: str
+    status: str
+    detail: str
+    fix: str = ""
+
+
+def _mark(status: str) -> str:
+    return {
+        PASS: f"{C.BGREEN}  ok  {C.RESET}",
+        WARN: f"{C.BYELLOW} warn {C.RESET}",
+        FAIL: f"{C.BRED} fail {C.RESET}",
+    }[status]
+
+
+def check_python() -> Check:
+    v = sys.version_info
+    if v < (3, 10):
+        return Check("Python", FAIL, f"{v.major}.{v.minor}; 3.10 or newer required",
+                     "Install the ARM64 build of Python 3.11 or newer from python.org.")
+    return Check("Python", PASS, f"{v.major}.{v.minor}.{v.micro} ({sys.executable})")
+
+
+def check_packages() -> list[Check]:
+    out: list[Check] = []
+    for mod, why, fix in (
+        ("numpy", "vector math for memory", "pip install numpy"),
+        ("onnxruntime", "embedding model runtime", "pip install onnxruntime"),
+    ):
+        try:
+            __import__(mod)
+            out.append(Check(mod, PASS, "importable"))
+        except ImportError:
+            out.append(Check(mod, WARN, f"missing; {why} off", fix))
+    return out
+
+
+def check_embedding_model(app_dir: Path | None = None) -> list[Check]:
+    """The silent-failure case that motivated this whole command."""
+    from . import paths
+    if app_dir is not None:   # an explicit location (tests, a custom layout)
+        model = app_dir / "onnx" / paths.EMBEDDING_MODEL_FILE
+        tok = app_dir / "onnx" / paths.EMBEDDING_TOKENIZER_FILE
+        dest = app_dir / "onnx"
+    else:
+        model = paths.embedding_model_path()
+        tok = paths.embedding_tokenizer_path()
+        dest = paths.embedding_dir(for_download=True)
+    fix = (
+        f"Download both into {dest} :\n"
+        f"      curl -L -o \"{dest / paths.EMBEDDING_MODEL_FILE}\" "
+        f"{paths.EMBEDDING_BASE_URL}/onnx/{paths.EMBEDDING_MODEL_FILE}\n"
+        f"      curl -L -o \"{dest / paths.EMBEDDING_TOKENIZER_FILE}\" "
+        f"{paths.EMBEDDING_BASE_URL}/{paths.EMBEDDING_TOKENIZER_FILE}"
+    )
+    checks = []
+    if model.exists() and model.stat().st_size > 1_000_000:
+        checks.append(Check("embedding model", PASS, f"{model.stat().st_size // 1_000_000} MB"))
+    else:
+        checks.append(Check("embedding model", WARN, "missing; memory is off", fix))
+    if tok.exists():
+        checks.append(Check("embedding tokenizer", PASS, "present"))
+    else:
+        checks.append(Check("embedding tokenizer", WARN, "missing; memory is off", fix))
+    return checks
+
+
+def _launcher():
+    try:
+        from . import launcher
+        return launcher
+    except Exception:
+        return None
+
+
+def check_qairt() -> list[Check]:
+    sdk = Path(os.environ.get("QNN_SDK_ROOT", r"C:\Qualcomm\AIStack\QAIRT_2.47.0"))
+    ln = _launcher()
+    if ln is not None:
+        sdk = ln.QNN_SDK_ROOT   # what the launcher actually exports (newest valid; Rewind SDK first)
+    checks: list[Check] = []
+    if not sdk.exists():
+        checks.append(Check("QAIRT SDK", FAIL, f"not found at {sdk}",
+                            "Download it from the Qualcomm developer portal and set QNN_SDK_ROOT."))
+        return checks
+    checks.append(Check("QAIRT SDK", PASS, str(sdk)))
+    lib = sdk / "lib" / "aarch64-windows-msvc"
+    checks.append(Check("QAIRT libs", PASS if lib.exists() else FAIL,
+                        str(lib) if lib.exists() else "missing aarch64-windows-msvc libs",
+                        "" if lib.exists() else "Re-run the QAIRT installer."))
+    adsp = Path(os.environ.get("ADSP_LIBRARY_PATH", ""))
+    wanted = sdk / "lib" / "hexagon-v73" / "unsigned"
+    if not adsp.exists():
+        checks.append(Check("ADSP_LIBRARY_PATH", WARN,
+                            "unset; npurun crashes without it",
+                            rf'setx ADSP_LIBRARY_PATH "{wanted}"'))
+    elif adsp.resolve() != wanted.resolve() and wanted.exists():
+        # Pinned to another SDK's libs (a setx from before 2.50 was installed).
+        # The launcher sets the right value for the server it starts; a
+        # server started by hand would use this one.
+        checks.append(Check("ADSP_LIBRARY_PATH", WARN,
+                            f"{adsp} is not the {sdk.name} SDK's; the launcher overrides it",
+                            rf'setx ADSP_LIBRARY_PATH "{wanted}"'))
+    else:
+        checks.append(Check("ADSP_LIBRARY_PATH", PASS, str(adsp)))
+    return checks
+
+
+def check_npurun() -> list[Check]:
+    ln = _launcher()
+    # The launcher's candidate order, so the doctor diagnoses the binary
+    # that will actually run.
+    path = ln.find_npurun_exe() if ln is not None else None
+    if path is None:
+        exe = shutil.which("npurun") or shutil.which("npurun.exe")
+        local = Path.home() / ".cargo" / "bin" / "npurun.exe"
+        path = Path(exe) if exe else (local if local.exists() else None)
+    if path is None:
+        return [Check("npurun", FAIL, "binary not found",
+                      f"hexcli --update\n{_NPURUN_RELEASES}")]
+    checks = [Check("npurun", PASS, str(path))]
+    if ln is not None:
+        version = ln._npurun_version(path)
+        ver = ".".join(str(n) for n in version) or "unknown"
+        need = ".".join(str(n) for n in ln.REQUIRED_NPURUN)
+        if ln.npurun_outdated(version=version) is not None:
+            checks.append(Check("npurun version", FAIL,
+                                f"{ver}; {need} required",
+                                "hexcli --update"))
+        else:
+            checks.append(Check("npurun version", PASS, ver))
+        if ln.REWIND_ROOT is not None:
+            checks.append(Check("KV prefix reuse", PASS,
+                                f"on: npurun {ver}, {ln.REWIND_ROOT.name}"))
+        else:
+            checks.append(Check("KV prefix reuse", WARN,
+                                f"off: npurun {ver}, {ln.QNN_SDK_ROOT.name}",
+                                r"Install QAIRT 2.50 or newer under C:\Qualcomm\AIStack."))
+    try:
+        r = subprocess.run([str(path), "list"], capture_output=True, text=True, timeout=20)
+        models = [ln.split()[0] for ln in r.stdout.splitlines() if ln.strip()]
+        if models:
+            checks.append(Check("model bundles", PASS, ", ".join(models)))
+        else:
+            checks.append(Check("model bundles", FAIL, "none downloaded",
+                                "npurun pull qwen3-4b-instruct-2507"))
+    except Exception as exc:
+        checks.append(Check("model bundles", WARN, f"could not list: {exc.__class__.__name__}"))
+    return checks
+
+
+def check_server(config: dict[str, Any]) -> Check:
+    base = str(config.get("openai_compatible", {}).get("base_url", ""))
+    ln = _launcher()
+    if ln is not None and "_npurun_model" not in config:
+        # Run outside the launcher (the installer, a bare --doctor): the server
+        # that matters is the one the launcher starts, on its port, not the
+        # example config's.
+        base = f"http://127.0.0.1:{ln.NPURUN_PORT}"
+    if not base:
+        return Check("model server", WARN, "no openai_compatible.base_url configured")
+    host = base.split("//")[-1].split("/")[0]
+    try:
+        with urllib.request.urlopen(f"http://{host}/healthz", timeout=3) as r:
+            if r.status == 200:
+                detail = f"healthy at {host}"
+                try:
+                    with urllib.request.urlopen(f"http://{host}/v1/models", timeout=3) as m:
+                        models = json.loads(m.read().decode("utf-8")).get("data") or []
+                    first = models[0] if models else {}
+                    if first.get("input_token_budget"):
+                        detail += (f"; input budget {first['input_token_budget']} of "
+                                   f"{first.get('context_size', '?')} tokens")
+                except Exception:
+                    pass
+                return Check("model server", PASS, detail)
+    except Exception:
+        pass
+    return Check("model server", WARN, f"not responding at {host}",
+                 "Launch Hex CLI, or run python launcher.py from the repo.")
+
+
+def check_ruff() -> Check:
+    if shutil.which("ruff"):
+        return Check("ruff (optional)", PASS, "on PATH")
+    return Check("ruff (optional)", WARN, "not found; lint_code is off",
+                 "pip install ruff")
+
+
+def check_workspace() -> list[Check]:
+    cwd = Path.cwd()
+    checks = [Check("working directory", PASS, str(cwd))]
+    for name in ("AGENTS.md", ".shellai/AGENTS.md", "HEXCLI.md"):
+        if (cwd / name).is_file():
+            checks.append(Check("project instructions", PASS, f"{name} found"))
+            break
+    else:
+        checks.append(Check("project instructions", WARN,
+                            "no AGENTS.md",
+                            "Create AGENTS.md with a few lines about this project."))
+    return checks
+
+
+def run_doctor(config: dict[str, Any], app_dir: Path | None = None) -> int:
+    """Print the full report. Returns 1 if any check FAILed."""
+    checks: list[Check] = [check_python()]
+    checks += check_packages()
+    checks += check_embedding_model()
+    checks += check_qairt()
+    checks += check_npurun()
+    checks.append(check_server(config))
+    checks.append(check_ruff())
+    checks += check_workspace()
+
+    print()
+    cprint("  Install check", C.BOLD)
+    print()
+    for c in checks:
+        print(f"  {_mark(c.status)}  {c.name:<22} {c.detail}")
+        if c.fix and c.status != PASS:
+            for line in c.fix.splitlines():
+                cprint(f"            {line}", C.DIM)
+    fails = sum(1 for c in checks if c.status == FAIL)
+    warns = sum(1 for c in checks if c.status == WARN)
+    print()
+    if fails:
+        cprint(f"  {fails} failed, {warns} warnings.", C.BRED)
+    elif warns:
+        cprint(f"  {warns} warnings.", C.BYELLOW)
+    else:
+        cprint("  All checks passed.", C.BGREEN)
+    print()
+    return 1 if fails else 0

hexcli/escalate.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""hexcli.escalate — Cloud escalation for stuck agent turns.
+
+Triggered by error-loop detection. Sends the last 6 turns and the
+failing tool sequence to Anthropic's API after a redaction pass.
+
+Transport: stdlib urllib.request — no SDK dependency.
+Key source: ANTHROPIC_API_KEY env var, then config["anthropic_api_key"].
+Default model: claude-haiku-4-5-20251001 (override via config["escalation_model"]).
+"""
+from __future__ import annotations
+
+import copy
+import json
+import os
+import re
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+_API_URL = "https://api.anthropic.com/v1/messages"
+_ANTHROPIC_VERSION = "2023-06-01"
+DEFAULT_ESCALATION_MODEL = "claude-haiku-4-5-20251001"
+_MAX_FILE_CONTENT = 200  # chars — truncate long strings before sending
+
+# ---------------------------------------------------------------------------
+# Sensitive path prefixes — content following these in payload text is redacted.
+# ---------------------------------------------------------------------------
+
+_SENSITIVE_PATH_PREFIXES: list[str] = [
+    str(Path.home() / ".ssh"),
+    str(Path.home() / ".aws"),
+    str(Path.home() / ".gnupg"),
+    str(Path.home() / ".gpg"),
+    # Generic tilde forms so tests can use them directly.
+    "~/.ssh",
+    "~/.aws",
+    "~/.gnupg",
+    "~/.gpg",
+]
+
+# ---------------------------------------------------------------------------
+# Redaction patterns: (compiled_pattern, replacement) applied in order.
+# ---------------------------------------------------------------------------
+
+_REDACT_PATTERNS: list[tuple[re.Pattern[str], str]] = [
+    # Anthropic / OpenAI API keys
+    (re.compile(r"sk-[A-Za-z0-9\-_]{10,}"), "sk-***"),
+    # Generic Bearer tokens
+    (re.compile(r"Bearer\s+[A-Za-z0-9._\-]{8,}"), "Bearer ***"),
+    # password= in query strings / config
+    (re.compile(r"password=[^\s&'\"\r\n<>]{1,200}", re.IGNORECASE), "password=***"),
+    # api_key= and api-key=
+    (re.compile(r"api[_\-]key=[^\s&'\"\r\n<>]{1,200}", re.IGNORECASE), "api_key=***"),
+    # token= (word-boundary to avoid "multipart" style false positives)
+    (re.compile(r"\btoken=[^\s&'\"\r\n<>]{1,200}", re.IGNORECASE), "token=***"),
+    # Connection strings
+    (
+        re.compile(
+            r"(postgresql|postgres|mongodb|mysql|redis|amqp|rabbitmq)://[^\s'\"\r\n<>{}[\]]{1,300}",
+            re.IGNORECASE,
+        ),
+        r"\1://***",
+    ),
+]
+
+
+def redact_text(text: str) -> str:
+    """Apply all redaction rules to a string, in-place (returns new string)."""
+    # Sensitive path content: if a sensitive path prefix appears, redact the
+    # following _MAX_FILE_CONTENT chars (which is likely file content).
+    for prefix in _SENSITIVE_PATH_PREFIXES:
+        idx = text.lower().find(prefix.lower())
+        while idx != -1:
+            end = min(idx + len(prefix) + _MAX_FILE_CONTENT, len(text))
+            text = text[:idx] + "[REDACTED:sensitive-path]" + text[end:]
+            idx = text.lower().find(prefix.lower())
+
+    for pattern, replacement in _REDACT_PATTERNS:
+        text = pattern.sub(replacement, text)
+    return text
+
+
+def _redact_value(v: Any) -> Any:
+    """Recursively redact strings in a JSON-like structure."""
+    if isinstance(v, str):
+        if len(v) > _MAX_FILE_CONTENT * 2:
+            v = v[: _MAX_FILE_CONTENT] + "...[truncated]"
+        return redact_text(v)
+    if isinstance(v, dict):
+        return {k: _redact_value(val) for k, val in v.items()}
+    if isinstance(v, list):
+        return [_redact_value(item) for item in v]
+    return v
+
+
+def redact_payload(turns: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Deep-copy and redact all strings in a list of message dicts."""
+    return [_redact_value(copy.deepcopy(t)) for t in turns]
+
+
+# ---------------------------------------------------------------------------
+# API key resolution
+# ---------------------------------------------------------------------------
+
+def get_api_key(config: dict[str, Any]) -> str | None:
+    """Return the Anthropic API key from env or config; None if absent."""
+    key = os.environ.get("ANTHROPIC_API_KEY", "").strip()
+    if not key:
+        key = str(config.get("anthropic_api_key", "") or "").strip()
+    return key or None
+
+
+# ---------------------------------------------------------------------------
+# Transport
+# ---------------------------------------------------------------------------
+
+def _call_api(api_key: str, model: str, messages: list[dict[str, Any]]) -> str:
+    payload = json.dumps({
+        "model": model,
+        "max_tokens": 1024,
+        "messages": messages,
+    }).encode()
+    req = urllib.request.Request(
+        _API_URL,
+        data=payload,
+        headers={
+            "Content-Type": "application/json",
+            "x-api-key": api_key,
+            "anthropic-version": _ANTHROPIC_VERSION,
+        },
+    )
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        data = json.loads(resp.read().decode())
+    content = data.get("content", [])
+    if content and isinstance(content[0], dict):
+        return str(content[0].get("text", "")).strip()
+    return str(data)
+
+
+# ---------------------------------------------------------------------------
+# Main escalation entry point
+# ---------------------------------------------------------------------------
+
+def escalate(
+    config: dict[str, Any],
+    turns: list[dict[str, Any]],
+    tool_seq: list[str],
+) -> str:
+    """Send redacted context to Claude cloud and return the suggestion.
+
+    Returns a user-visible message — either the LLM's suggestion or an
+    explanation of why escalation is unavailable.
+    """
+    api_key = get_api_key(config)
+    if not api_key:
+        return "(set ANTHROPIC_API_KEY to enable cloud escalation)"
+
+    model = str(config.get("escalation_model", DEFAULT_ESCALATION_MODEL)).strip()
+
+    # Build the escalation prompt.
+    parts: list[str] = [
+        "The local agent is stuck in a repeated error loop.\n",
+    ]
+    if tool_seq:
+        parts.append(f"Failing tool sequence: {', '.join(tool_seq)}\n")
+    if turns:
+        parts.append("\nLast session turns:\n")
+        for t in turns[-6:]:
+            role = t.get("role", "?")
+            content = str(t.get("content", ""))[:500]
+            parts.append(f"[{role}]: {content}\n")
+    parts.append(
+        "\nPlease provide a concise suggestion on how to resolve this loop "
+        "and unblock the agent."
+    )
+
+    prompt = redact_text("".join(parts))
+    messages = [{"role": "user", "content": prompt}]
+
+    try:
+        return _call_api(api_key, model, messages)
+    except urllib.error.HTTPError as exc:
+        body = ""
+        try:
+            body = exc.read().decode()[:200]
+        except Exception:
+            pass
+        return f"Cloud escalation failed (HTTP {exc.code}): {body}"
+    except Exception as exc:
+        return f"Cloud escalation failed: {exc}"