agenthud 0.1.5__py3-none-any.whl

agenthud/__init__.py

@@ -0,0 +1,3 @@
+"""Cross-tool agent session HUD."""
+
+__version__ = "0.1.5"

agenthud/__main__.py

@@ -0,0 +1,4 @@
+from agenthud.cli import main
+
+if __name__ == "__main__":
+    main()

agenthud/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapter package."""

agenthud/adapters/claude.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+from agenthud.models import Session, Status, Tool
+from agenthud.paths import home, project_basename
+
+
+def _projects_root() -> Path:
+    return home() / ".claude" / "projects"
+
+
+def _infer(last_role: str | None, mtime: float, now: float) -> tuple[Status, str]:
+    age = now - mtime
+    if last_role == "user":
+        if age < 600:
+            return Status.WAITING, "awaiting reply"
+        return Status.IDLE, "last: user"
+    if last_role == "assistant":
+        if age < 45:
+            return Status.RUNNING, "recent activity"
+        if age < 3600:
+            return Status.IDLE, "last: assistant"
+        return Status.DONE, "stale"
+    if age < 60:
+        return Status.RUNNING, "recent"
+    return Status.UNKNOWN, ""
+
+
+def _scan_jsonl(path: Path) -> tuple[str | None, str]:
+    try:
+        size = path.stat().st_size
+        with path.open("rb") as f:
+            if size > 96_000:
+                f.seek(-96_000, 2)
+            raw = f.read().decode("utf-8", errors="replace")
+    except OSError:
+        return None, ""
+    last_role = None
+    title = ""
+    for line in raw.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        role = obj.get("role") or obj.get("type")
+        if role in {"user", "assistant", "human"}:
+            last_role = "user" if role in {"user", "human"} else "assistant"
+        msg = obj.get("message") or obj.get("content") or ""
+        text = ""
+        if isinstance(msg, str):
+            text = msg
+        elif isinstance(msg, dict):
+            c = msg.get("content")
+            if isinstance(c, str):
+                text = c
+            elif isinstance(c, list):
+                for part in c:
+                    if isinstance(part, dict) and part.get("type") == "text":
+                        text = str(part.get("text") or "")
+                        break
+        if last_role == "user" and text:
+            title = " ".join(text.split())[:80]
+    return last_role, title
+
+
+def collect(*, limit: int = 40, max_age_hours: float = 72) -> list[Session]:
+    root = _projects_root()
+    if not root.is_dir():
+        return []
+    now = time.time()
+    cutoff = now - max_age_hours * 3600
+    found: list[tuple[float, Path, Path]] = []
+    for project in root.iterdir():
+        if not project.is_dir():
+            continue
+        for path in project.glob("*.jsonl"):
+            try:
+                mtime = path.stat().st_mtime
+            except OSError:
+                continue
+            if mtime < cutoff:
+                continue
+            found.append((mtime, project, path))
+    found.sort(key=lambda t: t[0], reverse=True)
+
+    sessions: list[Session] = []
+    for mtime, project, path in found[:limit]:
+        last_role, title = _scan_jsonl(path)
+        status, detail = _infer(last_role, mtime, now)
+        sessions.append(
+            Session(
+                id=path.stem,
+                tool=Tool.CLAUDE,
+                title=title or path.stem[:8],
+                status=status,
+                project=project_basename(project.name.replace("-", "/")),
+                updated_at=mtime,
+                detail=detail,
+                path=str(path),
+            )
+        )
+    return sessions

agenthud/adapters/codex.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+from agenthud.models import Session, Status, Tool
+from agenthud.paths import home, project_basename
+
+
+def _codex_root() -> Path:
+    return home() / ".codex" / "sessions"
+
+
+def _parse_iso(ts: str | None) -> float:
+    if not ts:
+        return 0.0
+    try:
+        # 2026-09-19T13:53:13.175Z
+        from datetime import datetime
+
+        return datetime.fromisoformat(ts.replace("Z", "+00:00")).timestamp()
+    except ValueError:
+        return 0.0
+
+
+def _title_and_status(path: Path) -> tuple[str, Status, str, float]:
+    title = path.stem
+    status = Status.IDLE
+    detail = ""
+    updated = path.stat().st_mtime
+    cwd = ""
+    try:
+        size = path.stat().st_size
+        with path.open("rb") as f:
+            if size > 120_000:
+                f.seek(-120_000, 2)
+            raw = f.read().decode("utf-8", errors="replace")
+    except OSError:
+        return title, Status.UNKNOWN, "", updated
+
+    for line in raw.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        ts = _parse_iso(obj.get("timestamp"))
+        if ts:
+            updated = max(updated, ts)
+        typ = obj.get("type")
+        payload = obj.get("payload") or {}
+        if typ == "session_meta":
+            cwd = str((payload.get("cwd") or payload.get("directory") or ""))
+            if payload.get("title"):
+                title = str(payload["title"])
+        if typ == "event_msg":
+            et = payload.get("type")
+            if et == "task_complete":
+                err = payload.get("error") or {}
+                if err:
+                    status = Status.ERROR
+                    detail = str(err.get("message") or err.get("codex_error_info") or "error")[:80]
+                else:
+                    status = Status.DONE
+                    detail = "complete"
+            item = payload.get("item") or {}
+            if item.get("type") == "UserMessage" and not title.startswith("rollout"):
+                pass
+            if item.get("type") == "UserMessage":
+                content = item.get("content") or []
+                for part in content:
+                    if isinstance(part, dict) and part.get("type") == "text":
+                        text = " ".join(str(part.get("text") or "").split())
+                        if text:
+                            title = text[:80]
+
+    age = time.time() - updated
+    if status == Status.IDLE and age < 90:
+        status = Status.RUNNING
+        detail = "recent"
+    elif status == Status.IDLE and age > 3600 * 6:
+        status = Status.DONE
+        detail = detail or "stale"
+    return title, status, detail, updated
+
+
+def collect(*, limit: int = 40, max_age_hours: float = 72) -> list[Session]:
+    root = _codex_root()
+    if not root.is_dir():
+        return []
+    cutoff = time.time() - max_age_hours * 3600
+    files: list[Path] = []
+    for path in root.rglob("rollout-*.jsonl"):
+        try:
+            if path.stat().st_mtime >= cutoff:
+                files.append(path)
+        except OSError:
+            continue
+    files.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+
+    sessions: list[Session] = []
+    for path in files[:limit]:
+        # rollout-...-<uuid>.jsonl
+        sid = path.stem
+        if "rollout-" in sid:
+            parts = sid.split("-")
+            # uuid often last 5 segments
+            sid = "-".join(parts[-5:]) if len(parts) >= 5 else sid
+        title, status, detail, updated = _title_and_status(path)
+        # try cwd from first bytes only already in parse — re-read meta lightly
+        project = project_basename(str(path.parent))
+        sessions.append(
+            Session(
+                id=sid,
+                tool=Tool.CODEX,
+                title=title,
+                status=status,
+                project=project,
+                updated_at=updated,
+                detail=detail,
+                path=str(path),
+            )
+        )
+    return sessions

agenthud/adapters/cursor.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import json
+import re
+import time
+from pathlib import Path
+
+from agenthud.models import Session, Status, Tool
+from agenthud.paths import cursor_projects_dir
+
+_USER_QUERY_RE = re.compile(
+    r"<user_query>\s*(.*?)\s*</user_query>",
+    re.DOTALL | re.IGNORECASE,
+)
+
+
+def _project_label(project_dir: Path) -> str:
+    """Map Cursor project folder slug to a short label."""
+    name = project_dir.name
+    # Users-ayaan-Documents-Default-Project → Default Project
+    for prefix in (
+        "Users-ayaan-Documents-",
+        "Users-ayaan-",
+        "Users-",
+    ):
+        if name.startswith(prefix):
+            name = name[len(prefix) :]
+            break
+    return name.replace("-", " ")
+
+
+def _infer_status(last_role: str | None, mtime: float, now: float) -> tuple[Status, str]:
+    age = now - mtime
+    if last_role == "user":
+        if age < 600:
+            return Status.WAITING, "awaiting agent reply"
+        return Status.IDLE, "last: user"
+    if last_role == "assistant":
+        if age < 45:
+            return Status.RUNNING, "recent assistant activity"
+        if age < 3600:
+            return Status.IDLE, "last: assistant"
+        return Status.DONE, "stale"
+    if age < 60:
+        return Status.RUNNING, "recently updated"
+    return Status.UNKNOWN, ""
+
+
+def _text_from_message(obj: dict) -> str:
+    msg = obj.get("message") or {}
+    content = msg.get("content")
+    if isinstance(content, list):
+        parts: list[str] = []
+        for part in content:
+            if isinstance(part, dict) and part.get("type") == "text":
+                parts.append(str(part.get("text") or ""))
+        return "\n".join(parts)
+    if isinstance(content, str):
+        return content
+    return ""
+
+
+def _title_from_text(text: str) -> str:
+    matches = _USER_QUERY_RE.findall(text)
+    if matches:
+        text = matches[-1]
+    else:
+        # drop injected timestamp / websearch blobs
+        text = re.sub(r"<timestamp>.*?</timestamp>", "", text, flags=re.DOTALL)
+        text = re.sub(r"<external_links>.*", "", text, flags=re.DOTALL | re.IGNORECASE)
+    text = " ".join(text.split())
+    return text[:80]
+
+
+def _last_role_and_snippet(path: Path) -> tuple[str | None, str]:
+    """Read last few KB of jsonl for last role + last user_query title."""
+    try:
+        size = path.stat().st_size
+        with path.open("rb") as f:
+            if size > 96_000:
+                f.seek(-96_000, 2)
+            raw = f.read().decode("utf-8", errors="replace")
+    except OSError:
+        return None, ""
+
+    last_role: str | None = None
+    title = ""
+    for line in raw.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        role = obj.get("role")
+        if role:
+            last_role = role
+        if role == "user":
+            candidate = _title_from_text(_text_from_message(obj))
+            if candidate:
+                title = candidate
+
+    return last_role, title
+
+
+def collect(*, limit: int = 40, max_age_hours: float = 72) -> list[Session]:
+    root = cursor_projects_dir()
+    if not root.is_dir():
+        return []
+
+    now = time.time()
+    cutoff = now - max_age_hours * 3600
+    found: list[tuple[float, Path, Path]] = []
+
+    for project in root.iterdir():
+        transcripts = project / "agent-transcripts"
+        if not transcripts.is_dir():
+            continue
+        for entry in transcripts.iterdir():
+            jsonl = entry / f"{entry.name}.jsonl" if entry.is_dir() else entry
+            if not jsonl.name.endswith(".jsonl"):
+                # also accept flat uuid.jsonl under agent-transcripts
+                if entry.is_file() and entry.suffix == ".jsonl":
+                    jsonl = entry
+                else:
+                    continue
+            if not jsonl.is_file():
+                continue
+            try:
+                mtime = jsonl.stat().st_mtime
+            except OSError:
+                continue
+            if mtime < cutoff:
+                continue
+            found.append((mtime, project, jsonl))
+
+    found.sort(key=lambda t: t[0], reverse=True)
+    sessions: list[Session] = []
+    for mtime, project, jsonl in found[:limit]:
+        last_role, snippet = _last_role_and_snippet(jsonl)
+        status, detail = _infer_status(last_role, mtime, now)
+        sid = jsonl.stem
+        title = snippet or sid[:8]
+        sessions.append(
+            Session(
+                id=sid,
+                tool=Tool.CURSOR,
+                title=title,
+                status=status,
+                project=_project_label(project),
+                updated_at=mtime,
+                detail=detail,
+                path=str(jsonl),
+                extra={"project_dir": str(project)},
+            )
+        )
+    return sessions

agenthud/adapters/freebuff.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from pathlib import Path
+
+from agenthud.models import Session, Status, Tool
+from agenthud.paths import freebuff_config_dir, project_basename
+
+
+def _ms_to_s(value: int | float | None) -> float:
+    if value is None:
+        return 0.0
+    v = float(value)
+    return v / 1000.0 if v > 1_000_000_000_000 else v
+
+
+def _map_status(
+    turn_state: str,
+    attention_reason: str | None,
+    last_outcome: str | None,
+    attention_rev: int,
+    attention_ack: int,
+) -> tuple[Status, str]:
+    ts = (turn_state or "idle").lower()
+    reason = (attention_reason or "").lower()
+    outcome = (last_outcome or "").lower()
+    needs_attention = attention_rev > attention_ack
+
+    if ts in {"running", "working", "streaming", "thinking"}:
+        return Status.RUNNING, ts
+    if ts in {"waiting", "blocked", "needs_input", "ask_user"}:
+        return Status.WAITING, ts
+    if outcome in {"error", "failed"} or reason in {"failed", "error"}:
+        return Status.ERROR, reason or outcome or "error"
+    if needs_attention and reason:
+        if reason in {"finished", "completed"}:
+            return Status.DONE, f"attention: {reason}"
+        if reason in {"failed", "error"}:
+            return Status.ERROR, f"attention: {reason}"
+        return Status.WAITING, f"attention: {reason}"
+    if outcome in {"completed", "finished"} or reason in {"finished", "completed"}:
+        return Status.DONE, outcome or reason
+    if outcome == "stopped" or reason == "stopped":
+        return Status.IDLE, "stopped"
+    if ts == "idle":
+        return Status.IDLE, ""
+    return Status.UNKNOWN, ts
+
+
+def _active_tab_ids(config: Path) -> set[str]:
+    state_path = config / "state.json"
+    if not state_path.is_file():
+        return set()
+    try:
+        data = json.loads(state_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return set()
+    tabs = (data.get("workspace") or {}).get("tabs") or []
+    return {str(t.get("id")) for t in tabs if isinstance(t, dict) and t.get("id")}
+
+
+def _collect_from_db(db_path: Path, *, limit: int, cutoff_ms: int, open_tabs: set[str]) -> list[Session]:
+    try:
+        uri = f"file:{db_path}?mode=ro"
+        conn = sqlite3.connect(uri, uri=True, timeout=1.0)
+        conn.row_factory = sqlite3.Row
+        rows = conn.execute(
+            """
+            SELECT id, title, project_path, turn_state, status,
+                   attention_reason, attention_revision, attention_acknowledged_revision,
+                   last_turn_outcome, last_prompt_at, last_turn_finished_at, updated_at,
+                   model, agent_mode
+            FROM threads
+            WHERE updated_at >= ?
+            ORDER BY updated_at DESC
+            LIMIT ?
+            """,
+            (cutoff_ms, limit),
+        ).fetchall()
+        conn.close()
+    except sqlite3.Error:
+        return []
+
+    now = time.time()
+    out: list[Session] = []
+    for row in rows:
+        status, detail = _map_status(
+            str(row["turn_state"] or "idle"),
+            row["attention_reason"],
+            row["last_turn_outcome"],
+            int(row["attention_revision"] or 0),
+            int(row["attention_acknowledged_revision"] or 0),
+        )
+        # Open workspace tabs that are idle still matter — mark as open
+        sid = str(row["id"])
+        if sid in open_tabs and status in {Status.IDLE, Status.DONE, Status.UNKNOWN}:
+            detail = (detail + " · open tab").strip(" ·")
+        model = row["model"] or row["agent_mode"] or ""
+        if model:
+            detail = f"{detail} · {model}".strip(" ·")
+        updated = _ms_to_s(row["updated_at"])
+        # Freshly running heuristic: turn_alive / recent prompt
+        if status == Status.IDLE:
+            prompt_at = _ms_to_s(row["last_prompt_at"])
+            finished = _ms_to_s(row["last_turn_finished_at"])
+            if prompt_at and prompt_at > finished and (now - prompt_at) < 180:
+                status = Status.RUNNING
+                detail = "prompt in flight"
+        out.append(
+            Session(
+                id=sid,
+                tool=Tool.FREEBUFF,
+                title=str(row["title"] or sid[:8]),
+                status=status,
+                project=project_basename(str(row["project_path"] or "")),
+                updated_at=updated,
+                detail=detail,
+                path=str(row["project_path"] or ""),
+                extra={"db": str(db_path), "thread_status": row["status"]},
+            )
+        )
+    return out
+
+
+def collect(*, limit: int = 40, max_age_hours: float = 72) -> list[Session]:
+    config = freebuff_config_dir()
+    projects = config / "projects"
+    if not projects.is_dir():
+        return []
+
+    now = time.time()
+    cutoff_ms = int((now - max_age_hours * 3600) * 1000)
+    open_tabs = _active_tab_ids(config)
+
+    sessions: list[Session] = []
+    for project_dir in projects.iterdir():
+        db = project_dir / "desktop-v2.db"
+        if not db.is_file():
+            continue
+        sessions.extend(
+            _collect_from_db(db, limit=limit, cutoff_ms=cutoff_ms, open_tabs=open_tabs)
+        )
+
+    sessions.sort(key=lambda s: s.updated_at, reverse=True)
+    return sessions[:limit]

agenthud/adapters/opencode.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from pathlib import Path
+
+from agenthud.models import Session, Status, Tool
+from agenthud.paths import opencode_db, project_basename
+
+
+def _model_label(raw: str | None) -> str:
+    if not raw:
+        return ""
+    try:
+        obj = json.loads(raw)
+        if isinstance(obj, dict):
+            return str(obj.get("id") or obj.get("model") or obj.get("providerID") or "")
+    except json.JSONDecodeError:
+        pass
+    return raw if len(raw) < 40 else ""
+
+
+def _ms_to_s(value: int | float | None) -> float:
+    if value is None:
+        return 0.0
+    v = float(value)
+    # OpenCode stores ms epoch
+    return v / 1000.0 if v > 1_000_000_000_000 else v
+
+
+def _infer_status(updated_s: float, now: float, archived: int | None) -> tuple[Status, str]:
+    if archived:
+        return Status.DONE, "archived"
+    age = now - updated_s
+    if age < 90:
+        return Status.RUNNING, "recently updated"
+    if age < 3600 * 6:
+        return Status.IDLE, ""
+    return Status.DONE, "stale"
+
+
+def collect(*, limit: int = 40, max_age_hours: float = 72) -> list[Session]:
+    db_path = opencode_db()
+    if not db_path.is_file():
+        return []
+
+    now = time.time()
+    cutoff_ms = int((now - max_age_hours * 3600) * 1000)
+    sessions: list[Session] = []
+
+    try:
+        # immutable + timeout so we don't block a running OpenCode
+        uri = f"file:{db_path}?mode=ro"
+        conn = sqlite3.connect(uri, uri=True, timeout=1.0)
+        conn.row_factory = sqlite3.Row
+        rows = conn.execute(
+            """
+            SELECT id, title, directory, time_updated, time_created, time_archived,
+                   summary_files, agent, model
+            FROM session
+            WHERE parent_id IS NULL
+              AND time_updated >= ?
+            ORDER BY time_updated DESC
+            LIMIT ?
+            """,
+            (cutoff_ms, limit),
+        ).fetchall()
+        conn.close()
+    except sqlite3.Error:
+        return []
+
+    for row in rows:
+        updated = _ms_to_s(row["time_updated"])
+        status, detail = _infer_status(updated, now, row["time_archived"])
+        files = row["summary_files"]
+        if files and not detail:
+            detail = f"{files} files touched"
+        model = _model_label(row["model"]) or (row["agent"] or "")
+        if model and detail:
+            detail = f"{detail} · {model}"
+        elif model:
+            detail = str(model)
+        sessions.append(
+            Session(
+                id=str(row["id"]),
+                tool=Tool.OPENCODE,
+                title=str(row["title"] or row["id"]),
+                status=status,
+                project=project_basename(str(row["directory"] or "")),
+                updated_at=updated,
+                detail=detail,
+                path=str(row["directory"] or ""),
+                extra={"db": str(db_path)},
+            )
+        )
+    return sessions

agenthud/adapters/stub.py

@@ -0,0 +1,9 @@
+"""Adapters that return [] until session format is wired — still listed in Settings."""
+
+from __future__ import annotations
+
+from agenthud.models import Session
+
+
+def collect(*, limit: int = 40, max_age_hours: float = 72) -> list[Session]:
+    return []

agenthud/aggregate.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from agenthud.adapters import claude, codex, cursor, freebuff, opencode, stub
+from agenthud.models import STATUS_ORDER, Session, Tool
+
+_COLLECTORS = {
+    Tool.CURSOR: cursor.collect,
+    Tool.OPENCODE: opencode.collect,
+    Tool.FREEBUFF: freebuff.collect,
+    Tool.CODEX: codex.collect,
+    Tool.CLAUDE: claude.collect,
+    Tool.GEMINI: stub.collect,
+    Tool.COPILOT: stub.collect,
+    Tool.AMP: stub.collect,
+    Tool.FACTORY: stub.collect,
+    Tool.PI: stub.collect,
+    Tool.KIRO: stub.collect,
+    Tool.CLINE: stub.collect,
+    Tool.ROO: stub.collect,
+}
+
+
+def collect_all(
+    *,
+    tools: set[Tool] | None = None,
+    limit_per_tool: int = 30,
+    max_age_hours: float = 72,
+) -> list[Session]:
+    tools = tools or set(_COLLECTORS)
+    sessions: list[Session] = []
+    for tool in tools:
+        fn = _COLLECTORS.get(tool)
+        if not fn:
+            continue
+        sessions.extend(fn(limit=limit_per_tool, max_age_hours=max_age_hours))
+    sessions.sort(key=lambda s: (STATUS_ORDER.get(s.status, 99), -s.updated_at))
+    return sessions