chartremotely 0.2.0__py3-none-any.whl

chartremotely/keystore.py

@@ -0,0 +1,101 @@
+"""Keep a patron's Nostr key for the patron, never for this agent.
+
+A key made by ``setup`` belongs to the human. It goes into their login
+Keychain as an internet password for the ChartRemotely site, and it is
+handed to Safari once, through the clipboard, so Safari can save it to
+iCloud Passwords where their other devices and apps find it. A command-line
+tool cannot write a synchronizable Keychain item itself (that needs an
+entitled app: ``errSecMissingEntitlement``), which is why Safari does the
+syncing.
+
+Nothing here writes the key to the agent's config, a log, a URL or a
+command line. It travels as ``kSecValueData`` or on a pipe, and nowhere else.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import threading
+
+SERVER = "chartremotely.tollbooth-dpyc.com"
+LABEL = "ChartRemotely — Nostr key"
+CLIPBOARD_SECONDS = 60
+
+ERR_DUPLICATE = -25299
+ERR_NOT_FOUND = -25300
+
+
+class KeystoreError(RuntimeError):
+    """The Keychain refused, and says why by its status code."""
+
+
+def _security():
+    import Security  # lazy: macOS only
+
+    return Security
+
+
+def item_query(npub: str) -> dict:
+    """The attributes that name one saved key. The secret is never among them."""
+    S = _security()
+    return {S.kSecClass: S.kSecClassInternetPassword,
+            S.kSecAttrServer: SERVER,
+            S.kSecAttrAccount: npub}
+
+
+def save(npub: str, nsec: str) -> None:
+    """Store (or replace) the patron's key in their login Keychain."""
+    S = _security()
+    secret = nsec.encode()
+    status = S.SecItemAdd({**item_query(npub), S.kSecAttrLabel: LABEL, S.kSecValueData: secret}, None)[0]
+    if status == ERR_DUPLICATE:
+        status = S.SecItemUpdate(item_query(npub), {S.kSecValueData: secret})
+    if status != 0:
+        raise KeystoreError(f"the Keychain refused to save the key (status {status})")
+
+
+def saved_npubs() -> list[str]:
+    """npubs with a key saved for this site. Reads names only, never secrets."""
+    S = _security()
+    query = {S.kSecClass: S.kSecClassInternetPassword, S.kSecAttrServer: SERVER,
+             S.kSecReturnAttributes: True, S.kSecMatchLimit: S.kSecMatchLimitAll}
+    status, found = S.SecItemCopyMatching(query, None)
+    if status == ERR_NOT_FOUND or not found:
+        return []
+    if status != 0:
+        raise KeystoreError(f"the Keychain could not be read (status {status})")
+    return sorted(str(item.get(S.kSecAttrAccount) or "") for item in found if item.get(S.kSecAttrAccount))
+
+
+def load(npub: str) -> str:
+    """The saved key for one npub. macOS asks the human before it answers."""
+    S = _security()
+    status, data = S.SecItemCopyMatching({**item_query(npub), S.kSecReturnData: True}, None)
+    if status != 0 or data is None:
+        raise KeystoreError(f"no key saved for {npub} (status {status})")
+    return bytes(data).decode()
+
+
+# -- the clipboard, for Safari's Save password prompt --------------------------
+
+def copy(secret: str) -> None:
+    """Put a secret on the clipboard over a pipe, never on a command line."""
+    subprocess.run(["pbcopy"], input=secret.encode(), check=True)
+
+
+def clear_if_unchanged(secret: str) -> bool:
+    """Empty the clipboard, but only if it still holds this secret."""
+    current = subprocess.run(["pbpaste"], capture_output=True, check=False).stdout.decode()
+    if current != secret:
+        return False
+    subprocess.run(["pbcopy"], input=b"", check=True)
+    return True
+
+
+def copy_briefly(secret: str, seconds: float = CLIPBOARD_SECONDS) -> threading.Timer:
+    """Copy a secret and clear it again after ``seconds``, unless something replaced it."""
+    copy(secret)
+    timer = threading.Timer(seconds, clear_if_unchanged, args=(secret,))
+    timer.daemon = True
+    timer.start()
+    return timer

chartremotely/layout.py

@@ -0,0 +1,106 @@
+"""Find controls without assuming where on screen anything lives.
+
+thinkorswim layouts differ per user, and one user's layout differs through
+the day - charts get rearranged, panes resized, grids switched. Anything
+that sweeps a fixed screen region works on the machine it was written on
+and nowhere else.
+
+The accessibility tree is no help on its own: the chart's controls are not
+reachable through ``AXChildren``. The combo box holding the symbol reports
+the window as its parent, yet the window does not list it as a child. The
+link exists upward but not downward, so hit-testing is the only way in.
+
+What the tree *does* expose reliably is the container layout - the split
+groups and tab groups that tile the window. So: ask the tree where the
+panes are, then hit-test relative to each pane's own bounds. Move the chart
+anywhere and the search follows it.
+"""
+
+from __future__ import annotations
+
+from . import ax
+
+# Panes smaller than this cannot be a chart.
+MIN_PANE_W, MIN_PANE_H = 400, 300
+
+# Charting apps put the symbol entry and the toolbar in a band at the top of
+# the pane. Searching that band first is an optimisation, not an assumption:
+# discovery falls back to the whole pane.
+BAND_HEIGHT = 140
+STEP_X, STEP_Y = 12, 6
+
+CONTAINER_ROLES = ("AXTabGroup", "AXSplitGroup", "AXScrollArea", "AXGroup")
+
+
+def panes(ax_app, window_prefix: str) -> list[tuple[int, int, int, int]]:
+    """Candidate chart panes as (x, y, w, h), largest first.
+
+    Derived entirely from what the tree reports, so it holds wherever the
+    user has dragged things.
+    """
+    window = ax.window(ax_app, window_prefix)
+    if window is None:
+        return []
+    found: set[tuple[int, int, int, int]] = set()
+
+    def visit(element):
+        if ax.attr(element, "AXRole") not in CONTAINER_ROLES:
+            return
+        p, s = ax.position(element), ax.size(element)
+        if p and s and s.width >= MIN_PANE_W and s.height >= MIN_PANE_H:
+            found.add((int(p.x), int(p.y), int(s.width), int(s.height)))
+
+    ax.walk(window, visit, budget=[400000])
+    # Whole-window fallback: a layout may expose no qualifying container.
+    p, s = ax.position(window), ax.size(window)
+    if p and s:
+        found.add((int(p.x), int(p.y), int(s.width), int(s.height)))
+    return sorted(found, key=lambda r: -(r[2] * r[3]))
+
+
+def scan(ax_app, rect, matches, *, band: int | None = BAND_HEIGHT,
+         step_x: int = STEP_X, step_y: int = STEP_Y) -> tuple[int, int] | None:
+    """Hit-test inside a rect until ``matches(element)`` is true.
+
+    Coordinates are derived from the rect, never hardcoded. ``band`` limits
+    the search to the top of the pane; pass None to sweep all of it.
+    """
+    x0, y0, w, h = rect
+    height = min(band, h) if band else h
+    for y in range(y0 + 2, y0 + height, step_y):
+        for x in range(x0 + 2, x0 + w, step_x):
+            if matches(ax.element_at(ax_app, x, y)):
+                return x, y
+    return None
+
+
+def scan_all(ax_app, rect, matches, *, band: int | None = BAND_HEIGHT,
+             step_x: int = STEP_X, step_y: int = STEP_Y) -> list[tuple[int, int]]:
+    """Every distinct match in a rect, de-duplicated by element bounds.
+
+    Used where a window may hold several charts: each gets its own hit.
+    """
+    x0, y0, w, h = rect
+    height = min(band, h) if band else h
+    hits: list[tuple[int, int]] = []
+    seen: set[tuple[int, int]] = set()
+    for y in range(y0 + 2, y0 + height, step_y):
+        for x in range(x0 + 2, x0 + w, step_x):
+            element = ax.element_at(ax_app, x, y)
+            if not matches(element):
+                continue
+            p = ax.position(element)
+            key = (int(p.x), int(p.y)) if p else (x, y)
+            if key not in seen:
+                seen.add(key)
+                hits.append((x, y))
+    return hits
+
+
+def find_in_panes(ax_app, window_prefix: str, matches, *, band: int | None = BAND_HEIGHT):
+    """Search each pane in turn, largest first. Returns (x, y) or None."""
+    for rect in panes(ax_app, window_prefix):
+        hit = scan(ax_app, rect, matches, band=band)
+        if hit:
+            return hit
+    return None

chartremotely/mcpclient.py

@@ -0,0 +1,98 @@
+"""Just enough of an MCP client to call three operator tools.
+
+``setup`` proves who the patron is and pairs this machine, which means
+calling ``chart_request_npub_proof``, ``chart_receive_npub_proof`` and
+``chart_pair_agent``. A full MCP SDK would be the only reason this agent
+grew a dependency tree, so this speaks the streamable-HTTP transport
+directly: initialize, the initialized notification, then ``tools/call``,
+reading JSON or server-sent-event answers and carrying the session header.
+
+Stdlib only, importable anywhere.
+"""
+
+from __future__ import annotations
+
+import itertools
+import json
+import urllib.request
+
+PROTOCOL_VERSION = "2025-06-18"
+
+
+class McpError(RuntimeError):
+    """The operator could not be reached, or answered with an error."""
+
+
+def parse_body(raw: str) -> dict:
+    """One JSON-RPC message, from a JSON body or the last SSE ``data:`` line."""
+    raw = raw.strip()
+    if not raw:
+        return {}
+    if raw.startswith("{"):
+        return json.loads(raw)
+    data = [line[5:].strip() for line in raw.splitlines() if line.startswith("data:")]
+    if not data:
+        raise McpError("the operator sent an answer this client cannot read")
+    return json.loads(data[-1])
+
+
+def tool_payload(result: dict) -> dict:
+    """What a tool answered: its structured content, else its first text block as JSON."""
+    if isinstance(result.get("structuredContent"), dict):
+        return result["structuredContent"]
+    for block in result.get("content") or []:
+        if block.get("type") == "text":
+            try:
+                parsed = json.loads(block.get("text") or "")
+            except ValueError:
+                return {"text": block.get("text")}
+            return parsed if isinstance(parsed, dict) else {"value": parsed}
+    return {}
+
+
+class Client:
+    """A session with one operator's ``/mcp`` endpoint."""
+
+    def __init__(self, base_url: str, timeout: float = 60.0) -> None:
+        self.url = base_url.rstrip("/") + "/mcp"
+        self.timeout = timeout
+        self.session: str | None = None
+        self._ids = itertools.count(1)
+
+    def _send(self, message: dict) -> dict:
+        headers = {"Content-Type": "application/json",
+                   "Accept": "application/json, text/event-stream"}
+        if self.session:
+            headers["mcp-session-id"] = self.session
+        request = urllib.request.Request(
+            self.url, data=json.dumps(message).encode(), headers=headers, method="POST")
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                self.session = response.headers.get("mcp-session-id") or self.session
+                return parse_body(response.read().decode("utf-8", "replace"))
+        except OSError as exc:
+            raise McpError(f"could not reach the operator: {exc}") from None
+
+    def _start(self) -> None:
+        if self.session:
+            return
+        answer = self._send({
+            "jsonrpc": "2.0", "id": next(self._ids), "method": "initialize",
+            "params": {"protocolVersion": PROTOCOL_VERSION, "capabilities": {},
+                       "clientInfo": {"name": "chartremotely-setup", "version": "1"}}})
+        if "error" in answer:
+            raise McpError(str(answer["error"].get("message", answer["error"])))
+        self._send({"jsonrpc": "2.0", "method": "notifications/initialized"})
+
+    def call(self, tool: str, arguments: dict) -> dict:
+        """Call a tool and return what it answered. Raises McpError on a protocol error."""
+        self._start()
+        answer = self._send({"jsonrpc": "2.0", "id": next(self._ids), "method": "tools/call",
+                             "params": {"name": tool, "arguments": arguments}})
+        if "error" in answer:
+            raise McpError(str(answer["error"].get("message", answer["error"])))
+        result = answer.get("result") or {}
+        payload = tool_payload(result)
+        if result.get("isError"):
+            raise McpError(payload.get("text") or json.dumps(payload) or "the tool failed")
+        return payload

chartremotely/push.py

@@ -0,0 +1,58 @@
+"""Tell the operator what the chart looks like after it changes.
+
+A chart changed by voice goes straight to this machine over the tailnet, so
+the operator never hears of it. Right after a change succeeds, one picture of
+the chart pane is pushed up so the patron's browser can offer it. The operator
+keeps only the newest, encrypted, for an hour.
+
+Off the voice path on purpose: the push runs in the background after the
+answer is already on its way, and any failure is swallowed. The chart has
+already changed; a missing picture must never turn into a spoken error.
+
+Stdlib only at module scope, like the relay: the capture is imported lazily.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+
+from . import config, relay
+
+#: Time for the chart to redraw before its picture is taken.
+SETTLE_SECONDS = 1.0
+
+_lock = threading.Lock()
+
+
+def payload(cfg: dict, image: str) -> tuple[str, dict] | None:
+    """Where to send a picture and what to send, or None when not paired."""
+    base = (cfg.get("operator_url") or "").rstrip("/")
+    agent_id, secret = cfg.get("agent_id"), cfg.get("agent_secret")
+    if not (base and agent_id and secret):
+        return None
+    return f"{base}/agent/snapshot", {"agent_id": agent_id, "secret": secret, "image": image}
+
+
+def after_change(reply: str) -> str:
+    """Start a picture push if the change worked. Returns the reply unchanged."""
+    if not reply.startswith("ERR"):
+        threading.Thread(target=push_now, name="push-latest", daemon=True).start()
+    return reply
+
+
+def push_now() -> None:
+    """Take the chart's picture and send it. Never raises."""
+    try:
+        cfg = config.load()
+        if payload(cfg, "") is None:
+            return
+        # One at a time: two quick changes should not capture over each other.
+        with _lock:
+            time.sleep(SETTLE_SECONDS)
+            from . import snapshot, window
+            image = snapshot.as_reply(snapshot.shrink(window.capture()))
+            url, body = payload(cfg, image)
+            relay._post(url, body, timeout=30)
+    except Exception:  # noqa: BLE001, S110 - deliberate: see the module docstring
+        pass

chartremotely/registry.py

@@ -0,0 +1,53 @@
+"""The SEC company registry, cached locally.
+
+Roughly 10,500 US issuers including ETFs. Ordered by prominence in the
+source file, which makes the index a usable tie-breaker: NVDA, AAPL and
+GOOGL are the first three entries.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.request
+
+from .config import DATA_DIR
+
+SEC_URL = "https://www.sec.gov/files/company_tickers.json"
+CACHE = DATA_DIR / "tickers.json"
+MAX_AGE = 7 * 24 * 3600
+# The SEC requires a User-Agent carrying a contact address and answers 403
+# without one. A repository URL alone is not enough.
+DEFAULT_CONTACT = "chartremotely@example.com"
+
+
+def _user_agent() -> str:
+    from .config import load
+    contact = load().get("contact") or DEFAULT_CONTACT
+    # SEC's documented format is plain "Name email". Anything fancier is
+    # rejected: a User-Agent carrying a URL answers 403, as does one with no
+    # contact address at all.
+    return f"ChartRemotely {contact}"
+
+
+def _fresh() -> bool:
+    return CACHE.exists() and time.time() - CACHE.stat().st_mtime < MAX_AGE
+
+
+def refresh() -> list[dict]:
+    request = urllib.request.Request(SEC_URL, headers={"User-Agent": _user_agent()})
+    with urllib.request.urlopen(request, timeout=20) as response:
+        raw = json.load(response)
+    rows = [{"t": v["ticker"], "n": v["title"], "r": rank}
+            for rank, v in enumerate(raw.values())]
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    tmp = CACHE.with_suffix(".tmp")
+    tmp.write_text(json.dumps(rows))
+    tmp.replace(CACHE)
+    return rows
+
+
+def load(force: bool = False) -> list[dict]:
+    if force or not _fresh():
+        return refresh()
+    return json.loads(CACHE.read_text())

chartremotely/relay.py

@@ -0,0 +1,145 @@
+"""Talk to the operator, so a display can be driven from anywhere.
+
+The agent dials OUT and holds a poll open. Nothing here ever listens on a
+public port and the operator never connects to this machine: no Funnel, no
+port forwarding, no firewall rules, and nothing on the patron's network
+becomes reachable. That single choice is why pairing is safe to offer to
+someone who is not a network engineer.
+
+Stdlib only, on purpose. This runs on a machine whose owner granted
+Accessibility permission to software that types into a trading
+application - the dependency list is part of what they are auditing.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+
+from . import config
+
+#: Poll window. The operator holds a request open for slightly less than
+#: this, so a timeout here means the network dropped it, not that the
+#: operator is idle.
+POLL_TIMEOUT = 35.0
+CLAIM_INTERVAL = 3.0
+BACKOFF_MAX = 60.0
+
+
+class PairingError(RuntimeError):
+    """Pairing could not be completed."""
+
+
+def execute(command: str) -> str:
+    """Hand a relayed command to the agent's own vocabulary.
+
+    Imported lazily and wrapped here for one reason: the wire logic in this
+    module is pure, and importing vocab at module scope would drag the macOS
+    drivers in with it - making the whole file unimportable anywhere the
+    drivers are not installed, CI included.
+    """
+    from .vocab import dispatch
+    return dispatch(command)
+
+
+def _post(url: str, payload: dict, timeout: float) -> dict:
+    body = json.dumps(payload).encode()
+    request = urllib.request.Request(
+        url, data=body, method="POST",
+        headers={"Content-Type": "application/json"})
+    with urllib.request.urlopen(request, timeout=timeout) as response:
+        raw = response.read().decode("utf-8", "replace")
+    return json.loads(raw) if raw.strip() else {}
+
+
+def open_code(base: str) -> tuple[str, float]:
+    """Ask the operator for a pairing code. Returns the code and its lifetime in seconds."""
+    opened = _post(f"{base}/agent/open", {}, timeout=20)
+    code = opened.get("code")
+    if not code:
+        raise PairingError("the operator did not issue a pairing code")
+    return code, float(opened.get("expires_in") or 900)
+
+
+def collect(base: str, code: str, expires_in: float) -> dict:
+    """Wait until someone adopts the code, then keep the identity it earns."""
+    deadline = time.time() + expires_in
+    while time.time() < deadline:
+        time.sleep(CLAIM_INTERVAL)
+        try:
+            claimed = _post(f"{base}/agent/collect", {"code": code}, timeout=45)
+        except (urllib.error.URLError, TimeoutError, OSError):
+            # A read timeout is TimeoutError, not URLError - catching only
+            # the latter turned a slow first response into a hard failure.
+            # The code stays valid, and collect is idempotent, so retrying
+            # is always safe.
+            continue
+        if claimed.get("paired"):
+            return config.update(operator_url=base,
+                                 agent_id=claimed["agent_id"],
+                                 agent_secret=claimed["secret"])
+    raise PairingError("the pairing code expired before anyone claimed it")
+
+
+def operator_base(operator_url: str | None) -> str:
+    base = (operator_url or config.load().get("operator_url") or "").rstrip("/")
+    if not base:
+        raise PairingError("no operator URL; pass one or set operator_url in config")
+    return base
+
+
+def pair(operator_url: str | None = None, on_code=print) -> dict:
+    """Ask the operator for a code, show it, and wait to be adopted.
+
+    The patron reads the code to their MCP client, which calls
+    ``pair_agent``. ``setup`` takes the same path and adopts the code itself.
+    This machine hands out nothing: it proves it is theirs and receives an
+    identity in return.
+    """
+    base = operator_base(operator_url)
+    code, expires_in = open_code(base)
+    on_code(code)
+    return collect(base, code, expires_in)
+
+
+def run(operator_url: str | None = None, once: bool = False) -> None:
+    """Hold a poll open, execute what arrives, report the result.
+
+    Commands are handed straight to the agent's own vocabulary. The
+    operator relays; this machine decides what is permitted, which is what
+    keeps a compromised operator from widening the surface.
+    """
+    cfg = config.load()
+    base = (operator_url or cfg.get("operator_url") or "").rstrip("/")
+    agent_id, secret = cfg.get("agent_id"), cfg.get("agent_secret")
+    if not (base and agent_id and secret):
+        raise PairingError("this agent is not paired; run: chartremotely pair")
+
+    credentials = {"agent_id": agent_id, "secret": secret}
+    backoff = 1.0
+    while True:
+        try:
+            envelope = _post(f"{base}/agent/poll", credentials, timeout=POLL_TIMEOUT)
+            backoff = 1.0
+        except (urllib.error.URLError, TimeoutError, OSError):
+            # The operator being unreachable is not fatal: this machine
+            # still works locally, and the display should reconnect by
+            # itself when the operator returns.
+            time.sleep(backoff)
+            backoff = min(backoff * 2, BACKOFF_MAX)
+            if once:
+                return
+            continue
+
+        if envelope.get("command"):
+            reply = execute(str(envelope["command"]))
+            try:
+                _post(f"{base}/agent/result",
+                      {**credentials, "id": envelope.get("id"), "reply": reply},
+                      timeout=20)
+            except (urllib.error.URLError, TimeoutError, OSError):
+                pass          # the caller has already timed out and refunded
+        if once:
+            return