agent-ps 0.2.0__py3-none-any.whl

agent_ps/__init__.py

@@ -0,0 +1,3 @@
+"""agent-ps: a process table for coding agent sessions."""
+
+VERSION = "0.2.0"

agent_ps/__main__.py

@@ -0,0 +1,197 @@
+"""Command line entry point."""
+
+import argparse
+import curses
+import json
+import sys
+
+from . import VERSION, backends
+from .collect import Snapshot, idle_seconds, is_live
+from .procs import stop_tree, terminate, table
+from .resume import open_in_terminal, resume_command
+from .ui import Tui, matches_filter, print_table
+from .util import FAILURES, human_bytes
+
+
+class UnknownAgent(Exception):
+    pass
+
+
+def build(args):
+    known = backends.names()
+    only = None
+    if getattr(args, "agent", ""):
+        only = set(args.agent.split(","))
+        unknown = sorted(only - set(known))
+        if unknown:
+            raise UnknownAgent(f"Unknown agent(s): {', '.join(unknown)}. "
+                               f"Known agents: {', '.join(known)}.")
+    chosen = backends.available(only)
+    if not chosen:
+        print(f"No agent data found. Known agents: {', '.join(known)}.",
+              file=sys.stderr)
+    return Snapshot(chosen)
+
+
+def select(snapshot, args, show_ended):
+    rows = snapshot.rows(show_ended=show_ended, limit=getattr(args, "limit", 40))
+    needle = (getattr(args, "filter", "") or "").lower()
+    return [r for r in rows if matches_filter(r, needle)] if needle else rows
+
+
+def cmd_list(args):
+    snapshot = build(args)
+    rows = select(snapshot, args, getattr(args, "all", False))
+
+    if args.json:
+        for row in rows:
+            row["idle"] = idle_seconds(row)
+        print(json.dumps(rows, indent=2))
+        return 0
+    if not rows:
+        if FAILURES:
+            print(f"Could not run {', '.join(sorted(FAILURES))}, so the table "
+                  f"could not be built.", file=sys.stderr)
+            return 1
+        print("No coding agent sessions running.")
+        return 0
+
+    print_table(rows)
+    live = [r for r in rows if is_live(r)]
+    disk = sum(r.get("disk", 0) for r in rows)
+    history = snapshot.history(force=True)
+    agents = sorted({r["agent"] for r in live})
+    print(f"\n{len(live)} running ({', '.join(agents) or 'none'}), "
+          f"{human_bytes(disk)} on disk. "
+          f"{history['ended']} session{'' if history['ended'] == 1 else 's'} "
+          f"on record, "
+          f"{human_bytes(max(0, history['bytes'] - disk))} in history.")
+    return 0
+
+
+def cmd_stop(args):
+    snapshot = build(args)
+    # one process table for both the check and the stop, so the tree that gets
+    # signalled is the one that was just validated
+    procs = table()
+    row = next((r for r in snapshot.rows() if r["pid"] == args.pid), None)
+    if not row:
+        print(f"PID {args.pid} is not a coding agent process.", file=sys.stderr)
+        return 1
+    order, stopped = stop_tree(args.pid, procs, args.dry_run)
+    if args.dry_run:
+        print("Would stop:", ", ".join(str(p) for p in order))
+        return 0
+    print(f"Stopped {len(stopped)} of {len(order)} processes.")
+    return 0 if len(stopped) == len(order) else 1
+
+
+def cmd_resume(args):
+    snapshot = build(args)
+    rows = snapshot.rows(show_ended=True, limit=1000)
+    match = next((r for r in rows
+                  if not r["pid"] and r["session_id"].startswith(args.session)), None)
+    if not match:
+        print(f"No ended session starts with {args.session}.", file=sys.stderr)
+        return 1
+    backend = snapshot.find_backend(match["agent"])
+    if not backend or not backend.resume_binary:
+        print(f"{match['agent']} sessions cannot be reopened from a terminal.",
+              file=sys.stderr)
+        return 1
+    command = resume_command(backend, match["session_id"], match["cwd"])
+    if args.print_only:
+        print(command)
+        return 0
+    ok, note = open_in_terminal(command)
+    print(note if ok else f"{note}\nRun: {command}")
+    return 0 if ok else 1
+
+
+def cmd_stop_background(args):
+    snapshot = build(args)
+    targets = [r for r in snapshot.rows() if r["background"]]
+    if not targets:
+        print("No background processes running.")
+        return 0
+    if args.dry_run:
+        print("Would stop:", ", ".join(str(r["pid"]) for r in targets))
+        return 0
+    stopped = [r for r in targets if terminate(r["pid"])]
+    print(f"Stopped {len(stopped)} of {len(targets)} background processes.")
+    return 0 if len(stopped) == len(targets) else 1
+
+
+def cmd_agents(args):
+    for cls in backends.ALL:
+        backend = cls()
+        if not backend.available():
+            print(f"  {backend.name:<13} present=no   sessions=-      {backend.root}")
+            continue
+        count, _ = backend.history_counts(0)
+        print(f"  {backend.name:<13} present=yes  sessions={count:<6} {backend.root}")
+    return 0
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="agent-ps", description="List and stop coding agent sessions.")
+    parser.add_argument("--version", action="version", version=f"agent-ps {VERSION}")
+    parser.add_argument("--agent", default="",
+                        help="limit to these agents, comma separated")
+    sub = parser.add_subparsers(dest="command")
+
+    p_list = sub.add_parser("list", help="print the table and exit")
+    p_list.add_argument("--json", action="store_true", help="output as JSON")
+    p_list.add_argument("--all", action="store_true",
+                        help="include sessions that have ended")
+    p_list.add_argument("--filter", metavar="TEXT",
+                        help="match session, title, agent, model, directory, or PID")
+    p_list.add_argument("--limit", type=int, default=40,
+                        help="how many ended sessions to show (default 40)")
+    p_list.set_defaults(func=cmd_list)
+
+    p_stop = sub.add_parser("stop", help="stop a process and its children")
+    p_stop.add_argument("pid", type=int)
+    p_stop.add_argument("--dry-run", action="store_true")
+    p_stop.set_defaults(func=cmd_stop)
+
+    p_resume = sub.add_parser("resume", help="reopen an ended session")
+    p_resume.add_argument("session", help="session id, or a unique prefix")
+    p_resume.add_argument("--print", dest="print_only", action="store_true",
+                          help="print the command instead of running it")
+    p_resume.set_defaults(func=cmd_resume)
+
+    p_bg = sub.add_parser("stop-background", help="stop daemons and warm spares")
+    p_bg.add_argument("--dry-run", action="store_true")
+    p_bg.set_defaults(func=cmd_stop_background)
+
+    p_agents = sub.add_parser("agents", help="show which agents were found")
+    p_agents.set_defaults(func=cmd_agents)
+
+    args = parser.parse_args()
+    try:
+        if args.command:
+            return args.func(args)
+    except UnknownAgent as error:
+        print(error, file=sys.stderr)
+        return 2
+
+    if not sys.stdout.isatty():
+        args.json = args.all = False
+        args.filter, args.limit = "", 40
+        return cmd_list(args)
+    try:
+        snapshot = build(args)
+    except UnknownAgent as error:
+        print(error, file=sys.stderr)
+        return 2
+    try:
+        curses.wrapper(lambda screen: Tui(screen, snapshot).loop())
+    except KeyboardInterrupt:
+        pass
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agent_ps/backends/__init__.py

@@ -0,0 +1,31 @@
+"""The registry.
+
+Adding an agent means writing one class and adding it to this list. Order sets
+the order rows appear in when nothing else separates them.
+"""
+
+from .claude import ClaudeBackend
+from .codex import CodexBackend
+from .copilot import CopilotBackend
+from .hermes import HermesBackend
+from .opencode import OpenCodeBackend
+from .pilike import CommandCodeBackend, PiBackend
+
+ALL = (ClaudeBackend, PiBackend, CommandCodeBackend, CodexBackend,
+       OpenCodeBackend, HermesBackend, CopilotBackend)
+
+
+def available(only=None):
+    """Backends whose data directory exists, optionally narrowed by name."""
+    chosen = []
+    for cls in ALL:
+        backend = cls()
+        if only and backend.name not in only:
+            continue
+        if backend.available():
+            chosen.append(backend)
+    return chosen
+
+
+def names():
+    return [cls.name for cls in ALL]

agent_ps/backends/base.py

@@ -0,0 +1,310 @@
+"""What every agent has to provide, and what most of them get for free.
+
+A backend answers questions about one agent and returns plain data. It never
+draws anything and never decides how a row is displayed, so the table never has
+to ask which agent a row came from.
+
+Most agents keep one JSONL log per session, so that is the default behaviour
+here. A backend overrides only the parts where its agent differs.
+"""
+
+import glob
+import os
+import time
+
+from .. import jsonl
+from ..procs import matches, working_dirs
+from ..util import directory_size
+
+KIND_SESSION = "session"
+KIND_ENDED = "ended"
+KIND_GATEWAY = "gateway"
+
+STATUS_BUSY = "busy"
+STATUS_IDLE = "idle"
+
+#: How long a size is trusted before the directories are walked again.
+DISK_POLL_SECONDS = 5.0
+
+ATTACH_NONE = ""
+ATTACH_DIRECT = "pid"
+ATTACH_INFERRED = "cwd"
+
+
+TITLE_LENGTH = 60
+
+
+def prompt_title(text):
+    """An opening prompt, trimmed to serve as a title.
+
+    Agents inject a context block as the first user message. That is machinery,
+    not what the session was about, so it is rejected and the caller moves on to
+    the next message.
+    """
+    text = " ".join((text or "").split())
+    if not text or text.startswith("<"):
+        return ""
+    return text[:TITLE_LENGTH]
+
+
+def blank_row(agent):
+    return {
+        "agent": agent,
+        "pid": 0,
+        "ppid": 0,
+        "cmd": "",
+        "kind": KIND_ENDED,
+        "background": False,
+        "session_id": "",
+        # the file backing this session, which for a SQLite agent is the one
+        # database every one of its sessions lives in
+        "path": "",
+        "name": "",
+        "title": "",
+        "cwd": "",
+        "model": "",
+        "uptime": 0,
+        "last_active": 0,
+        "cpu": 0.0,
+        "rss": 0,
+        "disk": 0,
+        "attach": ATTACH_NONE,
+        "status": "",
+    }
+
+
+class Backend:
+    name = ""
+    root = ""
+    session_glob = ""
+    process_patterns = ()
+    resume_binary = ""
+    resume_flag = "--resume"
+
+    #: Extra directories that grow alongside the logs, counted in the totals.
+    extra_dirs = ()
+
+    #: How long a turn may appear to be running before it is called idle. A live
+    #: turn keeps appending as it works, so silence for this long means the turn
+    #: ended without a final entry, or the agent stopped.
+    busy_timeout = 900
+
+    def __init__(self):
+        self.cache = jsonl.Cache()
+        self._disk = {}
+        self._disk_at = {}
+
+    # Discovery -----------------------------------------------------------
+
+    def available(self):
+        return bool(self.root) and os.path.isdir(self.root)
+
+    def session_paths(self):
+        return glob.glob(os.path.join(self.root, self.session_glob))
+
+    def owns(self, proc):
+        return matches(proc["cmd"], self.process_patterns)
+
+    # One session ---------------------------------------------------------
+
+    def extract(self, reader):
+        """Title, model, and working directory from one session log.
+
+        Returning a partial dict is fine. Anything absent stays blank, which the
+        table renders as a dash rather than treating as a special case.
+        """
+        return {}
+
+    def session_id(self, path):
+        return os.path.basename(path).split(".")[0]
+
+    def describe(self, path):
+        """One session as a row, whether or not a process is running it."""
+        blank = {"title": "", "model": "", "cwd": "", "status": "", "last_active": 0}
+        info = self.cache.info(path, self.extract, blank)
+        row = blank_row(self.name)
+        session_id = self.session_id(path)
+        cwd = info.get("cwd") or self.fallback_cwd(path)
+        row.update({
+            "session_id": session_id,
+            "path": path,
+            "title": info.get("title", ""),
+            "model": info.get("model", ""),
+            "cwd": cwd,
+            "name": os.path.basename(cwd) if cwd else "",
+            "last_active": info.get("last_active", 0),
+            "status": info.get("status", ""),
+            "disk": self.disk_usage(session_id, path),
+        })
+        return row
+
+    def fallback_cwd(self, path):
+        """Where to look when a log never recorded its working directory."""
+        return ""
+
+    def sessions(self, limit=None):
+        """Known sessions, most recently active first."""
+        rows = []
+        for path in self.session_paths():
+            try:
+                rows.append((os.path.getmtime(path), path))
+            except OSError:
+                continue
+        rows.sort(reverse=True)
+        if limit is not None:
+            rows = rows[:limit]
+        return [self.describe(path) for _, path in rows]
+
+    # Processes -----------------------------------------------------------
+
+    def classify(self, proc):
+        """Which sort of process this is. Agents with helpers override this."""
+        return KIND_SESSION
+
+    def is_background(self, kind):
+        return False
+
+    def live_sessions(self):
+        """Sessions that are alive without a process of their own.
+
+        An agent embedded in an editor has no process to find in `ps`, but its
+        sessions are still open and still spending. Backends that own processes
+        return nothing here.
+        """
+        return []
+
+    def attach(self, procs, index):
+        """Pair live processes with the sessions they are running.
+
+        Only Claude Code records the pairing, so the default is to match on
+        working directory. That is a guess: two sessions of the same agent in one
+        directory are indistinguishable, so the newer is chosen and the row is
+        marked inferred rather than presented as fact.
+        """
+        rows = []
+        dirs = working_dirs([p["pid"] for p in procs])
+        claimed = {}
+        # Sessions come newest first, so processes are matched newest first too.
+        # Pairing them in process table order would hand the oldest process the
+        # session that was active most recently, which is backwards whenever
+        # someone has two of the same agent open in one directory.
+        for proc in sorted(procs, key=lambda p: p["uptime"]):
+            found = self._best_match(index, dirs.get(proc["pid"], ""), set(claimed.values()))
+            if found:
+                claimed[proc["pid"]] = found["session_id"]
+
+        for proc in procs:
+            row = blank_row(self.name)
+            row.update({
+                "pid": proc["pid"],
+                "ppid": proc["ppid"],
+                "cmd": proc["cmd"],
+                "uptime": proc["uptime"],
+                "cpu": proc["cpu"],
+                "rss": proc["rss"],
+            })
+            row["kind"] = self.classify(proc)
+            row["background"] = self.is_background(row["kind"])
+            cwd = dirs.get(proc["pid"], "")
+            if cwd:
+                row["cwd"] = cwd
+                row["name"] = os.path.basename(cwd)
+            match = self._session_by_id(index, cwd, claimed.get(proc["pid"]))
+            if match:
+                row.update({
+                    "session_id": match["session_id"],
+                    "path": match["path"],
+                    "title": match["title"],
+                    "model": match["model"],
+                    "cwd": match["cwd"] or cwd,
+                    "name": match["name"] or row["name"],
+                    "last_active": match["last_active"],
+                    "status": self.settle(match["status"], match["last_active"]),
+                    "disk": match["disk"],
+                    "attach": ATTACH_INFERRED,
+                })
+            rows.append(row)
+        return rows
+
+    def settle(self, status, last_active):
+        """Drop a busy claim the log has stopped backing up."""
+        if status != STATUS_BUSY or not last_active:
+            return status
+        if time.time() - last_active > self.busy_timeout:
+            return STATUS_IDLE
+        return status
+
+    @staticmethod
+    def _best_match(index, cwd, claimed):
+        """The most recently active session in a directory that is still free."""
+        if not cwd:
+            return None
+        for candidate in index.get(cwd, []):
+            if candidate["session_id"] not in claimed:
+                return candidate
+        return None
+
+    @staticmethod
+    def _session_by_id(index, cwd, session_id):
+        if not session_id:
+            return None
+        return next((c for c in index.get(cwd, [])
+                     if c["session_id"] == session_id), None)
+
+    # Disk ----------------------------------------------------------------
+
+    def disk_paths(self, session_id, path):
+        """Everything on disk that belongs to one session.
+
+        Entries may contain a `*`, since some agents name files after the
+        session and then append a timestamp.
+        """
+        return [path]
+
+    def disk_usage(self, session_id, path):
+        now = time.time()
+        if now - self._disk_at.get(session_id, 0) < DISK_POLL_SECONDS:
+            return self._disk.get(session_id, 0)
+        total = 0
+        for entry in self.disk_paths(session_id, path):
+            if "*" in entry:
+                total += sum(directory_size(p) for p in glob.glob(entry))
+            else:
+                total += directory_size(entry)
+        self._disk[session_id] = total
+        self._disk_at[session_id] = now
+        return total
+
+    def history_counts(self, since):
+        """How many sessions exist, and how many were active since a moment.
+
+        Asked as a question rather than as a list of files, because not every
+        agent keeps one file per session.
+        """
+        total = recent = 0
+        for path in self.session_paths():
+            total += 1
+            try:
+                if os.path.getmtime(path) > since:
+                    recent += 1
+            except OSError:
+                pass
+        return total, recent
+
+    def history_bytes(self):
+        roots = [os.path.join(self.root, self.session_glob.split("*")[0])]
+        roots += [os.path.join(self.root, d) for d in self.extra_dirs]
+        return sum(directory_size(r) for r in roots)
+
+    def details(self, row):
+        """Extra facts about one session, as label and value pairs.
+
+        Some agents count tokens and cost and some do not, so this is optional
+        and the panel simply shows fewer lines where there is less to say.
+        """
+        return []
+
+    # Resume --------------------------------------------------------------
+
+    def resume(self, session_id):
+        return f"{self.resume_binary} {self.resume_flag} {session_id}"

agent_ps/backends/claude.py

@@ -0,0 +1,144 @@
+"""Claude Code.
+
+The only agent that records which process is running which session, so it is
+also the only one whose PID column is a fact rather than an inference.
+"""
+
+import glob
+import json
+import os
+
+from ..procs import environment
+from ..util import decode_project_dir
+from .base import (ATTACH_DIRECT, Backend, KIND_GATEWAY, KIND_SESSION,
+                   blank_row)
+
+KIND_DAEMON = "daemon"
+KIND_SPARE = "bg-spare"
+KIND_PTY = "bg-pty"
+BACKGROUND = {KIND_DAEMON, KIND_SPARE, KIND_PTY}
+
+
+class ClaudeBackend(Backend):
+    name = "claude"
+    root = os.path.expanduser(os.environ.get("CLAUDE_CONFIG_DIR", "~/.claude"))
+    session_glob = "projects/*/*.jsonl"
+    process_patterns = ("claude",)
+    resume_binary = "claude"
+    extra_dirs = ("file-history", "tasks", "session-env")
+
+    def extract(self, reader):
+        info = {"cwd": reader.find_head("cwd")}
+        for line in reader.tail():
+            if info.get("title") and info.get("model"):
+                break
+            if '"ai-title"' not in line and '"model"' not in line:
+                continue
+            try:
+                entry = json.loads(line)
+            except ValueError:
+                continue
+            if not info.get("title") and entry.get("type") == "ai-title":
+                info["title"] = entry.get("aiTitle", "")
+            if not info.get("model"):
+                model = (entry.get("message") or {}).get("model")
+                # <synthetic> marks messages Claude Code wrote itself, such as
+                # compaction notices, not a model that served a turn
+                if model and not model.startswith("<"):
+                    info["model"] = model
+        return info
+
+    def fallback_cwd(self, path):
+        return decode_project_dir(os.path.dirname(path))
+
+    def classify(self, proc):
+        cmd = proc["cmd"]
+        if "claude daemon" in cmd:
+            return KIND_DAEMON
+        if "bg-spare" in cmd:
+            return KIND_SPARE
+        if "bg-pty-host" in cmd:
+            return KIND_PTY
+        env = environment(proc["pid"], ("ANTHROPIC_",))
+        proc["_env"] = env
+        return KIND_GATEWAY if env.get("ANTHROPIC_BASE_URL") else KIND_SESSION
+
+    def is_background(self, kind):
+        return kind in BACKGROUND
+
+    def attach(self, procs, index):
+        """Read the pairing rather than guessing it.
+
+        Claude Code writes <config dir>/sessions/<pid>.json for every live
+        session, which also carries the name and whether it is mid-turn. That
+        file is authoritative and stops being written when the process exits, so
+        unlike the inferred backends its busy state never needs a stall timeout.
+        """
+        rows = []
+        for proc in procs:
+            row = blank_row(self.name)
+            row.update({
+                "pid": proc["pid"],
+                "ppid": proc["ppid"],
+                "cmd": proc["cmd"],
+                "uptime": proc["uptime"],
+                "cpu": proc["cpu"],
+                "rss": proc["rss"],
+            })
+            row["kind"] = self.classify(proc)
+            row["background"] = self.is_background(row["kind"])
+
+            data = self._pid_file(proc["pid"])
+            session_id = data.get("sessionId", "")
+            if session_id:
+                row.update({
+                    "session_id": session_id,
+                    "name": data.get("name", ""),
+                    "status": data.get("status", ""),
+                    "cwd": data.get("cwd", ""),
+                    "attach": ATTACH_DIRECT,
+                })
+                for candidate in index.get(data.get("cwd", ""), []):
+                    if candidate["session_id"] == session_id:
+                        row.update({
+                            "path": candidate["path"],
+                            "title": candidate["title"],
+                            "model": candidate["model"],
+                            "last_active": candidate["last_active"],
+                            "disk": candidate["disk"],
+                        })
+                        break
+                else:
+                    row.update(self._by_id(session_id))
+            # a launcher's routing alias is what the user picked, so it wins over
+            # whichever upstream model happened to answer last
+            alias = (proc.get("_env") or {}).get("ANTHROPIC_MODEL")
+            if alias:
+                row["model"] = alias
+            rows.append(row)
+        return rows
+
+    def _pid_file(self, pid):
+        try:
+            with open(os.path.join(self.root, "sessions", f"{pid}.json")) as handle:
+                data = json.load(handle)
+            return data if isinstance(data, dict) else {}
+        except (OSError, ValueError):
+            return {}
+
+    def _by_id(self, session_id):
+        found = glob.glob(os.path.join(self.root, "projects", "*", f"{session_id}.jsonl"))
+        if not found:
+            return {}
+        row = self.describe(found[0])
+        return {"path": row["path"], "title": row["title"],
+                "model": row["model"], "last_active": row["last_active"],
+                "disk": row["disk"]}
+
+    def disk_paths(self, session_id, path):
+        base = os.path.dirname(path)
+        return [path,
+                os.path.join(base, session_id),
+                os.path.join(self.root, "file-history", session_id),
+                os.path.join(self.root, "tasks", session_id),
+                os.path.join(self.root, "session-env", session_id)]