pocketshell 0.4.14__tar.gz → 0.4.18__tar.gz

{pocketshell-0.4.14 → pocketshell-0.4.18}/PKG-INFO

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

pocketshell-0.4.18/src/pocketshell/agent_card_push.py

@@ -0,0 +1,263 @@
+"""Server-side FCM push when an agent posts a typed card (epic #859, Slice D).
+
+This is the card sibling of :mod:`pocketshell.push` (which owns the usage-reset
+FCM path, #690). When a running agent calls ``pocketshell push checklist`` the
+host writes/updates a per-session card (:mod:`pocketshell.cards`); this module
+fires a best-effort FCM **data** push so the phone surfaces a heads-up
+notification that opens the session's card feed.
+
+Why a separate module (not inside :mod:`pocketshell.cards`)
+----------------------------------------------------------
+
+The card store and the FCM device token live in **two different state homes**
+(the #859 research spike's risk #1): cards under ``~/.pocketshell/cards/`` and
+the registered device token under the usage state dir
+(``$XDG_STATE_HOME/pocketshell/usage/push-token.json``). Rather than have
+:mod:`pocketshell.cards` import the token storage directly, the bridge lives
+here: it reads the token via :func:`pocketshell.push.read_token` and sends via
+:class:`pocketshell.push.FcmSender` — the exact same sender/credential the
+usage-reset path uses. Adding a second card type later (``note``) reuses this
+verbatim.
+
+Hard-cut (D22): the app receive path adds a NEW ``type=agent_card`` payload
+sibling to ``usage_reset`` — this module never emits ``usage_reset``.
+
+Fail-soft (matches :func:`pocketshell.push.push_reset_events`): no registered
+token, no service-account credential, or no :mod:`google.auth` installed → the
+trigger no-ops and returns ``None`` WITHOUT raising. ``pocketshell push
+checklist`` must never break because Firebase isn't set up.
+
+De-dup
+------
+
+A successful send records a deterministic **content key** under the cards dir
+(``push-sent.jsonl``) so re-pushing the *same* card (an agent re-runs the same
+``push checklist``) does not re-POST, while an *updated* card (different items /
+title) produces a new key and DOES push. The app's ``PushDedupStore`` is a
+second line of defence on the device; this is the server-side primary guard.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import socket
+from pathlib import Path
+from typing import Any, Optional
+
+from pocketshell import push as push_mod
+from pocketshell.cards import CardPaths
+from pocketshell.usage_capture import _append_history, resolve_paths as resolve_usage_paths
+
+# The app contract: an agent-card push is a `type=agent_card` FCM data message.
+AGENT_CARD_PUSH_TYPE = "agent_card"
+
+# Per-session content-key log so a re-push of an unchanged card never re-POSTs.
+# Lives under the cards dir (NOT the usage dir) — co-located with the cards it
+# de-dups. One small file is plenty: cards are rare and bounded.
+SENT_LOG_FILENAME = "push-sent.jsonl"
+DEFAULT_SENT_LOG_MAX_LINES = 1000
+
+
+def sent_log_file(paths: CardPaths) -> Path:
+    """Return the per-content-key already-pushed log path for ``paths``."""
+    return paths.cards_dir / SENT_LOG_FILENAME
+
+
+def sent_card_keys(paths: CardPaths) -> set[str]:
+    """Return the set of card content keys already successfully pushed."""
+    path = sent_log_file(paths)
+    if not path.exists():
+        return set()
+    keys: set[str] = set()
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return set()
+    for line in text.splitlines():
+        if not line.strip():
+            continue
+        try:
+            parsed = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(parsed, dict):
+            key = parsed.get("card_key")
+            if isinstance(key, str) and key:
+                keys.add(key)
+    return keys
+
+
+def _mark_sent(
+    card_key: str,
+    *,
+    paths: CardPaths,
+    sent_log_max_lines: int = DEFAULT_SENT_LOG_MAX_LINES,
+) -> None:
+    """Record ``card_key`` as successfully pushed so it never re-POSTs."""
+    _append_history(
+        sent_log_file(paths),
+        {"card_key": card_key},
+        history_max_lines=sent_log_max_lines,
+    )
+
+
+def _summarise(card: dict[str, Any]) -> str:
+    """One-line human summary of a card via its registered type, fail-soft.
+
+    Reuses the same per-type ``summarise`` the CLI's ``push status`` uses so the
+    notification body matches what the agent sees. Falls back to a generic line
+    for an unknown type (forward-compatible).
+    """
+    from pocketshell.cards import get_card_type
+
+    card_type = card.get("type", "")
+    handler = get_card_type(card_type) if isinstance(card_type, str) else None
+    body = card.get("body", {})
+    state = card.get("state", {})
+    if handler is not None and isinstance(body, dict) and isinstance(state, dict):
+        try:
+            return handler.summarise(dict(body), dict(state))
+        except Exception:
+            pass
+    return f"{card_type or 'card'} updated"
+
+
+def _host_alias() -> str:
+    """Best-effort host identifier for the deep-link, never raising.
+
+    The host CLI does NOT know the app's host alias (the #859 research spike's
+    risk #2). The most reliable thing it can emit is its own resolvable
+    hostname, which the app matches against ``HostEntity.hostname`` /
+    ``HostEntity.name`` to route the tap to the right host's session feed. When
+    the match is ambiguous or absent the app falls back to its home screen — it
+    never opens the WRONG host.
+    """
+    try:
+        fqdn = socket.getfqdn().strip()
+        if fqdn and fqdn.lower() != "localhost":
+            return fqdn
+    except Exception:
+        pass
+    try:
+        return socket.gethostname().strip()
+    except Exception:
+        return ""
+
+
+def card_to_data(
+    session: str,
+    card: dict[str, Any],
+    *,
+    host: Optional[str] = None,
+) -> dict[str, str]:
+    """Map a card + its session to the app's ``agent_card`` data-message keys.
+
+    Keys (mirrors the app's ``AgentCardPushPayload`` contract):
+
+    - ``type`` = ``agent_card``
+    - ``session`` = the tmux session the card belongs to (deep-link target)
+    - ``host`` = best-effort host hostname for host resolution (may be empty)
+    - ``card_id`` = the card id
+    - ``card_type`` = e.g. ``checklist``
+    - ``title`` = the card title (falls back to a type-derived label)
+    - ``summary`` = the per-type one-line summary (e.g. ``checklist 1/3 checked``)
+    - ``card_key`` = the content-hash de-dup identity (also the app dedup key)
+    """
+    card_type = str(card.get("type", "") or "")
+    card_id = str(card.get("id", "") or "")
+    title = card.get("title")
+    title_str = title.strip() if isinstance(title, str) and title.strip() else _default_title(card_type)
+    summary = _summarise(card)
+    resolved_host = host if host is not None else _host_alias()
+    card_key = content_key(session, card)
+    return {
+        "type": AGENT_CARD_PUSH_TYPE,
+        "session": session,
+        "host": resolved_host or "",
+        "card_id": card_id,
+        "card_type": card_type,
+        "title": title_str,
+        "summary": summary,
+        "card_key": card_key,
+    }
+
+
+def _default_title(card_type: str) -> str:
+    if card_type == "checklist":
+        return "Checklist"
+    if card_type:
+        return card_type[:1].upper() + card_type[1:]
+    return "Card"
+
+
+def content_key(session: str, card: dict[str, Any]) -> str:
+    """Deterministic content key for a card (drives server-side de-dup).
+
+    Hashes the session + card id + type + title + body + state — NOT
+    ``updated_at`` (which changes on every push) — so an identical re-push
+    yields the SAME key (suppressed) while any content/state change yields a NEW
+    key (pushed). Stable across processes (``sort_keys``).
+    """
+    payload = {
+        "session": session,
+        "id": card.get("id"),
+        "type": card.get("type"),
+        "title": card.get("title"),
+        "body": card.get("body"),
+        "state": card.get("state"),
+    }
+    blob = json.dumps(payload, sort_keys=True, ensure_ascii=False)
+    digest = hashlib.sha256(blob.encode("utf-8")).hexdigest()[:16]
+    return f"{session}|{card.get('id')}|{digest}"
+
+
+def notify_card_pushed(
+    session: str,
+    card: dict[str, Any],
+    *,
+    card_paths: CardPaths,
+    host: Optional[str] = None,
+    sender: Optional["push_mod.FcmSender"] = None,
+    env: Optional[dict[str, str]] = None,
+    sent_log_max_lines: int = DEFAULT_SENT_LOG_MAX_LINES,
+) -> Optional[str]:
+    """Best-effort FCM push for a freshly upserted ``card``. Fail-soft.
+
+    Returns the ``card_key`` actually pushed this call, or ``None`` when push
+    isn't configured / nothing new was sent. NEVER raises — the ``push
+    checklist`` CLI call must succeed even when Firebase isn't set up.
+
+    Guards, in order (mirroring :func:`pocketshell.push.push_reset_events`):
+
+    1. No registered device token -> ``None``.
+    2. No service-account credential / no ``google.auth`` -> ``None`` (pre-S0).
+    3. Already pushed this exact content (de-dup) -> ``None``.
+    4. On a successful send: record the content key so it never re-POSTs.
+       On a failed send: leave it un-recorded so the next push RETRIES.
+    """
+    try:
+        usage_paths = resolve_usage_paths(env=env)
+        token = push_mod.read_token(usage_paths)
+        if token is None:
+            return None
+
+        if sender is None:
+            sa_path = push_mod._resolve_service_account_path(usage_paths, env=env)
+            if sa_path is None:
+                return None
+            sender = push_mod.FcmSender.from_service_account(sa_path)
+            if sender is None:
+                return None
+
+        data = card_to_data(session, card, host=host)
+        card_key = data["card_key"]
+        if card_key in sent_card_keys(card_paths):
+            return None
+        if sender.send_data_message(token=token, data=data):
+            _mark_sent(card_key, paths=card_paths, sent_log_max_lines=sent_log_max_lines)
+            return card_key
+        return None
+    except Exception:
+        # Absolute fail-soft backstop: a card push must never wedge the CLI.
+        return None

{pocketshell-0.4.14 → pocketshell-0.4.18}/src/pocketshell/cards.py

@@ -360,6 +360,62 @@ register_card_type(
 )
 
 
+# ---------------------------------------------------------------------------
+# note card type (#859 Slice B — proves the registry is genuinely generic)
+# ---------------------------------------------------------------------------
+#
+# A ``note`` is a non-interactive message the agent hands the human ("deploy
+# finished", "found a flaky test"). Its only interaction is mark-as-read, so the
+# agent can tell from ``push status`` whether the human has seen it. Registering
+# it is exactly one ``register_card_type`` call + a ``push note`` verb — no new
+# transport, no change to the store/read/write/upsert path. That is the whole
+# point of the registry: a second real type is additive.
+
+# Default note card id used when ``--id`` is omitted (one default note per
+# session unless the agent names them — mirrors DEFAULT_CHECKLIST_ID).
+DEFAULT_NOTE_ID = "note"
+
+
+def _note_build_body(*, text: str, **_: Any) -> dict[str, Any]:
+    """Build the note ``body`` — ``{"text": <message>}``."""
+    return {"text": text}
+
+
+def _note_initial_state(_body: dict[str, Any]) -> dict[str, Any]:
+    """A fresh note is unread."""
+    return {"read": False, "read_at": None}
+
+
+def _note_apply_interaction(
+    body: dict[str, Any],
+    state: dict[str, Any],
+    interaction: Mapping[str, Any],
+) -> dict[str, Any]:
+    """Mark a note read/unread.
+
+    ``interaction = {"read": bool}``. ``read`` defaults to True (mark read).
+    ``read_at`` records when it was first read (cleared on unread) so the agent
+    can see acknowledgement timing via ``push status``.
+    """
+    read = bool(interaction.get("read", True))
+    return {"read": read, "read_at": _now_iso() if read else None}
+
+
+def _note_summarise(body: dict[str, Any], state: dict[str, Any]) -> str:
+    return "note: read" if state.get("read") else "note: unread"
+
+
+register_card_type(
+    CardType(
+        name="note",
+        build_body=_note_build_body,
+        initial_state=_note_initial_state,
+        apply_interaction=_note_apply_interaction,
+        summarise=_note_summarise,
+    )
+)
+
+
 # ---------------------------------------------------------------------------
 # Store read/write
 # ---------------------------------------------------------------------------
@@ -576,7 +632,17 @@ def register_push_card_commands(push_group: click.Group) -> None:
             build_kwargs={"items": parsed},
             preset_checked=preset_checked,
         )
-        path = upsert_card(target, card, paths=resolve_paths())
+        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
         click.echo(
             f"checklist {card_id!r} ({len(parsed)} items) -> session {target!r} ({path})"
         )
@@ -661,3 +727,71 @@ def register_push_card_commands(push_group: click.Group) -> None:
         state = card.get("state", {}) if isinstance(card.get("state"), Mapping) else {}
         summary = handler.summarise(dict(body), dict(state)) if handler else ""
         click.echo(f"{card_id}: {summary}")
+
+    @push_group.command("note")
+    @click.option("--title", "title", default=None, help="Human title for the note card.")
+    @click.option(
+        "--id",
+        "card_id",
+        default=DEFAULT_NOTE_ID,
+        help=f"Card id (default {DEFAULT_NOTE_ID!r}; one default note per session).",
+    )
+    @click.option(
+        "--text",
+        "text",
+        default=None,
+        help="The note body. Alternative to piping the message on stdin.",
+    )
+    @click.option("--session", "session", default=None, help="Override the auto-detected tmux session.")
+    def push_note(
+        title: Optional[str],
+        card_id: str,
+        text: Optional[str],
+        session: Optional[str],
+    ) -> None:
+        """Create/replace the session's note card from --text or piped stdin.
+
+        A note is a non-interactive message the human marks read (``push read``).
+        The session is auto-detected from ``$TMUX`` (override with ``--session``).
+        A re-push fully replaces the card of that id (hard-cut, D22).
+        """
+        target = _require_session(session)
+        if text is not None and text.strip():
+            body_text = text.strip()
+        else:
+            stdin_text = "" if sys.stdin is None or sys.stdin.isatty() else sys.stdin.read()
+            body_text = stdin_text.strip()
+        if not body_text:
+            raise click.ClickException(
+                "empty note: pass --text or pipe the message on stdin."
+            )
+        card = build_card(
+            card_type="note",
+            card_id=card_id,
+            title=title,
+            build_kwargs={"text": body_text},
+        )
+        path = upsert_card(target, card, paths=resolve_paths())
+        click.echo(f"note {card_id!r} -> session {target!r} ({path})")
+
+    @push_group.command("read")
+    @click.option("--id", "card_id", required=True, help="The note card id.")
+    @click.option("--read/--unread", "read", default=True, help="Mark read (default) or unread.")
+    @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)."""
+        target = _require_session(session)
+        try:
+            card = apply_interaction(
+                target,
+                card_id,
+                {"read": read},
+                paths=resolve_paths(),
+            )
+        except ValueError as exc:
+            raise click.ClickException(str(exc))
+        handler = get_card_type(card.get("type", ""))
+        body = card.get("body", {}) if isinstance(card.get("body"), Mapping) else {}
+        state = card.get("state", {}) if isinstance(card.get("state"), Mapping) else {}
+        summary = handler.summarise(dict(body), dict(state)) if handler else ""
+        click.echo(f"{card_id}: {summary}")