webbee 0.1.0__py3-none-any.whl

webbee/repl.py

@@ -0,0 +1,157 @@
+import asyncio
+import os
+import subprocess
+import sys
+
+from webbee import __version__
+from webbee.commands import CommandContext, dispatch
+from webbee.session import AgentSession
+from webbee.tui import next_mode
+
+
+def _git_branch(workspace: str) -> str:
+    try:
+        p = subprocess.run(["git", "rev-parse", "--abbrev-ref", "HEAD"], cwd=workspace,
+                           capture_output=True, text=True, timeout=5)
+        return p.stdout.strip() if p.returncode == 0 else "-"
+    except (OSError, subprocess.SubprocessError):
+        return "-"
+
+
+async def run_repl(cfg, mode: str = "default", *, sink=None, read_line=input,
+                   agent_factory=None, auth=None, account_fetcher=None) -> None:
+    """Interactive coding REPL. Production (a real tty, no injected sink) runs
+    the persistent prompt_toolkit dock (`tui.run_session`): the bordered input
+    box is pinned at the bottom, turn output scrolls above it (patch_stdout →
+    native scrollback), and turns run as background tasks. Tests / non-tty use
+    the injected sync `read_line` fallback loop. Both share `_handle`."""
+    if auth is None:
+        from imperal_mcp import auth as _auth
+        auth = _auth
+    if agent_factory is None:
+        agent_factory = lambda c, tp, ws, m: AgentSession(c, tp, ws, m)  # noqa: E731
+    if account_fetcher is None:
+        from webbee.account import fetch_account as account_fetcher
+
+    workspace = os.getcwd()
+
+    async def token_provider() -> str:
+        return await auth.ensure_access_token(cfg)
+
+    # Prod dock path = the default reader + a real tty + no injected sink; tests
+    # inject sink/read_line and take the plain fallback loop.
+    use_dock = sink is None and read_line is input and sys.stdin.isatty()
+    state = {"mode": mode, "logged_in": False}
+    _sink = None      # assigned by _boot
+    agent = None      # assigned by _boot
+
+    def _cycle() -> None:
+        state["mode"] = next_mode(state["mode"])
+        agent.mode = state["mode"]
+
+    def _ctx() -> CommandContext:
+        return CommandContext(mode=state["mode"], workspace=workspace, version=__version__,
+                              surface="terminal", logged_in=state["logged_in"],
+                              session_tokens=getattr(_sink, "session_tokens", 0),
+                              session_cost=getattr(_sink, "session_cost", 0.0),
+                              git_branch=_git_branch(workspace))
+
+    async def _handle(line: str) -> str:
+        """Process one input line. Returns 'exit' or 'continue'."""
+        if not line.strip():
+            return "continue"
+        res = dispatch(line, _ctx())
+        if res.handled:
+            if res.exit:
+                return "exit"
+            if res.action == "login":
+                email = auth.login(cfg)
+                state["logged_in"] = True
+                _sink.note(f"Signed in as {email}.")
+                return "continue"
+            if res.action == "logout":
+                await auth.logout(cfg)
+                state["logged_in"] = False
+                _sink.note("Signed out, local credentials removed.")
+                return "continue"
+            if res.action == "clear":
+                _sink.clear()
+                _sink.note(res.message)
+                return "continue"
+            if res.action == "mode" and res.new_mode:
+                state["mode"] = res.new_mode
+                agent.mode = res.new_mode
+            if res.message:
+                _sink.note(res.message)
+            return "continue"
+
+        # A task for the agent.
+        _sink.user_echo(line)
+        _sink.begin_turn()
+        try:
+            text = await agent.run(line, _sink)
+        except (KeyboardInterrupt, asyncio.CancelledError):
+            _sink.abort()
+            _sink.note("Interrupted.")
+            return "continue"
+        except Exception as e:  # network/auth/etc — never crash the REPL
+            _sink.note(f"Error: {type(e).__name__}: {e}")
+            return "continue"
+        _sink.end_turn(text)
+        return "continue"
+
+    async def _boot(s) -> None:
+        nonlocal _sink, agent
+        _sink = s
+        account = await account_fetcher(cfg, token_provider)
+        state["logged_in"] = account.signed_in
+        _sink.welcome(account, workspace, "terminal")
+        agent = agent_factory(cfg, token_provider, workspace, state["mode"])
+
+    if use_dock:
+        ok = False
+        pane = None
+        try:
+            import shutil
+
+            from webbee import tui
+            from webbee.render import RichSink
+            width = shutil.get_terminal_size((100, 24)).columns
+            pane = tui.OutputPane(width=width)
+            await _boot(RichSink(console=pane.console, on_output=pane.notify))
+
+            async def _on_line(text: str) -> None:
+                if await _handle(text) == "exit":
+                    from prompt_toolkit.application import get_app
+                    get_app().exit()
+
+            ok = await tui.run_session(
+                pane=pane, on_line=_on_line, mode_getter=lambda: state["mode"],
+                on_cycle=_cycle, status=_sink.status, is_busy=_sink.is_busy,
+                consent_pending=_sink.consent_pending, resolve_consent=_sink.resolve_consent)
+        except Exception:
+            ok = False
+        if ok:
+            # the alt screen is gone — reprint the session transcript to real
+            # stdout so the conversation stays in the terminal scrollback.
+            if pane is not None:
+                sys.stdout.write(pane.dump())
+                sys.stdout.flush()
+            return
+        # dock unavailable → fall through to the plain fallback loop
+
+    # Fallback loop (tests / non-tty / dock unavailable).
+    if _sink is None:
+        if sink is None:
+            from webbee.render import RichSink
+            sink = RichSink()
+        await _boot(sink)
+    while True:
+        try:
+            line = read_line("❯ ")
+        except (EOFError, KeyboardInterrupt):
+            return
+        if line is None:
+            return
+        if await _handle(line) == "exit":
+            return

webbee/session.py

@@ -0,0 +1,160 @@
+import os
+import subprocess
+
+
+def handle_tool_request(frame: dict, executor) -> dict:
+    """Run a (kernel-pre-approved) local tool. The kernel gates write/bash
+    consent via confirm_request BEFORE dispatching, so a tool_request here is
+    always cleared to run."""
+    return {"req_id": frame["req_id"], "result": executor.run(frame["tool"], frame.get("args", {}))}
+
+
+async def handle_confirm_request(frame: dict, mode: str, ask_consent) -> dict:
+    """ICNLI consent path. The client does NOT interpret consent words — it
+    relays the user's RAW reply; the kernel brain interprets intent
+    (safe-by-default). autopilot/plan are explicit and never prompt.
+    `ask_consent(app_id, tool, args)` is an async coroutine returning the raw
+    reply (resolved through the pinned dock, or a sync fallback reader)."""
+    req_id = frame["req_id"]
+    if mode == "autopilot":
+        return {"req_id": req_id, "result": {"approved": True}}
+    if mode == "plan":
+        return {"req_id": req_id, "result": {"approved": False, "reason": "plan_mode"}}
+    raw = await ask_consent(frame.get("app_id", ""), frame.get("tool", ""), frame.get("args", {}))
+    return {"req_id": req_id, "result": {"consent_reply": raw}}
+
+
+def build_coding_context(workspace_root: str) -> dict:
+    """Snapshot handed to the cloud brain: cwd (realpath), `git status -sb`
+    (empty for non-git/any error), and a bounded newline-joined file tree."""
+    cwd = os.path.realpath(workspace_root)
+    try:
+        proc = subprocess.run(
+            ["git", "status", "-sb"], cwd=cwd,
+            capture_output=True, text=True, timeout=10,
+        )
+        git = proc.stdout if proc.returncode == 0 else ""
+    except (OSError, subprocess.SubprocessError):
+        git = ""
+    paths = []
+    for dirpath, dirnames, filenames in os.walk(cwd):
+        dirnames[:] = [d for d in dirnames if d != ".git" and not d.startswith(".")]
+        for fn in filenames:
+            paths.append(os.path.relpath(os.path.join(dirpath, fn), cwd))
+            if len(paths) >= 200:
+                break
+        if len(paths) >= 200:
+            break
+    return {"cwd": cwd, "git": git, "tree": "\n".join(paths)}
+
+
+def _summary(result: dict) -> str:
+    """One-line summary of a tool result for the UI."""
+    content = str(result.get("content", ""))
+    first = content.strip().splitlines()[0] if content.strip() else ""
+    return first[:120]
+
+
+class AgentSession:
+    """Client-side driver for one coding turn against the Imperal cloud.
+    The brain runs server-side; this is the hands — it streams kernel-
+    pre-approved tool_request frames over SSE, runs each tool locally, relays
+    confirm_request replies RAW for the brain to interpret, drives the sink
+    for live UI, and posts results back until a final frame arrives.
+
+    P1: one POST per turn (server reloads the shared webbee-terminal thread,
+    so context carries across turns). Persistent signal-based sessions are P3."""
+
+    def __init__(self, cfg, token_provider, workspace_root: str, mode: str = "default") -> None:
+        self.cfg = cfg
+        self.token_provider = token_provider
+        self.workspace_root = workspace_root
+        self.mode = mode
+
+    async def _headers(self) -> dict:
+        token = await self.token_provider()
+        return {"Authorization": f"Bearer {token}"}
+
+    async def run(self, task: str, sink) -> str:
+        import httpx
+        from httpx_sse import aconnect_sse
+
+        from webbee.tools import LocalToolExecutor
+        from imperal_mcp.client import ImperalClient
+
+        coding_context = build_coding_context(self.workspace_root)
+        imperal_id = await ImperalClient(self.cfg, self.token_provider).whoami()
+        executor = LocalToolExecutor(self.workspace_root)
+
+        headers = await self._headers()
+        async with httpx.AsyncClient(base_url=self.cfg.api_url, timeout=60) as client:
+            resp = await client.post(
+                "/v1/agent/sessions",
+                json={"user_id": imperal_id, "task": task, "coding_context": coding_context},
+                headers=headers,
+            )
+            resp.raise_for_status()
+            session_id = resp.json()["session_id"]
+
+            seen: dict = {}  # req_id -> already-posted result (at-least-once dedup)
+            headers = await self._headers()
+            async with aconnect_sse(
+                client, "GET", f"/v1/agent/sessions/{session_id}/stream", headers=headers,
+            ) as event_source:
+                async for sse in event_source.aiter_sse():
+                    frame = sse.json()
+                    ftype = frame.get("type")
+
+                    if ftype == "tool_request":
+                        rid = frame.get("req_id")
+                        if rid in seen:
+                            out = seen[rid]
+                        else:
+                            sink.tool_start(frame.get("tool", ""), frame.get("args", {}))
+                            out = handle_tool_request(frame, executor)
+                            res = out["result"]
+                            sink.tool_result(frame.get("tool", ""), bool(res.get("ok")), _summary(res))
+                            seen[rid] = out
+                        await self._post_result(client, session_id, out)
+
+                    elif ftype == "confirm_request":
+                        rid = frame.get("req_id")
+                        if rid in seen:
+                            out = seen[rid]
+                        else:
+                            if self.mode == "plan":
+                                sink.plan_blocked(frame.get("tool", ""))
+                            out = await handle_confirm_request(frame, self.mode, sink.ask_consent)
+                            seen[rid] = out
+                        await self._post_result(client, session_id, out)
+
+                    elif ftype == "panel_release_required":
+                        sink.panel_release(frame.get("panel_url", ""), frame.get("summary", ""))
+
+                    elif ftype == "action":  # R2 — ext-tool call (server-side) surfaced in the feed
+                        _lbl = "·".join(x for x in (frame.get("app_id", ""), frame.get("tool", "")) if x)
+                        if frame.get("phase") == "start":
+                            sink.tool_start(_lbl, {})
+                        else:
+                            _summ = str(frame.get("summary", "") or "")
+                            if _summ in ("None", "none"):  # tool result had no content — clean ✓
+                                _summ = ""
+                            sink.tool_result(_lbl, bool(frame.get("ok")), _summ)
+
+                    elif ftype == "progress":  # P2 — server not emitting yet; forward-compatible
+                        sink.progress(frame.get("text", ""))
+
+                    elif ftype == "usage":  # P2 — cumulative tokens + USD cost
+                        sink.usage(
+                            int(frame.get("tokens", 0) or 0),
+                            float(frame.get("cost_usd", 0.0) or 0.0),
+                        )
+
+                    elif ftype == "final":
+                        return frame.get("text", "")
+
+        return ""
+
+    async def _post_result(self, client, session_id: str, out: dict) -> None:
+        headers = await self._headers()
+        await client.post(f"/v1/agent/sessions/{session_id}/result", json=out, headers=headers)

webbee/tools.py

@@ -0,0 +1,84 @@
+import os
+import re
+import subprocess
+
+
+class OutsideWorkspaceError(Exception):
+    pass
+
+
+class LocalToolExecutor:
+    def __init__(self, workspace_root: str) -> None:
+        self.root = os.path.realpath(workspace_root)
+
+    def resolve_in_workspace(self, path: str) -> str:
+        full = os.path.realpath(os.path.join(self.root, path))
+        if full != self.root and not full.startswith(self.root + os.sep):
+            raise OutsideWorkspaceError(path)
+        return full
+
+    def run(self, tool: str, args: dict) -> dict:
+        try:
+            fn = getattr(self, f"_t_{tool}", None)
+            if fn is None:
+                return {"ok": False, "content": f"unknown tool: {tool}"}
+            return fn(args)
+        except OutsideWorkspaceError:
+            raise
+        except Exception as e:  # surface tool errors to the brain, don't crash
+            return {"ok": False, "content": f"{type(e).__name__}: {e}"}
+
+    def _t_read_file(self, a: dict) -> dict:
+        p = self.resolve_in_workspace(a["path"])
+        with open(p, "r", encoding="utf-8") as f:
+            return {"ok": True, "content": f.read()}
+
+    def _t_write_file(self, a: dict) -> dict:
+        p = self.resolve_in_workspace(a["path"])
+        os.makedirs(os.path.dirname(p) or self.root, exist_ok=True)
+        with open(p, "w", encoding="utf-8") as f:
+            f.write(a.get("content", ""))
+        return {"ok": True, "content": f"wrote {a['path']}"}
+
+    def _t_edit_file(self, a: dict) -> dict:
+        p = self.resolve_in_workspace(a["path"])
+        with open(p, "r", encoding="utf-8") as f:
+            text = f.read()
+        if a["old"] not in text:
+            return {"ok": False, "content": "old string not found"}
+        with open(p, "w", encoding="utf-8") as f:
+            f.write(text.replace(a["old"], a["new"], 1))
+        return {"ok": True, "content": f"edited {a['path']}"}
+
+    def _t_bash(self, a: dict) -> dict:
+        proc = subprocess.run(
+            a["command"], shell=True, cwd=self.root,
+            capture_output=True, text=True, timeout=a.get("timeout", 120),
+        )
+        out = (proc.stdout or "") + (proc.stderr or "")
+        return {"ok": proc.returncode == 0, "content": out or f"(exit {proc.returncode})"}
+
+    def _t_grep(self, a: dict) -> dict:
+        pat = re.compile(a["pattern"])
+        base = self.resolve_in_workspace(a.get("path", "."))
+        hits = []
+        for dp, _dn, fns in os.walk(base):
+            if "/.git" in dp:
+                continue
+            for fn in fns:
+                fp = os.path.join(dp, fn)
+                try:
+                    with open(fp, "r", encoding="utf-8") as f:
+                        for i, line in enumerate(f, 1):
+                            if pat.search(line):
+                                rel = os.path.relpath(fp, self.root)
+                                hits.append(f"{rel}:{i}:{line.rstrip()}")
+                except (UnicodeDecodeError, OSError):
+                    continue
+        return {"ok": True, "content": "\n".join(hits[:200]) or "(no matches)"}
+
+    def _t_glob(self, a: dict) -> dict:
+        import glob as _g
+        base = os.path.join(self.root, a["pattern"])
+        rels = [os.path.relpath(p, self.root) for p in _g.glob(base, recursive=True)]
+        return {"ok": True, "content": "\n".join(sorted(rels)) or "(no matches)"}

webbee/tui.py

@@ -0,0 +1,217 @@
+"""Full-screen dock: a scrollable, colored output pane (Rich → ANSI) fills the
+top; a bordered input box + toolbar are pinned at the very bottom and never
+move while the output scrolls (mouse wheel / PageUp). Pure helpers
+(next_mode/build_toolbar) are unit-tested; the Application + OutputPane are
+TTY/headless-smoke verified. Grounded in prompt_toolkit 3.0.52."""
+import asyncio
+
+from webbee.render import _fmt_tokens
+
+_MODES = ("default", "plan", "autopilot")
+_SPINNER = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"   # braille frames — animated while a turn runs
+
+
+def next_mode(mode: str) -> str:
+    try:
+        return _MODES[(_MODES.index(mode) + 1) % len(_MODES)]
+    except ValueError:
+        return _MODES[0]
+
+
+def build_toolbar(mode: str, tokens: int, cost: float, *, busy: bool = False,
+                  current: str = "", elapsed: float = 0.0, tools: int = 0,
+                  consent: bool = False) -> list:
+    """The status line under the pinned input box, as prompt_toolkit formatted
+    text (per-segment styled). Three states: consent (awaiting a reply), busy
+    (a turn is running — an ANIMATED coloured spinner + the current action in
+    accent, so it pops, not grey), and idle (mode value coloured PER MODE —
+    default cyan / plan purple / autopilot yellow — + SESSION spend + the
+    Shift + TAB hint). Style classes are defined in run_session's Style."""
+    if consent:
+        return [("class:tb.consent", "  approve? type y / n / a reply · Enter to send")]
+    if busy:
+        spin = _SPINNER[int(elapsed * 10) % len(_SPINNER)]   # animates via the ticker
+        frags = [("class:tb.spin", f"  {spin} "), ("class:tb.working", "working")]
+        if current:
+            frags += [("class:tb.dim", " · "), ("class:tb.action", current)]
+        frags.append(("class:tb.dim",
+                      f" · {elapsed:.0f}s · {tools} · {_fmt_tokens(tokens)} tok"
+                      f"   ·   Ctrl-C to stop"))
+        return frags
+    return [("class:tb.dim", "  mode: "),
+            (f"class:tb.mode.{mode}", mode),
+            ("class:tb.dim",
+             f"   ·   {_fmt_tokens(tokens)} tok · ${cost:.4f}   ·   Shift + TAB: switch mode")]
+
+
+class OutputPane:
+    """A full-screen scrollable pane that shows COLORED output. Rich renders
+    into a StringIO as ANSI; a FormattedTextControl(ANSI(...)) shows it with the
+    colours intact. The `get_cursor_position == vertical_scroll` trick makes
+    Window.vertical_scroll authoritative so the mouse wheel / PageUp scroll it;
+    notify() auto-follows the tail ONLY when the user is already at the bottom
+    (so scrolling up to read history isn't yanked back down). Grounded in
+    prompt_toolkit 3.0.52 (verified in venv)."""
+
+    def __init__(self, width: int = 100) -> None:
+        import io
+
+        from prompt_toolkit.data_structures import Point
+        from prompt_toolkit.formatted_text import ANSI
+        from prompt_toolkit.layout.containers import Window
+        from prompt_toolkit.layout.controls import FormattedTextControl
+        from rich.console import Console
+
+        self._io = io.StringIO()
+        self.console = Console(file=self._io, force_terminal=True,
+                               color_system="truecolor", width=width, highlight=False)
+        self._ANSI = ANSI
+        self._cache = (None, None)   # (text, ANSI) memo — bounds re-parse cost
+        self.control = FormattedTextControl(
+            text=self._formatted, focusable=False, show_cursor=False,
+            get_cursor_position=lambda: Point(0, self.window.vertical_scroll))
+        self.window = Window(content=self.control, wrap_lines=False,
+                             always_hide_cursor=True, allow_scroll_beyond_bottom=False)
+
+    def _formatted(self):
+        text = self._io.getvalue()
+        if self._cache[0] != text:                # only re-parse when it changed
+            self._cache = (text, self._ANSI(text))
+        return self._cache[1]
+
+    def notify(self) -> None:
+        """Called after each sink print: follow the tail if the user is at the
+        bottom, then redraw. If they've scrolled up, leave their scroll alone."""
+        self._trim()
+        ri = self.window.render_info
+        if ri is not None and ri.bottom_visible:
+            n = self._io.getvalue().count("\n") + 1
+            self.window.vertical_scroll = max(0, n - ri.window_height)
+        try:
+            from prompt_toolkit.application import get_app_or_none
+            app = get_app_or_none()
+            if app is not None:
+                app.invalidate()
+        except Exception:
+            pass
+
+    def _trim(self, max_lines: int = 5000) -> None:
+        import io
+        s = self._io.getvalue()
+        if s.count("\n") > max_lines:
+            s = "\n".join(s.split("\n")[-max_lines:])
+            self._io = io.StringIO()
+            self._io.write(s)
+            self.console.file = self._io
+
+    def dump(self) -> str:
+        """The full session transcript (ANSI). Printed to real stdout on exit so
+        the conversation survives leaving the alternate screen."""
+        return self._io.getvalue()
+
+
+async def run_session(*, pane, on_line, mode_getter, on_cycle, status,
+                      is_busy, consent_pending, resolve_consent) -> bool:
+    """The full-screen dock: `pane` fills the top (scrollable), a bordered input
+    box + toolbar are FIXED at the bottom. Enter either resolves a pending
+    consent reply (ICNLI: raw verbatim) or starts a turn as a BACKGROUND task
+    (the box stays fixed during it). Returns True on clean exit; False if
+    prompt_toolkit is unavailable (caller uses the plain fallback loop)."""
+    try:
+        from prompt_toolkit.application import Application, get_app
+        from prompt_toolkit.buffer import Buffer
+        from prompt_toolkit.key_binding import KeyBindings
+        from prompt_toolkit.layout import HSplit, Layout, Window
+        from prompt_toolkit.layout.controls import BufferControl, FormattedTextControl
+        from prompt_toolkit.layout.processors import BeforeInput
+        from prompt_toolkit.styles import Style
+        from prompt_toolkit.widgets import Frame
+    except Exception:
+        return False
+
+    buf = Buffer(multiline=False)
+    turn = {"task": None}
+
+    async def _run_turn(text):
+        try:
+            await on_line(text)
+        finally:
+            turn["task"] = None
+            get_app().invalidate()
+
+    kb = KeyBindings()
+
+    @kb.add("enter")
+    def _enter(event):
+        text = buf.text
+        buf.reset()
+        if consent_pending():
+            resolve_consent(text)              # ICNLI: relay the raw reply verbatim
+            return
+        if is_busy() or not text.strip():
+            return
+        turn["task"] = event.app.create_background_task(_run_turn(text))
+
+    @kb.add("s-tab")
+    def _cycle(event):
+        on_cycle()
+        event.app.invalidate()
+
+    @kb.add("c-c")
+    def _interrupt(event):
+        t = turn["task"]
+        if t is not None and not t.done():
+            t.cancel()                          # cancel the running turn; dock survives
+
+    @kb.add("c-d")
+    def _eof(event):
+        if not is_busy():
+            event.app.exit()
+
+    @kb.add("pageup")
+    def _pgup(event):
+        pane.window.vertical_scroll = max(0, pane.window.vertical_scroll - 5)
+
+    @kb.add("pagedown")
+    def _pgdn(event):
+        pane.window.vertical_scroll += 5
+
+    def _toolbar():
+        st = status()
+        return build_toolbar(mode_getter(), st["tokens"], st["cost"], busy=st["busy"],
+                             current=st["current"], elapsed=st["elapsed"],
+                             tools=st["tools"], consent=st["consent"])
+
+    input_win = Window(
+        BufferControl(buffer=buf, input_processors=[BeforeInput("❯ ", style="class:prompt")]),
+        height=1)
+    toolbar = Window(FormattedTextControl(_toolbar), height=1, always_hide_cursor=True)
+    root = HSplit([pane.window, Frame(input_win), toolbar])
+    style = Style.from_dict({
+        "frame.border": "#5f5f5f",           # muted grey chrome — furniture, not focus
+        "prompt": "#00afd7 bold",            # cyan ❯ — the interactive accent
+        "tb.dim": "#8a8a8a",                 # idle chrome / secondary bits — dim
+        "tb.spin": "#e8a317 bold",           # animated spinner — bee-yellow, pops
+        "tb.working": "#e8a317",             # 'working' — yellow
+        "tb.action": "#00afd7",              # current action — cyan
+        "tb.consent": "#e8a317 bold",        # consent prompt line — yellow
+        "tb.mode.default": "#00afd7",        # default — cyan
+        "tb.mode.plan": "#af87ff",           # plan — purple
+        "tb.mode.autopilot": "#e8a317 bold", # autopilot — yellow (auto-approving: caution)
+    })
+    app = Application(layout=Layout(root, focused_element=input_win), key_bindings=kb,
+                      full_screen=True, mouse_support=True, style=style)
+
+    async def _ticker():
+        # animate the spinner + tick the elapsed clock while a turn runs
+        while True:
+            await asyncio.sleep(0.25)
+            if is_busy():
+                app.invalidate()
+
+    tick = asyncio.ensure_future(_ticker())
+    try:
+        await app.run_async()
+    finally:
+        tick.cancel()
+    return True

webbee/update.py

@@ -0,0 +1,52 @@
+import json
+from pathlib import Path
+
+PYPI_URL = "https://pypi.org/pypi/webbee/json"
+
+
+def _ver(s: str) -> tuple:
+    try:
+        return tuple(int(x) for x in s.strip().split("."))
+    except (ValueError, AttributeError):
+        return ()
+
+
+def default_fetch() -> "str | None":
+    """Fetch the latest version from PyPI. Returns None on ANY failure
+    (offline, timeout, parse) — the caller treats None as 'no update'."""
+    try:
+        import httpx
+        r = httpx.get(PYPI_URL, timeout=2.0)
+        r.raise_for_status()
+        return r.json()["info"]["version"]
+    except Exception:
+        return None
+
+
+def check_for_update(current: str, *, cache_path, now: float, fetch, ttl: float = 86400.0) -> "str | None":
+    """Return a one-line upgrade notice if a newer webbee is on PyPI, else None.
+    Caches the latest-seen version for `ttl` seconds. Never raises."""
+    cache_path = Path(cache_path)
+    latest = None
+    try:
+        cached = json.loads(cache_path.read_text())
+        if now - float(cached.get("checked_at", 0)) < ttl:
+            latest = cached.get("latest")
+    except Exception:
+        latest = None
+
+    if latest is None:
+        try:
+            latest = fetch()
+        except Exception:
+            latest = None
+        if latest:
+            try:
+                cache_path.parent.mkdir(parents=True, exist_ok=True)
+                cache_path.write_text(json.dumps({"latest": latest, "checked_at": now}))
+            except Exception:
+                pass
+
+    if latest and _ver(latest) > _ver(current):
+        return f"🐝 webbee v{latest} available — upgrade: pipx upgrade webbee  (or: uv tool upgrade webbee)"
+    return None