fleetwatcher 0.4.0__py3-none-any.whl

fleetwatch/__init__.py

@@ -0,0 +1,3 @@
+"""fleetwatch — one screen for every terminal coding session you're running."""
+
+__version__ = "0.3.1"

fleetwatch/adapters/__init__.py

@@ -0,0 +1,36 @@
+"""Vendor adapters. ``all_adapters()`` returns the enabled, importable set."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+
+from ..config import ENABLED_VENDORS
+from .base import Adapter, LocalSource, SessionRef, Source
+
+_REGISTRY = {
+    "claude": ("claude", "ClaudeAdapter"),
+    "codex": ("codex", "CodexAdapter"),
+    "grok": ("grok", "GrokAdapter"),
+    "gemini": ("gemini", "GeminiAdapter"),
+}
+
+
+def all_adapters() -> list[Adapter]:
+    """Instantiate every enabled adapter. An adapter that fails to import is
+    skipped with a warning rather than taking the whole tool down."""
+    out: list[Adapter] = []
+    for vendor in ENABLED_VENDORS:
+        spec = _REGISTRY.get(vendor)
+        if not spec:
+            continue
+        module_name, class_name = spec
+        try:
+            mod = importlib.import_module(f".{module_name}", __package__)
+            out.append(getattr(mod, class_name)())
+        except Exception as exc:  # never let one adapter break the others
+            print(f"fleetwatch: skipping {vendor} adapter ({exc})", file=sys.stderr)
+    return out
+
+
+__all__ = ["Adapter", "SessionRef", "Source", "LocalSource", "all_adapters"]

fleetwatch/adapters/base.py

@@ -0,0 +1,112 @@
+"""The adapter contract and the local-filesystem Source.
+
+Adapters never touch the filesystem directly; they go through a ``Source``.
+Today the only Source is ``LocalSource``. A future ``RemoteSource`` (SSH, or a
+pushed JSON export from each host) implements the same surface, so adapters work
+unchanged against VPS sessions.
+"""
+
+from __future__ import annotations
+
+import glob as _glob
+import os
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Optional
+
+from ..models import SessionState
+from ..tailer import read_tail_lines, read_tail_records
+
+
+@dataclass
+class SessionRef:
+    """A pointer to one session's primary file, returned by ``discover()``."""
+
+    path: str                   # the primary transcript / history file
+    session_id: str
+    cwd: Optional[str] = None   # decoded working directory when known
+    mtime: Optional[float] = None  # freshness hint: newest mtime across a
+    #                                multi-file session. When set, the aggregator
+    #                                uses it instead of the primary file's mtime,
+    #                                so a change in any of the session's files
+    #                                (e.g. Grok's events.jsonl) is not missed.
+
+
+class Source(ABC):
+    """Abstracts where session files live so the same adapters can read a remote
+    host later. Implementations must never raise on missing files."""
+
+    host: str = "local"
+
+    @abstractmethod
+    def expand(self, path: str) -> str: ...
+    @abstractmethod
+    def exists(self, path: str) -> bool: ...
+    @abstractmethod
+    def glob(self, pattern: str) -> list[str]: ...
+    @abstractmethod
+    def mtime(self, path: str) -> float: ...
+    @abstractmethod
+    def read_text(self, path: str) -> str: ...
+    @abstractmethod
+    def tail_lines(self, path: str, max_bytes: int = 512_000) -> list[str]: ...
+    @abstractmethod
+    def tail_records(self, path: str, max_bytes: int = 512_000) -> list[dict]: ...
+
+
+class LocalSource(Source):
+    host = "local"
+
+    def expand(self, path: str) -> str:
+        return os.path.expanduser(os.path.expandvars(path))
+
+    def exists(self, path: str) -> bool:
+        return os.path.exists(self.expand(path))
+
+    def glob(self, pattern: str) -> list[str]:
+        return _glob.glob(self.expand(pattern))
+
+    def mtime(self, path: str) -> float:
+        try:
+            return os.path.getmtime(self.expand(path))
+        except OSError:
+            return 0.0
+
+    def read_text(self, path: str) -> str:
+        try:
+            with open(self.expand(path), "r", encoding="utf-8", errors="replace") as fh:
+                return fh.read()
+        except OSError:
+            return ""
+
+    def tail_lines(self, path: str, max_bytes: int = 512_000) -> list[str]:
+        return read_tail_lines(self.expand(path), max_bytes)
+
+    def tail_records(self, path: str, max_bytes: int = 512_000) -> list[dict]:
+        return read_tail_records(self.expand(path), max_bytes)
+
+
+class Adapter(ABC):
+    """One adapter per vendor. Pure translation: vendor files in, SessionState out."""
+
+    vendor: str = "unknown"
+
+    @abstractmethod
+    def discover(self, source: Source) -> list[SessionRef]:
+        """Find candidate sessions for this vendor. Must be cheap — it runs every
+        refresh. Return ``[]`` when the vendor is not installed."""
+        ...
+
+    @abstractmethod
+    def read(
+        self, source: Source, ref: SessionRef, prev: Optional[SessionState]
+    ) -> Optional[SessionState]:
+        """Produce the current SessionState for one ref.
+
+        ``prev`` is the last state held for this session (or ``None`` on first
+        sight). Adapters may use it to carry context forward but must stay
+        correct when it is ``None``. Return ``None`` to skip a ref that is not
+        really a session. This method must not raise: on trouble, return a
+        SessionState with ``state=State.ERROR`` and a message in ``error``.
+        """
+        ...

fleetwatch/adapters/claude.py

@@ -0,0 +1,425 @@
+"""Claude Code adapter.
+
+Claude Code keeps one directory per working tree under ``~/.claude/projects``.
+The directory name is the cwd with every path separator (and other awkward
+characters) rewritten as ``-`` — e.g. ``/Users/luke/workspace`` becomes
+``-Users-luke-workspace``. Inside each directory is one ``<session-uuid>.jsonl``
+file per session (plus an occasional ``subagents/`` subdirectory, which we
+ignore — those are not top-level sessions).
+
+    ~/.claude/projects/<encoded-cwd>/<session-uuid>.jsonl
+
+Each line is one JSON record. The record shapes this adapter cares about, as
+observed in the real transcripts on this machine:
+
+``type`` is the discriminator. The big two are ``"user"`` and ``"assistant"``;
+the file is also peppered with bookkeeping records (``"attachment"``,
+``"summary"``, ``"system"``, ``"file-history-snapshot"``, ``"ai-title"``,
+``"mode"``, ``"last-prompt"``, ...) that have no ``message`` and are skipped.
+
+A message-bearing record carries:
+
+    {
+      "type": "user" | "assistant",
+      "message": {"role": ..., "content": <str | [block, ...]>},
+      "timestamp": "2026-06-17T23:03:50.692Z",   # ISO8601, UTC
+      "sessionId": "<uuid>",
+      "cwd": "/Users/luke/workspace",
+      "uuid": ..., "parentUuid": ...
+    }
+
+``message.content`` is either a plain string (a typed human prompt) or a list
+of typed blocks. Block ``type`` is one of ``text``, ``thinking``, ``tool_use``,
+``tool_result`` (and a few others). A ``tool_use`` block has ``{id, name,
+input}``; the matching ``tool_result`` block (which arrives inside a *later*
+``user`` record) carries ``tool_use_id`` pointing back at it.
+
+WAITING — the whole point of the tool — is detected from a *dangling* tool_use:
+the newest assistant ``tool_use`` whose ``id`` never shows up as a later
+``tool_result``'s ``tool_use_id``. If that exists and the file is stale (not
+ACTIVE), the agent is parked waiting on a tool to run or a permission to be
+granted. While the file is fresh, the same dangling tool_use just means a tool
+is mid-flight, so the session is ACTIVE. An ``AskUserQuestion`` tool_use is an
+explicit "blocked on the human" signal, and a stale plain-text turn ending in
+``?`` means the agent asked a question and is waiting on a reply.
+
+Plans: the current Claude Code builds its task list with ``TaskCreate`` /
+``TaskUpdate`` tool calls rather than a single ``TodoWrite`` blob, so this
+adapter reads both. ``TaskCreate`` input is ``{subject, description?,
+activeForm?}`` and ``TaskUpdate`` input is ``{taskId, status}``; we replay them
+in order to reconstruct the live task list. The classic ``TodoWrite`` shape
+(``input.todos`` = ``[{content, status, activeForm?}]``) is still honored when
+present.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from datetime import datetime
+from typing import Optional
+
+from ..config import ACTIVE_WINDOW, DONE_AFTER
+from ..models import SessionState, State, TodoItem
+from ..util import clean_command
+from .base import Adapter, SessionRef, Source
+
+PROJECTS_GLOB = "~/.claude/projects/*/*.jsonl"
+PROJECTS_ROOT = "~/.claude/projects"
+
+
+def _clip(text: str, limit: int = 280) -> str:
+    """Collapse whitespace and clip to ``limit`` chars for the detail pane."""
+    text = " ".join((text or "").split())
+    if len(text) <= limit:
+        return text
+    return text[: limit - 1].rstrip() + "…"
+
+
+def _basename(path: Optional[str]) -> str:
+    if not path:
+        return ""
+    return os.path.basename(path.replace("\\", "/").rstrip("/"))
+
+
+def _parse_ts(value) -> Optional[float]:
+    """ISO8601 (``...Z``) -> epoch seconds, or ``None`` if unparseable."""
+    if not isinstance(value, str) or not value:
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp()
+    except ValueError:
+        return None
+
+
+def _decode_dir_cwd(path: str) -> Optional[str]:
+    """Best-effort recovery of a cwd from the encoded project directory name.
+
+    ``~/.claude/projects/-Users-luke-workspace/<uuid>.jsonl`` -> ``/Users/luke
+    /workspace``. This is lossy: Claude rewrites both ``/`` and literal ``-`` in
+    directory names as ``-``, so a real ``clocks-app`` is indistinguishable from
+    ``clocks/app``. It is only a fallback for the ``cwd`` field inside records,
+    which is exact.
+    """
+    parts = path.replace("\\", "/").rstrip("/").split("/")
+    if len(parts) < 2:
+        return None
+    name = parts[-2]
+    if not name.startswith("-"):
+        return None
+    return "/" + name[1:].replace("-", "/")
+
+
+def _content_blocks(record: dict) -> list:
+    """The list of typed content blocks for a record, or ``[]`` for string/empty."""
+    msg = record.get("message")
+    if not isinstance(msg, dict):
+        return []
+    content = msg.get("content")
+    return content if isinstance(content, list) else []
+
+
+def _content_str(record: dict) -> Optional[str]:
+    """The raw string content of a record, when ``message.content`` is a string."""
+    msg = record.get("message")
+    if not isinstance(msg, dict):
+        return None
+    content = msg.get("content")
+    return content if isinstance(content, str) else None
+
+
+def _is_command_meta(text: str) -> bool:
+    """Slash-command scaffolding the UI shouldn't show as a real human prompt."""
+    return ("<command-name>" in text or "<local-command-" in text
+            or "<command-message>" in text)
+
+
+def _record_text(record: dict, role: str) -> str:
+    """Human-readable text from a user/assistant record (string or text blocks)."""
+    s = _content_str(record)
+    if s is not None:
+        return "" if _is_command_meta(s) else s
+    chunks = []
+    for b in _content_blocks(record):
+        if isinstance(b, dict) and b.get("type") == "text":
+            t = b.get("text")
+            if isinstance(t, str):
+                chunks.append(t)
+    return " ".join(chunks)
+
+
+def _doing_from_tool_use(block: dict) -> str:
+    """A short, human one-liner describing the latest tool the agent invoked."""
+    name = block.get("name") or "tool"
+    inp = block.get("input") if isinstance(block.get("input"), dict) else {}
+    if name in ("Edit", "Write", "MultiEdit", "NotebookEdit"):
+        return f"editing {_basename(inp.get('file_path'))}".rstrip()
+    if name == "Read":
+        return f"reading {_basename(inp.get('file_path'))}".rstrip()
+    if name == "Bash":
+        cmd = clean_command(inp.get("command") or "")
+        return f"running: {cmd}" if cmd else "running a command"
+    if name in ("Task", "Agent"):
+        return "delegating to subagent"
+    if name in ("TodoWrite", "TaskCreate", "TaskUpdate"):
+        return "updating plan"
+    if name in ("Grep", "Glob"):
+        return "searching"
+    if name == "AskUserQuestion":
+        return "asking a question"
+    if name.startswith("mcp__"):
+        return f"running {name.split('__')[-1]}"
+    return f"running {name}"
+
+
+def _status_of(item: dict) -> str:
+    status = item.get("status")
+    if status in ("pending", "in_progress", "completed"):
+        return status
+    return "pending"
+
+
+def _todos_from_records(records: list) -> list[TodoItem]:
+    """Reconstruct the live task list from the transcript.
+
+    Two shapes are supported, newest-wins:
+
+    * Classic ``TodoWrite`` — ``input.todos`` is the whole list. The most recent
+      one replaces everything.
+    * Current ``TaskCreate`` / ``TaskUpdate`` — replayed in order. ``TaskCreate``
+      adds an item (keyed by position, since ``taskId`` is "1", "2", ... in
+      creation order); ``TaskUpdate`` flips an existing item's status.
+    """
+    todo_write: Optional[list[TodoItem]] = None
+    created: list[dict] = []  # ordered {"text", "status"} for TaskCreate/Update
+
+    for rec in records:
+        if rec.get("type") != "assistant":
+            continue
+        for b in _content_blocks(rec):
+            if not isinstance(b, dict) or b.get("type") != "tool_use":
+                continue
+            name = b.get("name")
+            inp = b.get("input") if isinstance(b.get("input"), dict) else {}
+            if name == "TodoWrite":
+                items = inp.get("todos")
+                if isinstance(items, list):
+                    todo_write = [
+                        TodoItem(text=str(it.get("content", "")).strip(),
+                                 status=_status_of(it))
+                        for it in items
+                        if isinstance(it, dict) and it.get("content")
+                    ]
+            elif name == "TaskCreate":
+                subject = (inp.get("subject")
+                           or inp.get("activeForm")
+                           or inp.get("description") or "").strip()
+                if subject:
+                    created.append({"text": subject, "status": "pending"})
+            elif name == "TaskUpdate":
+                tid = inp.get("taskId")
+                status = inp.get("status")
+                try:
+                    idx = int(tid) - 1
+                except (TypeError, ValueError):
+                    idx = -1
+                if 0 <= idx < len(created) and status in (
+                    "pending", "in_progress", "completed"
+                ):
+                    created[idx]["status"] = status
+
+    if todo_write is not None:
+        return [t for t in todo_write if t.text]
+    return [TodoItem(text=c["text"], status=c["status"]) for c in created if c["text"]]
+
+
+def _latest_assistant_tool_use(records: list) -> Optional[dict]:
+    """The newest assistant ``tool_use`` block in the transcript, or ``None``."""
+    for rec in reversed(records):
+        if rec.get("type") != "assistant":
+            continue
+        for b in reversed(_content_blocks(rec)):
+            if isinstance(b, dict) and b.get("type") == "tool_use":
+                return b
+    return None
+
+
+def _resolved_tool_use_ids(records: list) -> set:
+    """Every ``tool_use_id`` that has a matching ``tool_result`` (i.e. completed)."""
+    done = set()
+    for rec in records:
+        for b in _content_blocks(rec):
+            if isinstance(b, dict) and b.get("type") == "tool_result":
+                tid = b.get("tool_use_id")
+                if tid:
+                    done.add(tid)
+    return done
+
+
+def _last_role_text(records: list, role: str) -> str:
+    """The most recent non-empty human-readable text for ``role``."""
+    rtype = "user" if role == "user" else "assistant"
+    for rec in reversed(records):
+        if rec.get("type") != rtype:
+            continue
+        text = _record_text(rec, role)
+        if text.strip():
+            return text
+    return ""
+
+
+def _last_timestamp(records: list) -> Optional[float]:
+    for rec in reversed(records):
+        ts = _parse_ts(rec.get("timestamp"))
+        if ts is not None:
+            return ts
+    return None
+
+
+def _cwd_from_records(records: list) -> Optional[str]:
+    for rec in reversed(records):
+        cwd = rec.get("cwd")
+        if isinstance(cwd, str) and cwd:
+            return cwd
+    return None
+
+
+class ClaudeAdapter(Adapter):
+    vendor = "claude"
+
+    def discover(self, source: Source) -> list[SessionRef]:
+        try:
+            if not source.exists(PROJECTS_ROOT):
+                return []
+            refs: list[SessionRef] = []
+            for path in source.glob(PROJECTS_GLOB):
+                # Ignore subagent transcripts nested under <session>/subagents/.
+                norm = path.replace("\\", "/")
+                if "/subagents/" in norm:
+                    continue
+                stem = _basename(path)
+                if stem.endswith(".jsonl"):
+                    stem = stem[: -len(".jsonl")]
+                refs.append(
+                    SessionRef(
+                        path=path,
+                        session_id=stem,
+                        cwd=_decode_dir_cwd(path),
+                    )
+                )
+            return refs
+        except Exception:
+            return []
+
+    def read(
+        self, source: Source, ref: SessionRef, prev: Optional[SessionState]
+    ) -> Optional[SessionState]:
+        try:
+            return self._read(source, ref)
+        except Exception as exc:  # read() must never raise
+            return SessionState(
+                vendor=self.vendor,
+                session_id=ref.session_id,
+                project=_basename(ref.cwd) or ref.session_id,
+                cwd=ref.cwd,
+                source=getattr(source, "host", "local"),
+                last_activity=None,
+                state=State.ERROR,
+                error=f"read failed: {type(exc).__name__}",
+            )
+
+    def _read(self, source: Source, ref: SessionRef) -> Optional[SessionState]:
+        records = source.tail_records(ref.path)
+
+        now = time.time()
+        mtime = source.mtime(ref.path)
+        recency = now - mtime if mtime else None
+
+        cwd = _cwd_from_records(records) or ref.cwd
+        project = _basename(cwd) or ref.session_id
+
+        if not records:
+            # Empty or wholly unparseable tail — flag rather than fabricate state.
+            return SessionState(
+                vendor=self.vendor,
+                session_id=ref.session_id,
+                project=project,
+                cwd=cwd,
+                source=getattr(source, "host", "local"),
+                last_activity=mtime or None,
+                state=State.ERROR,
+                error="no readable records",
+            )
+
+        last_ts = _last_timestamp(records)
+        last_activity = mtime or last_ts
+
+        last_user = _clip(_last_role_text(records, "user"))
+        last_agent = _clip(_last_role_text(records, "assistant"))
+        todos = _todos_from_records(records)
+
+        latest_tool = _latest_assistant_tool_use(records)
+        resolved = _resolved_tool_use_ids(records)
+        dangling_tool = (
+            latest_tool is not None
+            and latest_tool.get("id") is not None
+            and latest_tool.get("id") not in resolved
+        )
+
+        doing = ""
+        if latest_tool is not None:
+            doing = _doing_from_tool_use(latest_tool)
+        elif last_agent:
+            doing = _clip(last_agent, 80)
+
+        is_active = recency is not None and recency <= ACTIVE_WINDOW
+        is_stale = not is_active
+
+        state = State.IDLE
+        needs: Optional[str] = None
+
+        if is_active:
+            # Activity beats everything. A dangling tool_use here is just a tool
+            # mid-run, not a block.
+            state = State.ACTIVE
+        else:
+            asking = (
+                latest_tool is not None
+                and latest_tool.get("name") == "AskUserQuestion"
+            )
+            ends_in_question = (
+                latest_tool is None
+                and bool(last_agent)
+                and last_agent.rstrip().endswith("?")
+            )
+            if dangling_tool and asking:
+                state = State.WAITING
+                needs = "answer a question"
+            elif dangling_tool:
+                state = State.WAITING
+                needs = "waiting on tool/permission"
+            elif ends_in_question:
+                state = State.WAITING
+                needs = "asked a question"
+            else:
+                # A completed turn: IDLE while recent, DONE once it goes cold.
+                if recency is not None and recency >= DONE_AFTER:
+                    state = State.DONE
+                else:
+                    state = State.IDLE
+
+        return SessionState(
+            vendor=self.vendor,
+            session_id=ref.session_id,
+            project=project,
+            cwd=cwd,
+            source=getattr(source, "host", "local"),
+            last_activity=last_activity,
+            state=state,
+            doing=doing,
+            needs=needs,
+            summary=None,
+            todos=todos,
+            last_user=last_user,
+            last_agent=last_agent,
+        )