agent-ps 0.2.0__py3-none-any.whl

agent_ps/backends/codex.py

@@ -0,0 +1,84 @@
+"""Codex CLI.
+
+Every entry is an envelope: a type, a timestamp, and a `payload` holding the
+actual record. The working directory arrives in `session_meta` at the top of the
+file, the model in the most recent `turn_context`.
+"""
+
+import os
+
+from .. import jsonl
+from .base import Backend, STATUS_BUSY, STATUS_IDLE, prompt_title
+
+
+class CodexBackend(Backend):
+    name = "codex"
+    root = os.path.expanduser("~/.codex")
+    session_glob = "sessions/*/*/*/*.jsonl"
+    process_patterns = ("codex",)
+    resume_binary = "codex"
+    resume_flag = "resume"
+    extra_dirs = ("shell_snapshots", "thread-writer-locks")
+
+    def disk_paths(self, session_id, path):
+        # the shell snapshot is routinely larger than the transcript it belongs
+        # to, and it is named after the session with a timestamp appended
+        return [path,
+                os.path.join(self.root, "shell_snapshots", f"{session_id}.*.sh"),
+                os.path.join(self.root, "thread-writer-locks", f"{session_id}.lock")]
+
+    def extract(self, reader):
+        info = {}
+        for entry in reader.head():
+            payload = entry.get("payload") or {}
+            if entry.get("type") == "session_meta":
+                info["cwd"] = payload.get("cwd", "")
+                break
+        for line in reader.tail():
+            if '"turn_context"' not in line:
+                continue
+            entry = jsonl.parse_line(line)
+            payload = (entry or {}).get("payload") or {}
+            if payload.get("model"):
+                info["model"] = payload["model"]
+                break
+        info["title"] = self._opening_prompt(reader)
+        info["status"] = self._turn(reader)
+        return info
+
+    @staticmethod
+    def _turn(reader):
+        """Codex marks the start and end of a turn itself, so read the marker."""
+        for line in reader.tail():
+            if '"task_started"' not in line and '"task_complete"' not in line:
+                continue
+            entry = jsonl.parse_line(line)
+            kind = ((entry or {}).get("payload") or {}).get("type")
+            if kind == "task_started":
+                return STATUS_BUSY
+            if kind == "task_complete":
+                return STATUS_IDLE
+        return ""
+
+    @staticmethod
+    def _opening_prompt(reader):
+        for entry in reader.head():
+            payload = entry.get("payload") or {}
+            if entry.get("type") != "response_item" or payload.get("role") != "user":
+                continue
+            content = payload.get("content")
+            if isinstance(content, str):
+                text = content
+            else:
+                text = " ".join(c.get("text", "") for c in content or []
+                                if isinstance(c, dict))
+            title = prompt_title(text)
+            if title:
+                return title
+        return ""
+
+    def session_id(self, path):
+        # named rollout-<timestamp>-<uuid>.jsonl
+        stem = os.path.basename(path)[:-len(".jsonl")]
+        parts = stem.split("-")
+        return "-".join(parts[-5:]) if len(parts) >= 5 else stem

agent_ps/backends/copilot.py

@@ -0,0 +1,211 @@
+"""GitHub Copilot Chat, in VS Code.
+
+The odd one out: Copilot runs inside the editor's extension host, so there is no
+process to find and no process to stop. What it does have is the richest
+accounting of the six, including the credits a turn spent, which the free tier
+meters and nothing else surfaces.
+
+A chat is alive when its workspace is open in VS Code, which is answered by
+asking the editor which storage directories it currently holds open.
+"""
+
+import glob
+import json
+import os
+
+from ..procs import run
+from ..util import directory_size
+from .base import (Backend, KIND_ENDED, KIND_SESSION, STATUS_BUSY,
+                   STATUS_IDLE)
+
+
+class CopilotBackend(Backend):
+    name = "copilot"
+    root = os.path.expanduser(
+        os.environ.get("VSCODE_USER_DIR",
+                       "~/Library/Application Support/Code/User"))
+    session_glob = "workspaceStorage/*/chatSessions/*.jsonl"
+    #: Nothing in the process table belongs to Copilot, so it claims no process.
+    process_patterns = ()
+    #: A chat lives in the editor's UI, so there is no command that reopens one.
+    resume_binary = ""
+
+    def __init__(self):
+        super().__init__()
+        self._open = None
+
+    def owns(self, proc):
+        return False
+
+    def open_workspaces(self):
+        """Storage directories VS Code currently has open.
+
+        One lsof call for every editor process, cached for the pass. A workspace
+        that is not open cannot have a live chat, which is the only way to tell
+        an abandoned conversation from one still on screen.
+        """
+        if self._open is not None:
+            return self._open
+        self._open = set()
+        pids = run(["pgrep", "-f", "Visual Studio Code|Code Helper"]).split()
+        if pids:
+            out = run(["lsof", "-p", ",".join(pids[:60])], timeout=15)
+            for line in out.splitlines():
+                marker = line.find("workspaceStorage/")
+                if marker < 0:
+                    continue
+                tail = line[marker + len("workspaceStorage/"):]
+                self._open.add(tail.split("/")[0])
+        return self._open
+
+    def session_id(self, path):
+        return os.path.basename(path)[:-len(".jsonl")]
+
+    def workspace_of(self, path):
+        return os.path.basename(os.path.dirname(os.path.dirname(path)))
+
+    def fallback_cwd(self, path):
+        """The folder a workspace points at, from the editor's own record."""
+        marker = os.path.join(os.path.dirname(os.path.dirname(path)),
+                              "workspace.json")
+        try:
+            with open(marker) as handle:
+                folder = json.load(handle).get("folder", "")
+        except (OSError, ValueError):
+            return ""
+        return folder[len("file://"):] if folder.startswith("file://") else folder
+
+    def extract(self, reader):
+        state = replay(reader.path)
+        requests = [r for r in (state.get("requests") or []) if isinstance(r, dict)]
+        if not requests:
+            # a chat that was opened and never used, of which there are many
+            return {"skip": True}
+        last = requests[-1]
+        info = {
+            "title": state.get("customTitle") or "",
+            "model": model_of(state, requests),
+            "status": turn_status(last),
+        }
+        stamp = last.get("timestamp")
+        if stamp:
+            info["last_active"] = stamp / 1000.0
+        return info
+
+    def describe(self, path):
+        row = super().describe(path)
+        row["kind"] = (KIND_SESSION if self.workspace_of(path) in self.open_workspaces()
+                       else KIND_ENDED)
+        return row
+
+    def sessions(self, limit=None):
+        self._open = None
+        rows = [r for r in super().sessions(limit) if r["title"] or r["model"]]
+        return rows
+
+    def live_sessions(self):
+        """Chats in a window that is currently open."""
+        return [r for r in self.sessions(limit=200) if r["kind"] == KIND_SESSION]
+
+    def details(self, row):
+        matches = glob.glob(os.path.join(self.root, "workspaceStorage", "*",
+                                         "chatSessions", f"{row['session_id']}.jsonl"))
+        if not matches:
+            return []
+        requests = [r for r in (replay(matches[0]).get("requests") or [])
+                    if isinstance(r, dict)]
+        if not requests:
+            return []
+        prompt = sum(r.get("promptTokens") or 0 for r in requests)
+        output = sum(r.get("completionTokens") or 0 for r in requests)
+        credits = sum(r.get("copilotCredits") or 0 for r in requests)
+        return [
+            ("host", "VS Code, no process of its own"),
+            ("tokens", f"in {prompt:,}  out {output:,}"),
+            ("turns", f"{len(requests)}"),
+            ("credits", f"{credits:.2f} used"),
+        ]
+
+    def disk_paths(self, session_id, path):
+        base = os.path.dirname(os.path.dirname(path))
+        return [path, os.path.join(base, "chatEditingSessions", session_id)]
+
+    def history_bytes(self):
+        return sum(directory_size(p) for p in
+                   glob.glob(os.path.join(self.root, "workspaceStorage", "*",
+                                          "chatSessions")))
+
+
+def replay(path):
+    """Rebuild a session from its journal of changes.
+
+    The file is not a log of messages but a list of edits: an initial object,
+    then `{kind, k: [path], v}` entries that set a value somewhere inside it.
+    Replaying them in order is the only way to read any field.
+    """
+    state = {}
+    try:
+        handle = open(path, errors="ignore")
+    except OSError:
+        return state
+    with handle:
+        for line in handle:
+            try:
+                entry = json.loads(line)
+            except ValueError:
+                continue
+            key, value = entry.get("k"), entry.get("v")
+            if not key:
+                if isinstance(value, dict):
+                    state.update(value)
+                continue
+            node = state
+            try:
+                for step in key[:-1]:
+                    node = _descend(node, step)
+                _assign(node, key[-1], value)
+            except (TypeError, AttributeError, IndexError):
+                continue
+    return state
+
+
+def _descend(node, step):
+    if isinstance(step, int):
+        while len(node) <= step:
+            node.append({})
+        return node[step]
+    return node.setdefault(step, {})
+
+
+def _assign(node, key, value):
+    if isinstance(key, int):
+        while len(node) <= key:
+            node.append({})
+        node[key] = value
+    else:
+        node[key] = value
+
+
+def model_of(state, requests):
+    """What actually answered, not the picker that chose it.
+
+    A request records `modelId`, but under the default setting that is the
+    alias `copilot/auto`, which says nothing. The family behind the alias is
+    kept with the model the user selected.
+    """
+    selected = ((state.get("inputState") or {}).get("selectedModel") or {})
+    family = (selected.get("metadata") or {}).get("family")
+    if family:
+        return family
+    for request in reversed(requests):
+        raw = request.get("modelId")
+        if raw and raw != "copilot/auto":
+            return raw
+    return ""
+
+
+def turn_status(request):
+    state = request.get("modelState")
+    if isinstance(state, dict) and not state.get("completedAt"):
+        return STATUS_BUSY
+    return STATUS_IDLE if request.get("response") is not None else STATUS_BUSY

agent_ps/backends/hermes.py

@@ -0,0 +1,129 @@
+"""Hermes.
+
+Keeps its state in one SQLite database, and keeps more of it than the others:
+a session row already holds the working directory, the title, the model, and
+when it was last active, so a row costs a single query.
+
+Hermes also runs a gateway process that outlives the sessions it serves, which
+is the sort of thing worth noticing before it sits there for a week.
+"""
+
+import glob
+import os
+
+from ..util import directory_size
+from .base import KIND_GATEWAY, KIND_SESSION, STATUS_BUSY, STATUS_IDLE
+from .sqlite import SqliteBackend
+
+KIND_SUPERVISOR = "supervisor"
+BACKGROUND = {KIND_GATEWAY, KIND_SUPERVISOR}
+
+
+class HermesBackend(SqliteBackend):
+    name = "hermes"
+    root = os.path.expanduser(os.environ.get("HERMES_HOME", "~/.hermes"))
+    process_patterns = ("hermes", "hermes_cli.main", "hermes_cli.stderr_timestamp")
+    resume_binary = "hermes"
+    # the --resume flag reopens a session; `hermes resume` is a different
+    # command that lifts an emergency stop, so do not "simplify" this
+    resume_flag = "--resume"
+
+    db_filename = "state.db"
+
+    def available(self):
+        return bool(self.database)
+
+    def classify(self, proc):
+        """Tell the gateway apart from the thing that watches it.
+
+        Hermes starts a messaging gateway on its own and detaches it, so it
+        outlives the session that caused it. The gateway runs under a wrapper
+        that timestamps its stderr, and since the wrapper carries the gateway
+        command after a `--`, both would otherwise read as the gateway.
+        """
+        cmd = proc["cmd"]
+        if "stderr_timestamp" in cmd:
+            return KIND_SUPERVISOR
+        if "gateway run" in cmd:
+            return KIND_GATEWAY
+        return KIND_SESSION
+
+    def is_background(self, kind):
+        return kind in BACKGROUND
+
+    def sessions(self, limit=None):
+        return self.rows_from(
+            "SELECT id, cwd, title, model, last_activity_at, ended_at "
+            "FROM sessions ORDER BY last_activity_at DESC",
+            limit,
+            lambda r: {
+                "session_id": r["id"],
+                "title": r["title"] or "",
+                "model": r["model"] or "",
+                "cwd": r["cwd"] or "",
+                "last_active": r["last_activity_at"] or 0,
+                "status": "" if r["ended_at"] else self._turn(r["id"]),
+                "disk": self._session_bytes(r["id"]),
+            })
+
+    def _turn(self, session_id):
+        """Whose turn it is, from the newest message.
+
+        Hermes records a finish reason when a reply completes, so an assistant
+        message without one is still being written.
+        """
+        found = self.query("SELECT role, finish_reason FROM messages "
+                           "WHERE session_id = ? ORDER BY timestamp DESC LIMIT 1",
+                           (session_id,))
+        if not found:
+            return ""
+        role = found[0]["role"]
+        if role == "user":
+            return STATUS_BUSY
+        if role == "assistant":
+            return STATUS_IDLE if found[0]["finish_reason"] else STATUS_BUSY
+        return ""
+
+    def _session_bytes(self, session_id):
+        """The conversation in the database, plus what it dumped beside it.
+
+        Hermes writes a full request dump per turn, and those are two orders of
+        magnitude larger than the messages they record.
+        """
+        found = self.query("SELECT total(length(content)) + total(length(tool_calls)) "
+                           "FROM messages WHERE session_id = ?", (session_id,))
+        total = int(found[0][0] or 0) if found else 0
+        dumps = os.path.join(self.root, "sessions", f"request_dump_{session_id}_*.json")
+        return total + sum(directory_size(p) for p in glob.glob(dumps))
+
+    def details(self, row):
+        found = self.query(
+            "SELECT input_tokens, output_tokens, reasoning_tokens, api_call_count, "
+            "estimated_cost_usd, billing_provider, message_count, tool_call_count "
+            "FROM sessions WHERE id = ?", (row["session_id"],))
+        if not found:
+            return []
+        r = found[0]
+        return [
+            ("provider", r["billing_provider"] or "-"),
+            ("tokens", f"in {r['input_tokens'] or 0:,}  out {r['output_tokens'] or 0:,}"
+                       f"  reasoning {r['reasoning_tokens'] or 0:,}"),
+            ("calls", f"{r['api_call_count'] or 0} api, {r['message_count'] or 0} messages,"
+                      f" {r['tool_call_count'] or 0} tool calls"),
+            ("cost", f"${r['estimated_cost_usd'] or 0:.4f} estimated"),
+        ]
+
+    def history_counts(self, since):
+        found = self.query("SELECT count(*), "
+                           "sum(CASE WHEN last_activity_at > ? THEN 1 ELSE 0 END) "
+                           "FROM sessions", (since,))
+        if not found:
+            return 0, 0
+        return int(found[0][0] or 0), int(found[0][1] or 0)
+
+    def history_bytes(self):
+        # the request dumps under sessions/ are debugging artefacts, and they are
+        # larger than the database that holds the actual conversations
+        return (directory_size(self.database)
+                + directory_size(os.path.join(self.root, "sessions"))
+                + directory_size(os.path.join(self.root, "logs")))

agent_ps/backends/opencode.py

@@ -0,0 +1,191 @@
+"""OpenCode.
+
+Newer versions keep everything in one SQLite database, where a session row
+already carries its directory, title, and model. Nothing has to be parsed to
+build a row, which makes this the cheapest backend of the set.
+
+Older versions wrote a tree of JSON files under `storage/`. Installs that never
+migrated still have only that, so it is read when the database is absent.
+"""
+
+import glob
+import json
+import os
+
+from .. import jsonl
+from ..util import directory_size
+from .base import Backend, KIND_SESSION, STATUS_BUSY, STATUS_IDLE
+from .sqlite import SqliteBackend
+
+KIND_SERVE = "serve"
+
+
+class OpenCodeBackend(SqliteBackend):
+    name = "opencode"
+    root = os.path.expanduser(
+        os.environ.get("OPENCODE_DATA", "~/.local/share/opencode"))
+    session_glob = "storage/session/*/*.json"
+    process_patterns = ("opencode",)
+    resume_binary = "opencode"
+    resume_flag = "--session"
+
+    db_filename = "opencode.db"
+
+    def classify(self, proc):
+        # `opencode serve` hosts sessions for editors and keeps running after
+        # every one of them is closed
+        return KIND_SERVE if " serve" in proc["cmd"] else KIND_SESSION
+
+    def is_background(self, kind):
+        return kind == KIND_SERVE
+
+    # SQLite ---------------------------------------------------------------
+
+    def sessions(self, limit=None):
+        if not self.database:
+            return super(SqliteBackend, self).sessions(limit)
+        return self.rows_from(
+            "SELECT id, directory, title, model, time_updated "
+            "FROM session ORDER BY time_updated DESC",
+            limit,
+            lambda r: {
+                "session_id": r["id"],
+                "title": r["title"] or "",
+                "model": _model_name(r["model"]),
+                "cwd": r["directory"] or "",
+                "last_active": (r["time_updated"] or 0) / 1000.0,
+                "status": self._turn(r["id"]),
+                "disk": self._session_bytes(r["id"]),
+            })
+
+    def _turn(self, session_id):
+        """Whose turn it is, from the newest message.
+
+        An assistant message carries a `finish` reason once its turn is over, so
+        one without it is still being written.
+        """
+        found = self.query("SELECT data FROM message WHERE session_id = ? "
+                           "ORDER BY time_created DESC LIMIT 1", (session_id,))
+        if not found:
+            return ""
+        try:
+            data = json.loads(found[0]["data"])
+        except ValueError:
+            return ""
+        if data.get("role") == "user":
+            return STATUS_BUSY
+        if data.get("role") == "assistant":
+            return STATUS_IDLE if data.get("finish") else STATUS_BUSY
+        return ""
+
+    def _session_bytes(self, session_id):
+        """What one session holds in the database, rather than on its own."""
+        found = self.query(
+            "SELECT (SELECT total(length(data)) FROM message WHERE session_id = ?)"
+            " + (SELECT total(length(data)) FROM part WHERE session_id = ?)",
+            (session_id, session_id))
+        return int(found[0][0] or 0) if found else 0
+
+    def details(self, row):
+        if not self.database:
+            return []
+        found = self.query(
+            "SELECT cost, tokens_input, tokens_output, tokens_reasoning, "
+            "tokens_cache_read, tokens_cache_write, agent "
+            "FROM session WHERE id = ?", (row["session_id"],))
+        if not found:
+            return []
+        r = found[0]
+        return [
+            ("agent mode", r["agent"] or "-"),
+            ("tokens", f"in {r['tokens_input'] or 0:,}  out {r['tokens_output'] or 0:,}"
+                       f"  reasoning {r['tokens_reasoning'] or 0:,}"),
+            ("cache", f"read {r['tokens_cache_read'] or 0:,}"
+                      f"  write {r['tokens_cache_write'] or 0:,}"),
+            ("cost", f"${r['cost'] or 0:.4f}"),
+        ]
+
+    def history_counts(self, since):
+        if not self.database:
+            return super().history_counts(since)
+        found = self.query("SELECT count(*), "
+                           "sum(CASE WHEN time_updated > ? THEN 1 ELSE 0 END) "
+                           "FROM session", (since * 1000,))
+        if not found:
+            return 0, 0
+        return int(found[0][0] or 0), int(found[0][1] or 0)
+
+    def history_bytes(self):
+        # a migrated install keeps the old tree around, and those are still
+        # bytes sitting on the disk
+        return (directory_size(self.database) if self.database else 0) \
+            + directory_size(os.path.join(self.root, "storage"))
+
+    # The JSON store older versions wrote ----------------------------------
+
+    def extract(self, reader):
+        data = jsonl.load(reader.path)
+        model, status = self._latest(data.get("id", ""))
+        info = {
+            "cwd": data.get("directory", ""),
+            "title": data.get("title", ""),
+            "model": model,
+            "status": status,
+        }
+        updated = (data.get("time") or {}).get("updated")
+        if updated:
+            info["last_active"] = updated / 1000.0
+        return info
+
+    def _latest(self, session_id):
+        """Model and turn state from the newest message files, newest first."""
+        if not session_id:
+            return "", ""
+        paths = glob.glob(os.path.join(self.root, "storage", "message",
+                                       session_id, "*.json"))
+        model = status = ""
+        for path in sorted(paths, key=_mtime, reverse=True):
+            data = jsonl.load(path)
+            if not status:
+                role = data.get("role")
+                if role == "user":
+                    status = STATUS_BUSY
+                elif role == "assistant":
+                    status = STATUS_IDLE
+            if not model and data.get("modelID"):
+                provider = data.get("providerID", "")
+                model = f"{provider}/{data['modelID']}" if provider else data["modelID"]
+            if model and status:
+                break
+        return model, status
+
+    def session_id(self, path):
+        return os.path.basename(path)[:-len(".json")]
+
+    def disk_paths(self, session_id, path):
+        return [path,
+                os.path.join(self.root, "storage", "message", session_id),
+                os.path.join(self.root, "storage", "session_diff",
+                             f"{session_id}.json")]
+
+
+def _model_name(value):
+    """`{"id": "mimo-claude", "providerID": "9router"}` as `9router/mimo-claude`."""
+    if not value:
+        return ""
+    try:
+        data = json.loads(value)
+    except ValueError:
+        return str(value)
+    if not isinstance(data, dict):
+        return str(value)
+    model = data.get("id", "")
+    provider = data.get("providerID", "")
+    return f"{provider}/{model}" if provider and model else model
+
+
+def _mtime(path):
+    try:
+        return os.path.getmtime(path)
+    except OSError:
+        return 0