chartremotely 0.2.0__py3-none-any.whl

chartremotely/resolve.py

@@ -0,0 +1,207 @@
+"""Turn a spoken security name into a ticker.
+
+Speech recognition is the weak link in voice-driven charting. Dictation
+matches against the whole English language, so "Palantir" arrives as
+"Volunteer" and "Qualcomm" as "Callalon". This module repairs what it can
+without ever inventing an answer: every tier is gated so that noise is
+refused rather than mapped confidently onto some unrelated company.
+
+Matching runs in tiers, highest score wins:
+
+    1000  the query IS a ticker
+     900  exact company name
+     800  the name starts with the query
+     700  every spoken word appears in the name
+     650  the query COVERS the name, plus extra words   ("john deere")
+     600  consonant skeletons match                     ("volunteer")
+     400  fuzzy, as a last resort
+"""
+
+from __future__ import annotations
+
+import difflib
+import re
+
+__all__ = ["candidates", "normalize", "phonetic", "resolve", "spelled"]
+
+# Corporate furniture, stripped from both sides before comparison. "and"
+# is here because "&" normalises to it, so DEERE & CO reduces to "deere".
+SUFFIXES = {
+    "inc", "incorporated", "corp", "corporation", "co", "company", "ltd",
+    "limited", "plc", "lp", "llc", "holdings", "holding", "group", "trust",
+    "the", "sa", "nv", "ag", "adr", "ads", "class", "a", "b", "c", "etf",
+    "fund", "common", "stock", "shares", "new", "series", "and",
+}
+
+# Filler, pronouns and contraction fragments. Without these the phonetic
+# tier maps conversation onto companies: "whatever" codes like DOV, and
+# "i don t" codes exactly like "at and t".
+STOPWORDS = {
+    "the", "a", "an", "and", "um", "uh", "er", "hey", "hi", "ok", "okay",
+    "what", "who", "how", "why", "when", "yes", "no", "please", "thanks",
+    "siri", "show", "me", "go", "to", "open", "chart", "stock", "symbol",
+    "it", "that", "this", "is", "whatever", "something", "nothing",
+    "anything", "everything", "nevermind", "never", "mind", "forget",
+    "cancel", "stop", "quit", "wait", "hold", "on", "hmm", "hello",
+    "sorry", "maybe", "dunno", "know", "guess", "again", "i", "you", "we",
+    "my", "your", "don", "dont", "doesn", "doesnt", "can", "cant", "wont",
+    "im", "ive", "id", "let", "just", "well", "yeah", "yep", "nope", "like",
+}
+
+# Transcripts that discard the consonant skeleton entirely, so no algorithm
+# recovers them, plus renames the SEC registry has not caught up with.
+# Grow this only from transcripts actually observed in the wild.
+ALIASES = {
+    "kuehn": "COIN",        # nasal "Coin"
+    "koon": "COIN",
+    "pierre": "PLTR",       # Siri's web-search guess for "Palantir"
+    "callalon": "QCOM",     # nasal "Qualcomm"
+    "ge aerospace": "GE",   # still filed as GENERAL ELECTRIC CO
+    "ge aviation": "GE",
+}
+
+# Soundex-style consonant coding: vowels carry almost no information in a
+# mis-hearing, consonants carry nearly all of it.
+_SOUNDEX = {
+    **dict.fromkeys("bfpv", "1"), **dict.fromkeys("cgjkqsxz", "2"),
+    **dict.fromkeys("dt", "3"), "l": "4",
+    **dict.fromkeys("mn", "5"), "r": "6",
+}
+
+LETTER_WORDS = {
+    "ay": "a", "eh": "a", "bee": "b", "be": "b", "see": "c", "sea": "c",
+    "dee": "d", "de": "d", "ee": "e", "eff": "f", "ef": "f", "gee": "g",
+    "aitch": "h", "haitch": "h", "eye": "i", "aye": "i", "jay": "j",
+    "kay": "k", "el": "l", "ell": "l", "em": "m", "en": "n", "oh": "o",
+    "owe": "o", "pee": "p", "pea": "p", "cue": "q", "queue": "q", "ar": "r",
+    "are": "r", "arr": "r", "ess": "s", "es": "s", "tee": "t", "tea": "t",
+    "you": "u", "yoo": "u", "vee": "v", "doubleyou": "w", "ex": "x",
+    "ecks": "x", "why": "y", "wye": "y", "zee": "z", "zed": "z",
+}
+
+MIN_PHONETIC = 3          # shorter skeletons collide with everything
+PHONETIC_MIN_RATIO = 0.45  # a skeleton match must also look plausible
+MIN_PREFIX = 4
+MIN_FUZZY = 5
+FUZZY_FLOOR = 0.82
+NAME_COVERAGE = 0.6       # how much of the company name the query must cover
+
+
+def normalize(text: str) -> str:
+    t = text.lower().replace("&", " and ")
+    return " ".join(re.sub(r"[^a-z0-9 ]+", " ", t).split())
+
+
+def strip_suffixes(norm: str) -> str:
+    return " ".join(w for w in norm.split() if w not in SUFFIXES) or norm
+
+
+def phonetic(text: str) -> str:
+    """Consonant skeleton. 'palantir' and 'volunteer' both give '14536'."""
+    out: list[str] = []
+    last = ""
+    for ch in text.lower():
+        code = _SOUNDEX.get(ch)
+        if code and code != last:
+            out.append(code)
+        if ch.isalpha():
+            last = code or ""
+    return "".join(out)
+
+
+def deinflect(word: str) -> set[str]:
+    """Dictation returns inflected words: 'volunteered' for 'Palantir'."""
+    forms = {word}
+    for suf in ("ing", "ed", "es", "s"):
+        if word.endswith(suf) and len(word) - len(suf) >= 5:
+            forms.add(word[: -len(suf)])
+    return forms
+
+
+def spelled(query: str) -> str | None:
+    """'p l t r' / 'pee ell tee are' / 'P-L-T-R' -> 'PLTR', else None."""
+    raw = re.sub(r"[^a-z0-9 ]+", " ", query.lower()).replace("double u", "doubleyou")
+    toks = raw.split()
+    if not 2 <= len(toks) <= 6:
+        return None
+    out = []
+    for t in toks:
+        if len(t) == 1 and t.isalpha():
+            out.append(t)
+        elif t in LETTER_WORDS:
+            out.append(LETTER_WORDS[t])
+        else:
+            return None
+    return "".join(out).upper()
+
+
+def candidates(query: str, rows: list[dict]) -> list[tuple[float, str, str]]:
+    """Score every row. `rows` are {"t": ticker, "n": name, "r": rank}."""
+    q = normalize(query)
+    qs = strip_suffixes(q)
+    tokens = set(qs.split()) - STOPWORDS
+    if not tokens:
+        return []
+    qs = " ".join(w for w in qs.split() if w not in STOPWORDS) or qs
+    qtokens = tokens
+
+    forms = set()
+    for base in (q, qs):
+        forms |= deinflect(base)
+    skeletons = {p for p in (phonetic(f) for f in forms) if len(p) >= MIN_PHONETIC}
+
+    out = []
+    for row in rows:
+        ticker, name, rank = row["t"], row["n"], row.get("r", 0)
+        n = normalize(name)
+        ns = strip_suffixes(n)
+        heads = {ns, ns.split()[0]} if ns else {""}
+
+        if q == ticker.lower():
+            score = 1000.0
+        elif qs == ns or q == n:
+            score = 900.0
+        elif len(qs) >= MIN_PREFIX and (ns.startswith(qs) or n.startswith(q)):
+            score = 800 - min(len(ns) - len(qs), 99) * 0.1
+        elif qtokens <= set(ns.split()) and all(len(t) >= 3 for t in qtokens):
+            score = 700 - min(len(ns.split()) - len(qtokens), 99) * 0.5
+        elif ns and (overlap := qtokens & set(ns.split())):
+            # The query CONTAINS the company name plus extras: "john deere"
+            # for DEERE & CO. Requiring the query to cover most of the NAME
+            # keeps a single shared word from winning - otherwise "in video"
+            # matches Video River Networks.
+            cov = len(overlap) / max(len(set(ns.split())), 1)
+            strong = any(len(w) >= 4 and w not in SUFFIXES for w in overlap)
+            if not strong or cov < NAME_COVERAGE:
+                continue
+            score = 650 + cov * 60
+        elif skeletons and any(phonetic(h) in skeletons for h in heads):
+            ratio = max(difflib.SequenceMatcher(None, a, h).ratio()
+                        for a in forms for h in heads)
+            if ratio < PHONETIC_MIN_RATIO:
+                continue
+            score = 600 + ratio * 60
+        elif len(qs) >= MIN_FUZZY:
+            ratio = max(difflib.SequenceMatcher(None, qs, h).ratio() for h in heads)
+            if ratio < FUZZY_FLOOR:
+                continue
+            score = 400 + ratio * 100
+        else:
+            continue
+
+        out.append((score - rank * 0.002, ticker, name))
+
+    out.sort(key=lambda x: -x[0])
+    return out
+
+
+def resolve(query: str, rows: list[dict]) -> str | None:
+    """Best ticker for a spoken query, or None when nothing is convincing."""
+    letters = spelled(query)
+    if letters and any(r["t"] == letters for r in rows):
+        return letters
+    direct = ALIASES.get(normalize(query))
+    if direct:
+        return direct
+    ranked = candidates(query, rows)
+    return ranked[0][1] if ranked else None

chartremotely/scales.py

@@ -0,0 +1,77 @@
+"""Spoken time-frame vocabulary. Pure logic, no macOS dependency.
+
+Kept apart from the driver so it can be imported anywhere - by CI on Linux,
+and by the operator, which needs to validate a spoken phrase before it has
+any agent to send it to.
+
+The mnemonics are chosen for phonetic distance rather than literal
+accuracy. Digits are the worst thing to say to a recogniser: "fifteen" and
+"fifty" collide, "one" and "won" collide. None of these ten do.
+"""
+
+from __future__ import annotations
+
+import re
+
+MNEMONIC = {
+    "1d1m": "minute", "5d5m": "scalp", "5d15m": "quarter", "10d30m": "half",
+    "20d1h": "hourly", "180d4h": "swing", "1y1d": "daily", "3yw": "weekly",
+    "1d133t": "ticks", "1d10t": "micro",
+}
+
+ALIAS = {
+    "minute": "1d1m", "scalp": "5d5m", "quarter": "5d15m", "half": "10d30m",
+    "hourly": "20d1h", "swing": "180d4h", "daily": "1y1d", "weekly": "3yw",
+    "ticks": "1d133t", "micro": "1d10t",
+    # variants people actually say
+    "tick": "1d133t", "ten tick": "1d10t", "quarter hour": "5d15m",
+    "half hour": "10d30m", "hour": "20d1h", "day": "1y1d", "week": "3yw",
+    "intraday": "1d1m", "swing trade": "180d4h",
+}
+
+AS_IS = {"as is", "as-is", "asis", "same", "leave it", "unchanged",
+         "no change", "keep it", "current", "skip", "none", ""}
+
+_WORDS = {"one": 1, "two": 2, "three": 3, "four": 4, "five": 5, "six": 6,
+          "seven": 7, "eight": 8, "nine": 9, "ten": 10, "fifteen": 15,
+          "twenty": 20, "thirty": 30, "sixty": 60, "ninety": 90}
+_UNIT = {"d": "d", "day": "d", "days": "d", "daily": "d", "y": "y",
+         "year": "y", "years": "y", "w": "w", "week": "w", "weekly": "w",
+         "weeks": "w", "m": "m", "min": "m", "minute": "m", "minutes": "m",
+         "h": "h", "hour": "h", "hours": "h", "t": "t", "tick": "t",
+         "ticks": "t"}
+
+
+def canon(text: str) -> str:
+    """'5 D : 5m' and 'five day five minute' both give '5d5m'.
+
+    Returns "" when nothing parses. Callers MUST treat that as a refusal:
+    every string ends with "", so a loose endswith match against menu
+    labels would otherwise select whichever preset came first.
+    """
+    s = re.sub(r"[^a-z0-9 ]", " ", text.lower().replace(":", " ").replace("/", " "))
+    for word, n in _WORDS.items():
+        s = re.sub(rf"\b{word}\b", str(n), s)
+    s = re.sub(r"(\d)\s*([a-z])", r"\1\2", s)
+    out = []
+    for token in s.split():
+        m = re.match(r"^(\d+)([a-z]+)$", token)
+        if m and m.group(2) in _UNIT:
+            out.append(m.group(1) + _UNIT[m.group(2)])
+        elif token in _UNIT and out:
+            out.append(_UNIT[token])
+    return "".join(out)
+
+
+def to_code(phrase: str) -> str:
+    return ALIAS.get(phrase.lower().strip(), canon(phrase))
+
+
+def mnemonic_for(phrase: str) -> str | None:
+    """The word we say back, or None if the phrase names no preset."""
+    return MNEMONIC.get(to_code(phrase))
+
+
+def spoken_options() -> str:
+    """What to read aloud when someone says something unrecognised."""
+    return ", ".join(MNEMONIC.values())

chartremotely/server.py

@@ -0,0 +1,69 @@
+"""Loopback listener fronting the command vocabulary.
+
+Bound to 127.0.0.1 only. TLS is terminated by Tailscale Serve, which proxies
+to this socket - so the wire carries a real certificate while the socket is
+never exposed on the LAN.
+
+Clients talk to it with an ordinary HTTPS request, which matters more than it
+sounds: Shortcuts' SSH action re-prompts for permission every time the
+shortcut is edited and needs a key per device, while Get Contents of URL
+needs neither.
+"""
+
+from __future__ import annotations
+
+import json
+import secrets
+import urllib.parse
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+from . import config
+from .vocab import dispatch
+
+
+class Handler(BaseHTTPRequestHandler):
+    token = ""
+
+    def _reply(self, code: int, text: str) -> None:
+        body = (text + "\n").encode()
+        self.send_response(code)
+        self.send_header("Content-Type", "text/plain; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _authorised(self, offered) -> bool:
+        return bool(offered) and secrets.compare_digest(str(offered), self.token)
+
+    def do_POST(self) -> None:
+        if urllib.parse.urlparse(self.path).path not in ("/chart", "/"):
+            return self._reply(404, "ERR not found")
+        if not self._authorised(self.headers.get("X-Token")):
+            return self._reply(403, "ERR forbidden")
+        length = int(self.headers.get("Content-Length") or 0)
+        raw = self.rfile.read(length).decode("utf-8", "replace").strip()
+        # Shortcuts posts JSON most cleanly; curl and scripts post raw text.
+        if raw.startswith("{"):
+            try:
+                raw = str(json.loads(raw).get("cmd") or "").strip()
+            except ValueError:
+                return self._reply(400, "ERR bad JSON")
+        self._reply(200, dispatch(raw))
+
+    def do_GET(self) -> None:
+        parsed = urllib.parse.urlparse(self.path)
+        if parsed.path not in ("/chart", "/"):
+            return self._reply(404, "ERR not found")
+        query = urllib.parse.parse_qs(parsed.query)
+        if not self._authorised((query.get("t") or [None])[0]):
+            return self._reply(403, "ERR forbidden")
+        self._reply(200, dispatch((query.get("cmd") or [""])[0].strip()))
+
+    def log_message(self, *args) -> None:
+        """Silence. Requests carry spoken input; do not write it to a log."""
+
+
+def serve(port: int | None = None) -> None:
+    cfg = config.load()
+    Handler.token = config.ensure_token()
+    HTTPServer(("127.0.0.1", port or cfg["port"]), Handler).serve_forever()

chartremotely/services.py

@@ -0,0 +1,116 @@
+"""The agent's two background services, and the one-shot checks run like them.
+
+``serve`` (the listener a Shortcut reaches over the tailnet) and ``relay``
+(the outbound poll to the operator) run under launchd as separate agents, so
+a relay that loses the network cannot take the listener down with it.
+
+macOS grants Accessibility and Screen Recording to the process that asks,
+and a launchd job is its own process, distinct from the Terminal that ran
+``setup``. So the permission probe runs as a one-shot launchd job too: what
+it reports is what the services will actually have.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+from xml.sax.saxutils import escape
+
+LABELS = {"serve": "com.chartremotely.serve", "relay": "com.chartremotely.relay"}
+PROBE_LABEL = "com.chartremotely.permissions"
+AGENTS_DIR = Path(os.path.expanduser("~/Library/LaunchAgents"))
+LOG_DIR = Path(os.path.expanduser("~/Library/Logs"))
+
+
+def executable() -> str:
+    """The installed ``chartremotely`` command, absolute."""
+    found = shutil.which("chartremotely")
+    return os.path.realpath(found) if found else os.path.realpath(sys.argv[0])
+
+
+def render(label: str, args: list[str], *, keep_alive: bool, log: Path) -> str:
+    """A LaunchAgent plist. Every value is escaped; nothing secret is ever in it."""
+    arguments = "\n".join(f"    <string>{escape(a)}</string>" for a in args)
+    alive = "<true/>" if keep_alive else "<false/>"
+    return f"""<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>{escape(label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+{arguments}
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key>{alive}
+  <key>ThrottleInterval</key><integer>10</integer>
+  <key>StandardOutPath</key><string>{escape(str(log))}</string>
+  <key>StandardErrorPath</key><string>{escape(str(log))}</string>
+</dict>
+</plist>
+"""
+
+
+def _domain() -> str:
+    return f"gui/{os.getuid()}"
+
+
+def loaded(label: str) -> bool:
+    return subprocess.run(["launchctl", "print", f"{_domain()}/{label}"],
+                          capture_output=True, check=False).returncode == 0
+
+
+def install(command: str) -> Path:
+    """Write and (re)start one service. Idempotent."""
+    label = LABELS[command]
+    path = AGENTS_DIR / f"{label}.plist"
+    AGENTS_DIR.mkdir(parents=True, exist_ok=True)
+    path.write_text(render(label, [executable(), command], keep_alive=True,
+                           log=LOG_DIR / f"chartremotely-{command}.log"))
+    if loaded(label):
+        subprocess.run(["launchctl", "bootout", f"{_domain()}/{label}"], capture_output=True, check=False)
+    subprocess.run(["launchctl", "bootstrap", _domain(), str(path)], check=True)
+    return path
+
+
+def probe_permissions(request: bool, out: Path, timeout: float = 30.0) -> dict:
+    """Run ``chartremotely permissions`` as a one-shot launchd job and read its answer."""
+    AGENTS_DIR.mkdir(parents=True, exist_ok=True)
+    path = AGENTS_DIR / f"{PROBE_LABEL}.plist"
+    out.unlink(missing_ok=True)
+    args = [executable(), "permissions", "--out", str(out)] + (["--request"] if request else [])
+    path.write_text(render(PROBE_LABEL, args, keep_alive=False, log=LOG_DIR / "chartremotely-permissions.log"))
+    subprocess.run(["launchctl", "bootout", f"{_domain()}/{PROBE_LABEL}"], capture_output=True, check=False)
+    subprocess.run(["launchctl", "bootstrap", _domain(), str(path)], check=True)
+    try:
+        deadline = time.time() + timeout
+        while time.time() < deadline and not out.exists():
+            time.sleep(0.5)
+        return json.loads(out.read_text()) if out.exists() else {}
+    finally:
+        subprocess.run(["launchctl", "bootout", f"{_domain()}/{PROBE_LABEL}"], capture_output=True, check=False)
+        path.unlink(missing_ok=True)
+
+
+def permissions(request: bool) -> dict:
+    """What this process has been granted; with ``request``, ask macOS to prompt."""
+    result = {"python": os.path.realpath(sys.executable), "accessibility": False, "screen_recording": False}
+    try:
+        from ApplicationServices import AXIsProcessTrustedWithOptions, kAXTrustedCheckOptionPrompt
+        result["accessibility"] = bool(AXIsProcessTrustedWithOptions({kAXTrustedCheckOptionPrompt: request}))
+    except ImportError:
+        pass
+    try:
+        import Quartz
+        granted = bool(Quartz.CGPreflightScreenCaptureAccess())
+        if not granted and request:
+            granted = bool(Quartz.CGRequestScreenCaptureAccess())
+        result["screen_recording"] = granted
+    except ImportError:
+        pass
+    return result

chartremotely/setup.py

@@ -0,0 +1,202 @@
+"""``chartremotely setup``: from a fresh Mac to a paired, voice-driven display.
+
+Each step checks first and skips what is already done, so running setup
+again is always safe:
+
+1. **Identity.** Either the patron's existing npub, proven by the Nostr DM
+   challenge (setup never sees their nsec), or a key made here for them.
+   A made key is kept for the human - their Keychain, then Safari's saved
+   passwords - and used once, in memory, to sign the pairing. It is never
+   written to this agent's config.
+2. **Pairing**, without a code to copy: setup adopts this machine's code itself.
+3. **Tailscale**: the Mac's tailnet address, with ``/chart`` forwarded to the agent.
+4. **Services**: the listener and the relay, under launchd.
+5. **Permissions**: Accessibility and Screen Recording, asked for by the
+   services' own Python, since that is the process macOS grants them to.
+6. **The voice Shortcut**: this Mac's copy, opened for import.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import tempfile
+from collections.abc import Callable
+from pathlib import Path
+
+from . import config, mcpclient, relay
+
+OPERATOR_URL = "https://chartremotely-mcp.fastmcp.app"
+SITE = "https://chartremotely.tollbooth-dpyc.com"
+SAVE_KEY_PAGE = f"{SITE}/#/save-key"
+
+Ask = Callable[[str], str]
+Say = Callable[[str], None]
+
+
+class SetupError(RuntimeError):
+    """A step that cannot continue, with the reason a person can act on."""
+
+
+# -- identity -----------------------------------------------------------------
+
+def prove_by_dm(client: mcpclient.Client, npub: str, ask: Ask, say: Say) -> str:
+    """Prove an existing npub by the Secure Courier DM. Returns the dpop_token.
+
+    The human answers from their own Nostr client, so no key passes through here.
+    """
+    sent = client.call("chart_request_npub_proof", {
+        "patron_npub": npub, "verify_at": SITE,
+        "reason": "You asked to pair a Mac with ChartRemotely."})
+    phrase = sent.get("dpop_token")
+    if not phrase:
+        raise SetupError(sent.get("error") or "the operator did not send a proof request")
+    say(f"A Nostr DM is on its way to {npub[:12]}…")
+    say(f"Its confirmation code is: {phrase}")
+    say("Reply to the DM from your Nostr client only if the codes match.")
+    ask("Press Return once you have replied… ")
+    got = client.call("chart_receive_npub_proof", {"patron_npub": npub, "dpop_token": phrase})
+    if got.get("error"):
+        raise SetupError(got["error"])
+    return got.get("dpop_token") or phrase
+
+
+def new_key() -> tuple[str, str]:
+    """A fresh Nostr keypair, made by the SDK's own key code. Returns (npub, nsec)."""
+    from pynostr.key import PrivateKey  # the tollbooth-dpyc SDK's key library
+
+    key = PrivateKey()
+    return key.public_key.bech32(), key.bech32()
+
+
+def sign_once(nsec: str, tool: str) -> str:
+    """One kind-27235 proof for one tool call, signed by the SDK."""
+    from tollbooth.identity_proof import create_proof
+
+    return create_proof(nsec, tool)
+
+
+def keep_for_human(npub: str, nsec: str, ask: Ask, say: Say) -> None:
+    """Store a made key in the Keychain and let Safari save it to iCloud Passwords."""
+    from . import keystore
+
+    keystore.save(npub, nsec)
+    say("Your key is saved in this Mac's Keychain, under “ChartRemotely — Nostr key”.")
+    say("Next, Safari saves it to your iCloud Passwords so your other devices have it.")
+    timer = keystore.copy_briefly(nsec)
+    try:
+        subprocess.run(["open", f"{SAVE_KEY_PAGE}?npub={npub}"], check=False)
+        say("Paste the key (⌘V) into the page, press Save, and accept Safari's offer to save it.")
+        ask("Press Return when Safari has saved it… ")
+    finally:
+        timer.cancel()
+        keystore.clear_if_unchanged(nsec)
+
+
+def identity(client: mcpclient.Client, ask: Ask, say: Say) -> tuple[str, str]:
+    """Who owns this display, proven. Returns (npub, proof for chart_pair_agent)."""
+    say("Your Nostr identity owns this display.")
+    say("  1  I have an npub (I'll answer a Nostr DM to prove it)")
+    say("  2  Use a key saved on this Mac")
+    say("  3  Make me a new key")
+    choice = ask("Choose 1, 2 or 3: ").strip()
+    if choice == "1":
+        npub = ask("Your npub: ").strip()
+        if not npub.startswith("npub1"):
+            raise SetupError("that is not an npub")
+        return npub, prove_by_dm(client, npub, ask, say)
+    if choice == "2":
+        from . import keystore
+
+        saved = keystore.saved_npubs()
+        if not saved:
+            raise SetupError("no ChartRemotely key is saved on this Mac yet; choose 1 or 3")
+        for i, npub in enumerate(saved, 1):
+            say(f"  {i}  {npub}")
+        picked = saved[int(ask("Which key? ").strip() or "1") - 1]
+        nsec = keystore.load(picked)  # macOS asks the human first
+        try:
+            return picked, sign_once(nsec, "chart_pair_agent")
+        finally:
+            del nsec
+    if choice == "3":
+        npub, nsec = new_key()
+        try:
+            say(f"Your new npub is {npub}")
+            keep_for_human(npub, nsec, ask, say)
+            return npub, sign_once(nsec, "chart_pair_agent")
+        finally:
+            del nsec
+    raise SetupError("choose 1, 2 or 3")
+
+
+# -- pairing ------------------------------------------------------------------
+
+def pair(client: mcpclient.Client, base: str, npub: str, proof: str, label: str) -> dict:
+    """Adopt this machine's pairing code with the patron's proof, then collect."""
+    code, expires_in = relay.open_code(base)
+    answer = client.call("chart_pair_agent", {"code": code, "label": label, "npub": npub, "dpop_token": proof})
+    if not answer.get("ok"):
+        raise SetupError(answer.get("error") or "the operator refused the pairing")
+    return relay.collect(base, code, expires_in)
+
+
+# -- the whole run ------------------------------------------------------------
+
+def run(ask: Ask = input, say: Say = print, operator_url: str = OPERATOR_URL) -> int:
+    cfg = config.load()
+    base = (cfg.get("operator_url") or operator_url).rstrip("/")
+    token = config.ensure_token()
+
+    # 1-2. Identity and pairing, unless this Mac is already paired.
+    if cfg.get("agent_id") and cfg.get("agent_secret"):
+        say(f"This Mac is already paired ({cfg['agent_id']}).")
+        npub = ""
+    else:
+        client = mcpclient.Client(base)
+        npub, proof = identity(client, ask, say)
+        label = ask("Name this display (e.g. Desk, Office wall): ").strip() or "display"
+        pair(client, base, npub, proof, label)
+        del proof
+        say(f"Paired as “{label}”.")
+
+    # 3. Tailscale.
+    from . import tailnet
+
+    url = tailnet.chart_url(tailnet.status())
+    tailnet.serve(int(cfg.get("port") or 8899))
+    say(f"Your Shortcut will reach this Mac at {url}")
+
+    # 4. Services.
+    from . import services
+
+    for command in ("serve", "relay"):
+        services.install(command)
+    say("The listener and the relay are running, and start with this Mac.")
+
+    # 5. Permissions, as the services' own Python sees them.
+    probe = Path(tempfile.gettempdir()) / "chartremotely-permissions.json"
+    granted = services.probe_permissions(request=True, out=probe)
+    while not (granted.get("accessibility") and granted.get("screen_recording")):
+        python = granted.get("python", "the Python that runs ChartRemotely")
+        missing = [name for name, key in (("Accessibility", "accessibility"),
+                                          ("Screen Recording", "screen_recording")) if not granted.get(key)]
+        say(f"macOS needs you to allow {' and '.join(missing)} for: {python}")
+        pane = "Privacy_Accessibility" if not granted.get("accessibility") else "Privacy_ScreenCapture"
+        subprocess.run(["open", f"x-apple.systempreferences:com.apple.preference.security?{pane}"], check=False)
+        ask("Turn it on in System Settings, then press Return… ")
+        granted = services.probe_permissions(request=False, out=probe)
+    say("Accessibility and Screen Recording are allowed.")
+
+    # 6. The voice Shortcut.
+    from . import shortcut
+
+    made = shortcut.build(url, token)
+    subprocess.run(["open", str(made)], check=False)
+    say("Add the ChartRemotely Shortcut when it opens; iCloud brings it to your iPhone, iPad and Watch.")
+
+    say("")
+    say("Done. Say “Hey Siri, ChartRemotely” from any of your devices.")
+    if npub:
+        say(f"Your npub: {npub}")
+    say(f"Sign in at {SITE} to see your screens.")
+    return 0