pocketshell 0.4.8__tar.gz → 0.4.10__tar.gz

{pocketshell-0.4.8 → pocketshell-0.4.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pocketshell
-Version: 0.4.8
+Version: 0.4.10
 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.8 → pocketshell-0.4.10}/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.8"
+version = "0.4.10"
 description = "Unified server-side Python utility for the PocketShell Android client."
 readme = "README.md"
 requires-python = ">=3.11"

{pocketshell-0.4.8 → pocketshell-0.4.10}/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.10/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.8 → pocketshell-0.4.10}/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
@@ -35,6 +36,7 @@ from pocketshell.push import push_group
 from pocketshell.qr_share import qr_share_command
 from pocketshell.repos import repos_group
 from pocketshell.sessions import sessions_group
+from pocketshell.tree import tree_group
 from pocketshell.usage import usage_command
 
 
@@ -55,9 +57,11 @@ 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")
+cli.add_command(tree_group, name="tree")
 cli.add_command(agent_log_command, name="agent-log")
 cli.add_command(repos_group, name="repos")
 cli.add_command(github_group, name="github")

{pocketshell-0.4.8 → pocketshell-0.4.10}/src/pocketshell/daemon.py

@@ -92,6 +92,12 @@ METHOD_TTLS: Mapping[str, float] = {
     # not hidden for long.
     "sessions.list": 5.0,
     "jobs.list": 5.0,
+    # `tree.get` is the cold-start hydrate read. Short TTL like `sessions.list`
+    # so a `tree.upsert` mutation (which also invalidates it explicitly) is not
+    # masked for long and an external edit is not hidden. `tree.upsert` and
+    # `tree.reconcile` carry NO TTL (mutations) so their results are never
+    # cached.
+    "tree.get": 5.0,
 }
 
 # Length-prefix is a 4-byte unsigned big-endian integer. ``struct``
@@ -574,6 +580,32 @@ def _agents_kind_for_panes_handler(params: Mapping[str, Any]) -> dict[str, Any]:
     return {"results": _cgroup_agents.kind_for_panes(panes)}
 
 
+# ---------------------------------------------------------------------------
+# Methods: tree.* (epic #821 slice C / issue #837)
+# ---------------------------------------------------------------------------
+
+
+def _tree_get_handler(params: Mapping[str, Any]) -> dict[str, Any]:
+    """Delegate ``tree.get`` to the durable per-host tree registry."""
+    from pocketshell import tree as _tree
+
+    return _tree.daemon_handler_get(dict(params))
+
+
+def _tree_upsert_handler(params: Mapping[str, Any]) -> dict[str, Any]:
+    """Delegate ``tree.upsert`` to the durable per-host tree registry."""
+    from pocketshell import tree as _tree
+
+    return _tree.daemon_handler_upsert(dict(params))
+
+
+def _tree_reconcile_handler(params: Mapping[str, Any]) -> dict[str, Any]:
+    """Delegate ``tree.reconcile`` to the durable per-host tree registry."""
+    from pocketshell import tree as _tree
+
+    return _tree.daemon_handler_reconcile(dict(params))
+
+
 # Single shared registry; tests can register additional methods via
 # :meth:`Daemon.register_method` on a fresh instance without touching
 # this dict.
@@ -592,6 +624,9 @@ DEFAULT_METHODS: Mapping[str, RpcHandler] = {
     "jobs.remove": _jobs_remove_handler,
     "jobs.status": _jobs_status_handler,
     "agents.kind_for_panes": _agents_kind_for_panes_handler,
+    "tree.get": _tree_get_handler,
+    "tree.upsert": _tree_upsert_handler,
+    "tree.reconcile": _tree_reconcile_handler,
 }
 
 
@@ -612,6 +647,13 @@ METHOD_CACHE_INVALIDATIONS: Mapping[str, tuple[str, ...]] = {
     "jobs.edit": ("jobs.list",),
     "jobs.remove": ("jobs.list",),
     "jobs.trigger": ("jobs.list",),
+    # `tree.upsert` rewrites the host's persisted node list, so the cached
+    # `tree.get` cold-start read is stale the moment it lands — drop it so the
+    # very next `tree.get` reflects the just-persisted ordering/expansion.
+    # `tree.reconcile` prunes gone nodes from the registry, so it must also
+    # invalidate the `tree.get` cache.
+    "tree.upsert": ("tree.get",),
+    "tree.reconcile": ("tree.get",),
 }