nxplora 0.16.0__py3-none-any.whl

nxplora-0.16.0.dist-info/METADATA

@@ -0,0 +1,56 @@
+Metadata-Version: 2.5
+Name: nxplora
+Version: 0.16.0
+Summary: NX in your terminal, on your Nexplora account.
+License: Proprietary
+Requires-Python: >=3.9
+Requires-Dist: certifi
+Requires-Dist: textual<2,>=1.0
+Description-Content-Type: text/markdown
+
+# nx-cli
+
+**Private source. Proprietary. Published to PyPI as `nxplora` only when ready.**
+
+The NX terminal client: a thin client of a person's Nexplora account. Each message is a real run on the same engine the
+chat uses, with the account's approvals and billing. It shows what really came back and nothing else.
+
+## Charter
+
+| nx-cli OWNS | nx-cli NEVER contains |
+|---|---|
+| Sign-in / enrollment with nx-cloud | Brain logic: routing, prompts, CodeChat harness, council, cognition router, brain core (these stay in private `Nexploraai/NX`) |
+| Terminal UI, streaming, rendering | Model IDs, provider URLs or provider keys |
+| Actions that must run on the operator's own machine (host, computer, phone) — only under nx-cloud-issued, approval-gated commands | Global Nexplora / NX secrets |
+| Its own update channel | Any upload / publish path to a package index other than the gated release job |
+
+Every published build must pass a check that none of the private NX modules are present in the wheel.
+
+## What it does
+
+- **In a Nexplora Code session's terminal** it is already signed in: the app writes a short-lived session ticket (bound to the
+  person, the Operation and that session, one hour, usable only for sending a message there) to a private file, and renews it
+  while the page holds the terminal. The person's login is never on that computer. The ticket can't approve anything.
+- **On any other computer** `nx` shows a short link and a code. Approve it in the browser and it's done. The sign-in stays in
+  `~/.nx-cli/credentials.json` (0600). `nx logout` ends it. Work runs on the person's Nexplora cloud computer, not this one.
+- **Approvals** are given in the chat. `nx` says what is waiting and where, then follows the run as it goes on.
+- **Colours** are the terminal's own, with no painted background, so it matches a light or dark panel.
+
+```bash
+python -m pip install .
+nx
+```
+
+## Checks
+
+```bash
+python -m pytest                                  # includes a real local HTTP server (tests/stub_server.py)
+python -m build --wheel && python scripts/check_wheel.py dist/*.whl   # the charter's check; a release must pass it
+python scripts/pty_proof.py "$(command -v nx)" /tmp/nx-proof          # real pty, reads the screen, fails on any painted background
+```
+
+## PyPI
+
+The `nxplora` project name is owned and all historical releases are yanked (2026-09-29). Existing installs
+run `nx upgrade` → `pip install -U nxplora`, so the first nx-cli release published under `nxplora` becomes
+the migration path for those users. Never delete the PyPI project (name-takeover risk).

nxplora-0.16.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+nxplora_cli/__init__.py,sha256=3Msc5baw88UJubVj5AVFB8tExkT2OFIsNWe2leaoHhc,23
+nxplora_cli/__main__.py,sha256=IZXKBzDjyPsmZMJx7kOlZWGlUPsup6PU3UB62qEPPy8,1656
+nxplora_cli/app.py,sha256=1CjjZYM0lPTDrATtEkV_kjc3GCNE0RcYno7LBvPZrMg,19834
+nxplora_cli/auth.py,sha256=cDH8W5YRT1-v5WPz_Cf-2tpTHaV21GWeYEEiM5HNS7U,5118
+nxplora_cli/events.py,sha256=X10BXDHNkc80UC_5MxIFIkN_tjUXHxurZkEFJdafHy8,3447
+nxplora_cli/opening.py,sha256=MU_UUQV3Gr74O_RK86TZcXcdFHMY-EBsEZcCTiwF1OQ,8426
+nxplora_cli/transport.py,sha256=NlDCUJShVDPIMfAiseNBo3zTn79xJw9nDBjJJDAp0x0,9552
+nxplora-0.16.0.dist-info/METADATA,sha256=CjmxfmQb7TCi7Ft9WiTtXzPCPY6AlVNV9hYb_gAM2L0,2841
+nxplora-0.16.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+nxplora-0.16.0.dist-info/entry_points.txt,sha256=SlKpaKzRQ9mGKAylpk5N5zY03oHQC08luALiFGdtmfw,85
+nxplora-0.16.0.dist-info/RECORD,,

nxplora-0.16.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

nxplora-0.16.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+nx = nxplora_cli.__main__:main
+nxplora = nxplora_cli.__main__:main

nxplora_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.16.0"

nxplora_cli/__main__.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .auth import DEFAULT_ORIGIN, forget_device_login, load_device_login, safe_origin
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="nx", description="NX in your terminal, on your Nexplora account")
+    parser.add_argument("--version", action="version", version=__version__)
+    parser.add_argument("--connect", metavar="URL", help="the Nexplora address to use (default: nexplora.ai)")
+    parser.add_argument("command", nargs="?", choices=["login", "logout"], help="sign in or out on this computer")
+    args = parser.parse_args()
+    origin = safe_origin(args.connect) if args.connect else None
+    if args.connect and not origin:
+        parser.error("that address isn't https, so nx won't send your sign-in to it")
+    if args.command == "logout":
+        _logout()
+        return
+    from .app import NxploraApp
+
+    app = NxploraApp(origin=origin or DEFAULT_ORIGIN, origin_chosen=bool(origin), force_login=args.command == "login")
+    app.run(mouse=False)
+    if app.exit_note:
+        print(app.exit_note)
+
+
+def _logout() -> None:
+    from .transport import Unreachable, revoke_device_session
+
+    login = load_device_login()
+    if login and login.device_session_id:
+        try:
+            revoke_device_session(login.origin, login.access_token, login.device_session_id)
+        except Unreachable:
+            print("Signed out here, but Nexplora couldn't be reached. You can end this sign-in in your account.", file=sys.stderr)
+    forget_device_login()
+    print("Signed out on this computer.")
+
+
+if __name__ == "__main__":
+    main()

nxplora_cli/app.py

@@ -0,0 +1,422 @@
+"""The terminal. A thin client: each message is a real run on the person's account, and all it shows is what really came back.
+
+Colours: everything is the terminal's own (ansi_default and the 16 named colours), so nothing paints a box. A panel's theme
+decides what they look like, light or dark. The old screen painted #edf1eb; on the terminal panel's 16-colour TERM that
+became ANSI 15, which the panel's light theme sets to its dark ink, and that was the dark box.
+"""
+from __future__ import annotations
+
+import platform
+import threading
+import time
+from typing import Any, Callable
+
+from rich.text import Text
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Vertical, VerticalScroll
+from textual.widgets import Input, Static
+
+from . import __version__, transport
+from .auth import (
+    DeviceLogin,
+    SessionTicket,
+    forget_device_login,
+    load_device_login,
+    on_nexplora_computer,
+    read_session_ticket,
+    safe_origin,
+    save_device_login,
+)
+from .events import Line, clean, line_for
+from .opening import WorkspaceContext, default_opening, inspect_workspace
+
+APPROVE_BESIDE = "Approve or deny it in the chat beside this terminal."
+TICKET_OUT = "This terminal's sign-in has run out. Close the terminal panel and open it again."
+TICKET_MISSING = "This terminal isn't signed in. Close the terminal panel and open it again."
+UNREACHABLE = "Can't reach Nexplora. Check the connection and try again."
+HELP = "Type a message and press Enter. Esc stops the run. Page Up and Page Down scroll. /clear clears this screen. /quit leaves."
+_TONE_STYLE = {"assistant": "", "step": "bright_black", "waiting": "bold yellow", "problem": "red", "you": "bold"}
+_EVENT_POLL_S = 2.0
+_TICKET_POLL_S = 1.0
+_TICKET_WAIT_S = 8.0
+
+
+class NxploraApp(App[None]):
+    TITLE = "nx"
+    ENABLE_COMMAND_PALETTE = False
+    CSS = """
+    Screen { background: ansi_default; color: ansi_default; layers: base; }
+    #brand { height: 1; margin: 1 2 0 2; background: ansi_default; color: ansi_bright_black; }
+    #signin { height: 1fr; margin: 2 2 0 2; background: ansi_default; color: ansi_default; }
+    #signin Static { height: auto; margin-bottom: 1; background: ansi_default; color: ansi_default; }
+    #transcript { height: 1fr; margin: 1 2 0 2; background: ansi_default; color: ansi_default; scrollbar-size: 0 0; }
+    .line { height: auto; margin-bottom: 1; background: ansi_default; color: ansi_default; }
+    #status { height: 1; margin: 0 2; background: ansi_default; color: ansi_bright_black; }
+    #prompt { height: 1; border: none; margin: 0 2 1 2; padding: 0; background: ansi_default; color: ansi_default; }
+    #prompt:focus { border: none; background: ansi_default; }
+    Input > .input--cursor { background: ansi_default; color: ansi_default; text-style: reverse; }
+    Input > .input--placeholder { background: ansi_default; color: ansi_bright_black; }
+    Input > .input--suggestion { background: ansi_default; color: ansi_bright_black; }
+    Input > .input--selection { background: ansi_default; color: ansi_default; text-style: reverse; }
+    """
+    BINDINGS = [
+        Binding("escape", "stop_run", "Stop", priority=True),
+        Binding("ctrl+c", "quit", "Quit", priority=True),
+        Binding("pageup", "page(-1)", show=False, priority=True),
+        Binding("pagedown", "page(1)", show=False, priority=True),
+    ]
+
+    def __init__(
+        self,
+        origin: str = "https://nexplora.ai",
+        origin_chosen: bool = False,
+        force_login: bool = False,
+        workspace: str | None = None,
+        opening_provider: Callable[[WorkspaceContext], str] | None = None,
+    ) -> None:
+        super().__init__(ansi_color=True)
+        self.theme = "textual-ansi"
+        self.origin = origin
+        self.origin_chosen = origin_chosen
+        self.force_login = force_login
+        self.workspace = inspect_workspace(workspace)
+        self.opening_provider = opening_provider
+        self.exit_note = ""
+        self.ticket: SessionTicket | None = None
+        self.login: DeviceLogin | None = None
+        self.running = False
+        self.waiting_for_ok = False
+        self._stop_following = threading.Event()
+        self._quitting = threading.Event()
+        self._last_assistant: Static | None = None
+        self._last_assistant_text = ""
+
+    # ── never show a credential: Textual's crash report prints local variables, so it isn't used ──
+    def _fatal_error(self) -> None:
+        self.exit_note = "NX CLI hit a problem and closed. Run nx to start again."
+        self._close_messages_no_wait()
+
+    # ── screens ────────────────────────────────────────────────────────────────
+    def compose(self) -> ComposeResult:
+        yield Static("nx  ·  Nexplora", id="brand")
+        yield Vertical(id="signin")
+
+    async def on_mount(self) -> None:
+        ticket = read_session_ticket()
+        if on_nexplora_computer() or ticket:
+            await self._say_signin("Signing in…")
+            self.run_worker(self._wait_for_ticket, thread=True, exclusive=True, group="signin")
+            return
+        login = None if self.force_login else load_device_login(self.origin if self.origin_chosen else None)
+        if login:
+            self.login = login
+            await self._open_work()
+            return
+        await self._say_signin("Getting a sign-in link…")
+        self.run_worker(self._device_grant, thread=True, exclusive=True, group="signin")
+
+    async def _say_signin(self, *lines: str) -> None:
+        box = self.query_one("#signin")
+        await box.remove_children()
+        for line in lines:
+            await box.mount(Static(Text(clean(line))))
+
+    async def _open_work(self) -> None:
+        await self.query_one("#signin").remove()
+        transcript = VerticalScroll(id="transcript", can_focus=False)
+        await self.mount(transcript)
+        await self.mount(Static("", id="status"))
+        await self.mount(Input(placeholder="Message NX", id="prompt"))
+        opening = self.opening_provider(self.workspace) if self.opening_provider else default_opening(self.workspace)
+        self._write(Line(opening, "assistant"))
+        if self.login:
+            self._write(Line("This runs on your Nexplora cloud computer, not on this one, and it doesn't see files here.", "step"))
+        self._last_assistant = None
+        self.query_one("#prompt", Input).focus()
+
+    # ── signing in ─────────────────────────────────────────────────────────────
+    def _wait_for_ticket(self) -> None:
+        """On a Code session's computer the app puts the ticket here. Nothing to do but see it arrive."""
+        said = False
+        deadline = time.time() + _TICKET_WAIT_S
+        while not self._quitting.is_set():
+            ticket = read_session_ticket()
+            if ticket and ticket.fresh():
+                self.ticket = ticket
+                self.call_from_thread(self._open_work)
+                return
+            if not said and time.time() > deadline:
+                said = True
+                self.call_from_thread(self._say_signin, TICKET_OUT if ticket else TICKET_MISSING)
+            time.sleep(_TICKET_POLL_S)
+
+    def _device_grant(self) -> None:
+        while not self._quitting.is_set():
+            try:
+                grant = transport.start_device_grant(self.origin, __version__, platform.node()[:128])
+            except transport.Unreachable:
+                self._signin_line(UNREACHABLE)
+                if self._quitting.wait(5):
+                    return
+                continue
+            except transport.Refused as refused:
+                self._signin_line(str(refused))
+                if self._quitting.wait(10):
+                    return
+                continue
+            self._signin_line("Sign in to Nexplora", f"Open this link:  {grant.link}", f"Your code is  {grant.user_code}", "Waiting for you to approve it there…")
+            outcome = self._await_grant(grant)
+            if outcome == "signed_in" or outcome == "quit":
+                return
+            if outcome == "denied":
+                self._signin_line("That sign-in was denied. Run nx to try again, or Ctrl+C to leave.")
+                return
+            # expired: a fresh code, without asking
+
+    def _await_grant(self, grant: transport.DeviceCode) -> str:
+        deadline = time.time() + grant.expires_in_s
+        while time.time() < deadline:
+            if self._quitting.wait(max(1.0, grant.interval_s)):
+                return "quit"
+            try:
+                result = transport.poll_device_grant(self.origin, grant.device_code)
+            except transport.Unreachable:
+                continue
+            if isinstance(result, dict):
+                device_session = result.get("device_session_id")
+                self.login = DeviceLogin(
+                    self.origin, str(result["access_token"]), str(result.get("refresh_token") or ""),
+                    device_session if isinstance(device_session, str) else None,
+                )
+                save_device_login(self.login)
+                self.call_from_thread(self._open_work)
+                return "signed_in"
+            if result in ("denied", "expired"):
+                return str(result)
+        return "expired"
+
+    def _signin_line(self, *lines: str) -> None:
+        self.call_from_thread(self._say_signin, *lines)
+
+    # ── a credential, fresh, for one request ───────────────────────────────────
+    def _credential(self) -> tuple[str, str, str]:
+        """(origin, bearer, session id). Raises Refused with the one plain line when there is none."""
+        if self.login:
+            login = self.login
+            if not login.session_id:
+                login.session_id = self._with_refresh(lambda bearer: transport.create_session(login.origin, bearer))
+                save_device_login(login)
+            return login.origin, login.access_token, login.session_id
+        ticket = read_session_ticket()
+        if not ticket:
+            raise transport.Refused(TICKET_MISSING)
+        if not ticket.fresh():
+            raise transport.Refused(TICKET_OUT)
+        return ticket.origin, ticket.ticket, ticket.session_id
+
+    def _with_refresh(self, call: Callable[[str], Any]) -> Any:
+        login = self.login
+        assert login is not None
+        try:
+            return call(login.access_token)
+        except transport.SignedOut:
+            tokens = transport.refresh_login(login.origin, login.refresh_token) if login.refresh_token else None
+            if not tokens:
+                raise
+            login.access_token, login.refresh_token = tokens
+            save_device_login(login)
+            return call(login.access_token)
+
+    def _signed_out_line(self) -> str:
+        if self.login:
+            forget_device_login()
+            return "You're signed out. Run nx to sign in again."
+        return TICKET_OUT
+
+    # ── a message ──────────────────────────────────────────────────────────────
+    async def on_input_submitted(self, event: Input.Submitted) -> None:
+        text = event.value.strip()
+        event.input.value = ""
+        if not text:
+            return
+        if text == "/quit":
+            self.exit()
+            return
+        if text == "/clear":
+            await self.query_one("#transcript").remove_children()
+            self._last_assistant = None
+            return
+        if text == "/help":
+            self._write(Line(HELP, "step"))
+            return
+        if self.running:
+            self._write(Line("NX is still on the last message. Wait for it, or press Esc to stop it.", "step"))
+            return
+        self._write(Line(f"› {text}", "you"))
+        self._last_assistant = None
+        self.running = True
+        self._stop_following.clear()
+        self._status("Working…")
+        self.run_worker(lambda: self._run_turn(text), thread=True, exclusive=False, group="turn")
+
+    def _run_turn(self, task: str) -> None:
+        try:
+            self._drive(task)
+        except transport.SignedOut:
+            self._show(Line(self._signed_out_line(), "problem"))
+        except transport.Refused as refused:
+            self._show(Line(str(refused), "problem"))
+        except transport.Unreachable:
+            self._show(Line(UNREACHABLE, "problem"))
+        except Exception:  # noqa: BLE001 - a turn that breaks says so in plain words; the screen stays usable
+            self._show(Line("Something went wrong showing that. Check the chat for what happened.", "problem"))
+        finally:
+            self.call_from_thread(self._turn_ended)
+
+    def _turn_ended(self) -> None:
+        self.running = False
+        self.waiting_for_ok = False
+        self._status("")
+
+    def _drive(self, task: str) -> None:
+        tick = 0
+        while True:
+            origin, bearer, session_id = self._credential()
+            try:
+                if self.login:
+                    stream = self._with_refresh(lambda b: transport.post_run(origin, b, session_id, task, tick))
+                else:
+                    stream = transport.post_run(origin, bearer, session_id, task, tick)
+            except transport.Refused as refused:
+                if self.login and "session is gone" in str(refused):
+                    self.login.session_id = None
+                    self._show(Line("That session is gone, so this starts a new one.", "step"))
+                    continue
+                raise
+            seen = 0
+            next_tick: int | None = None
+            finished: str | None = None
+            try:
+                for event in stream.events:
+                    seen += 1
+                    kind = event.get("event")
+                    if kind == "checkpoint":
+                        last = event.get("lastTick")
+                        next_tick = last if isinstance(last, int) else tick
+                    elif kind == "done":
+                        finished = str(event.get("status") or "completed")
+                    elif kind == "error":
+                        finished = "error"
+                    self._render_event(event)
+            except transport.Unreachable:
+                self._show(Line("The connection dropped. Following the run from what it logged…", "step"))
+            if finished == "completed" or finished == "error":
+                return
+            if finished == "awaiting_approval" or finished == "awaiting_plan":
+                self.waiting_for_ok = True
+                self.call_from_thread(self._status, "Waiting for your OK. Esc stops watching here; the change keeps waiting in the chat.")
+                self._follow(stream.run_id, seen, session_id)
+                return
+            if next_tick is not None:
+                tick = next_tick
+                continue
+            self._follow(stream.run_id, seen, session_id)
+            return
+
+    def _follow(self, run_id: str | None, seq: int, session_id: str) -> None:
+        """Read the run's own log until it ends: a change approved in the chat, or a stream that dropped, shows as it went."""
+        if not run_id:
+            self._show(Line("Follow the rest of this in the chat beside this terminal.", "step"))
+            return
+        current_run = run_id
+        while not self._stop_following.is_set() and not self._quitting.is_set():
+            origin, bearer, _ = self._credential()
+            if self.login:
+                events, seq, current_run = self._with_refresh(lambda b: transport.read_events(origin, b, session_id, current_run, seq))
+            else:
+                events, seq, current_run = transport.read_events(origin, bearer, session_id, current_run, seq)
+            ended = False
+            for event in events:
+                self._render_event(event)
+                kind = event.get("event")
+                if kind == "done":
+                    status = str(event.get("status") or "completed")
+                    ended = status not in ("awaiting_approval", "awaiting_plan")
+                elif kind == "error":
+                    ended = True
+                elif kind == "tool_call":
+                    self.waiting_for_ok = False
+                    self.call_from_thread(self._status, "Working…")
+            if ended:
+                return
+            if self._stop_following.wait(_EVENT_POLL_S):
+                return
+
+    def _render_event(self, event: dict[str, Any]) -> None:
+        where = APPROVE_BESIDE
+        if self.login and self.login.session_id:
+            where = f"Approve or deny it in Nexplora: {self.login.origin}/code?codeSession={self.login.session_id}"
+        line = line_for(event, where)
+        if line:
+            self._show(line)
+
+    # ── the screen ─────────────────────────────────────────────────────────────
+    def _show(self, line: Line) -> None:
+        self.call_from_thread(self._write, line)
+
+    def _write(self, line: Line) -> None:
+        if not self.query("#transcript"):
+            return
+        transcript = self.query_one("#transcript", VerticalScroll)
+        if line.tone == "assistant" and self._last_assistant is not None:
+            text = line.text if line.replace_assistant else f"{self._last_assistant_text}\n\n{line.text}"
+            self._last_assistant.update(Text(text))
+            self._last_assistant_text = text
+        else:
+            widget = Static(Text(line.text, style=_TONE_STYLE.get(line.tone, "")), classes="line")
+            transcript.mount(widget)
+            self._last_assistant = widget if line.tone == "assistant" else None
+            self._last_assistant_text = line.text if line.tone == "assistant" else ""
+        transcript.scroll_end(animate=False)
+
+    def _status(self, text: str) -> None:
+        if self.query("#status"):
+            self.query_one("#status", Static).update(Text(text))
+
+    def action_page(self, direction: int) -> None:
+        if self.query("#transcript"):
+            box = self.query_one("#transcript", VerticalScroll)
+            if direction < 0:
+                box.scroll_page_up(animate=False)
+            else:
+                box.scroll_page_down(animate=False)
+
+    def action_stop_run(self) -> None:
+        if not self.running:
+            return
+        self._stop_following.set()
+        if self.waiting_for_ok:
+            return  # nothing is running: it is waiting on the person, and Esc here must not throw that away
+        self._status("Stopping…")
+        self.run_worker(self._stop_on_server, thread=True, exclusive=False, group="stop")
+
+    def _stop_on_server(self) -> None:
+        try:
+            origin, bearer, session_id = self._credential()
+            if self.login:
+                self._with_refresh(lambda b: transport.stop_run(origin, b, session_id))
+            else:
+                transport.stop_run(origin, bearer, session_id)
+        except (transport.SignedOut, transport.Refused, transport.Unreachable):
+            self._show(Line("Couldn't stop it from here. Press Stop in the chat.", "problem"))
+
+    async def action_quit(self) -> None:
+        self._quitting.set()
+        self._stop_following.set()
+        if self.running:
+            self.exit_note = "NX may still be working in this session. It shows in the chat."
+        self.exit()
+
+
+__all__ = ["NxploraApp", "safe_origin"]

nxplora_cli/auth.py

@@ -0,0 +1,151 @@
+"""How `nx` is signed in. Nothing here prints, logs or puts a credential anywhere but the one request it is for.
+
+In a Nexplora Code session the app writes a short-lived session ticket to a private file (never the person's login). On any
+other computer the person signs in once with a short link and code, and the result stays in a 0600 file.
+"""
+from __future__ import annotations
+
+import json
+import os
+import stat
+import tempfile
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlsplit
+
+DEFAULT_ORIGIN = "https://nexplora.ai"
+_LOCAL_HOSTS = {"localhost", "127.0.0.1", "[::1]", "::1"}
+
+
+def safe_origin(origin: object) -> str | None:
+    """Only https, or a local address. A credential is never sent anywhere else."""
+    if not isinstance(origin, str):
+        return None
+    parts = urlsplit(origin.strip())
+    if parts.path not in ("", "/") or parts.query or parts.fragment or parts.username or parts.password:
+        return None
+    if parts.scheme == "https" and parts.hostname:
+        return f"https://{parts.netloc}"
+    if parts.scheme == "http" and parts.hostname in _LOCAL_HOSTS:
+        return f"http://{parts.netloc}"
+    return None
+
+
+def _home() -> Path:
+    return Path(os.path.expanduser("~"))
+
+
+def _private(path: Path) -> bool:
+    """Ours, and nobody else can read it."""
+    try:
+        info = path.lstat()
+    except OSError:
+        return False
+    return stat.S_ISREG(info.st_mode) and info.st_uid == os.getuid() and not (info.st_mode & 0o077)
+
+
+def session_file_paths() -> tuple[Path, Path]:
+    """Same order the app writes them in: tmpfs first, then the home folder."""
+    return (Path(f"/dev/shm/nx-cli-{os.getuid()}/session.json"), _home() / ".nx-cli" / "session.json")
+
+
+def on_nexplora_computer() -> bool:
+    """A Code session's computer. Its terminal is set up by the app, which leaves this folder behind."""
+    return (_home() / ".nx-pty").is_dir()
+
+
+@dataclass(frozen=True)
+class SessionTicket:
+    origin: str
+    session_id: str
+    ticket: str
+    expires_at_ms: int
+
+    def __repr__(self) -> str:
+        return f"SessionTicket(session_id={self.session_id!r})"
+
+    def fresh(self, now_ms: float | None = None) -> bool:
+        return self.expires_at_ms > (time.time() * 1000 if now_ms is None else now_ms)
+
+
+def read_session_ticket() -> SessionTicket | None:
+    """The ticket on this computer, read fresh each time so a renewal is picked up without restarting."""
+    for path in session_file_paths():
+        if not _private(path):
+            continue
+        try:
+            doc = json.loads(path.read_text("utf-8"))
+        except (OSError, ValueError):
+            continue
+        origin = safe_origin(doc.get("origin"))
+        ticket, session_id, expires = doc.get("ticket"), doc.get("session_id"), doc.get("expires_at_ms")
+        if origin and isinstance(ticket, str) and ticket and isinstance(session_id, str) and session_id and isinstance(expires, (int, float)):
+            return SessionTicket(origin, session_id, ticket, int(expires))
+    return None
+
+
+def credentials_path() -> Path:
+    return _home() / ".nx-cli" / "credentials.json"
+
+
+@dataclass
+class DeviceLogin:
+    origin: str
+    access_token: str
+    refresh_token: str
+    device_session_id: str | None = None
+    session_id: str | None = None
+
+    def __repr__(self) -> str:
+        return f"DeviceLogin(origin={self.origin!r})"
+
+
+def load_device_login(origin: str | None = None) -> DeviceLogin | None:
+    path = credentials_path()
+    if not _private(path):
+        return None
+    try:
+        doc = json.loads(path.read_text("utf-8"))
+    except (OSError, ValueError):
+        return None
+    stored = safe_origin(doc.get("origin"))
+    access, refresh = doc.get("access_token"), doc.get("refresh_token")
+    if not stored or not isinstance(access, str) or not access or not isinstance(refresh, str):
+        return None
+    if origin and stored != origin:
+        return None
+    session_id = doc.get("session_id")
+    device_session_id = doc.get("device_session_id")
+    return DeviceLogin(
+        stored, access, refresh,
+        device_session_id if isinstance(device_session_id, str) else None,
+        session_id if isinstance(session_id, str) else None,
+    )
+
+
+def save_device_login(login: DeviceLogin) -> None:
+    path = credentials_path()
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    os.chmod(path.parent, 0o700)
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=".credentials.")  # mkstemp creates it 0600
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as out:
+            json.dump({
+                "origin": login.origin, "access_token": login.access_token, "refresh_token": login.refresh_token,
+                "device_session_id": login.device_session_id, "session_id": login.session_id,
+            }, out)
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def forget_device_login() -> None:
+    try:
+        credentials_path().unlink()
+    except OSError:
+        pass

nxplora_cli/events.py

@@ -0,0 +1,75 @@
+"""What each thing the run really did looks like in the terminal. Nothing here is made up: no event, no line."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+CREDIT_PAUSE = "paused: credit limit"
+OUT_OF_CREDIT_LINE = "You're out of credit. Add more in Nexplora to keep going."
+
+
+@dataclass(frozen=True)
+class Line:
+    text: str
+    tone: str  # assistant | step | waiting | problem
+    replace_assistant: bool = False
+
+
+def clean(text: object, limit: int = 60_000) -> str:
+    """Words from the server may not move the cursor, change colours or fake a screen."""
+    if not isinstance(text, str):
+        return ""
+    return "".join(ch for ch in text[:limit] if ch in "\n\t" or (ord(ch) >= 0x20 and not 0x7f <= ord(ch) <= 0x9f))
+
+
+def first_line(text: object, limit: int = 300) -> str:
+    cleaned = clean(text, 4_000).strip()
+    return cleaned.splitlines()[0][:limit] if cleaned else ""
+
+
+def line_for(event: dict[str, Any], where_to_approve: str) -> Line | None:
+    kind = event.get("event")
+    if kind == "assistant_text":
+        text = clean(event.get("text"))
+        if text.strip() == CREDIT_PAUSE:
+            return Line(OUT_OF_CREDIT_LINE, "problem")
+        return Line(text, "assistant") if text.strip() else None
+    if kind == "assistant_revision":
+        text = clean(event.get("text"))
+        return Line(text, "assistant", True) if text.strip() else None
+    if kind in ("plan", "build_plan"):
+        text = clean(event.get("text"))
+        return Line(text, "step") if text.strip() else None
+    if kind == "tool_call":
+        summary = first_line(event.get("summary")) or first_line(event.get("tool"))
+        return Line(f"· {summary}", "step") if summary else None
+    if kind == "tool_result" and event.get("ok") is False:
+        detail = first_line(event.get("detail")) or first_line(event.get("stderr"))
+        return Line(f"  That step didn't work{': ' + detail if detail else '.'}", "problem")
+    if kind == "file_changed":
+        path = first_line(event.get("path"))
+        return Line(f"· {clean(event.get('changeType')) or 'changed'} {path}", "step") if path else None
+    if kind == "approval_required":
+        summary = first_line(event.get("summary")) or "A change"
+        return Line(f"Waiting for your OK: {summary}\n{where_to_approve}", "waiting")
+    if kind == "images_generated":
+        urls = event.get("urls")
+        shown = [clean(u, 2_000) for u in urls if isinstance(u, str)] if isinstance(urls, list) else []
+        return Line("\n".join(shown), "step") if shown else None
+    if kind == "video_pending":
+        return Line("A video is being made. It will show in the chat.", "step")
+    if kind in ("web_operator_launch", "computer_operator_launch", "mission_operator_launch"):
+        return Line("This part runs outside the terminal. Follow it in Nexplora.", "step")
+    if kind == "halt":
+        detail = first_line(event.get("detail"))
+        reason = event.get("reason")
+        if reason == "aborted":
+            return Line("Stopped.", "step")
+        if reason in ("awaiting_approval", "awaiting_plan", "maxduration_checkpoint", "done", "session_busy"):
+            return None
+        return Line(detail or "The run stopped before it finished.", "problem")
+    if kind == "error":
+        from .transport import friendly
+
+        return Line(friendly(200, str(event.get("code") or ""), ""), "problem")
+    return None

nxplora_cli/opening.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+import os
+import random
+import re
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+
+_INDEX_SCAN_LIMIT = 4096
+_INDEX_STAT = re.compile(
+    r"  ctime: \d+:\d+\n  mtime: (\d+):(\d+)\n"
+    r"  dev: \d+\tino: \d+\n  uid: \d+\tgid: \d+\n"
+    r"  size: (\d+)\tflags: [0-9a-f]+\n"
+)
+
+
+def _unstaged_paths(cwd: Path, index: str) -> list[str]:
+    # --stage --debug emits a NUL-terminated mode/OID/stage/path record,
+    # followed by five lines of index-only stat data. Never split paths on LF.
+    deadline = time.monotonic() + 0.7
+    offset = 0
+    changed = []
+    for _ in range(_INDEX_SCAN_LIMIT):
+        if time.monotonic() >= deadline:
+            break
+        end = index.find("\0", offset)
+        if end < 0:
+            break
+        entry = index[offset:end]
+        metadata = _INDEX_STAT.match(index, end + 1)
+        if metadata is None:
+            break  # Unknown debug format: keep the other sources of context.
+        offset = metadata.end()
+        mode, separator, path = entry.partition("\t")
+        if not separator or mode.startswith("160000 "):
+            continue  # Do not inspect gitlinks/submodule directories.
+        try:
+            info = os.lstat(cwd / path)
+        except (OSError, ValueError):
+            changed.append(path)
+            continue
+        seconds, nanoseconds, size = map(int, metadata.groups())
+        # Some Git platforms store only whole-second index timestamps.
+        if (info.st_size != size
+                or info.st_mtime_ns // 1_000_000_000 != seconds
+                or (nanoseconds and info.st_mtime_ns % 1_000_000_000 != nanoseconds)):
+            changed.append(path)
+    return changed
+
+
+@dataclass(frozen=True)
+class WorkspaceContext:
+    directory: str
+    branch: str | None
+    changed_files: tuple[str, ...]
+    latest_commit: str | None
+
+    @property
+    def has_work(self) -> bool:
+        return bool(self.branch or self.changed_files or self.latest_commit)
+
+
+def inspect_workspace(directory: str | None = None) -> WorkspaceContext:
+    cwd = Path(directory or os.getcwd())
+    # Startup may inspect an untrusted checkout before the user signs in.
+    # Do not inherit credentials, Git config injection, or user/system config.
+    env = {
+        "PATH": os.environ.get("PATH", os.defpath),
+        "LC_ALL": "C",
+        "GIT_CONFIG_NOSYSTEM": "1",
+        "GIT_CONFIG_SYSTEM": os.devnull,
+        "GIT_CONFIG_GLOBAL": os.devnull,
+        "GIT_OPTIONAL_LOCKS": "0",
+        "GIT_TERMINAL_PROMPT": "0",
+        # Partial clones can otherwise invoke repo-configured remote helpers.
+        "GIT_NO_LAZY_FETCH": "1",
+        "GIT_ALLOW_PROTOCOL": "",
+    }
+    if os.name == "nt" and "SystemRoot" in os.environ:
+        env["SystemRoot"] = os.environ["SystemRoot"]
+
+    def git(*args: str) -> str | None:
+        try:
+            result = subprocess.run(
+                [
+                    "git", "-c", "core.fsmonitor=false",
+                    "-c", "core.untrackedCache=false",
+                    "-c", f"core.hooksPath={os.devnull}", *args,
+                ],
+                cwd=cwd, env=env, capture_output=True, text=True,
+                encoding="utf-8", errors="replace", timeout=0.7, check=False,
+            )
+        except (OSError, subprocess.TimeoutExpired, UnicodeDecodeError, ValueError):
+            return None
+        return result.stdout if result.returncode == 0 else None
+
+    # Never inspect worktree contents: status/worktree diffs can run filters or
+    # enter submodules. The plumbing command compares index paths with HEAD;
+    # unlike `diff`, it has no auto-refresh fallback or configured order file.
+    # Staged gitlinks remain visible. Fall back to index paths without HEAD.
+    staged = git(
+        "diff-index", "--cached", "--name-only", "--no-ext-diff", "--no-textconv",
+        "--no-renames", "--ignore-submodules=none", "--no-relative",
+        "-z", "HEAD", "--",
+    )
+    if staged is None and git("rev-parse", "--verify", "-q", "HEAD") is None:
+        staged = git("ls-files", "-z")
+    # ls-files reads index metadata and walks directory names only. Python
+    # compares stat data without opening files; this is deliberately a bounded,
+    # best-effort hint (same-size edits preserving mtime may be missed).
+    unstaged = _unstaged_paths(cwd, git("ls-files", "--stage", "--debug", "-z") or "")
+    untracked = git(
+        "ls-files", "-z", "--others", "--exclude-standard",
+        "--directory", "--no-empty-directory",
+    )
+    changed = dict.fromkeys(
+        unstaged + [path for path in (staged or "").split("\0") if path]
+        + [path for path in (untracked or "").split("\0") if path]
+    )
+    return WorkspaceContext(
+        directory=str(cwd),
+        branch=(git("symbolic-ref", "--short", "-q", "HEAD") or "").strip() or None,
+        changed_files=tuple(changed),
+        latest_commit=(git(
+            "log", "-1", "--no-show-signature", "--no-use-mailmap", "--format=%s",
+        ) or "").strip() or None,
+    )
+
+
+def default_opening(context: WorkspaceContext, chooser: Callable[[list[str]], str] | None = None) -> str:
+    choose = chooser or random.SystemRandom().choice
+    if context.has_work:
+        branch = f" on `{context.branch}`" if context.branch else ""
+        extra = f" The last move was `{context.latest_commit}`." if context.latest_commit else ""
+        if context.changed_files:
+            focus = context.changed_files[0]
+            extra += f" I see work in `{focus}`."
+        return choose([
+            f"Welcome back{branch}.{extra} Want to finish it, inspect the diff, or keep building?",
+            f"I found an active workspace{branch}.{extra} What should we continue?",
+            f"Back in the work{branch}.{extra} Shall we pick up where you left off?",
+        ])
+    return choose([
+        "Hey — how are you doing? What’s on your mind?",
+        "Hey, what’s up? What are we building today?",
+        "Good to see you. What’s cooking?",
+        "Hey — where should we start?",
+        "What are you thinking about? NX is ready when you are.",
+        "Morning. What would make today’s work feel like a win?",
+        "Hey there — what’s the first thing you want to move forward?",
+        "What’s alive in your head right now?",
+        "Welcome in. Do you want to explore, make, or fix something?",
+        "Hey — got a spark to chase?",
+        "What are we making better today?",
+        "I’m here. What should we look at first?",
+        "What’s the shape of the problem you’re carrying in?",
+        "Hey — want to start with an idea or an action?",
+        "What do you want to get unstuck?",
+        "Good to have you back. What’s worth your attention right now?",
+        "What’s the interesting thing on your desk today?",
+        "Hey — should we make something, understand something, or ship something?",
+        "What would be useful to finish before you leave this session?",
+        "Tell me what’s brewing.",
+        "What’s the next good move?",
+        "Hey — where is your attention pulling you?",
+        "What do you want NX to help carry today?",
+        "What’s the question behind the task?",
+        "Welcome. What are we curious about?",
+        "Hey — want to turn a rough thought into a plan?",
+        "What’s the thing you keep meaning to get back to?",
+        "What should we make clear first?",
+        "I’m ready when you are. What’s happening?",
+        "Hey — what deserves a closer look?",
+        "What are you hoping to discover today?",
+        "Want to start small or take on the big thing?",
+        "What’s changing in your world right now?",
+        "Hey — what can we make lighter?",
+        "What would you like to have in motion by the end of this?",
+        "What’s the story behind today’s work?",
+        "Welcome back to the workbench. What’s next?",
+        "Hey — do you have a direction, or should we find one together?",
+        "What’s the most useful place to begin?",
+        "What are we solving for?",
+        "Hey — bring me the half-formed version.",
+        "What’s on your mind, even if it’s not fully formed yet?",
+        "Should we follow the signal or inspect the noise?",
+        "What do you want to make real today?",
+        "Hey — what’s calling for your attention?",
+    ])
+

nxplora_cli/transport.py

@@ -0,0 +1,221 @@
+"""The whole of what `nx` says to Nexplora: send a message, follow what really happened, stop, and sign in.
+
+Standard library only. No brain, no model, no provider: every step is the same run a message typed in the chat makes.
+Redirects are never followed, so a credential only ever goes to the address it was issued for.
+"""
+from __future__ import annotations
+
+import http.client
+import json
+import ssl
+import uuid
+from dataclasses import dataclass
+from typing import Any, Callable, Iterator
+from urllib.parse import urlencode, urlsplit
+
+_TIMEOUT_S = 30
+# A run's stream may sit quiet for a long step. The server's own deadline ends it, so this is only for a dead connection.
+_STREAM_TIMEOUT_S = 660
+RUN_ID_HEADER = "x-nx-code-run-id"
+
+
+class SignedOut(Exception):
+    """The credential was refused."""
+
+
+class Refused(Exception):
+    """The server answered no. str() is one plain line for the person."""
+
+
+class Unreachable(Exception):
+    """Nothing answered."""
+
+
+def friendly(status: int, code: str, reason: str) -> str:
+    """One plain line for a refusal. A server's words are used only where they are already written for the person."""
+    if status == 402 or "credit" in code or "budget" in code:
+        return "You're out of credit. Add more in Nexplora to keep going."
+    if code == "session_not_found" or status == 404:
+        return "This session is gone. Open a new one in Nexplora."
+    if code == "session_busy":
+        return "This session is already working on something. Wait for it to finish, or stop it in the chat."
+    if code == "busy" or status == 429:
+        return "Nexplora is busy right now. Try again in a moment."
+    if code in {"workspace_expired", "workspace_unavailable"}:
+        return "This session's computer isn't available. Open a new session in Nexplora."
+    if code in {"approval_elsewhere", "ticket_message_only", "ticket_other_session"}:
+        return "This terminal can't do that. Do it in the chat beside it."
+    if status == 403 and reason:
+        return reason  # a plan or compute refusal: the same words the app shows
+    if code == "model_unavailable":
+        return "That model isn't available right now. Try again in a moment."
+    if status >= 500 or code in {"backend_unavailable", "plan_unavailable", "not_configured", "request_timeout"}:
+        return "Nexplora couldn't do that just now. Try again in a moment."
+    return "That didn't go through. Try again in a moment."
+
+
+def _connection(origin: str, timeout: float) -> http.client.HTTPConnection:
+    parts = urlsplit(origin)
+    if parts.scheme == "https":
+        context = ssl.create_default_context()
+        try:
+            import certifi
+
+            context.load_verify_locations(certifi.where())
+        except (ImportError, OSError, ssl.SSLError):
+            pass
+        return http.client.HTTPSConnection(parts.hostname or "", parts.port, timeout=timeout, context=context)
+    return http.client.HTTPConnection(parts.hostname or "", parts.port, timeout=timeout)
+
+
+def _headers(bearer: str | None, has_body: bool, accept: str = "application/json") -> dict[str, str]:
+    headers = {"accept": accept, "user-agent": "nx-cli"}
+    if has_body:
+        headers["content-type"] = "application/json"
+    if bearer:
+        headers["authorization"] = f"Bearer {bearer}"
+    return headers
+
+
+def _json_request(origin: str, method: str, path: str, bearer: str | None = None, body: object | None = None) -> tuple[int, dict[str, Any]]:
+    conn = _connection(origin, _TIMEOUT_S)
+    try:
+        conn.request(method, path, json.dumps(body) if body is not None else None, _headers(bearer, body is not None))
+        res = conn.getresponse()
+        raw = res.read(2_000_000)
+        try:
+            parsed = json.loads(raw) if raw else {}
+        except ValueError:
+            parsed = {}
+        return res.status, parsed if isinstance(parsed, dict) else {}
+    except (OSError, http.client.HTTPException) as err:
+        raise Unreachable() from err
+    finally:
+        conn.close()
+
+
+@dataclass(frozen=True)
+class RunStream:
+    run_id: str | None
+    events: Iterator[dict[str, Any]]
+
+
+def post_run(origin: str, bearer: str, session_id: str, task: str, resume_from_tick: int = 0) -> RunStream:
+    """One run request. A refusal raises; otherwise the events arrive as the server emits them."""
+    body: dict[str, object] = {"sessionId": session_id, "task": task, "idempotencyKey": f"nx-cli:{uuid.uuid4()}"}
+    if resume_from_tick > 0:
+        body["resumeFromTick"] = resume_from_tick
+    conn = _connection(origin, _STREAM_TIMEOUT_S)
+    try:
+        conn.request("POST", "/api/code/run", json.dumps(body), _headers(bearer, True, "application/x-ndjson"))
+        res = conn.getresponse()
+    except (OSError, http.client.HTTPException) as err:
+        conn.close()
+        raise Unreachable() from err
+    if res.status == 401:
+        conn.close()
+        raise SignedOut()
+    if res.status >= 300:
+        raw = res.read(64_000)
+        conn.close()
+        code, reason = "", ""
+        for line in raw.decode("utf-8", "replace").splitlines():
+            try:
+                doc = json.loads(line)
+            except ValueError:
+                continue
+            if isinstance(doc, dict):
+                code = str(doc.get("code") or doc.get("error") or "")
+                reason = str(doc.get("reason") or doc.get("message") or "")
+                break
+        raise Refused(friendly(res.status, code, reason))
+    return RunStream(res.getheader(RUN_ID_HEADER), _iter_events(conn, res))
+
+
+def _iter_events(conn: http.client.HTTPConnection, res: http.client.HTTPResponse) -> Iterator[dict[str, Any]]:
+    try:
+        while True:
+            line = res.readline(1_000_000)
+            if not line:
+                return
+            try:
+                doc = json.loads(line)
+            except ValueError:
+                continue
+            if isinstance(doc, dict) and isinstance(doc.get("event"), str):
+                yield doc
+    except (OSError, http.client.HTTPException) as err:
+        raise Unreachable() from err
+    finally:
+        conn.close()
+
+
+def read_events(origin: str, bearer: str, session_id: str, run_id: str, seq: int) -> tuple[list[dict[str, Any]], int, str]:
+    """What the session's run has logged since this mark, and the next mark."""
+    query = urlencode({"sessionId": session_id, "runId": run_id, "seq": seq})
+    status, doc = _json_request(origin, "GET", f"/api/nx-cli/session-events?{query}", bearer)
+    if status == 401:
+        raise SignedOut()
+    if status >= 300:
+        raise Refused(friendly(status, str(doc.get("error") or ""), ""))
+    events = doc.get("events")
+    mark = doc.get("mark")
+    next_seq, next_run = seq, run_id
+    if isinstance(mark, dict) and isinstance(mark.get("seq"), int) and isinstance(mark.get("runId"), str):
+        next_seq, next_run = mark["seq"], mark["runId"]
+    return [e for e in events if isinstance(e, dict)] if isinstance(events, list) else [], next_seq, next_run
+
+
+def stop_run(origin: str, bearer: str, session_id: str) -> bool:
+    status, doc = _json_request(origin, "POST", "/api/nx-cli/session-stop", bearer, {"sessionId": session_id})
+    if status == 401:
+        raise SignedOut()
+    return status < 300 and doc.get("ok") is True
+
+
+def create_session(origin: str, bearer: str) -> str:
+    status, doc = _json_request(origin, "POST", "/api/nx-cli/sessions", bearer, {})
+    if status == 401:
+        raise SignedOut()
+    session_id = doc.get("sessionId")
+    if status >= 300 or not isinstance(session_id, str):
+        raise Refused(friendly(status, str(doc.get("error") or ""), str(doc.get("message") or "")))
+    return session_id
+
+
+@dataclass(frozen=True)
+class DeviceCode:
+    device_code: str
+    user_code: str
+    link: str
+    interval_s: float
+    expires_in_s: float
+
+
+def start_device_grant(origin: str, version: str, device_name: str) -> DeviceCode:
+    status, doc = _json_request(origin, "POST", "/api/oauth/device/code", None, {"client_name": "NX CLI", "client_version": version, "device_name": device_name})
+    device_code, user_code, link = doc.get("device_code"), doc.get("user_code"), doc.get("verification_uri_complete")
+    if status >= 300 or not isinstance(device_code, str) or not isinstance(user_code, str) or not isinstance(link, str):
+        raise Refused(friendly(status, str(doc.get("error") or ""), ""))
+    return DeviceCode(device_code, user_code, link, float(doc.get("interval") or 5), float(doc.get("expires_in") or 900))
+
+
+def poll_device_grant(origin: str, device_code: str) -> dict[str, Any] | str:
+    """The tokens, or "pending", "denied" or "expired"."""
+    status, doc = _json_request(origin, "POST", "/api/oauth/token", None, {"device_code": device_code})
+    if status < 300 and isinstance(doc.get("access_token"), str):
+        return doc
+    error = doc.get("error")
+    if error == "authorization_pending" or status >= 500:
+        return "pending"
+    return "denied" if error == "access_denied" else "expired"
+
+
+def refresh_login(origin: str, refresh_token: str) -> tuple[str, str] | None:
+    status, doc = _json_request(origin, "POST", "/api/oauth/refresh", None, {"refresh_token": refresh_token})
+    access, refresh = doc.get("access_token"), doc.get("refresh_token")
+    return (access, refresh) if status < 300 and isinstance(access, str) and isinstance(refresh, str) else None
+
+
+def revoke_device_session(origin: str, bearer: str, device_session_id: str) -> None:
+    _json_request(origin, "DELETE", f"/api/oauth/sessions/{device_session_id}", bearer)