pocketshell 0.4.24__tar.gz → 0.4.26__tar.gz

{pocketshell-0.4.24 → pocketshell-0.4.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pocketshell
-Version: 0.4.24
+Version: 0.4.26
 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
@@ -21,6 +21,7 @@ Requires-Python: >=3.11
 Requires-Dist: click>=8.2.0
 Requires-Dist: google-auth>=2.0.0
 Requires-Dist: pyyaml>=6.0
+Requires-Dist: quse==0.0.9
 Requires-Dist: tmuxctl>=0.3.3
 Provides-Extra: dev
 Requires-Dist: pytest>=8.4.0; extra == 'dev'

{pocketshell-0.4.24 → pocketshell-0.4.26}/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.24"
+version = "0.4.26"
 description = "Unified server-side Python utility for the PocketShell Android client."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -27,12 +27,19 @@ classifiers = [
     "Topic :: Software Development",
     "Topic :: System :: Monitoring",
 ]
-# `pocketshell usage` delegates to the existing `quse` CLI via subprocess
-# (see `pocketshell/usage.py`) so this utility does not need `quse`
-# published on PyPI; the provider-detection implementation may be folded
-# in directly later. Pin lower-bound only.
+# `pocketshell usage` delegates to the `quse` CLI, which is now a PINNED
+# hard dependency (issue #1318): quse owns the unified usage schema, so we
+# ship a known-good quse WITH pocketshell and invoke that pinned console-
+# script (next to `sys.executable`, never PATH — see `pocketshell/usage.py`
+# `_resolve_quse_binary`). A host-level quse upgrade must not reach us.
 dependencies = [
     "click>=8.2.0",
+    # Usage backend + single source of truth for the unified provider schema
+    # (issue #1318). Pinned exactly: `pocketshell usage --json` expects quse
+    # 0.0.9's provider-keyed `--json` document (per provider: status +
+    # short_term/long_term {percent_remaining, reset_at, window} + error) and
+    # fails loudly on any schema drift, so the version is frozen, not a range.
+    "quse==0.0.9",
     # FCM HTTP v1 push delivery (#690): service-account OAuth2 bearer minting
     # for `pocketshell push` / the `usage --capture` reset-push send. Imported
     # lazily and fail-soft — a host without it (or without a Firebase

{pocketshell-0.4.24 → pocketshell-0.4.26}/src/pocketshell/cards.py

@@ -572,6 +572,29 @@ def _require_session(explicit: Optional[str]) -> str:
     return session
 
 
+def _notify_card_pushed_best_effort(
+    session: str, card: dict[str, Any], *, card_paths: CardPaths
+) -> None:
+    """Fire a best-effort FCM push for a freshly upserted card (#859 Slice D/2).
+
+    The single notification path shared by EVERY card-creating ``push`` verb
+    (``checklist``, ``note``, and any future card type). Centralising it here is
+    the durable class fix for #1446: a new ``push <cardtype>`` verb that upserts
+    a card just calls this one helper, so it can't silently forget to notify the
+    phone the way ``push note`` originally did.
+
+    Fail-soft — the push deps are imported lazily so a host without them still
+    pushes the card, and any failure is swallowed so a card write never wedges
+    the CLI. De-dup + configuration guards live in :func:`notify_card_pushed`.
+    """
+    try:
+        from pocketshell.agent_card_push import notify_card_pushed
+
+        notify_card_pushed(session, card, card_paths=card_paths)
+    except Exception:
+        pass
+
+
 def register_push_card_commands(push_group: click.Group) -> None:
     """Register the typed-card verbs onto the existing ``push`` click group.
 
@@ -635,14 +658,8 @@ def register_push_card_commands(push_group: click.Group) -> None:
         card_paths = resolve_paths()
         path = upsert_card(target, card, paths=card_paths)
         # Slice D (#859): fire a best-effort FCM push so the phone surfaces a
-        # heads-up notification opening this session's card feed. Fail-soft —
-        # imported lazily so a host without the push deps still pushes the card.
-        try:
-            from pocketshell.agent_card_push import notify_card_pushed
-
-            notify_card_pushed(target, card, card_paths=card_paths)
-        except Exception:
-            pass
+        # heads-up notification opening this session's card feed.
+        _notify_card_pushed_best_effort(target, card, card_paths=card_paths)
         click.echo(
             f"checklist {card_id!r} ({len(parsed)} items) -> session {target!r} ({path})"
         )
@@ -652,6 +669,8 @@ def register_push_card_commands(push_group: click.Group) -> None:
     @click.option("--session", "session", default=None, help="Override the auto-detected tmux session.")
     def push_get(as_json: bool, session: Optional[str]) -> None:
         """Return the session's cards (human/YAML by default, --json for the app)."""
+        # No notify (#1446 audit): read-only query, upserts no card. The app is
+        # the caller here; there is nothing new to surface.
         target = _require_session(session)
         cards = read_cards(target, paths=resolve_paths())
         if as_json:
@@ -677,6 +696,7 @@ def register_push_card_commands(push_group: click.Group) -> None:
     @click.option("--session", "session", default=None, help="Override the auto-detected tmux session.")
     def push_status(card_id: Optional[str], as_json: bool, session: Optional[str]) -> None:
         """Report interaction state — which checklist items the human has ticked."""
+        # No notify (#1446 audit): read-only query, upserts no card.
         target = _require_session(session)
         cards = read_cards(target, paths=resolve_paths())
         if card_id is not None:
@@ -712,6 +732,9 @@ def register_push_card_commands(push_group: click.Group) -> None:
     @click.option("--session", "session", default=None, help="Override the auto-detected tmux session.")
     def push_check(card_id: str, item_id: str, done: bool, session: Optional[str]) -> None:
         """Set a checklist item's checked state (this is what the app's tick calls)."""
+        # No notify (#1446 audit): this is the APP writing back the human's tick,
+        # not an agent pushing a new card. Notifying would push the phone about
+        # its own action (and could loop). It mutates state, never upserts a card.
         target = _require_session(session)
         try:
             card = apply_interaction(
@@ -771,7 +794,13 @@ def register_push_card_commands(push_group: click.Group) -> None:
             title=title,
             build_kwargs={"text": body_text},
         )
-        path = upsert_card(target, card, paths=resolve_paths())
+        card_paths = resolve_paths()
+        path = upsert_card(target, card, paths=card_paths)
+        # #1446: a pushed note is a card the human must see, just like a
+        # checklist — fire the same best-effort FCM push so the phone surfaces a
+        # heads-up notification opening this session's card feed. (Slice D/#859
+        # shipped this only on `checklist`; `push note` was silently omitted.)
+        _notify_card_pushed_best_effort(target, card, card_paths=card_paths)
         click.echo(f"note {card_id!r} -> session {target!r} ({path})")
 
     @push_group.command("read")
@@ -780,6 +809,8 @@ def register_push_card_commands(push_group: click.Group) -> None:
     @click.option("--session", "session", default=None, help="Override the auto-detected tmux session.")
     def push_read(card_id: str, read: bool, session: Optional[str]) -> None:
         """Set a note's read state (this is what the app's "mark read" calls)."""
+        # No notify (#1446 audit): this is the APP writing back "human read it",
+        # not an agent pushing a new card. Same rationale as `push check`.
         target = _require_session(session)
         try:
             card = apply_interaction(

{pocketshell-0.4.24 → pocketshell-0.4.26}/src/pocketshell/daemon.py

@@ -358,11 +358,11 @@ def _usage_fetch_handler(params: Mapping[str, Any]) -> dict[str, Any]:
        }
 
     Returning stdout in the envelope preserves the CLI/daemon contract.
-    The stdout is normalized by :mod:`pocketshell.usage` before it is cached,
-    because ``quse --json`` can expose provider quirks that are not the
-    PocketShell app-facing schema. ``quse --json`` emits **NDJSON** (one
-    provider per line, not a single document), so normalization keeps that
-    line-oriented wire format.
+    ``quse --json`` emits a **provider-keyed JSON object**; the daemon
+    FLATTENS it into per-provider NDJSON via
+    :func:`pocketshell.usage.normalize_usage_stdout` before caching, so the
+    cached envelope stdout is already the app-facing NDJSON wire format (the
+    CLI proxies it verbatim, without re-flattening).
     """
     # Lazy import to avoid a circular module load at startup: the
     # daemon module is imported from ``cli.py`` which also imports
@@ -378,17 +378,13 @@ def _usage_fetch_handler(params: Mapping[str, Any]) -> dict[str, Any]:
 
     quse_path = _usage._resolve_quse_binary()
     if quse_path is None:
-        # Mirror the CLI's exit-127 behaviour. The daemon does NOT
-        # cache this; a `quse` install during the daemon's lifetime
-        # should be picked up on the next call.
+        # quse is bundled WITH pocketshell (issue #1318): a missing pinned
+        # copy is a packaging-integrity error, not a "install quse" nag. The
+        # daemon does NOT cache this failure.
         return {
             "stdout": "",
-            "stderr": (
-                "pocketshell: `quse` is not installed on this host. "
-                "Install it via `uv tool install quse` or `pipx install quse` "
-                "and re-run.\n"
-            ),
-            "returncode": 127,
+            "stderr": _usage._QUSE_MISSING_MESSAGE + "\n",
+            "returncode": _usage._QUSE_MISSING_EXIT_CODE,
             "provider": provider,
         }
 
@@ -402,8 +398,16 @@ def _usage_fetch_handler(params: Mapping[str, Any]) -> dict[str, Any]:
         capture_output=True,
         text=True,
     )
+    # Only a successful (exit 0) quse run is flattened into per-provider
+    # NDJSON. A failed fetch is proxied raw (it is not a valid provider-keyed
+    # document, and the daemon does not cache failures anyway).
+    stdout = (
+        _usage.normalize_usage_stdout(completed.stdout)
+        if completed.returncode == 0
+        else completed.stdout
+    )
     return {
-        "stdout": _usage.normalize_usage_stdout(completed.stdout),
+        "stdout": stdout,
         "stderr": completed.stderr,
         "returncode": completed.returncode,
         "provider": provider,

{pocketshell-0.4.24 → pocketshell-0.4.26}/src/pocketshell/hooks.py

@@ -195,6 +195,7 @@ stop and never injects a follow-up (integration only; see D26).
 """
 import json
 import os
+import subprocess
 import sys
 from datetime import datetime, timezone
 
@@ -202,6 +203,32 @@ HERE = os.path.dirname(os.path.abspath(__file__))
 EVENTS_FILE = os.path.join(HERE, "events.jsonl")
 
 
+def record_tmux_agent_state(state):
+    if "TMUX" not in os.environ:
+        return
+    option_value = {
+        "FINISHED": "idle",
+        "WAITING_FOR_INPUT": "waiting_for_input",
+    }.get(state)
+    if option_value is None:
+        return
+    try:
+        subprocess.run(
+            ["tmux", "set-option", "@ps_agent_state", option_value],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=False,
+        )
+        subprocess.run(
+            ["tmux", "set-option", "@ps_agent_state_updated_at", datetime.now(timezone.utc).isoformat()],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        pass
+
+
 def main():
     raw = sys.stdin.read()
     try:
@@ -232,6 +259,7 @@ def main():
     os.makedirs(os.path.dirname(EVENTS_FILE), exist_ok=True)
     with open(EVENTS_FILE, "a") as handle:
         handle.write(json.dumps(record) + "\\n")
+    record_tmux_agent_state(state)
     # Exit clean with no stdout so Claude proceeds with the stop.
     sys.exit(0)
 
@@ -252,6 +280,7 @@ event bus next to this script.
 """
 import json
 import os
+import subprocess
 import sys
 from datetime import datetime, timezone
 
@@ -259,6 +288,32 @@ HERE = os.path.dirname(os.path.abspath(__file__))
 EVENTS_FILE = os.path.join(HERE, "events.jsonl")
 
 
+def record_tmux_agent_state(state):
+    if "TMUX" not in os.environ:
+        return
+    option_value = {
+        "FINISHED": "idle",
+        "WAITING_FOR_INPUT": "waiting_for_input",
+    }.get(state)
+    if option_value is None:
+        return
+    try:
+        subprocess.run(
+            ["tmux", "set-option", "@ps_agent_state", option_value],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=False,
+        )
+        subprocess.run(
+            ["tmux", "set-option", "@ps_agent_state_updated_at", datetime.now(timezone.utc).isoformat()],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        pass
+
+
 def main():
     raw = sys.argv[1] if len(sys.argv) > 1 else "{}"
     try:
@@ -283,6 +338,7 @@ def main():
     os.makedirs(os.path.dirname(EVENTS_FILE), exist_ok=True)
     with open(EVENTS_FILE, "a") as handle:
         handle.write(json.dumps(record) + "\\n")
+    record_tmux_agent_state(state)
     sys.exit(0)
 
 
@@ -300,6 +356,7 @@ _OPENCODE_PLUGIN_SOURCE = '''\
 // (WAITING_FOR_INPUT), or errors (ERROR). Integration only — no
 // continue/stop decision (see D26).
 import fs from "node:fs";
+import child_process from "node:child_process";
 import os from "node:os";
 import path from "node:path";
 
@@ -311,6 +368,27 @@ function busPath() {
   return path.join(dir, "events.jsonl");
 }
 
+function recordTmuxAgentState(state) {
+  if (!process.env.TMUX) return;
+  const value = {
+    FINISHED: "idle",
+    WAITING_FOR_INPUT: "waiting_for_input",
+  }[state];
+  if (!value) return;
+  try {
+    child_process.spawnSync("tmux", ["set-option", "@ps_agent_state", value], {
+      stdio: "ignore",
+    });
+    child_process.spawnSync(
+      "tmux",
+      ["set-option", "@ps_agent_state_updated_at", new Date().toISOString()],
+      { stdio: "ignore" },
+    );
+  } catch (e) {
+    // best-effort; never throw out of a plugin hook
+  }
+}
+
 export const PocketShellIdleSignal = async () => {
   const EVENTS_FILE = busPath();
   function emit(state, event) {
@@ -325,6 +403,7 @@ export const PocketShellIdleSignal = async () => {
     try {
       fs.mkdirSync(path.dirname(EVENTS_FILE), { recursive: true });
       fs.appendFileSync(EVENTS_FILE, JSON.stringify(rec) + "\\n");
+      recordTmuxAgentState(state);
     } catch (e) {
       // best-effort; never throw out of a plugin hook
     }