fleetwatcher 0.4.0__py3-none-any.whl

fleetwatch/render.py

@@ -0,0 +1,157 @@
+"""Plain-text snapshot rendering for ``fleetwatch --once``.
+
+This module is deliberately dependency-light: it produces a single multi-line
+string from a list of :class:`~fleetwatch.models.SessionState`. The TUI uses
+Textual, but ``--once`` (and any pipe-to-a-log usage) only needs text, so this
+stays importable and runnable with nothing but the standard library.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Iterable, Optional
+
+from .models import SessionState, State
+from .palette import paint, state_glyph, state_style, vendor_style
+
+
+# Order counts appear in the header line, matching the lifecycle in State.
+_COUNT_ORDER = ("active", "waiting", "idle", "done", "error")
+
+
+def humanize_age(last_activity: Optional[float], now: Optional[float] = None) -> str:
+    """Render a seconds-since-epoch timestamp as a compact age (e.g. "5m").
+
+    ``None`` -> "-". Buckets: <60s -> Ns, <1h -> Nm, <1d -> Nh, else Nd.
+    """
+    if last_activity is None:
+        return "-"
+    now = time.time() if now is None else now
+    delta = now - last_activity
+    if delta < 0:
+        delta = 0
+    if delta < 60:
+        return f"{int(delta)}s"
+    if delta < 3600:
+        return f"{int(delta // 60)}m"
+    if delta < 86400:
+        return f"{int(delta // 3600)}h"
+    return f"{int(delta // 86400)}d"
+
+
+def _truncate(text: str, width: int) -> str:
+    text = (text or "").replace("\n", " ").strip()
+    if len(text) <= width:
+        return text
+    if width <= 1:
+        return text[:width]
+    return text[: width - 1] + "…"  # ellipsis
+
+
+def _header(counts: Optional[dict], now: float, color: bool = False) -> list[str]:
+    clock = time.strftime("%H:%M:%S", time.localtime(now))
+    head = paint("cyan", "fleetwatch", color)
+    clock_s = paint("grey58", clock, color)
+    if not counts:
+        return [f"{head}  {clock_s}"]
+    parts = []
+    for name in _COUNT_ORDER:
+        if name in counts:
+            chunk = f"{name} {counts[name]}"
+            if name in State._value2member_map_:
+                chunk = paint(state_style(State(name)), chunk, color)
+            parts.append(chunk)
+    total = counts.get("total")
+    summary = "  ".join(parts)
+    if total is not None:
+        total_s = paint("bold", f"total {total}", color)
+        summary = f"{summary}  ({total_s})" if summary else total_s
+    return [f"{head}  {clock_s}  {summary}".rstrip()]
+
+
+def render_snapshot(
+    sessions: Iterable[SessionState],
+    counts: Optional[dict] = None,
+    now: Optional[float] = None,
+    color: bool = False,
+) -> str:
+    """Return a clean multi-line text table for ``fleetwatch --once``.
+
+    One line per session: vendor, project, state, humanized idle age, a "!"
+    when the session needs attention, and the doing/needs text. A header with
+    counts is included when ``counts`` is provided. An empty list renders a
+    friendly placeholder.
+
+    With ``color=True`` the same state/vendor palette as the dashboard is
+    written as ANSI; the CLI turns it on only when stdout is a TTY, so piping
+    ``--once`` to a file or a log stays plain text. Column widths are computed
+    on the uncolored text, so alignment holds whether or not color is on.
+    """
+    sessions = list(sessions)
+    now = time.time() if now is None else now
+
+    lines = _header(counts, now, color)
+
+    if not sessions:
+        lines.append("")
+        lines.append("No active sessions.")
+        return "\n".join(lines)
+
+    # Only show a host column when watching more than one source, so the
+    # single-machine view stays uncluttered.
+    sources = {s.source for s in sessions}
+    show_host = len(sources) > 1
+
+    # Column widths sized to content, with sane caps.
+    host_w = min(10, max(4, *(len(s.source) for s in sessions))) if show_host else 0
+    vendor_w = max(6, *(len(s.vendor) for s in sessions))
+    project_w = min(24, max(7, *(len(s.project) for s in sessions)))
+    state_w = max(len(str(s.state)) for s in sessions)
+    state_w = max(state_w, 5)
+
+    host_head = f"{'HOST':<{host_w}}  " if show_host else ""
+    header_row = (
+        f"{host_head}"
+        f"{'VENDOR':<{vendor_w}}  "
+        f"{'PROJECT':<{project_w}}  "
+        f"  {'STATE':<{state_w}}  "  # two-space gutter under the status glyph
+        f"{'IDLE':>4}  "
+        f"{'!':<1}  "
+        f"WHAT"
+    )
+    lines.append("")
+    lines.append(header_row)
+    lines.append("─" * len(header_row))
+
+    for s in sessions:
+        age = humanize_age(s.last_activity, now)
+        bang = "!" if s.needs_attention else " "
+        # Prefer the human-facing "needs" reason when attention is wanted,
+        # otherwise the adapter's "doing" one-liner.
+        what = s.needs if (s.needs_attention and s.needs) else s.doing
+
+        # Pad to width first, then paint, so the ANSI bytes never throw the
+        # column alignment off.
+        vendor_c = paint(vendor_style(s.vendor),
+                         f"{_truncate(s.vendor, vendor_w):<{vendor_w}}", color)
+        state_c = paint(state_style(s.state),
+                        f"{state_glyph(s.state)} {str(s.state):<{state_w}}", color)
+        age_c = paint("grey58", f"{age:>4}", color)
+        bang_c = (paint("bold bright_red", f"{bang:<1}", color)
+                  if s.needs_attention else f"{bang:<1}")
+        host_cell = ""
+        if show_host:
+            host_cell = paint("grey58",
+                              f"{_truncate(s.source, host_w):<{host_w}}", color) + "  "
+
+        lines.append(
+            f"{host_cell}"
+            f"{vendor_c}  "
+            f"{_truncate(s.project, project_w):<{project_w}}  "
+            f"{state_c}  "
+            f"{age_c}  "
+            f"{bang_c}  "
+            f"{_truncate(what, 60)}"
+        )
+
+    return "\n".join(lines)

fleetwatch/summarize.py

@@ -0,0 +1,141 @@
+"""Hybrid plain-language summaries.
+
+Every session already carries a free, instant heuristic one-liner (``doing``,
+set by its adapter). On top of that, this module asks a fast model (Haiku) for a
+single plain-language sentence — but only for sessions that need attention, and
+only once per distinct activity timestamp. Results are cached and written back
+onto the SessionState in place, off the UI thread, so the dashboard never blocks
+on the network and idle fleets cost nothing.
+
+If there is no API key, or the model is disabled, this degrades silently to the
+heuristic line (``summary`` simply stays ``None`` and the UI falls back to
+``doing``).
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+from typing import Optional
+
+from . import config
+from .models import SessionState
+
+_SYSTEM = (
+    "You report the status of a developer's terminal coding session in ONE "
+    "plain-language sentence, 25 words max. Say what it is doing and, if it is "
+    "blocked, exactly what it needs from the user. No preamble, no markdown, no "
+    "quotes — just the sentence."
+)
+
+
+class Summarizer:
+    """Background, cached, best-effort model summaries."""
+
+    def __init__(self, model: Optional[str] = None, use_model: Optional[bool] = None):
+        self.model = model or config.SUMMARY_MODEL
+        use = config.USE_MODEL if use_model is None else use_model
+        self._client = None
+        self._pool: Optional[ThreadPoolExecutor] = None
+        self._cache: dict = {}      # (key, last_activity) -> sentence
+        self._inflight: set = set()
+        self._lock = threading.Lock()
+
+        if use and os.environ.get("ANTHROPIC_API_KEY"):
+            try:
+                import anthropic
+
+                self._client = anthropic.Anthropic()
+                self._pool = ThreadPoolExecutor(
+                    max_workers=2, thread_name_prefix="fw-summary"
+                )
+            except Exception:
+                self._client = None  # any import/auth trouble → heuristics only
+
+    @property
+    def enabled(self) -> bool:
+        return self._client is not None
+
+    def cached(self, st: SessionState) -> Optional[str]:
+        """Return a cached sentence for this session's current activity, if any."""
+        with self._lock:
+            return self._cache.get((st.key, st.last_activity))
+
+    def request(self, st: SessionState, force: bool = False) -> None:
+        """Ensure a summary exists for ``st``, computing it in the background.
+
+        Applies a cached result immediately when available; otherwise schedules
+        one model call (deduplicated per activity timestamp unless ``force``).
+        """
+        if not self.enabled:
+            return
+        ckey = (st.key, st.last_activity)
+        with self._lock:
+            if ckey in self._cache:
+                st.summary = self._cache[ckey]
+                if not force:
+                    return
+            if ckey in self._inflight:
+                return
+            if self._pool is None:  # enabled implies a pool, but never assert in a thread
+                return
+            self._inflight.add(ckey)
+        self._pool.submit(self._run, st, ckey)
+
+    def drain(self, timeout: float = 6.0) -> None:
+        """Block until in-flight summaries finish (or timeout). Used by --once."""
+        if not self.enabled:
+            return
+        end = time.time() + timeout
+        while time.time() < end:
+            with self._lock:
+                if not self._inflight:
+                    return
+            time.sleep(0.1)
+
+    # --- internals ---
+
+    def _run(self, st: SessionState, ckey) -> None:
+        text = None
+        try:
+            text = self._call_model(st)
+        except Exception:
+            text = None  # network/model failure → leave heuristic in place
+        with self._lock:
+            self._inflight.discard(ckey)
+            if text:
+                self._cache[ckey] = text
+        if text:
+            st.summary = text
+
+    def _call_model(self, st: SessionState) -> Optional[str]:
+        msg = self._client.messages.create(  # type: ignore[union-attr]
+            model=self.model,
+            max_tokens=120,
+            system=_SYSTEM,
+            messages=[{"role": "user", "content": self._build_prompt(st)}],
+        )
+        parts = [
+            b.text for b in msg.content if getattr(b, "type", None) == "text"
+        ]
+        # Collapse to a single clean line: a model that returns multiple text
+        # blocks or internal newlines must never read as concatenated summaries.
+        out = " ".join(" ".join(parts).split()).strip()
+        if len(out) > 240:
+            out = out[:239].rstrip() + "…"
+        return out or None
+
+    def _build_prompt(self, st: SessionState) -> str:
+        todos = "\n".join(f"- [{t.status}] {t.text}" for t in st.todos[:8])
+        return (
+            f"Vendor: {st.vendor}\n"
+            f"Project: {st.project}\n"
+            f"State: {st.state}\n"
+            f"Needs: {st.needs or '-'}\n"
+            f"Heuristic activity: {st.doing or '-'}\n"
+            f"Most recent user message: {st.last_user[:400] or '-'}\n"
+            f"Most recent agent message: {st.last_agent[:400] or '-'}\n"
+            f"Plan / todos:\n{todos or '-'}"
+        )

fleetwatch/tailer.py

@@ -0,0 +1,63 @@
+"""Bounded, crash-proof reads of append-only JSONL transcripts.
+
+Session transcripts can be tens of megabytes (one on this machine is 25 MB) and
+are written while we read them, so the final line is frequently a half-finished
+write. Everything here reads only a bounded tail and never raises on a partial
+final line or a missing file.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+DEFAULT_TAIL_BYTES = 512_000  # ~0.5 MB of tail captures plenty of recent activity
+
+
+def read_tail_lines(path: str, max_bytes: int = DEFAULT_TAIL_BYTES) -> list[str]:
+    """Return complete, non-empty text lines from the last ``max_bytes`` of a file.
+
+    If we did not start at byte 0, the first (possibly partial) line is dropped.
+    Returns ``[]`` for a missing, empty, or unreadable file instead of raising.
+    """
+    try:
+        size = os.path.getsize(path)
+    except OSError:
+        return []
+    if size == 0:
+        return []
+    start = max(0, size - max_bytes)
+    try:
+        with open(path, "rb") as fh:
+            fh.seek(start)
+            chunk = fh.read()
+    except OSError:
+        return []
+    text = chunk.decode("utf-8", errors="replace")
+    lines = text.split("\n")
+    if start > 0 and lines:
+        lines = lines[1:]  # the leading line is truncated; drop it
+    return [ln for ln in lines if ln.strip()]
+
+
+def parse_jsonl_lines(lines: list[str]) -> list[dict[str, Any]]:
+    """Parse lines into dicts, silently skipping any that do not parse.
+
+    The last line is often a partial live write, so unparseable lines are
+    expected and ignored rather than treated as errors.
+    """
+    out: list[dict[str, Any]] = []
+    for ln in lines:
+        try:
+            obj = json.loads(ln)
+        except (ValueError, TypeError):
+            continue
+        if isinstance(obj, dict):
+            out.append(obj)
+    return out
+
+
+def read_tail_records(path: str, max_bytes: int = DEFAULT_TAIL_BYTES) -> list[dict[str, Any]]:
+    """Convenience: tail a file and parse its JSONL lines in one step."""
+    return parse_jsonl_lines(read_tail_lines(path, max_bytes))