pocketshell 0.4.7__tar.gz → 0.4.9__tar.gz

{pocketshell-0.4.7 → pocketshell-0.4.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pocketshell
-Version: 0.4.7
+Version: 0.4.9
 Summary: Unified server-side Python utility for the PocketShell Android client.
 Project-URL: Homepage, https://github.com/alexeygrigorev/pocketshell
 Project-URL: Issues, https://github.com/alexeygrigorev/pocketshell/issues

{pocketshell-0.4.7 → pocketshell-0.4.9}/pyproject.toml

@@ -8,7 +8,7 @@ name = "pocketshell"
 # scripts/check-pypi-version.sh enforces this; .github/workflows/build.yml
 # runs that check before publishing to PyPI. See
 # tools/pocketshell/README.md ("Release flow") for the bump procedure.
-version = "0.4.7"
+version = "0.4.9"
 description = "Unified server-side Python utility for the PocketShell Android client."
 readme = "README.md"
 requires-python = ">=3.11"

{pocketshell-0.4.7 → pocketshell-0.4.9}/src/pocketshell/agents.py

@@ -74,6 +74,7 @@ from __future__ import annotations
 import json
 import os
 import shutil
+import subprocess
 from pathlib import Path
 from typing import Optional
 
@@ -354,6 +355,56 @@ def _resolve_dir(ctx: click.Context, directory: str) -> Path:
     return path
 
 
+def record_agent_kind(
+    kind: str,
+    env: Optional[dict[str, str]] = None,
+    runner=None,
+) -> bool:
+    """Record the launched agent ``kind`` as a per-session tmux user option.
+
+    Workstream A / epic #821: the durable "what is this session running"
+    state lives **host-side** as the tmux user option ``@ps_agent_kind`` on
+    the session this wrapper runs in. Writing it here (in the same process
+    that becomes the agent) means the recorded kind cannot drift from what
+    actually launched, and it covers every launch caller — the folder
+    picker, the assistant, the repo browser — with zero Kotlin launch-exec
+    change. The client reads it back through its session enumeration
+    (``tmux list-sessions -F '…#{@ps_agent_kind}'``).
+
+    The option is session-scoped (not global): ``tmux set-option`` without
+    ``-g`` sets it on the current session, which is the session the agent
+    was launched into. tmux session options persist for the life of the
+    session, so the recorded kind survives reconnect / app restart /
+    app-kill / reinstall — exactly the durability the epic requires.
+
+    No-op (returns ``False``) when not running inside tmux (``$TMUX``
+    unset) — e.g. a bare SSH ``pocketshell agent`` invocation — or when the
+    kind is unknown. A failure of the ``tmux`` call is swallowed: recording
+    the kind must never prevent the agent from launching.
+
+    ``runner`` is injected so tests can assert the exact ``tmux`` argv
+    without spawning a real process; production passes ``None`` and it
+    resolves to :func:`subprocess.run`.
+    """
+    if not kind:
+        return False
+    source_env = os.environ if env is None else env
+    if not source_env.get("TMUX"):
+        # Not inside a tmux server — nothing to record onto.
+        return False
+    if runner is None:
+        runner = subprocess.run
+    try:
+        runner(
+            ["tmux", "set-option", "@ps_agent_kind", kind],
+            check=False,
+        )
+    except Exception:
+        # Recording the kind is best-effort; never block the launch on it.
+        return False
+    return True
+
+
 def launch_agent(
     ctx: click.Context,
     kind: str,
@@ -363,6 +414,7 @@ def launch_agent(
     config_dir: Optional[str],
     extra_env: Optional[dict[str, str]] = None,
     execvpe=None,
+    record_kind=None,
 ) -> None:
     """Resolve the dir, build env+argv, suppress prompts, exec the agent.
 
@@ -376,9 +428,17 @@ def launch_agent(
     ``os`` so a monkeypatch on ``agents.os.execvpe`` is honoured (a default
     argument would bind the original at def-time and bypass the patch).
     :func:`os.execvpe` never returns on success.
+
+    Before the exec, when running inside tmux, the launched ``kind`` is
+    recorded as the per-session ``@ps_agent_kind`` user option
+    (:func:`record_agent_kind`) so the client can read the agent type back
+    from the host without output-parsing detection (epic #821 Workstream A).
+    ``record_kind`` is injected the same way as ``execvpe`` for tests.
     """
     if execvpe is None:
         execvpe = os.execvpe
+    if record_kind is None:
+        record_kind = record_agent_kind
 
     path = _resolve_dir(ctx, directory)
     resolved_dir = str(path)
@@ -409,6 +469,12 @@ def launch_agent(
     if kind == "claude":
         seed_claude_trust(claude_config_path(env), resolved_dir)
 
+    # Record the launched kind on the tmux session BEFORE the exec replaces
+    # this process (epic #821 Workstream A). Use this wrapper's own
+    # environment (os.environ) for the TMUX detection — `env` is the
+    # provider-stripped launch env that does not necessarily carry $TMUX.
+    record_kind(kind, dict(os.environ))
+
     # Replace this process with the agent so it owns the pty cleanly.
     execvpe(argv[0], argv, env)
 

pocketshell-0.4.9/src/pocketshell/agents_kind.py

@@ -0,0 +1,216 @@
+"""`pocketshell agents kind` — CLI seam over the cgroup agent-kind detector.
+
+Epic #821 (workstream A2-infra). The daemon RPC ``agents.kind_for_panes``
+(:func:`pocketshell.cgroup_agents.kind_for_panes`,
+:func:`pocketshell.daemon._agents_kind_for_panes_handler`) does cgroup-v2 +
+``/proc`` agent-kind detection on the host, but it is **daemon-registry-only**:
+the PocketShell Android client only ever execs ``pocketshell <subcommand>`` over
+its warm SSH session — it never speaks JSON-RPC directly. So the detection has
+no way to be reached from the client today.
+
+This module adds the missing seam: ``pocketshell agents kind`` accepts a pane
+list (each pane ``{pane_id, pane_pid}``, matching the RPC's input shape),
+dispatches to the daemon when it is up (mirroring the
+:func:`pocketshell.jobs._try_daemon_jobs_call` CLI→daemon pattern), falls back
+to calling :func:`pocketshell.cgroup_agents.kind_for_panes` in-process when the
+daemon is absent (the detection is pure cgroupfs/``/proc`` reads — no shell-out,
+so the in-process call is the same computation the daemon performs), and emits
+the RPC's ``{"results": [{pane_id, agent_kind, scope, evidence_pid?}]}`` as
+stable, client-parseable JSON on stdout.
+
+Input forms (pick whichever is convenient — they merge):
+
+- **stdin JSON** — ``{"panes": [{"pane_id": "%1", "pane_pid": 2647034}, ...]}``,
+  byte-for-byte the RPC request shape. This is the primary form the client uses
+  (it pipes the pane snapshot it already has).
+- **``--pane PANE_ID=PANE_PID``** (repeatable) — an ergonomic alternative for a
+  one-shot SSH exec / manual debugging.
+
+``none`` / ``unknown`` / empty-pane inputs never error: an empty pane list
+yields ``{"results": []}``, a missing/invalid ``pane_pid`` yields
+``agent_kind="unknown"`` for that pane, and one bad pane never sinks the batch
+(the detector is defensive by design — see ``cgroup_agents``).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, Mapping, Optional
+
+import click
+
+from pocketshell.cgroup_agents import (
+    DEFAULT_CGROUP_MOUNT,
+    DEFAULT_PROC_ROOT,
+)
+
+
+def _parse_stdin_panes() -> list[dict[str, Any]]:
+    """Read ``{"panes": [...]}`` from stdin, returning the pane list.
+
+    A non-TTY empty stdin (the common ``--pane``-only or no-input case) yields
+    an empty list rather than an error. Malformed JSON is a clear usage error.
+    """
+    if sys.stdin is None or sys.stdin.isatty():
+        return []
+    raw = sys.stdin.read()
+    if not raw.strip():
+        return []
+    try:
+        doc = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise click.ClickException(
+            f"agents kind: stdin is not valid JSON: {exc}"
+        ) from exc
+    if not isinstance(doc, Mapping):
+        raise click.ClickException(
+            "agents kind: stdin JSON must be an object with a `panes` list"
+        )
+    raw_panes = doc.get("panes")
+    if raw_panes is None:
+        return []
+    if not isinstance(raw_panes, list):
+        raise click.ClickException(
+            "agents kind: `panes` must be a list of objects"
+        )
+    return [dict(p) for p in raw_panes if isinstance(p, Mapping)]
+
+
+def _parse_pane_options(pane_specs: tuple[str, ...]) -> list[dict[str, Any]]:
+    """Parse ``--pane PANE_ID=PANE_PID`` specs into pane mappings.
+
+    ``PANE_PID`` is left as the raw string; the detector coerces it to ``int``
+    and degrades an invalid value to ``agent_kind="unknown"`` rather than
+    failing — so a non-numeric pid here is not a CLI error, mirroring the RPC.
+    """
+    panes: list[dict[str, Any]] = []
+    for spec in pane_specs:
+        pane_id, sep, pane_pid = spec.partition("=")
+        if not sep:
+            raise click.ClickException(
+                f"agents kind: --pane must be PANE_ID=PANE_PID (got {spec!r})"
+            )
+        panes.append({"pane_id": pane_id, "pane_pid": pane_pid})
+    return panes
+
+
+def _try_daemon_call(
+    panes: list[dict[str, Any]],
+    *,
+    proc_root: str,
+    cgroup_mount: str,
+    timeout: float = 5.0,
+) -> Optional[dict[str, Any]]:
+    """Dispatch ``agents.kind_for_panes`` to the daemon; ``None`` on miss/error.
+
+    Mirrors :func:`pocketshell.jobs._try_daemon_jobs_call`. Only used when the
+    detection runs against the real host roots — when the caller overrode
+    ``--proc-root`` / ``--cgroup-mount`` (tests, debugging), the in-process path
+    is used directly so the override is honoured (the daemon reads the live
+    host roots and cannot see a synthetic tree).
+    """
+    if proc_root != DEFAULT_PROC_ROOT or cgroup_mount != DEFAULT_CGROUP_MOUNT:
+        return None
+
+    from pocketshell import daemon as _daemon
+
+    socket_path = _daemon.resolve_socket_path()
+    if not socket_path.exists():
+        return None
+    try:
+        result = _daemon.call(
+            "agents.kind_for_panes",
+            params={"panes": panes},
+            socket_path=socket_path,
+            timeout=timeout,
+        )
+    except (_daemon.DaemonClientError, RuntimeError, OSError):
+        return None
+    if not isinstance(result, dict) or "results" not in result:
+        return None
+    return result
+
+
+def _classify_in_process(
+    panes: list[dict[str, Any]],
+    *,
+    proc_root: str,
+    cgroup_mount: str,
+) -> dict[str, Any]:
+    """Call the detector in-process and wrap it in the RPC's result envelope."""
+    from pocketshell import cgroup_agents as _cgroup_agents
+
+    results = _cgroup_agents.kind_for_panes(
+        panes, proc_root=proc_root, cgroup_mount=cgroup_mount
+    )
+    return {"results": results}
+
+
+@click.group(
+    name="agents",
+    context_settings={"help_option_names": ["-h", "--help"]},
+    help=(
+        "Host-side agent-awareness helpers for the PocketShell client.\n\n"
+        "`kind` classifies the coding-agent (claude / codex / opencode) "
+        "running in each tmux pane's cgroup scope — the CLI seam over the "
+        "`agents.kind_for_panes` daemon RPC. See epic #821."
+    ),
+)
+def agents_group() -> None:
+    """Top-level `agents` group registered onto the root `pocketshell` CLI."""
+
+
+@agents_group.command(
+    name="kind",
+    context_settings={"help_option_names": ["-h", "--help"]},
+    help=(
+        "Classify the agent kind in each pane's cgroup scope.\n\n"
+        "Reads a pane list as `{\"panes\": [{\"pane_id\", \"pane_pid\"}, ...]}` "
+        "JSON on stdin (the RPC request shape), and/or via repeatable "
+        "`--pane PANE_ID=PANE_PID`. Emits "
+        "`{\"results\": [{\"pane_id\", \"agent_kind\", \"scope\", "
+        "\"evidence_pid\"?}]}` as JSON on stdout. `agent_kind` is one of "
+        "claude / codex / opencode / none (scope, no agent) / unknown "
+        "(pane pid/cgroup unreadable). Empty input -> `{\"results\": []}`."
+    ),
+)
+@click.option(
+    "--pane",
+    "pane_specs",
+    multiple=True,
+    metavar="PANE_ID=PANE_PID",
+    help=(
+        "A pane to classify, as PANE_ID=PANE_PID. Repeatable. Merges with any "
+        "panes read from stdin JSON."
+    ),
+)
+@click.option(
+    "--proc-root",
+    default=DEFAULT_PROC_ROOT,
+    show_default=True,
+    help="Override the /proc root (testing / debugging).",
+)
+@click.option(
+    "--cgroup-mount",
+    default=DEFAULT_CGROUP_MOUNT,
+    show_default=True,
+    help="Override the cgroup v2 mount point (testing / debugging).",
+)
+def agents_kind_command(
+    pane_specs: tuple[str, ...],
+    proc_root: str,
+    cgroup_mount: str,
+) -> None:
+    """Classify the agent kind running in each pane's cgroup scope."""
+    panes = _parse_stdin_panes() + _parse_pane_options(pane_specs)
+
+    envelope = _try_daemon_call(
+        panes, proc_root=proc_root, cgroup_mount=cgroup_mount
+    )
+    if envelope is None:
+        envelope = _classify_in_process(
+            panes, proc_root=proc_root, cgroup_mount=cgroup_mount
+        )
+
+    click.echo(json.dumps(envelope))

pocketshell-0.4.9/src/pocketshell/cgroup_agents.py

@@ -0,0 +1,309 @@
+"""Scope/cgroup-based agent-kind detection for the ``agents.kind_for_panes`` RPC.
+
+Replaces the fragile client-side ``ps -eo … | grep`` agent scan (issue #809 /
+#811) with a deterministic server-side read of cgroup v2 + ``/proc``:
+
+1. **pane → scope** — read ``/proc/<pane_pid>/cgroup``. On a cgroup-v2 host the
+   sole ``0::`` line carries the cgroup-relative path of the leaf, which for a
+   PocketShell session is ``…/robust.slice/tmuxctl-<session>.scope`` (the
+   deterministic name `tmuxctl` assigns at ``robust.scope_unit_name``). Sessions
+   started outside tmuxctl resolve to ``tmux-spawn-<uuid>.scope`` or a login
+   scope; "no scope" is detectable, never a crash.
+2. **scope → procs** — read that cgroup's ``cgroup.procs`` then each
+   ``/proc/<pid>/comm`` + ``/proc/<pid>/cmdline``. No ``systemctl status``
+   shell-out (it forks, pretty-prints ~100 ms, and truncates the proc list);
+   raw cgroupfs reads are ~7-17 ms and complete.
+3. **classify** — match comm/cmdline tokens for claude / codex / opencode,
+   mirroring the proven token rules in
+   ``shared/core-agents/.../AgentDetector.kt`` (``namesAgent`` /
+   ``containsCommandToken``): a word-boundary match so ``codex`` matches a bare
+   ``codex`` comm AND a ``node …/codex`` node-wrapped cmdline, but
+   ``codex-helper`` substrings of an unrelated path do not false-positive on the
+   raw token alone.
+
+All filesystem roots are injectable (``proc_root`` / ``cgroup_mount``) so the
+classifier unit-tests against a synthetic ``/proc``-like tree with zero live
+sessions. Every read is defensive: a missing pid, a pid that vanished between
+the ``cgroup.procs`` read and the ``comm`` read, a no-scope pane, or a
+permission error degrades to ``agent_kind = "none"`` (or an explicit
+``"unknown"`` for an unreadable pane) — never an exception that fails the whole
+batch.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, Mapping, Optional, Sequence
+
+# Default cgroup v2 mount point on Linux. Injectable for tests.
+DEFAULT_CGROUP_MOUNT = "/sys/fs/cgroup"
+DEFAULT_PROC_ROOT = "/proc"
+
+# Agent kinds returned to the client. ``none`` = pane resolved to a scope (or a
+# readable proc set) but no agent process is present. ``unknown`` = the pane's
+# pid / cgroup could not be read at all (vanished, permission), so we cannot
+# even assert "no agent" — the client should treat it as not-yet-known, not as
+# a confirmed plain shell.
+AGENT_CLAUDE = "claude"
+AGENT_CODEX = "codex"
+AGENT_OPENCODE = "opencode"
+AGENT_NONE = "none"
+AGENT_UNKNOWN = "unknown"
+
+# Token patterns mirror AgentDetector.namesAgent (Kotlin). Each is wrapped in
+# the same word-boundary guard as Kotlin's `containsCommandToken` so the token
+# only matches as a whole command word — bounded by start/end, whitespace, or
+# the shell/path delimiters `/ | ; & ( ) ' " \``. This lets `codex` match both
+# a bare `codex` comm and a `node /…/codex` node-wrapped cmdline while a stray
+# substring inside an unrelated token does not light up.
+_AGENT_TOKEN_PATTERNS: Sequence[tuple[str, str]] = (
+    # (agent_kind, command-token regex — verbatim from the Kotlin rules)
+    (AGENT_CLAUDE, r"claude(?:-?code)?"),
+    (AGENT_CODEX, r"codex"),
+    (AGENT_OPENCODE, r"open[-_]?code(?:[-_][a-z0-9]+)?"),
+)
+
+# Pre-compile the boundary-wrapped matchers once. The guard is identical to
+# `containsCommandToken`: a leading start/delimiter and a trailing
+# end/delimiter lookahead, case-insensitive.
+_BOUNDARY_LEAD = r"(^|[\s/|;&('\"`])"
+_BOUNDARY_TAIL = r"(?=$|[\s/|;&):'\"`])"
+_COMPILED_TOKENS: Sequence[tuple[str, "re.Pattern[str]"]] = tuple(
+    (kind, re.compile(_BOUNDARY_LEAD + pattern + _BOUNDARY_TAIL))
+    for kind, pattern in _AGENT_TOKEN_PATTERNS
+)
+
+# Extract the scope unit basename from a cgroup-v2 relative path. Matches both
+# the tmuxctl session scope and the non-tmuxctl spawn scope so "which scope"
+# is reported even when no agent is detected.
+_SCOPE_BASENAME_RE = re.compile(r"(?P<scope>(?:tmuxctl|tmux-spawn)-[^/]+\.scope)")
+
+
+@dataclass(frozen=True)
+class PaneAgentResult:
+    """One pane's classification result.
+
+    ``scope`` is the cgroup scope basename the pane resolved to (e.g.
+    ``tmuxctl-git-pocketshell.scope``) or ``None`` if the pane had no
+    tmuxctl/spawn scope (login shell, no systemd scopes). ``evidence_pid`` is
+    the pid of the process whose comm/cmdline named the agent, for debugging.
+    """
+
+    pane_id: Optional[str]
+    agent_kind: str
+    scope: Optional[str]
+    evidence_pid: Optional[int] = None
+
+    def to_json(self) -> dict[str, object]:
+        out: dict[str, object] = {
+            "pane_id": self.pane_id,
+            "agent_kind": self.agent_kind,
+            "scope": self.scope,
+        }
+        if self.evidence_pid is not None:
+            out["evidence_pid"] = self.evidence_pid
+        return out
+
+
+def classify_token(text: str) -> Optional[str]:
+    """Return the agent kind named by ``text`` (a comm or cmdline), or ``None``.
+
+    Mirrors ``AgentDetector.namesAgent``: lowercases then applies the
+    word-boundary command-token match for each engine, in claude→codex→opencode
+    order. The order only matters in the impossible case of a single string
+    naming two engines; a real comm/cmdline names at most one.
+    """
+    lowered = text.lower()
+    for kind, pattern in _COMPILED_TOKENS:
+        if pattern.search(lowered):
+            return kind
+    return None
+
+
+def _read_text(path: Path) -> Optional[str]:
+    """Read a small ``/proc``/cgroupfs file, returning ``None`` on any error.
+
+    cgroupfs and ``/proc`` files can race away between enumeration and read
+    (the pid exits), or be unreadable; callers treat ``None`` as "skip", never
+    as a fatal error.
+    """
+    try:
+        return path.read_text(encoding="utf-8", errors="replace")
+    except (FileNotFoundError, ProcessLookupError, PermissionError, OSError):
+        return None
+
+
+def _read_cmdline(path: Path) -> Optional[str]:
+    """Read a ``/proc/<pid>/cmdline`` (NUL-delimited) as a space-joined string."""
+    try:
+        raw = path.read_bytes()
+    except (FileNotFoundError, ProcessLookupError, PermissionError, OSError):
+        return None
+    if not raw:
+        return ""
+    # cmdline args are NUL-separated, trailing NUL terminates the last arg.
+    decoded = raw.decode("utf-8", errors="replace")
+    return " ".join(part for part in decoded.split("\x00") if part).strip()
+
+
+def scope_relpath_for_pid(
+    pane_pid: int,
+    *,
+    proc_root: str = DEFAULT_PROC_ROOT,
+) -> Optional[str]:
+    """Resolve a pid's cgroup-v2 relative scope path from ``/proc/<pid>/cgroup``.
+
+    Returns the cgroup-relative path of the leaf cgroup (the part after the
+    ``0::``), e.g.
+    ``/user.slice/…/robust.slice/tmuxctl-git-pocketshell.scope``. Returns
+    ``None`` when the pid is gone, unreadable, or the cgroup file is not
+    cgroup-v2 unified (no ``0::`` line).
+    """
+    content = _read_text(Path(proc_root) / str(pane_pid) / "cgroup")
+    if content is None:
+        return None
+    for line in content.splitlines():
+        # cgroup v2 unified hierarchy: exactly one line "0::<path>".
+        if line.startswith("0::"):
+            relpath = line[len("0::"):].strip()
+            return relpath or None
+    return None
+
+
+def scope_basename(relpath: str) -> Optional[str]:
+    """Return the ``tmuxctl-*.scope`` / ``tmux-spawn-*.scope`` basename, if any."""
+    match = _SCOPE_BASENAME_RE.search(relpath)
+    if match:
+        return match.group("scope")
+    return None
+
+
+def _scope_procs(
+    relpath: str,
+    *,
+    cgroup_mount: str = DEFAULT_CGROUP_MOUNT,
+) -> Optional[list[int]]:
+    """Read ``cgroup.procs`` for the cgroup at ``relpath``.
+
+    ``relpath`` is the cgroup-v2 relative path from
+    :func:`scope_relpath_for_pid`; the absolute cgroupfs path is the mount plus
+    that relative path. Returns the list of pids, or ``None`` if the cgroup is
+    gone / unreadable (e.g. the session ended between the pane read and now).
+    """
+    # relpath is absolute-style ("/user.slice/…"); join under the mount.
+    cgroup_dir = Path(cgroup_mount) / relpath.lstrip("/")
+    content = _read_text(cgroup_dir / "cgroup.procs")
+    if content is None:
+        return None
+    pids: list[int] = []
+    for token in content.split():
+        try:
+            pids.append(int(token))
+        except ValueError:
+            continue
+    return pids
+
+
+def classify_scope_procs(
+    pids: Iterable[int],
+    *,
+    proc_root: str = DEFAULT_PROC_ROOT,
+) -> tuple[str, Optional[int]]:
+    """Classify the agent kind present among ``pids`` by their comm + cmdline.
+
+    Returns ``(agent_kind, evidence_pid)``. Reads each pid's ``comm`` first
+    (cheap, definitive for a non-wrapped CLI like ``claude``/``codex``) then
+    its ``cmdline`` (catches the node-wrapped form where ``comm`` is
+    ``node``/``MainThread`` but the cmdline carries ``node /…/codex``). The
+    first pid that names an agent wins; if none do, returns ``("none", None)``.
+    """
+    proc = Path(proc_root)
+    for pid in pids:
+        comm = _read_text(proc / str(pid) / "comm")
+        if comm is not None:
+            kind = classify_token(comm.strip())
+            if kind is not None:
+                return kind, pid
+        cmdline = _read_cmdline(proc / str(pid) / "cmdline")
+        if cmdline:
+            kind = classify_token(cmdline)
+            if kind is not None:
+                return kind, pid
+    return AGENT_NONE, None
+
+
+def kind_for_pane(
+    pane_pid: int,
+    *,
+    pane_id: Optional[str] = None,
+    proc_root: str = DEFAULT_PROC_ROOT,
+    cgroup_mount: str = DEFAULT_CGROUP_MOUNT,
+) -> PaneAgentResult:
+    """Resolve one pane's agent kind end-to-end (pane_pid → scope → classify).
+
+    Never raises: an unreadable pane pid yields ``agent_kind="unknown"`` (we
+    cannot even assert "no agent"); a readable scope with no agent process
+    yields ``agent_kind="none"``.
+    """
+    relpath = scope_relpath_for_pid(pane_pid, proc_root=proc_root)
+    if relpath is None:
+        # pid gone / cgroup unreadable — we cannot say anything definitive.
+        return PaneAgentResult(
+            pane_id=pane_id, agent_kind=AGENT_UNKNOWN, scope=None
+        )
+
+    scope = scope_basename(relpath)
+    pids = _scope_procs(relpath, cgroup_mount=cgroup_mount)
+    if pids is None:
+        # The cgroup itself is gone/unreadable even though the pane's cgroup
+        # line resolved — treat as unknown (the session likely just ended).
+        return PaneAgentResult(
+            pane_id=pane_id, agent_kind=AGENT_UNKNOWN, scope=scope
+        )
+
+    agent_kind, evidence_pid = classify_scope_procs(pids, proc_root=proc_root)
+    return PaneAgentResult(
+        pane_id=pane_id,
+        agent_kind=agent_kind,
+        scope=scope,
+        evidence_pid=evidence_pid,
+    )
+
+
+def kind_for_panes(
+    panes: Iterable[Mapping[str, object]],
+    *,
+    proc_root: str = DEFAULT_PROC_ROOT,
+    cgroup_mount: str = DEFAULT_CGROUP_MOUNT,
+) -> list[dict[str, object]]:
+    """Batch classifier: resolve agent kind for every pane in ``panes``.
+
+    Each pane is a mapping with ``pane_pid`` (int, required) and an optional
+    ``pane_id`` (passed through so the client can correlate). A pane with a
+    missing/invalid ``pane_pid`` yields ``agent_kind="unknown"`` rather than
+    failing the batch — one bad pane never sinks the others.
+    """
+    results: list[dict[str, object]] = []
+    for pane in panes:
+        pane_id = pane.get("pane_id")
+        pane_id_str = str(pane_id) if pane_id is not None else None
+        raw_pid = pane.get("pane_pid")
+        try:
+            pane_pid = int(raw_pid)  # type: ignore[arg-type]
+        except (TypeError, ValueError):
+            results.append(
+                PaneAgentResult(
+                    pane_id=pane_id_str, agent_kind=AGENT_UNKNOWN, scope=None
+                ).to_json()
+            )
+            continue
+        result = kind_for_pane(
+            pane_pid,
+            pane_id=pane_id_str,
+            proc_root=proc_root,
+            cgroup_mount=cgroup_mount,
+        )
+        results.append(result.to_json())
+    return results

{pocketshell-0.4.7 → pocketshell-0.4.9}/src/pocketshell/cli.py

@@ -24,6 +24,7 @@ import click
 from pocketshell import __version__
 from pocketshell.agent_log import agent_log_command
 from pocketshell.agents import agent_group
+from pocketshell.agents_kind import agents_group
 from pocketshell.env import env_group
 from pocketshell.github import github_group
 from pocketshell.hooks import hooks_group
@@ -55,6 +56,7 @@ def cli() -> None:
 
 cli.add_command(usage_command, name="usage")
 cli.add_command(agent_group, name="agent")
+cli.add_command(agents_group, name="agents")
 cli.add_command(profiles_group, name="profiles")
 cli.add_command(jobs_group, name="jobs")
 cli.add_command(sessions_group, name="sessions")