fleetwatcher 0.4.0__py3-none-any.whl

fleetwatch/core.py

@@ -0,0 +1,241 @@
+"""The aggregator: poll every adapter, hold the current fleet, sort it.
+
+This is the only place that knows about all the adapters at once. It scans them
+on demand (``refresh``), keeps one normalized ``SessionState`` per session,
+re-ages quiet sessions cheaply, drops the ones that vanished, and dispatches
+plain-language summaries for whatever needs attention. The TUI and the CLI both
+talk to exactly this surface:
+
+    refresh()            re-scan; cheap; safe to call on an interval
+    sessions()           current fleet, sorted needs-first then most-recent
+    counts()             {"active": n, "waiting": n, ..., "total": n}
+    request_summary(key) force a model summary for one session (the TUI 's' key)
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Optional
+
+from . import config
+from .adapters import all_adapters
+from .adapters.base import LocalSource, Source
+from .models import SessionState, State
+from .remote import parse_hosts
+from .summarize import Summarizer
+
+# Sort priority: the things that want you, first.
+_STATE_ORDER = {
+    State.WAITING: 0,
+    State.ERROR: 1,
+    State.ACTIVE: 2,
+    State.IDLE: 3,
+    State.DONE: 4,
+}
+
+# States that can change as time passes even when the file does not, so they
+# must be re-read on every refresh rather than trusting the mtime cache.
+_VOLATILE = {State.ACTIVE, State.WAITING}
+
+
+class Aggregator:
+    def __init__(
+        self,
+        source: Optional[Source] = None,
+        summarizer: Optional[Summarizer] = None,
+        hosts: Optional[list] = None,
+    ):
+        self.source = source or LocalSource()
+        self.adapters = all_adapters()
+        self.summarizer = summarizer if summarizer is not None else Summarizer()
+        # Remote hosts watched over ssh. Any object with `.name` and `.fetch()`
+        # works (tests inject fakes); by default parsed from config.
+        self.hosts = hosts if hosts is not None else parse_hosts(config.REMOTE_HOSTS)
+        self._states: dict[tuple, SessionState] = {}
+        self._mtimes: dict[tuple, float] = {}
+        self._lock = threading.Lock()
+
+    # --- public surface ---
+
+    def refresh(self) -> None:
+        now = time.time()
+        seen: set[tuple] = set()
+
+        for adapter in self.adapters:
+            try:
+                refs = adapter.discover(self.source)
+            except Exception:
+                refs = []  # a broken adapter must never sink the whole scan
+            for ref in refs:
+                key = (self.source.host, adapter.vendor, ref.session_id)
+                # Prefer the adapter's freshness hint (newest mtime across a
+                # multi-file session) so a change in any of the session's files
+                # is noticed, not just the primary transcript's.
+                mtime = (
+                    ref.mtime
+                    if ref.mtime is not None
+                    else self.source.mtime(ref.path)
+                )
+
+                # Skip files too old to care about without ever reading them —
+                # this is what keeps a refresh cheap when hundreds of stale
+                # transcripts sit on disk. Not adding to `seen` lets eviction
+                # drop one that just aged out.
+                if mtime and (now - mtime) > config.MAX_AGE:
+                    continue
+
+                seen.add(key)
+                prev = self._states.get(key)
+
+                unchanged = prev is not None and self._mtimes.get(key) == mtime
+                if unchanged and prev.state not in _VOLATILE:
+                    self._reage(prev, now)
+                    continue
+
+                try:
+                    state = adapter.read(self.source, ref, prev)
+                except Exception as exc:
+                    state = self._error_state(adapter.vendor, ref, str(exc))
+                if state is None:
+                    continue
+
+                # Carry a model summary across re-reads of the same activity.
+                if not state.summary:
+                    if prev and prev.summary and prev.last_activity == state.last_activity:
+                        state.summary = prev.summary
+                    else:
+                        cached = self.summarizer.cached(state)
+                        if cached:
+                            state.summary = cached
+
+                with self._lock:
+                    self._states[key] = state
+                    self._mtimes[key] = mtime
+
+        self._fetch_remotes(seen)
+        self._evict(seen, now)
+        self._dispatch_summaries()
+
+    def _fetch_remotes(self, seen: set) -> None:
+        """Pull each remote host's JSON export and merge it in. An unreachable
+        host keeps its last-known sessions (marked seen so eviction spares them)
+        rather than blinking out of existence."""
+        for host in self.hosts:
+            try:
+                states, reachable = host.fetch()
+            except Exception:
+                states, reachable = [], False
+            if not reachable:
+                with self._lock:
+                    for key in self._states:
+                        if key[0] == host.name:
+                            seen.add(key)
+                continue
+            for st in states:
+                st.source = host.name  # always display under the host it came from
+                key = (host.name, st.vendor, st.session_id)
+                seen.add(key)
+                if not st.summary:
+                    prev = self._states.get(key)
+                    if prev and prev.summary and prev.last_activity == st.last_activity:
+                        st.summary = prev.summary
+                    else:
+                        cached = self.summarizer.cached(st)
+                        if cached:
+                            st.summary = cached
+                with self._lock:
+                    self._states[key] = st
+                    self._mtimes[key] = st.last_activity or 0.0
+
+    def sessions(self) -> list[SessionState]:
+        with self._lock:
+            items = list(self._states.values())
+        items.sort(
+            key=lambda s: (
+                _STATE_ORDER.get(s.state, 9),
+                -(s.last_activity or 0.0),
+            )
+        )
+        return items
+
+    def counts(self) -> dict:
+        with self._lock:
+            items = list(self._states.values())
+        out = {s.value: 0 for s in State}
+        for st in items:
+            out[st.state.value] += 1
+        out["total"] = len(items)
+        return out
+
+    def request_summary(self, key, force: bool = True) -> None:
+        key = tuple(key)
+        with self._lock:
+            st = self._states.get(key)
+            if st is None:
+                # Stored entries are keyed by the discover-time id, but a caller
+                # (the TUI) passes the session's canonical key — adapters such as
+                # Codex/Gemini rewrite session_id from file contents. Fall back to
+                # matching on the state's own key so manual summaries never no-op.
+                for s in self._states.values():
+                    if s.key == key:
+                        st = s
+                        break
+        if st is not None:
+            self.summarizer.request(st, force=force)
+
+    def summarize_all(self, force: bool = False) -> int:
+        """Full sweep: request a plain-language summary for every current
+        session. Cached summaries are reused unless ``force``. Returns the
+        number of sessions swept (0 when the model is disabled)."""
+        if not self.summarizer.enabled:
+            return 0
+        sessions = self.sessions()
+        for st in sessions:
+            self.summarizer.request(st, force=force)
+        return len(sessions)
+
+    # --- internals ---
+
+    def _reage(self, st: SessionState, now: float) -> None:
+        """Promote a quiet IDLE session to DONE once it crosses DONE_AFTER,
+        without re-reading the file."""
+        if (
+            st.state == State.IDLE
+            and st.last_activity is not None
+            and (now - st.last_activity) >= config.DONE_AFTER
+        ):
+            st.state = State.DONE
+
+    def _evict(self, seen: set, now: float) -> None:
+        with self._lock:
+            for key in list(self._states):
+                st = self._states[key]
+                gone = key not in seen
+                too_old = (
+                    st.last_activity is not None
+                    and (now - st.last_activity) > config.MAX_AGE
+                )
+                if gone or too_old:
+                    self._states.pop(key, None)
+                    self._mtimes.pop(key, None)
+
+    def _dispatch_summaries(self) -> None:
+        if not self.summarizer.enabled:
+            return
+        for st in self.sessions():
+            if st.needs_attention and not st.summary:
+                self.summarizer.request(st)
+
+    @staticmethod
+    def _error_state(vendor: str, ref, msg: str) -> SessionState:
+        return SessionState(
+            vendor=vendor,
+            session_id=ref.session_id,
+            project=(ref.cwd or "?").rstrip("/").split("/")[-1] or "?",
+            cwd=ref.cwd,
+            state=State.ERROR,
+            doing="could not read session",
+            needs="unreadable transcript",
+            error=msg[:200],
+        )

fleetwatch/models.py

@@ -0,0 +1,110 @@
+"""The data contract shared by every adapter, the aggregator, and the UI.
+
+A ``SessionState`` is a normalized snapshot of one CLI coding session, no matter
+which vendor produced it. Adapters translate vendor-specific files into this
+shape; the aggregator collects them; the TUI renders them. It stays fully
+JSON-serializable on purpose: a remote host can export the exact same records
+over the wire, which is how VPS support drops in later without reworking this.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+
+class State(str, Enum):
+    """Lifecycle of a session, in rough order of how much it wants you."""
+
+    ACTIVE = "active"    # transcript changed very recently; the agent is working
+    WAITING = "waiting"  # blocked on the human (permission prompt, a question)
+    IDLE = "idle"        # last turn finished recently; likely still open
+    DONE = "done"        # last turn finished long ago; effectively over
+    ERROR = "error"      # vendor error, or the transcript could not be read
+
+    def __str__(self) -> str:  # so f-strings print "active" not "State.ACTIVE"
+        return self.value
+
+
+@dataclass
+class TodoItem:
+    text: str
+    status: str = "pending"  # pending | in_progress | completed
+
+
+@dataclass
+class SessionState:
+    # --- identity ---
+    vendor: str                    # "claude" | "codex" | "grok" | "gemini"
+    session_id: str
+    project: str                   # human label, usually the basename of cwd
+    cwd: Optional[str] = None      # full working directory when known
+    source: str = "local"          # host label; "local" now, a VPS hostname later
+
+    # --- liveness ---
+    last_activity: Optional[float] = None  # epoch seconds (file mtime / last ts)
+    state: State = State.IDLE
+
+    # --- what it's doing ---
+    doing: str = ""                # heuristic one-liner the adapter fills in
+    needs: Optional[str] = None    # human-facing reason it wants attention
+    summary: Optional[str] = None  # model-written paragraph, filled in lazily
+
+    # --- context for the detail pane ---
+    todos: list[TodoItem] = field(default_factory=list)
+    last_user: str = ""
+    last_agent: str = ""
+
+    # --- bookkeeping ---
+    error: Optional[str] = None
+
+    @property
+    def key(self) -> tuple[str, str, str]:
+        """Stable identity across refreshes and across hosts."""
+        return (self.source, self.vendor, self.session_id)
+
+    @property
+    def needs_attention(self) -> bool:
+        return self.state in (State.WAITING, State.ERROR)
+
+    def to_dict(self) -> dict:
+        return {
+            "vendor": self.vendor,
+            "session_id": self.session_id,
+            "project": self.project,
+            "cwd": self.cwd,
+            "source": self.source,
+            "last_activity": self.last_activity,
+            "state": self.state.value,
+            "doing": self.doing,
+            "needs": self.needs,
+            "summary": self.summary,
+            "todos": [{"text": t.text, "status": t.status} for t in self.todos],
+            "last_user": self.last_user,
+            "last_agent": self.last_agent,
+            "error": self.error,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "SessionState":
+        return cls(
+            vendor=d["vendor"],
+            session_id=d["session_id"],
+            project=d["project"],
+            cwd=d.get("cwd"),
+            source=d.get("source", "local"),
+            last_activity=d.get("last_activity"),
+            state=State(d.get("state", "idle")),
+            doing=d.get("doing", ""),
+            needs=d.get("needs"),
+            summary=d.get("summary"),
+            todos=[
+                TodoItem(text=str(t.get("text", "")), status=t.get("status", "pending"))
+                for t in d.get("todos", [])
+                if isinstance(t, dict) and t.get("text")
+            ],
+            last_user=d.get("last_user", ""),
+            last_agent=d.get("last_agent", ""),
+            error=d.get("error"),
+        )

fleetwatch/palette.py

@@ -0,0 +1,107 @@
+"""The one place fleetwatch decides what color anything is.
+
+Two renderers consume these colors — the Textual dashboard (:mod:`tui`), which
+speaks Rich style strings, and the plain-text snapshot (:mod:`render`), which
+speaks ANSI for ``--once`` on a terminal. Keeping both mappings here means the
+live board and the text view never disagree about what "waiting" looks like.
+
+The scheme is built for color-blind readers: state is carried by luminance and
+hue *position*, never red-vs-green alone. ``active`` is cyan (not green) so it
+never collides with ``error``'s red on a deuteranope's screen, and ``idle`` /
+``done`` recede into grey. Vendor accents live in a separate hue family
+(orange, green, magenta, blue) so a vendor tag is never read as a status.
+"""
+
+from __future__ import annotations
+
+from .models import State
+
+# Bright primaries for the three states that carry signal — blue is "live",
+# yellow is "your move", red is "broken". WAITING and ERROR are bold so they
+# jump out of a full table. IDLE and DONE recede into grey. No state leans on a
+# red-vs-green distinction, the one pair color-blind readers can't separate.
+STATE_STYLE: dict[State, str] = {
+    State.ACTIVE: "bright_blue",
+    State.WAITING: "bold bright_yellow",
+    State.ERROR: "bold bright_red",
+    State.IDLE: "grey58",
+    State.DONE: "grey42",
+}
+
+# A glyph per state: a second, color-free channel. Read by shape alone, the
+# board still parses for a reader who can't see the hue — and ● / ○ / · also
+# track "presence" (live, idle, faded) at a glance.
+STATE_GLYPH: dict[State, str] = {
+    State.ACTIVE: "●",
+    State.WAITING: "◆",
+    State.ERROR: "✗",
+    State.IDLE: "○",
+    State.DONE: "·",
+}
+
+# Per-vendor accent: a hue family of its own (orange, cyan, magenta, violet),
+# every one distinct from the state colors so a vendor tag never reads as a
+# status. No green here either.
+VENDOR_STYLE: dict[str, str] = {
+    "claude": "dark_orange",
+    "codex": "bright_cyan",
+    "grok": "bright_magenta",
+    "gemini": "medium_purple1",
+}
+
+_DEFAULT = "white"
+
+
+def state_style(state: State) -> str:
+    """Rich style for a session state; white for anything unrecognized."""
+    return STATE_STYLE.get(state, _DEFAULT)
+
+
+def state_glyph(state: State) -> str:
+    """Single-character status mark for a state; a space if unrecognized."""
+    return STATE_GLYPH.get(state, " ")
+
+
+def state_label(state: State) -> str:
+    """Glyph + name, e.g. ``"● active"`` — the state as it reads in a cell."""
+    return f"{state_glyph(state)} {state}"
+
+
+def vendor_style(vendor: str) -> str:
+    """Rich style for a vendor accent; white for an unknown vendor."""
+    return VENDOR_STYLE.get((vendor or "").lower(), _DEFAULT)
+
+
+# --- ANSI for the plain-text snapshot ------------------------------------- #
+# SGR codes mirroring the Rich styles above, so `fleetwatch --once` on a TTY
+# carries the same scheme. Unknown styles paint nothing (graceful no-op).
+_ANSI: dict[str, str] = {
+    "cyan": "36",
+    "bright_blue": "94",
+    "bold bright_yellow": "1;93",
+    "bold bright_red": "1;91",
+    "grey58": "38;5;246",
+    "grey42": "38;5;240",
+    "dark_orange": "38;5;208",
+    "bright_cyan": "96",
+    "bright_magenta": "95",
+    "medium_purple1": "38;5;141",
+    "white": "37",
+    "dim": "2",
+    "bold": "1",
+}
+
+
+def paint(style: str, text: str, enabled: bool = True) -> str:
+    """Wrap ``text`` in the ANSI code for ``style`` when ``enabled``.
+
+    Returns ``text`` untouched when disabled or when the style has no ANSI
+    mapping, so callers can always route through here and let a non-TTY (or an
+    unknown style) degrade to plain text.
+    """
+    if not enabled:
+        return text
+    code = _ANSI.get(style)
+    if not code:
+        return text
+    return f"\x1b[{code}m{text}\x1b[0m"

fleetwatch/remote.py

@@ -0,0 +1,104 @@
+"""Watching other machines, the cheap and robust way.
+
+Instead of tailing a remote host's session files over a long-lived connection,
+fleetwatch asks the remote to do its own normalization and just hand back the
+answer: one ``ssh <host> fleetwatch --export-json`` per refresh returns that
+host's whole fleet as JSON. One command per host (not N file tails), the work
+happens where the files are, and the conversation content never leaves the
+channel you already trust.
+
+A failed fetch does NOT drop the host's sessions — the aggregator keeps the last
+snapshot so an unreachable host reads as "stale", never as "all gone".
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from typing import Optional
+
+from .models import SessionState
+
+
+class RemoteHost:
+    """One machine reachable over ssh, watched by pulling its JSON export."""
+
+    def __init__(
+        self,
+        name: str,
+        ssh_target: Optional[str] = None,
+        command: str = "fleetwatch --export-json",
+        timeout: float = 15.0,
+    ):
+        self.name = name
+        self.ssh_target = ssh_target or name
+        self.command = command
+        self.timeout = timeout
+
+    def fetch(self) -> "tuple[list[SessionState], bool]":
+        """Return ``(sessions, reachable)``. Never raises.
+
+        ``reachable`` is False on any ssh/parse trouble; sessions is then empty
+        and the caller should keep whatever it already had for this host.
+        """
+        # Force heuristics-only on the remote so it never spends tokens; the
+        # local summarizer fills in plain-language summaries for the whole fleet
+        # from one API key.
+        remote_cmd = f"FLEETWATCH_NO_MODEL=1 {self.command}"
+        argv = [
+            "ssh",
+            "-o", "BatchMode=yes",
+            "-o", f"ConnectTimeout={int(self.timeout)}",
+            self.ssh_target,
+            remote_cmd,
+        ]
+        try:
+            proc = subprocess.run(
+                argv,
+                capture_output=True,
+                text=True,
+                timeout=self.timeout + 5,
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            return [], False
+        if proc.returncode != 0 or not proc.stdout.strip():
+            return [], False
+        try:
+            data = json.loads(proc.stdout)
+        except (ValueError, TypeError):
+            return [], False
+        if not isinstance(data, list):
+            return [], False
+
+        out: list[SessionState] = []
+        for d in data:
+            try:
+                st = SessionState.from_dict(d)
+            except Exception:
+                continue
+            st.source = self.name  # relabel: these sessions live on this host
+            out.append(st)
+        return out, True
+
+
+def parse_hosts(spec: str) -> list[RemoteHost]:
+    """Parse a ``--hosts`` / ``FLEETWATCH_HOSTS`` string into RemoteHosts.
+
+    Comma-separated. Each entry is ``name`` or ``name=ssh_target``. The pseudo
+    host ``local`` is ignored here (the aggregator always watches local).
+
+        "dreamer"                       -> ssh dreamer
+        "dreamer=luke@dr.eamer.dev"     -> ssh luke@dr.eamer.dev (labelled dreamer)
+        "local,dreamer,box=user@host"   -> dreamer + box
+    """
+    hosts: list[RemoteHost] = []
+    for raw in (spec or "").split(","):
+        entry = raw.strip()
+        if not entry or entry.lower() == "local":
+            continue
+        if "=" in entry:
+            name, target = entry.split("=", 1)
+            hosts.append(RemoteHost(name.strip(), target.strip()))
+        else:
+            hosts.append(RemoteHost(entry))
+    return hosts