cdx-manager 0.17.1 → 0.18.0

package/src/tray_capability.py

@@ -0,0 +1,120 @@
+"""What the desktop can actually do for the tray, read at the moment asked.
+
+Two capabilities decide whether the companion's output ever reaches a person,
+and both fail silently when absent, which is why `cdx tray doctor` has to name
+them rather than leave the user to notice nothing happening:
+
+  - Windows shows a toast from a non-packaged program only when a Start Menu
+    shortcut carrying its AppUserModelID exists. Without one the notification
+    API succeeds and nothing appears. A success code and no toast is the worst
+    kind of failure to debug from the outside.
+  - Linux draws a tray icon only where something owns the
+    `org.kde.StatusNotifierWatcher` name. A desktop without it is not broken,
+    it simply has no system tray, and saying so beats a companion that appears
+    to start and then cannot be seen.
+
+Nothing here repairs anything, and nothing runs unbounded: every probe is local
+and time-limited, because a diagnostic that hangs is worse than one that admits
+it does not know.
+"""
+import os
+import platform
+import subprocess
+
+# Matches the identifier the companion registers with, and the name a user would
+# recognise in the Start Menu. Both have to agree for a toast to be delivered.
+SHORTCUT_NAME = "CDX.lnk"
+PROBE_TIMEOUT_SECONDS = 3
+
+
+def shortcut_path(env=None):
+    """Where Windows looks for the shortcut, or None off Windows."""
+    env = os.environ if env is None else env
+    appdata = (env.get("APPDATA") or "").strip()
+    if not appdata:
+        return None
+    return os.path.join(appdata, "Microsoft", "Windows", "Start Menu", "Programs", SHORTCUT_NAME)
+
+
+def toast_capability(env=None, system=None):
+    """Whether a toast raised by the companion could actually be shown.
+
+    Only Windows makes this conditional. Elsewhere the answer is "nothing stands
+    in the way", which is reported as such rather than as a pass on a check that
+    was never run.
+    """
+    system = platform.system() if system is None else system
+    if system != "Windows":
+        return {
+            "supported": True,
+            "gated": False,
+            "present": True,
+            "path": None,
+            "detail": "no Start Menu shortcut is required on this platform",
+        }
+    path = shortcut_path(env)
+    if not path:
+        return {
+            "supported": True,
+            "gated": True,
+            "present": False,
+            "path": None,
+            "detail": "APPDATA is unset, so the Start Menu location cannot be resolved",
+        }
+    present = os.path.isfile(path)
+    return {
+        "supported": True,
+        "gated": True,
+        "present": present,
+        "path": path,
+        "detail": path if present else f"missing: {path}. Toasts are dropped silently without it",
+    }
+
+
+def desktop_capability(env=None, system=None, run=None):
+    """Whether this desktop can draw a tray icon at all.
+
+    macOS and Windows always can. Linux depends on a StatusNotifierItem watcher,
+    which is a property of the running session rather than of the distribution,
+    so it is resolved by asking the bus and never by matching a name.
+    """
+    system = platform.system() if system is None else system
+    if system in ("Darwin", "Windows"):
+        return {"available": True, "detail": "native tray"}
+
+    env = os.environ if env is None else env
+    if not (env.get("DBUS_SESSION_BUS_ADDRESS") or "").strip():
+        return {"available": False, "detail": "no D-Bus session bus: this is not a desktop session"}
+
+    runner = run or _run_dbus_send
+    try:
+        names = runner()
+    except Exception:  # noqa: BLE001 - a diagnostic never propagates a failure
+        return {"available": None, "detail": "could not query the session bus"}
+    if names is None:
+        return {"available": None, "detail": "could not query the session bus"}
+    if "org.kde.StatusNotifierWatcher" in names:
+        return {"available": True, "detail": "StatusNotifierItem watcher present"}
+    return {
+        "available": False,
+        "detail": "no org.kde.StatusNotifierWatcher: this desktop has no system tray. "
+                  "On GNOME, install the AppIndicator extension",
+    }
+
+
+def _run_dbus_send():
+    """The same question the Linux backend asks, asked the same way."""
+    try:
+        completed = subprocess.run(
+            [
+                "dbus-send", "--session", "--dest=org.freedesktop.DBus",
+                "--type=method_call", "--print-reply", "/org/freedesktop/DBus",
+                "org.freedesktop.DBus.ListNames",
+            ],
+            capture_output=True, text=True, timeout=PROBE_TIMEOUT_SECONDS, check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if completed.returncode != 0:
+        return None
+    return completed.stdout

package/src/tray_contract.py

@@ -0,0 +1,229 @@
+"""The snapshot a tray companion reads, and the display state it renders.
+
+A tray consumer needs three things the CLI status rows do not give it: one
+urgency state for a closed icon, a per-session line short enough for a menu, and
+an honest word for "this number is old". This module derives all three from the
+rows `cdx status` already produces, so the companion never talks to a provider.
+
+The refresh policy is the load-bearing part. `src/codex_usage.py` serializes
+live probes on `codex_auth_lock` because Codex rotates its OAuth refresh token,
+and the launcher holds that lock for a whole interactive session. A background
+consumer polling for fresh quota would either be locked out or race the token,
+so the tray reads the cache and says so. `auth_locked` is a first-class state
+here, not an error.
+"""
+from datetime import datetime, timezone
+
+from .session_status import (
+    CLAUDE_STATUS_CACHE_TTL_SECONDS,
+    CODEX_STATUS_CACHE_TTL_SECONDS,
+    STATUS_CACHE_TTL_SECONDS,
+)
+
+SCHEMA_NAME = "cdx.tray.snapshot"
+SCHEMA_MAJOR = 1
+SCHEMA_MINOR = 0
+
+# Below this much remaining capacity a session cannot usefully take work. Shared
+# with the ranking's own usability threshold so the tray and `cdx next` do not
+# disagree about what "blocked" means.
+CRITICAL_PCT = 5
+LOW_PCT = 25
+
+ICON_OK = "ok"
+ICON_LOW = "low"
+ICON_CRITICAL = "critical"
+ICON_UNKNOWN = "unknown"
+
+FRESH = "fresh"
+STALE = "stale"
+AUTH_LOCKED = "auth_locked"
+UNKNOWN = "unknown"
+
+_PROVIDER_TTL = {
+    "codex": CODEX_STATUS_CACHE_TTL_SECONDS,
+    "claude": CLAUDE_STATUS_CACHE_TTL_SECONDS,
+}
+
+
+def ttl_seconds_for(provider):
+    return _PROVIDER_TTL.get(provider, STATUS_CACHE_TTL_SECONDS)
+
+
+def parse_iso(value):
+    """Rows carry local-offset ISO strings; comparison needs a real instant."""
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(str(value).replace("Z", "+00:00")).astimezone(timezone.utc)
+    except ValueError:
+        return None
+
+
+def _age_seconds(updated_at, now):
+    moment = parse_iso(updated_at)
+    if moment is None:
+        return None
+    return max(0.0, (now - moment).total_seconds())
+
+
+def session_freshness(row, now):
+    """How much this row's numbers can be trusted, and whether that is fixable.
+
+    A running session holds the provider auth lock, so its quota cannot be
+    refreshed until it exits. Reporting that as `stale` would invite the user to
+    hit refresh forever; `auth_locked` tells them why it will not help.
+    """
+    age = _age_seconds(row.get("updated_at"), now)
+    if age is None:
+        return UNKNOWN, None
+    if age <= ttl_seconds_for(row.get("provider")):
+        return FRESH, age
+    return (AUTH_LOCKED if row.get("active") else STALE), age
+
+
+def icon_state_for_pct(available_pct):
+    if available_pct is None:
+        return ICON_UNKNOWN
+    if available_pct < CRITICAL_PCT:
+        return ICON_CRITICAL
+    if available_pct < LOW_PCT:
+        return ICON_LOW
+    return ICON_OK
+
+
+def _eligible(row):
+    return row.get("enabled", True) is not False
+
+
+def menu_session(row, now):
+    """One menu line. Everything the tray shows once the user opens it."""
+    freshness, age = session_freshness(row, now)
+    return {
+        "name": row.get("session_name"),
+        "label": row.get("label"),
+        "provider": row.get("provider"),
+        "available_pct": row.get("available_pct"),
+        "remaining_5h_pct": row.get("remaining_5h_pct"),
+        "remaining_week_pct": row.get("remaining_week_pct"),
+        "reset_at": row.get("reset_at"),
+        "active": bool(row.get("active")),
+        "state": icon_state_for_pct(row.get("available_pct")),
+        "freshness": freshness,
+        "age_seconds": None if age is None else int(age),
+        "updated_at": row.get("updated_at"),
+    }
+
+
+def _worst(sessions):
+    """The session whose state the closed icon should show.
+
+    Ordered by severity, then by least remaining capacity, so a tie between two
+    critical sessions still names the one closest to empty. Unknown loses to
+    every known state: an icon that cries wolf because one session never
+    reported is worse than one that shows the worst thing it actually knows.
+    """
+    severity = {ICON_CRITICAL: 0, ICON_LOW: 1, ICON_OK: 2, ICON_UNKNOWN: 3}
+    return min(
+        sessions,
+        key=lambda s: (
+            severity[s["state"]],
+            s["available_pct"] if s["available_pct"] is not None else 101,
+        ),
+    )
+
+
+_STATE_WORDS = {
+    ICON_OK: "capacity ok",
+    ICON_LOW: "capacity low",
+    ICON_CRITICAL: "capacity critical",
+    ICON_UNKNOWN: "capacity unknown",
+}
+
+_FRESHNESS_WORDS = {
+    STALE: "figures are stale",
+    AUTH_LOCKED: "cannot refresh while a session runs",
+    UNKNOWN: "never reported",
+}
+
+
+def tooltip_for(worst):
+    """What the closed icon may say on hover.
+
+    Deliberately without the session name. `req_035` AC3 forbids exposing
+    accounts before the menu is opened and `req_038` AC4 asks the tooltip to
+    name the limiting source and its reset; a tooltip appears on hover, without
+    a click, and shows up in a screen share. Naming the provider and the reset
+    satisfies the second without breaking the first. The session name is one
+    click away in the menu.
+
+    It is also the accessibility path: every state the glyph conveys is written
+    here in words, so nothing depends on telling two shapes apart.
+    """
+    if worst is None:
+        return "CDX · no enabled sessions"
+    parts = [_STATE_WORDS.get(worst["state"], worst["state"])]
+    if worst["available_pct"] is not None:
+        parts.append(f"{int(worst['available_pct'])}% left")
+    note = _FRESHNESS_WORDS.get(worst["freshness"])
+    if note:
+        parts.append(note)
+    if worst.get("reset_at"):
+        parts.append(f"resets {worst['reset_at']}")
+    return "CDX · " + " · ".join(parts)
+
+
+def build_snapshot(rows, now, cdx_version, refreshable=True):
+    """The whole contract, from the rows `cdx status` already returns.
+
+    `icon` carries no session name, account, or figure: it is what shows while
+    the menu is closed, and `req_035` AC3 forbids leaking anything there.
+    """
+    sessions = [menu_session(row, now) for row in rows if _eligible(row)]
+    if not sessions:
+        icon = {
+            "state": ICON_UNKNOWN,
+            "reason": "no_sessions",
+            "session_count": 0,
+            "tooltip": tooltip_for(None),
+        }
+    else:
+        worst = _worst(sessions)
+        icon = {
+            "state": worst["state"],
+            "reason": worst["freshness"],
+            "session_count": len(sessions),
+            # Everything the closed icon is allowed to say, in words.
+            "tooltip": tooltip_for(worst),
+        }
+    return {
+        "schema": {"name": SCHEMA_NAME, "major": SCHEMA_MAJOR, "minor": SCHEMA_MINOR},
+        "cdx_version": cdx_version,
+        "generated_at": now.isoformat(),
+        "icon": icon,
+        "sessions": sessions,
+        "refreshable": bool(refreshable),
+        "actions": ["refresh", "open_terminal"],
+    }
+
+
+def read_snapshot(payload):
+    """Read a snapshot that may be newer than this reader.
+
+    A companion and the CLI are updated separately, so version drift is the
+    normal state. An unknown major version keeps every field this reader
+    understands and adds one hint, rather than refusing to render.
+    """
+    schema = (payload or {}).get("schema") or {}
+    major = schema.get("major")
+    if schema.get("name") != SCHEMA_NAME or not isinstance(major, int):
+        return {"ok": False, "reason": "not_a_cdx_tray_snapshot", "snapshot": None, "update_hint": None}
+    known = {
+        key: payload.get(key)
+        for key in ("schema", "cdx_version", "generated_at", "icon", "sessions", "refreshable", "actions")
+        if key in payload
+    }
+    hint = None
+    if major > SCHEMA_MAJOR:
+        hint = f"This CDX reads tray snapshot v{SCHEMA_MAJOR}; the snapshot is v{major}. Update CDX to see everything."
+    return {"ok": True, "reason": None, "snapshot": known, "update_hint": hint}

package/src/tray_events.py

@@ -0,0 +1,210 @@
+"""The handoff from a provider hook to a running tray, and back.
+
+`cdx notify` runs inside a provider's hook. It cannot wait on a GUI, it may be
+killed the moment the turn ends, and several sessions can fire at once. Those
+three facts decide the whole design:
+
+  - **Append-only JSONL, opened `O_APPEND`.** A small append is atomic, so two
+    hooks firing together cannot interleave or lose each other's event. A
+    read-modify-write of one JSON array would silently drop one of them, and
+    the loser would be a notification the user simply never gets.
+  - **A heartbeat, not a process check.** The tray says it is alive by writing a
+    file; `notify` publishes only when that file is fresh. A pid check would
+    claim a companion in a different WSL namespace is reachable when it is not.
+  - **Freshness wider than one poll period.** The tray writes its heartbeat once
+    per poll, so a window narrower than that period reads a perfectly healthy
+    tray as stale every time — and the alert would then be delivered twice, once
+    by the tray and once by the direct fallback.
+
+Everything degrades to the existing direct notification. A tray that is absent,
+stale, too old to understand the schema, or backed by unreadable state is not an
+error: it means `notify` keeps doing exactly what it did before.
+"""
+import json
+import os
+import time
+
+SCHEMA_VERSION = 1
+# The tray heartbeats once per poll: 30s native, 60s across WSL. This window has
+# to clear the slowest of those with room for a late tick, or a live tray reads
+# as stale and the user gets the same alert twice.
+HEARTBEAT_FRESH_SECONDS = 150
+# Old alerts are worth less than new ones, so the spool drops the oldest rather
+# than growing without bound. A tray that has been down for an hour should not
+# flood the user on return.
+MAX_SPOOLED_EVENTS = 32
+# Compaction threshold. Acknowledged lines stay on disk until this many have
+# accumulated, so the common path is one append and no rewrite at all.
+COMPACT_AFTER_LINES = 128
+
+
+def _tray_dir(base_dir):
+    return os.path.join(base_dir, "tray")
+
+
+def events_path(base_dir):
+    return os.path.join(_tray_dir(base_dir), "events.jsonl")
+
+
+def heartbeat_path(base_dir):
+    return os.path.join(_tray_dir(base_dir), "heartbeat.json")
+
+
+def _write_atomic(path, text):
+    """Replace a file in one step, so a killed writer never leaves half of one."""
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    temp = f"{path}.{os.getpid()}.tmp"
+    with open(temp, "w", encoding="utf-8") as handle:
+        handle.write(text)
+    os.replace(temp, path)
+
+
+# --- the tray's side -------------------------------------------------------
+
+def write_heartbeat(base_dir, pid=None, now=None):
+    """Say the tray is alive, and which schema it speaks."""
+    now = time.time() if now is None else now
+    _write_atomic(heartbeat_path(base_dir), json.dumps({
+        "schema": SCHEMA_VERSION,
+        "pid": os.getpid() if pid is None else pid,
+        "at": now,
+    }))
+
+
+def read_heartbeat(base_dir):
+    """The heartbeat, or None. Unreadable and malformed both read as absent."""
+    try:
+        with open(heartbeat_path(base_dir), encoding="utf-8") as handle:
+            beat = json.load(handle)
+    except (OSError, ValueError):
+        return None
+    if not isinstance(beat, dict) or not isinstance(beat.get("at"), (int, float)):
+        return None
+    return beat
+
+
+def tray_is_listening(base_dir, now=None):
+    """Whether a tray should own this notification instead of the direct path.
+
+    A schema this CDX does not speak counts as not listening. Publishing to a
+    companion that cannot read the event would lose the notification entirely,
+    where falling back merely delivers it the old way.
+    """
+    now = time.time() if now is None else now
+    beat = read_heartbeat(base_dir)
+    if not beat:
+        return False
+    if beat.get("schema") != SCHEMA_VERSION:
+        return False
+    return (now - beat["at"]) <= HEARTBEAT_FRESH_SECONDS
+
+
+# --- the hook's side -------------------------------------------------------
+
+def publish(base_dir, title, message, kind="complete", now=None, event_id=None):
+    """Hand one event to the tray. Returns True only if it was written.
+
+    False means the caller must deliver it directly, so every failure here has
+    to be a False and never an exception: the alternative is a provider hook
+    that raises inside someone's agent turn.
+    """
+    now = time.time() if now is None else now
+    try:
+        if not tray_is_listening(base_dir, now=now):
+            return False
+        event = {
+            "id": event_id or f"{int(now * 1000)}-{os.getpid()}",
+            "at": now,
+            "kind": kind,
+            "title": title,
+            "message": message,
+        }
+        path = events_path(base_dir)
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        line = json.dumps(event, ensure_ascii=False) + "\n"
+        # O_APPEND makes this atomic against other hooks firing at the same
+        # instant, which a read-modify-write of a JSON array would not be.
+        with open(path, "a", encoding="utf-8") as handle:
+            handle.write(line)
+        return True
+    except OSError:
+        return False
+
+
+# --- shared -----------------------------------------------------------------
+
+def read_events(base_dir, include_acknowledged=False):
+    """Every event still on the spool, oldest first.
+
+    A malformed line is skipped rather than fatal. The spool is written by a
+    process that can be killed mid-write, so a partial last line is an expected
+    state, not corruption.
+    """
+    try:
+        with open(events_path(base_dir), encoding="utf-8") as handle:
+            lines = handle.readlines()
+    except OSError:
+        return []
+    events = []
+    for line in lines:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            event = json.loads(line)
+        except ValueError:
+            continue
+        if not isinstance(event, dict) or not event.get("id"):
+            continue
+        if event.get("acknowledged") and not include_acknowledged:
+            continue
+        events.append(event)
+    # Keep the newest when the spool has overflowed: a stale alert helps nobody.
+    return events[-MAX_SPOOLED_EVENTS:]
+
+
+def acknowledge(base_dir, ids, now=None):
+    """Mark events consumed, idempotently, and compact when it is worth it.
+
+    Acknowledging is what stops one event being shown twice, so it has to
+    survive being called with ids already acknowledged, ids that never existed,
+    and a tray that crashed between showing and acknowledging.
+    """
+    now = time.time() if now is None else now
+    wanted = set(ids or [])
+    if not wanted:
+        return {"acknowledged": 0, "compacted": False}
+
+    try:
+        with open(events_path(base_dir), encoding="utf-8") as handle:
+            lines = handle.readlines()
+    except OSError:
+        return {"acknowledged": 0, "compacted": False}
+
+    kept = []
+    marked = 0
+    for line in lines:
+        stripped = line.strip()
+        if not stripped:
+            continue
+        try:
+            event = json.loads(stripped)
+        except ValueError:
+            continue
+        if not isinstance(event, dict) or not event.get("id"):
+            continue
+        if event["id"] in wanted and not event.get("acknowledged"):
+            event = {**event, "acknowledged": now}
+            marked += 1
+        kept.append(event)
+
+    compact = len(kept) >= COMPACT_AFTER_LINES
+    if compact:
+        # Drop what the tray has already shown; unacknowledged events stay,
+        # because dropping one would be losing a notification outright.
+        kept = [event for event in kept if not event.get("acknowledged")]
+    _write_atomic(
+        events_path(base_dir),
+        "".join(json.dumps(event, ensure_ascii=False) + "\n" for event in kept),
+    )
+    return {"acknowledged": marked, "compacted": compact}