agent-ps 0.2.0__py3-none-any.whl

agent_ps/backends/pilike.py

@@ -0,0 +1,108 @@
+"""Pi and CommandCode.
+
+These write the same log: a `session` entry carrying the working directory, then
+`message` entries, with `model_change` whenever the model is switched. Only the
+field naming the model differs, so one parser serves both.
+
+Neither records a title, so the opening prompt stands in for one. That is what
+the session was about, which is the question a title answers.
+"""
+
+import os
+
+from .. import jsonl
+from .base import Backend, STATUS_BUSY, STATUS_IDLE, prompt_title
+
+
+class PiLikeBackend(Backend):
+    #: Fields on a model_change entry, joined with a slash when there are two.
+    model_fields = ("model",)
+
+    def extract(self, reader):
+        info = {"cwd": reader.find_head("cwd")}
+        for line in reader.tail():
+            if '"model_change"' not in line:
+                continue
+            entry = jsonl.parse_line(line)
+            if entry and entry.get("type") == "model_change":
+                parts = [entry.get(f) for f in self.model_fields if entry.get(f)]
+                if parts:
+                    info["model"] = "/".join(parts)
+                    break
+        info["title"] = self._opening_prompt(reader)
+        info["status"] = self._turn(reader)
+        return info
+
+    @staticmethod
+    def _turn(reader):
+        """Whose turn it is, from the last message in the log.
+
+        A user message with no reply after it means the agent is answering. An
+        assistant message means it is waiting for the next prompt.
+        """
+        for line in reader.tail():
+            if '"message"' not in line:
+                continue
+            entry = jsonl.parse_line(line)
+            if not entry or entry.get("type") != "message":
+                continue
+            role = (entry.get("message") or {}).get("role")
+            if role == "user":
+                return STATUS_BUSY
+            if role == "assistant":
+                return STATUS_IDLE
+        return ""
+
+    @staticmethod
+    def _opening_prompt(reader):
+        for entry in reader.head():
+            message = entry.get("message") or {}
+            if message.get("role") != "user":
+                continue
+            content = message.get("content")
+            if isinstance(content, str):
+                text = content
+            else:
+                text = next((c.get("text", "") for c in content or []
+                             if isinstance(c, dict) and c.get("type") == "text"), "")
+            title = prompt_title(text)
+            if title:
+                return title
+        return ""
+
+
+class PiBackend(PiLikeBackend):
+    name = "pi"
+    root = os.path.expanduser("~/.pi/agent")
+    session_glob = "sessions/*/*.jsonl"
+    process_patterns = ("pi",)
+    resume_binary = "pi"
+    # --resume opens a picker and takes no argument; --session is the one that
+    # accepts an id
+    resume_flag = "--session"
+    model_fields = ("provider", "modelId")
+
+    def session_id(self, path):
+        # named <timestamp>_<uuid>.jsonl, and only the second half identifies it
+        stem = os.path.basename(path)[:-len(".jsonl")]
+        return stem.split("_", 1)[-1]
+
+
+class CommandCodeBackend(PiLikeBackend):
+    name = "commandcode"
+    root = os.path.expanduser("~/.commandcode")
+    session_glob = "projects/*/*.jsonl"
+    process_patterns = ("cmd", "commandcode")
+    resume_binary = "cmd"
+    extra_dirs = ("file-history",)
+
+    def session_paths(self):
+        # checkpoint files sit beside the logs and share the session id
+        return [p for p in super().session_paths() if ".checkpoints." not in p]
+
+    def disk_paths(self, session_id, path):
+        base = os.path.dirname(path)
+        return [path,
+                os.path.join(base, f"{session_id}.checkpoints.jsonl"),
+                os.path.join(base, f"{session_id}.meta.json"),
+                os.path.join(self.root, "file-history", session_id)]

agent_ps/backends/sqlite.py

@@ -0,0 +1,55 @@
+"""Shared behaviour for agents that keep their sessions in SQLite.
+
+Two of them do, and both are read while the agent is writing, so the connection
+is opened read only and a locked or half written database costs a row of dashes
+rather than an error.
+"""
+
+import os
+import sqlite3
+
+from .base import Backend, blank_row
+
+
+class SqliteBackend(Backend):
+    #: File inside `root` holding the sessions.
+    db_filename = ""
+
+    @property
+    def database(self):
+        path = os.path.join(self.root, self.db_filename)
+        return path if os.path.exists(path) else ""
+
+    def query(self, sql, args=()):
+        if not self.database:
+            return []
+        connection = None
+        try:
+            connection = sqlite3.connect(f"file:{self.database}?mode=ro",
+                                         uri=True, timeout=1.0)
+            connection.row_factory = sqlite3.Row
+            return connection.execute(sql, args).fetchall()
+        except sqlite3.Error:
+            return []
+        finally:
+            if connection is not None:
+                connection.close()
+
+    def rows_from(self, sql, limit, build):
+        """Run a session query and turn each record into a row.
+
+        `build` fills in the fields that differ between agents; everything a row
+        always has is set here so the two backends cannot drift apart.
+        """
+        if limit is not None:
+            sql += f" LIMIT {int(limit)}"
+        rows = []
+        for record in self.query(sql):
+            row = blank_row(self.name)
+            row["path"] = self.database
+            fields = build(record)
+            cwd = fields.get("cwd") or ""
+            row.update(fields)
+            row["name"] = os.path.basename(cwd) if cwd else ""
+            rows.append(row)
+        return rows

agent_ps/collect.py

@@ -0,0 +1,101 @@
+"""Turning backends into one table.
+
+Every backend answers about its own agent. This is where those answers are put
+side by side, and it is the only place that knows more than one agent exists.
+"""
+
+import time
+
+from . import procs as proc_table
+from .backends.base import KIND_ENDED
+
+#: How many recent sessions per agent are considered when pairing processes.
+#: A session with a live process was active moments ago, so the newest few
+#: hundred always cover it, and older logs are never parsed to find one.
+ATTACH_WINDOW = 200
+
+HISTORY_POLL_SECONDS = 30.0
+
+
+class Snapshot:
+    """One pass over everything, with per-backend caches kept between passes."""
+
+    def __init__(self, backends):
+        self.backends = backends
+        self._history = {"bytes": 0, "ended": 0, "recent": 0}
+        self._history_at = 0.0
+
+    def rows(self, show_ended=False, limit=40):
+        table = proc_table.table()
+        taken = set()
+        running = []
+        ended = []
+
+        for backend in self.backends:
+            mine = proc_table.drop_shims(
+                [p for p in table if p["pid"] not in taken and backend.owns(p)])
+            taken.update(p["pid"] for p in mine)
+
+            recent = backend.sessions(limit=ATTACH_WINDOW)
+            index = {}
+            for session in recent:
+                index.setdefault(session["cwd"], []).append(session)
+
+            attached = backend.attach(mine, index) if mine else []
+            hosted = backend.live_sessions()
+            running.extend(attached)
+            running.extend(hosted)
+
+            if show_ended:
+                live = {r["session_id"] for r in attached + hosted if r["session_id"]}
+                for session in recent:
+                    if session["session_id"] in live:
+                        continue
+                    session["kind"] = KIND_ENDED
+                    ended.append(session)
+
+        ended.sort(key=lambda r: r["last_active"], reverse=True)
+        return running + ended[:limit]
+
+    def history(self, force=False):
+        """What finished sessions are costing on disk, refreshed slowly.
+
+        Walking the log directories is the one expensive call here, and the
+        answer moves by megabytes an hour, so it runs on its own schedule.
+        """
+        now = time.time()
+        if not force and now - self._history_at < HISTORY_POLL_SECONDS:
+            return self._history
+        week_ago = now - 7 * 86400
+        total = ended = recent = 0
+        for backend in self.backends:
+            total += backend.history_bytes()
+            count, fresh = backend.history_counts(week_ago)
+            ended += count
+            recent += fresh
+        self._history = {"bytes": total, "ended": ended, "recent": recent}
+        self._history_at = now
+        return self._history
+
+    def find_backend(self, name):
+        return next((b for b in self.backends if b.name == name), None)
+
+
+def is_live(row):
+    """Whether a session is still open.
+
+    Not the same as having a process. An agent embedded in an editor is running
+    without one, so a PID is evidence of life rather than the definition of it.
+    """
+    return row["kind"] != KIND_ENDED
+
+
+def idle_seconds(row):
+    """How long since the session last wrote to its log.
+
+    Every turn appends, so the modification time is when the session was last
+    used. That is a different question from uptime: a process can be five days
+    old and have answered a minute ago.
+    """
+    last = row.get("last_active", 0)
+    return int(time.time() - last) if last else 0

agent_ps/jsonl.py

@@ -0,0 +1,110 @@
+"""Cached reading of session logs.
+
+Session logs reach several megabytes, and the fields worth showing sit at one
+end or the other: the working directory is written when the session starts, the
+title and current model near the last turn. So the whole file is never parsed.
+
+Backends say what to pull out; the caching and the file handling live here, so
+no backend reimplements either.
+"""
+
+import json
+import os
+
+HEAD_LINES = 40
+TAIL_BYTES = 262144
+
+
+class Reader:
+    """The two ends of one log file, parsed lazily and at most once."""
+
+    def __init__(self, path):
+        self.path = path
+        self._head = None
+        self._tail = None
+
+    def head(self):
+        """Entries from the start of the file, in order."""
+        if self._head is None:
+            self._head = []
+            try:
+                with open(self.path, "r", errors="ignore") as handle:
+                    for _ in range(HEAD_LINES):
+                        line = handle.readline()
+                        if not line:
+                            break
+                        entry = parse_line(line)
+                        if entry is not None:
+                            self._head.append(entry)
+            except OSError:
+                pass
+        return self._head
+
+    def tail(self):
+        """Raw lines from the end of the file, newest first.
+
+        Raw rather than parsed, so a caller can skip most lines with a substring
+        test before paying for json.loads.
+        """
+        if self._tail is None:
+            self._tail = []
+            try:
+                with open(self.path, "rb") as handle:
+                    handle.seek(0, os.SEEK_END)
+                    size = handle.tell()
+                    handle.seek(max(0, size - TAIL_BYTES))
+                    chunk = handle.read().decode("utf-8", "ignore")
+                self._tail = list(reversed(chunk.splitlines()))
+            except OSError:
+                pass
+        return self._tail
+
+    def find_head(self, *fields):
+        """First value found for any of these fields near the start."""
+        for entry in self.head():
+            for field in fields:
+                if entry.get(field):
+                    return entry[field]
+        return ""
+
+
+class Cache:
+    """Extraction results, keyed by path and invalidated by modification time."""
+
+    def __init__(self):
+        self._values = {}
+        self._mtimes = {}
+
+    def info(self, path, extract, blank):
+        try:
+            mtime = os.path.getmtime(path)
+        except OSError:
+            return dict(blank)
+        if self._mtimes.get(path) == mtime:
+            return self._values[path]
+        value = dict(blank, last_active=mtime)
+        try:
+            value.update(extract(Reader(path)) or {})
+        except (OSError, ValueError):
+            pass
+        self._values[path] = value
+        self._mtimes[path] = mtime
+        return value
+
+
+def parse_line(line):
+    try:
+        entry = json.loads(line)
+    except ValueError:
+        return None
+    return entry if isinstance(entry, dict) else None
+
+
+def load(path):
+    """A whole JSON file, or an empty dict. For sidecar metadata, not logs."""
+    try:
+        with open(path, "r", errors="ignore") as handle:
+            data = json.load(handle)
+        return data if isinstance(data, dict) else {}
+    except (OSError, ValueError):
+        return {}

agent_ps/procs.py

@@ -0,0 +1,188 @@
+"""The process table, and stopping things in it."""
+
+import os
+import re
+import signal
+import sys
+import time
+
+from .util import parse_elapsed, run
+
+SELF_PIDS = {os.getpid(), os.getppid()}
+
+#: Programs that are never a session. Matched on the executable only, so a
+#: session that merely mentions one of these in a prompt survives.
+SKIP = ("agent-ps", "grep", "lsof")
+
+#: Helpers launched through an interpreter, where the executable is `node` or
+#: `python` and the name to look for is an argument. Matched against path
+#: arguments as well, which is a looser test and so kept to what needs it.
+SKIP_SCRIPTS = ("statusline",)
+
+
+def table():
+    """Every process on the machine, as plain dicts. One ps call."""
+    out = run(["ps", "-axo", "pid=,ppid=,etime=,pcpu=,rss=,command="])
+    procs = []
+    for line in out.splitlines():
+        parts = line.split(None, 5)
+        if len(parts) < 6:
+            continue
+        pid, ppid, etime, pcpu, rss, cmd = parts
+        if int(pid) in SELF_PIDS or is_tool(cmd, SKIP, SKIP_SCRIPTS):
+            continue
+        procs.append({
+            "pid": int(pid),
+            "ppid": int(ppid),
+            "cmd": cmd.strip(),
+            "uptime": parse_elapsed(etime),
+            "cpu": float(pcpu),
+            "rss": int(rss),
+        })
+    return procs
+
+
+def drop_shims(procs):
+    """Remove launcher processes that only exist to exec the real one.
+
+    Version managers put a shim on PATH which spawns the actual interpreter
+    under the same name, so one session shows up twice. The shim is always the
+    parent and always carries an identical command line, which is what separates
+    it from a supervisor: those spawn helpers with different arguments, so a
+    daemon and its workers are left alone.
+    """
+    by_parent = {}
+    for proc in procs:
+        by_parent.setdefault(proc["ppid"], []).append(proc)
+    return [p for p in procs
+            if not any(c["cmd"] == p["cmd"] for c in by_parent.get(p["pid"], []))]
+
+
+def is_tool(cmd, programs, scripts=()):
+    """Whether a command line runs one of these.
+
+    `programs` is checked against the executable alone, so a session whose
+    prompt happens to contain the word `grep` is not mistaken for grep itself.
+    `scripts` is also checked against path arguments, since a helper run as
+    `node .../statusline.js` names itself there rather than in the executable.
+    """
+    tokens = cmd.split()
+    if not tokens:
+        return False
+    if _stem(tokens[0]) in programs or _stem(tokens[0]) in scripts:
+        return True
+    return any(_stem(t) in scripts for t in tokens[1:] if "/" in t)
+
+
+def _stem(token):
+    return os.path.basename(token).split(".")[0]
+
+
+def environment(pid, prefixes):
+    """Environment variables of one process, filtered by prefix."""
+    env = {}
+    for token in run(["ps", "eww", "-p", str(pid)]).split():
+        if "=" not in token:
+            continue
+        key, _, value = token.partition("=")
+        if key.startswith(prefixes):
+            env[key] = value
+    return env
+
+
+def working_dirs(pids):
+    """Working directory of each PID, as one lookup rather than one per process.
+
+    This is how a session is matched to a process when the agent does not record
+    the pairing itself. Linux exposes it in /proc; macOS needs lsof, which is
+    slow enough that asking once for every PID matters.
+    """
+    if not pids:
+        return {}
+    if sys.platform.startswith("linux"):
+        found = {}
+        for pid in pids:
+            try:
+                found[pid] = os.readlink(f"/proc/{pid}/cwd")
+            except OSError:
+                pass
+        return found
+
+    joined = ",".join(str(p) for p in pids)
+    out = run(["lsof", "-a", "-d", "cwd", "-p", joined, "-Fpn"], timeout=10)
+    found = {}
+    current = None
+    for line in out.splitlines():
+        if line.startswith("p"):
+            current = int(line[1:]) if line[1:].isdigit() else None
+        elif line.startswith("n") and current is not None:
+            found[current] = line[1:]
+            current = None
+    return found
+
+
+def matches(cmd, patterns):
+    """Whether a command line belongs to an agent.
+
+    Matched on the executable rather than anywhere in the string, because short
+    names like `pi` otherwise match any path that happens to contain them.
+    """
+    for pattern in patterns:
+        if re.search(r"(^|[/\s])" + re.escape(pattern) + r"(\s|$)", cmd):
+            return True
+    return False
+
+
+def alive(pid):
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+
+
+def children_of(procs):
+    tree = {}
+    for proc in procs:
+        tree.setdefault(proc["ppid"], []).append(proc)
+    return tree
+
+
+def collect_tree(pid, tree, seen=None):
+    """PIDs of a process and its descendants, deepest first."""
+    if seen is None:
+        seen = []
+    for child in tree.get(pid, []):
+        collect_tree(child["pid"], tree, seen)
+    if pid not in seen:
+        seen.append(pid)
+    return seen
+
+
+def terminate(pid, grace=1.0):
+    """SIGTERM, a moment to exit cleanly, then SIGKILL."""
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except ProcessLookupError:
+        return True
+    except PermissionError:
+        return False
+    deadline = time.time() + grace
+    while time.time() < deadline:
+        if not alive(pid):
+            return True
+        time.sleep(0.05)
+    try:
+        os.kill(pid, signal.SIGKILL)
+    except (ProcessLookupError, PermissionError):
+        pass
+    return not alive(pid)
+
+
+def stop_tree(pid, procs, dry_run=False):
+    order = collect_tree(pid, children_of(procs))
+    if dry_run:
+        return order, []
+    return order, [p for p in order if terminate(p)]

agent_ps/resume.py

@@ -0,0 +1,60 @@
+"""Reopening a session in a new terminal."""
+
+import json
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+
+
+def resume_command(backend, session_id, cwd):
+    """Shell line that reopens a session in the directory it ran in."""
+    where = shlex.quote(cwd) if cwd else "."
+    return f"cd {where} && {backend.resume(shlex.quote(session_id))}"
+
+
+def open_in_terminal(command):
+    """Run a command in a new terminal window or tab.
+
+    Falls through the terminals that can be scripted, and returns a message
+    either way so the caller can show what happened.
+    """
+    if sys.platform == "darwin":
+        if os.environ.get("TERM_PROGRAM") == "iTerm.app":
+            script = f'''
+                tell application "iTerm"
+                    tell current window
+                        create tab with default profile
+                        tell current session to write text {json.dumps(command)}
+                    end tell
+                end tell
+            '''
+        else:
+            script = f'''
+                tell application "Terminal"
+                    do script {json.dumps(command)}
+                    activate
+                end tell
+            '''
+        try:
+            # a terminal that hangs on the AppleScript would otherwise freeze
+            # the whole view, since this runs on the drawing thread
+            result = subprocess.run(["osascript", "-e", script],
+                                    capture_output=True, text=True, timeout=10)
+        except (subprocess.SubprocessError, OSError):
+            return False, "The terminal did not respond."
+        if result.returncode == 0:
+            return True, "Opened in a new tab."
+        return False, "Could not open a terminal tab."
+
+    for launcher in (["x-terminal-emulator", "-e"], ["gnome-terminal", "--"],
+                     ["konsole", "-e"], ["xterm", "-e"]):
+        if shutil.which(launcher[0]):
+            try:
+                subprocess.Popen(launcher + ["sh", "-c", command],
+                                 start_new_session=True)
+                return True, "Opened in a new window."
+            except OSError:
+                continue
+    return False, "No terminal emulator found."