superresearch-agent 0.1.0__py3-none-any.whl

facade/__init__.py

@@ -0,0 +1,19 @@
+"""research-facade — the Super Agent bridge.
+
+A standalone, account-authed client on Super Research's normal Firestore
+plane. It lets a chat runtime (Hermes / OpenClaw) drive Super Research as a
+*headless session of the user's account*: the user signs in once with Google
+(`/login`), and the bridge then enqueues research runs on the account's
+existing devices. Runs surface in the web app as normal chats.
+
+Hard boundaries (the "nothing breaks" contract):
+  * This package NEVER imports or mutates research-automate or research-app.
+  * It uses its OWN secret store namespace ("super-agent"), never the device
+    daemon's keystore ("super-research") — so refresh-token rotation here can
+    never disturb a paired device.
+  * It writes only what a normal account client may write (research docs +
+    device-queue start docs), all gated by the existing Firestore rules.
+  * Research-only: it can never control devices (add/remove/pair/share).
+"""
+
+__version__ = "0.0.1"

facade/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

facade/autostart.py

@@ -0,0 +1,375 @@
+"""Keep the host bridge up across logon — the engine behind `agent resurrect` /
+`agent retire`. Cross-platform, one install/uninstall/status/start_detached API
+dispatched by OS:
+
+  • Windows — a **Scheduled Task** (`SuperAgentBridge`) that launches the bridge
+    WINDOWLESS (pythonw.exe) at logon. The proven, shipping path.
+  • Linux   — a **systemd --user** service (`super-agent-bridge.service`).
+  • macOS   — a **launchd LaunchAgent** (`io.superresearch.agent-bridge`).
+
+All three launch the SAME tiny generated launcher (~/.super-agent/bridge_launcher.py)
+which puts the agent package on sys.path and calls the `serve` entry point, so the
+bridge resumes cleanly after a reboot (the account session + device selection persist
+in keyring + prefs).
+
+The per-OS argv / unit / plist are built by pure functions (unit-testable); only
+install / uninstall / status / start_detached shell out.
+
+NOTE: the Windows path is the validated one. The Linux (systemd) and macOS (launchd)
+paths are unit-tested at the generation + dispatch level but have NOT yet been
+validated end-to-end on a live Linux/macOS host.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+from . import config
+
+TASK_NAME = "SuperAgentBridge"                    # Windows Scheduled Task name
+SYSTEMD_UNIT = "super-agent-bridge.service"       # Linux systemd --user unit
+LAUNCHD_LABEL = "io.superresearch.agent-bridge"   # macOS launchd LaunchAgent label
+
+
+# ── platform ───────────────────────────────────────────────────────────────────
+
+def is_windows() -> bool:
+    return sys.platform.startswith("win")
+
+
+def is_macos() -> bool:
+    return sys.platform == "darwin"
+
+
+def is_linux() -> bool:
+    return sys.platform.startswith("linux")
+
+
+def platform_label() -> str:
+    if is_windows():
+        return "Windows"
+    if is_macos():
+        return "macOS"
+    if is_linux():
+        return "Linux"
+    return sys.platform
+
+
+# ── shared launcher (every OS runs this) ─────────────────────────────────────
+
+def agent_dir() -> Path:
+    """The dir that contains the ``facade`` package (so ``import facade`` works
+    even when the service launches with a cwd like C:\\Windows\\System32 or /)."""
+    return Path(__file__).resolve().parent.parent
+
+
+def pythonw_exe() -> str:
+    """No-console interpreter (pythonw.exe) sibling of the current interpreter on
+    Windows; sys.executable elsewhere (POSIX has no windowless variant — the
+    service manager detaches it)."""
+    cur = Path(sys.executable)
+    if cur.name.lower() == "python.exe":
+        sib = cur.parent / "pythonw.exe"
+        if sib.exists():
+            return str(sib)
+    return str(cur)
+
+
+def launcher_path() -> Path:
+    """The generated launcher script the service / detached start run."""
+    return config.store_dir() / "bridge_launcher.py"
+
+
+def launcher_source(agentdir: Path | None = None) -> str:
+    """Python source for the launcher: inject the agent dir on sys.path, then call
+    the `serve` entry point. ``repr`` quotes the path safely (handles Windows
+    backslashes), so there are no schtasks-quoting hazards."""
+    d = str(agentdir or agent_dir())
+    return (
+        "# Auto-generated by `agent resurrect` — launches the Super Agent bridge.\n"
+        "# Safe to delete; `agent retire` removes it.\n"
+        "import sys\n"
+        f"sys.path.insert(0, {d!r})\n"
+        "from facade.cli import main\n"
+        "raise SystemExit(main(['serve']))\n"
+    )
+
+
+def write_launcher(agentdir: Path | None = None) -> Path:
+    """Write (refresh) the launcher script; return its path."""
+    p = launcher_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(launcher_source(agentdir), encoding="utf-8")
+    return p
+
+
+def _rm_launcher() -> None:
+    try:
+        launcher_path().unlink(missing_ok=True)
+    except OSError:
+        pass
+
+
+def _exec(argv: list[str]) -> tuple[bool, str]:
+    no_window = getattr(subprocess, "CREATE_NO_WINDOW", 0x08000000) if is_windows() else 0
+    try:
+        proc = subprocess.run(argv, capture_output=True, text=True, encoding="utf-8",
+                              errors="replace", timeout=30, creationflags=no_window)
+    except (OSError, subprocess.SubprocessError) as e:  # pragma: no cover - env-specific
+        return False, str(e)
+    out = (proc.stdout or "") + (proc.stderr or "")
+    return proc.returncode == 0, out.strip()
+
+
+# ── Windows: Scheduled Task (validated) ──────────────────────────────────────
+
+def run_command(exe: str | None = None, launcher: Path | None = None) -> str:
+    """The /TR command line: ``"pythonw.exe" "<launcher>"`` (both quoted)."""
+    return f'"{exe or pythonw_exe()}" "{launcher or launcher_path()}"'
+
+
+def install_argv(task_name: str = TASK_NAME, command: str | None = None) -> list[str]:
+    # ONLOGON so it starts at sign-in; LIMITED run level (no elevation); /F
+    # overwrites (idempotent re-install). /IT (interactive token) is LOAD-BEARING:
+    # without it schtasks makes an S4U task whose logon token cannot decrypt the
+    # per-user DPAPI Credential Locker — keyring.get_password() returns nothing and
+    # the rehydrated bridge comes up unauthenticated after a reboot, breaking the
+    # "resumes cleanly without re-login" promise. pythonw.exe stays windowless
+    # regardless of /IT.
+    return ["schtasks", "/Create", "/TN", task_name, "/TR", command or run_command(),
+            "/SC", "ONLOGON", "/RL", "LIMITED", "/IT", "/F"]
+
+
+def uninstall_argv(task_name: str = TASK_NAME) -> list[str]:
+    return ["schtasks", "/Delete", "/TN", task_name, "/F"]
+
+
+def status_argv(task_name: str = TASK_NAME) -> list[str]:
+    return ["schtasks", "/Query", "/TN", task_name]
+
+
+def _win_start(exe: str | None = None, launcher: Path | None = None) -> tuple[bool, str]:
+    """Start the bridge NOW — windowless + detached, so it survives this process.
+    Mirrors research.py's detached daemon-loop spawn."""
+    exe = exe or pythonw_exe()
+    p = launcher or write_launcher()
+    detached = getattr(subprocess, "DETACHED_PROCESS", 0x00000008)
+    newgroup = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0x00000200)
+    no_window = getattr(subprocess, "CREATE_NO_WINDOW", 0x08000000)
+    try:
+        subprocess.Popen(
+            [exe, str(p)],
+            creationflags=detached | newgroup | no_window,
+            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+            stdin=subprocess.DEVNULL, close_fds=True,
+        )
+    except (OSError, ValueError) as e:  # pragma: no cover - env-specific
+        return False, str(e)
+    return True, ""
+
+
+# ── Linux: systemd --user service ─────────────────────────────────────────────
+
+def systemd_unit_path() -> Path:
+    return Path.home() / ".config" / "systemd" / "user" / SYSTEMD_UNIT
+
+
+def systemd_unit_source(exe: str | None = None, launcher: Path | None = None) -> str:
+    e = exe or sys.executable
+    p = str(launcher or launcher_path())
+    return (
+        "[Unit]\n"
+        "Description=Super Agent bridge (Super Research)\n"
+        "After=network-online.target\n"
+        "\n"
+        "[Service]\n"
+        "Type=simple\n"
+        f'ExecStart="{e}" "{p}"\n'  # quoted — systemd splits on spaces otherwise
+        "Restart=always\n"
+        "RestartSec=5\n"
+        "\n"
+        "[Install]\n"
+        "WantedBy=default.target\n"
+    )
+
+
+def systemctl_argv(*verbs: str) -> list[str]:
+    return ["systemctl", "--user", *verbs]
+
+
+def _write_systemd_unit() -> Path:
+    write_launcher()
+    up = systemd_unit_path()
+    up.parent.mkdir(parents=True, exist_ok=True)
+    up.write_text(systemd_unit_source(), encoding="utf-8")
+    return up
+
+
+def _linux_install() -> tuple[bool, str]:
+    _write_systemd_unit()
+    ok, out = _exec(systemctl_argv("daemon-reload"))
+    if not ok:
+        return ok, out
+    return _exec(systemctl_argv("enable", SYSTEMD_UNIT))
+
+
+def _linux_uninstall() -> tuple[bool, str]:
+    ok, out = _exec(systemctl_argv("disable", "--now", SYSTEMD_UNIT))
+    try:
+        systemd_unit_path().unlink(missing_ok=True)
+    except OSError:
+        pass
+    _rm_launcher()
+    if not ok:
+        return ok, out
+    # disable succeeded → the result that matters now is daemon-reload; surface its
+    # failure (with its own message) rather than swallowing it.
+    return _exec(systemctl_argv("daemon-reload"))
+
+
+def _linux_status() -> tuple[bool, str]:
+    return _exec(systemctl_argv("is-enabled", SYSTEMD_UNIT))
+
+
+def _linux_start() -> tuple[bool, str]:
+    return _exec(systemctl_argv("start", SYSTEMD_UNIT))
+
+
+# ── macOS: launchd LaunchAgent ───────────────────────────────────────────────
+
+def launchd_plist_path() -> Path:
+    return Path.home() / "Library" / "LaunchAgents" / f"{LAUNCHD_LABEL}.plist"
+
+
+def _xml_escape(s: str) -> str:
+    return s.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+def launchd_plist_source(exe: str | None = None, launcher: Path | None = None) -> str:
+    e = _xml_escape(exe or sys.executable)
+    p = _xml_escape(str(launcher or launcher_path()))
+    return (
+        '<?xml version="1.0" encoding="UTF-8"?>\n'
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" '
+        '"http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n'
+        '<plist version="1.0">\n'
+        '<dict>\n'
+        f'  <key>Label</key><string>{LAUNCHD_LABEL}</string>\n'
+        '  <key>ProgramArguments</key>\n'
+        '  <array>\n'
+        f'    <string>{e}</string>\n'
+        f'    <string>{p}</string>\n'
+        '  </array>\n'
+        '  <key>RunAtLoad</key><true/>\n'
+        '  <key>KeepAlive</key><true/>\n'
+        '</dict>\n'
+        '</plist>\n'
+    )
+
+
+def launchctl_argv(*verbs: str) -> list[str]:
+    return ["launchctl", *verbs]
+
+
+def _darwin_install() -> tuple[bool, str]:
+    write_launcher()
+    pl = launchd_plist_path()
+    pl.parent.mkdir(parents=True, exist_ok=True)
+    pl.write_text(launchd_plist_source(), encoding="utf-8")
+    return _exec(launchctl_argv("load", "-w", str(pl)))
+
+
+def _darwin_uninstall() -> tuple[bool, str]:
+    pl = launchd_plist_path()
+    ok, out = _exec(launchctl_argv("unload", "-w", str(pl)))
+    try:
+        pl.unlink(missing_ok=True)
+    except OSError:
+        pass
+    _rm_launcher()
+    return ok, out
+
+
+def _darwin_status() -> tuple[bool, str]:
+    return _exec(launchctl_argv("list", LAUNCHD_LABEL))
+
+
+def _darwin_start() -> tuple[bool, str]:
+    return _exec(launchctl_argv("start", LAUNCHD_LABEL))
+
+
+# ── dispatch (public API) ─────────────────────────────────────────────────────
+
+def _unsupported() -> tuple[bool, str]:
+    return (False, f"run-on-startup isn't supported on this platform ({sys.platform})")
+
+
+def supported() -> bool:
+    """Whether run-on-startup pinning is implemented for this OS."""
+    return is_windows() or is_linux() or is_macos()
+
+
+def kind_label() -> str:
+    """What the login-pin is on this OS (for user-facing copy)."""
+    if is_windows():
+        return "Scheduled Task"
+    if is_linux():
+        return "systemd --user service"
+    if is_macos():
+        return "launchd LaunchAgent"
+    return "service"
+
+
+def install(task_name: str = TASK_NAME) -> tuple[bool, str]:
+    """Pin the bridge to start on login — Windows Scheduled Task / Linux systemd
+    --user / macOS launchd. (``task_name`` only affects the Windows task name.)"""
+    if is_windows():
+        write_launcher()
+        return _exec(install_argv(task_name))
+    if is_linux():
+        return _linux_install()
+    if is_macos():
+        return _darwin_install()
+    return _unsupported()
+
+
+def uninstall(task_name: str = TASK_NAME) -> tuple[bool, str]:
+    """Remove the login pin + the generated launcher (best-effort)."""
+    if is_windows():
+        ok, out = _exec(uninstall_argv(task_name))
+        _rm_launcher()
+        return ok, out
+    if is_linux():
+        return _linux_uninstall()
+    if is_macos():
+        return _darwin_uninstall()
+    return _unsupported()
+
+
+def status(task_name: str = TASK_NAME) -> tuple[bool, str]:
+    if is_windows():
+        return _exec(status_argv(task_name))
+    if is_linux():
+        return _linux_status()
+    if is_macos():
+        return _darwin_status()
+    return _unsupported()
+
+
+def is_installed(task_name: str = TASK_NAME) -> bool:
+    """Whether the login pin currently exists (False on an unsupported OS)."""
+    return status(task_name)[0]
+
+
+def start_detached(exe: str | None = None, launcher: Path | None = None) -> tuple[bool, str]:
+    """Start the bridge NOW in the background (windowless on Windows; via the
+    service manager on Linux/macOS)."""
+    if is_windows():
+        return _win_start(exe, launcher)
+    if is_linux():
+        return _linux_start()
+    if is_macos():
+        return _darwin_start()
+    return _unsupported()

facade/branding.py

@@ -0,0 +1,275 @@
+"""Branded terminal UI for the Super Agent CLI.
+
+A self-contained mirror of the backend's `--pair` aesthetic (research.py) so the
+agent's interactive screens read as the same "Super Research" product. This
+module deliberately imports NOTHING from the app (research.py) — the facade
+stays an isolated sub-package (see test_app_plane_unchanged).
+
+Pure rendering + a tiny `input()`-based picker. No network, no side effects
+beyond stdout/stdin, so cli.py remains the only place that orchestrates I/O.
+"""
+
+from __future__ import annotations
+
+import itertools
+import os
+import shutil
+import sys
+import threading
+
+# ── Color support (tty + Windows VT enable) — mirrors research.py ───────────
+_USE_COLOR = False
+try:
+    if sys.stdout.isatty() and "NO_COLOR" not in os.environ:
+        _USE_COLOR = True
+        if sys.platform == "win32":
+            # Enable ANSI escape processing on Win10+ consoles.
+            import ctypes
+
+            try:
+                _k32 = ctypes.windll.kernel32
+                _k32.SetConsoleMode(_k32.GetStdHandle(-11), 7)
+            except Exception:
+                pass
+except Exception:
+    _USE_COLOR = False
+
+# 256-color palette matching the app's "Super Research" brand.
+_ACCENT = "\033[38;5;75m"   # bright blue — matches the wordmark
+_DIM = "\033[38;5;244m"     # muted grey — auxiliary lines
+_OK = "\033[38;5;108m"      # muted green — success marks
+_WARN = "\033[38;5;214m"    # amber — warnings
+_BRIGHT = "\033[38;5;231m"  # glowing white
+_RED = "\033[38;5;160m"     # deep red — failure marks
+_BOLD = "\033[1m"
+_RESET = "\033[0m"
+
+_SIGIL = "◆"
+MARK_OK = "✓"
+MARK_WARN = "⚠"
+MARK_NO = "✗"
+ARROW = "→"
+CARET = "›"
+
+
+def c(color: str, text: str) -> str:
+    """Wrap text in an ANSI color (no-op when color is disabled)."""
+    return f"{color}{text}{_RESET}" if _USE_COLOR else text
+
+
+def rgb(r: int, g: int, b: int) -> str:
+    """TrueColor foreground escape — used for the runtime brand marks
+    (Hermes gold, OpenClaw orange). Degrades to no color off-tty."""
+    return f"\033[38;2;{r};{g};{b}m"
+
+
+def rule(char: str = "─", color: str = _DIM, max_width: int = 62) -> str:
+    """Width-aware horizontal rule (sizes to the terminal, capped)."""
+    cols = shutil.get_terminal_size(fallback=(80, 24)).columns
+    width = max(10, min(max_width, cols - 4))
+    return c(color, char * width)
+
+
+def header(tagline: str, gloss: str, *, tagline_color: str | None = None) -> None:
+    """The shared SUPER RESEARCH banner + a ◆ tagline · gloss line, so every
+    agent subcommand wears the same crown as `--pair` / `--resurrect`."""
+    tc = tagline_color or (_BOLD + _ACCENT)
+    bar = rule("━")
+    print()
+    print(f"  {bar}")
+    print()
+    print(f"                   {c(_BOLD + _ACCENT, 'SUPER')} {c(_BOLD, 'RESEARCH')}")
+    print(
+        f"                {c(tc, _SIGIL)}  {c(tc, tagline)} "
+        f"{c(_DIM, '·')} {c(_DIM, gloss)}"
+    )
+    print()
+    print(f"  {bar}")
+
+
+def step_arc(steps: list[str]) -> None:
+    """Compact preview of the whole step sequence (like --pair's 'Five steps')."""
+    parts = []
+    for i, name in enumerate(steps, 1):
+        parts.append(f"{c(_ACCENT, str(i))} {name}")
+    print()
+    print(f"  {c(_DIM, 'Steps:')}   " + f"   {c(_DIM, ARROW)}   ".join(parts))
+
+
+def step(n: int, total: int, title: str) -> None:
+    """Section header for one step inside a subcommand."""
+    print()
+    print(f"  {c(_ACCENT + _BOLD, f'[{n}/{total}]')} {c(_BOLD, title)}")
+    print(f"  {rule(max_width=58)}")
+
+
+def ok(msg: str) -> None:
+    print(f"  {c(_OK, MARK_OK)}  {msg}")
+
+
+def warn(msg: str) -> None:
+    print(f"  {c(_WARN, MARK_WARN)}  {msg}")
+
+
+def no(msg: str) -> None:
+    print(f"  {c(_RED, MARK_NO)}  {msg}")
+
+
+def dim(msg: str) -> None:
+    print(f"  {c(_DIM, msg)}")
+
+
+def line(msg: str = "") -> None:
+    print(f"  {msg}" if msg else "")
+
+
+def brand_mark(icon: str, color_rgb: tuple[int, int, int], label: str, suffix: str = "") -> str:
+    """A runtime brand chip: a full-glow brand-tinted glyph + a bold WHITE name —
+    only the SYMBOL carries the brand color, the text reads as normal bold text.
+    The tint lands on vector glyphs (⚚ → gold); emoji (🦞) ignore ANSI foreground
+    and keep their own native color — which is the intent.
+    e.g.  ⚚  Hermes   · WSL · Ubuntu-24.04"""
+    glyph = c(rgb(*color_rgb) + _BOLD, icon)   # symbol: full-on glow (bold + brand color)
+    name = c(_BOLD + _BRIGHT, label)            # name: bold white (normal-text look); only the glyph glows
+    tail = f"   {c(_DIM, suffix)}" if suffix else ""
+    return f"{glyph}  {name}{tail}"
+
+
+def channels(items: list[tuple[str, tuple[int, int, int]]]) -> None:
+    """A row of the chat channels Super Research reaches, under the header — each
+    the channel NAME in its exact brand color (TrueColor), no glyph.
+
+    A terminal can't render the apps' real SVG logos (the way the web auth page
+    does), and stand-in emoji/vector glyphs read as subpar — so we show clean
+    brand-colored wordmarks instead, spaced apart (the colors do the separating;
+    no glyph or punctuation that could mojibake). items = (name, (r,g,b))."""
+    if not items:
+        return
+    chips = [c(rgb(*col), name) for name, col in items]
+    print()
+    print(f"  {c(_DIM, 'reach it from')}   " + "    ".join(chips))
+
+
+def next_actions(items: list[tuple[str, str]]) -> None:
+    """Compact 'Next' block — 2-3 likely follow-up commands with one-liners."""
+    if not items:
+        return
+    bar = rule("┈")
+    width = min(max(len(cmd) for cmd, _ in items), 44)
+    print()
+    print(f"  {bar}")
+    print(f"  {c(_DIM, 'Next')}")
+    for cmd, desc in items:
+        print(f"    {c(_ACCENT, ARROW)}  {c(_BOLD, cmd.ljust(width))}   {c(_DIM, desc)}")
+    print()
+
+
+def next_grouped(groups: list[tuple[str, list[tuple[str, str]]]]) -> None:
+    """Closing 'Next' block split into labelled groups — e.g. terminal commands
+    vs in-chat slash commands — so the user can tell them apart. Empty groups are
+    dropped. groups = [(group_label, [(cmd, desc), …]), …]."""
+    groups = [(lbl, items) for lbl, items in groups if items]
+    if not groups:
+        return
+    bar = rule("┈")
+    all_cmds = [cmd for _, items in groups for cmd, _ in items]
+    width = min(max((len(cmd) for cmd in all_cmds), default=0), 40)
+    print()
+    print(f"  {bar}")
+    print(f"  {c(_DIM, 'Next')}")
+    for label, items in groups:
+        print(f"    {c(_BOLD + _ACCENT, label)}")
+        for cmd, desc in items:
+            print(f"      {c(_ACCENT, ARROW)}  {c(_BOLD, cmd.ljust(width))}   {c(_DIM, desc)}")
+    print()
+
+
+def ask(prompt: str, default: str = "", *, cancel_on_interrupt: bool = False) -> str | None:
+    """Blocking prompt with a branded caret.
+
+    On EOF/Ctrl-C: returns None when ``cancel_on_interrupt`` (so a caller can
+    treat an abort as cancel — distinct from an empty Enter that accepts the
+    default), otherwise returns ``default`` (the convenient behavior for
+    confirm-style prompts)."""
+    try:
+        ans = input(f"  {c(_ACCENT, CARET)} {prompt} ").strip()
+        return ans or default
+    except (EOFError, KeyboardInterrupt):
+        print()
+        return None if cancel_on_interrupt else default
+
+
+# ── progress spinner ────────────────────────────────────────────────────────
+# Braille frames — smooth, single-column, widely rendered (same family the app's
+# CLI uses). Animated only on a real TTY; everywhere else we degrade to a static
+# line so a blocking step never just looks hung (and piped output stays clean).
+_SPIN_FRAMES = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+_FRAME_SECONDS = 0.08
+
+
+class _Spinner:
+    """A branded progress spinner for one blocking step that does NOT itself print.
+
+    Use as a context manager around the blocking call::
+
+        with branding.spinner("Installing the skill"):
+            connect.install(...)
+
+    On a TTY it animates a brand-tinted glyph on one rewritten line, then clears
+    it on exit so the caller's success/failure line prints clean. When stdout
+    isn't a TTY (piped/captured/windowless) it prints ONE static line instead —
+    never carriage-return spam. Best-effort and exception-safe: __exit__ always
+    clears the line and restores the cursor, including on Ctrl-C."""
+
+    def __init__(self, message: str, *, color: str = _ACCENT) -> None:
+        self.message = message
+        self.color = color
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        # Animate only when we can both color AND own a live terminal line.
+        self._animate = _USE_COLOR and sys.stdout.isatty()
+
+    def _run(self) -> None:
+        sys.stdout.write("\033[?25l")  # hide the cursor while spinning
+        sys.stdout.flush()
+        for frame in itertools.cycle(_SPIN_FRAMES):
+            if self._stop.is_set():
+                break
+            sys.stdout.write(f"\r  {self.color}{frame}{_RESET}  {_DIM}{self.message}…{_RESET} ")
+            sys.stdout.flush()
+            self._stop.wait(_FRAME_SECONDS)
+
+    def __enter__(self) -> "_Spinner":
+        if self._animate:
+            self._thread = threading.Thread(target=self._run, daemon=True)
+            self._thread.start()
+        else:
+            print(f"  {self.message}…")
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        if self._thread is not None:
+            self._stop.set()
+            self._thread.join(timeout=1.0)
+            sys.stdout.write("\r\033[K\033[?25h")  # clear the line + restore the cursor
+            sys.stdout.flush()
+        return False  # never suppress the wrapped block's exception
+
+
+def spinner(message: str, *, color: str = _ACCENT) -> _Spinner:
+    """A branded progress spinner — `with spinner("…"): blocking_call()`.
+    Animates on a TTY, degrades to a static line otherwise (see _Spinner)."""
+    return _Spinner(message, color=color)
+
+
+def confirm(prompt: str, default: bool = True) -> bool:
+    """Yes/No prompt. A bare Enter takes `default` (and sets the [Y/n] hint). A
+    Ctrl-C / EOF returns False — an interrupt must NEVER silently proceed as a
+    default 'yes' (e.g. it must not trigger an install or run a command in WSL)."""
+    hint = "[Y/n]" if default else "[y/N]"
+    ans = ask(f"{prompt} {c(_DIM, hint)}", cancel_on_interrupt=True)
+    if ans is None:        # Ctrl-C / EOF → abort, not the default
+        return False
+    if not ans:            # bare Enter → the default
+        return default
+    return ans.lower() in ("y", "yes")