pocketshell 0.4.13__tar.gz → 0.4.17__tar.gz

{pocketshell-0.4.13 → pocketshell-0.4.17}/PKG-INFO

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

{pocketshell-0.4.13 → pocketshell-0.4.17}/src/pocketshell/agents.py

@@ -379,8 +379,13 @@ def record_agent_kind(
     profile name is known here, before ``os.execvpe``; #826 record-at-start
     hard-cut — no detection/parse path). When set, it is written as the
     per-session ``@ps_agent_profile`` user option alongside ``@ps_agent_kind``.
-    A default / no-profile launch passes ``None`` and writes NO profile
-    option, so a default session carries no spurious profile label.
+    A default / no-profile launch passes ``None`` and the option is
+    RECONCILED to the current launch by UNSETTING it
+    (``tmux set-option -uq @ps_agent_profile``), so a session previously
+    launched with a non-default profile and then relaunched as a default
+    agent in the SAME tmux session does not keep the stale profile label
+    (issue #889). ``@ps_agent_kind`` is always overwritten on every launch
+    so it has no equivalent stale hazard.
 
     The options are session-scoped (not global): ``tmux set-option`` without
     ``-g`` sets it on the current session, which is the session the agent
@@ -411,12 +416,26 @@ def record_agent_kind(
             check=False,
         )
         if profile:
-            # Only a non-default profile is recorded; a default/no-profile
-            # launch writes no option so the tree shows the plain kind.
+            # A non-default profile is recorded so the tree shows its label.
             runner(
                 ["tmux", "set-option", "@ps_agent_profile", profile],
                 check=False,
             )
+        else:
+            # A default / no-profile launch must RECONCILE the option to the
+            # current launch by UNSETTING it (issue #889). tmux session
+            # options persist for the life of the session, so a session
+            # launched once with a non-default profile (e.g. z.ai) and then
+            # relaunched as a default agent in the SAME session would keep the
+            # stale @ps_agent_profile and be mislabelled in the tree. The
+            # ``-u`` unsets the session option; ``-q`` makes unsetting an
+            # already-absent option a no-op (a fresh default session stays
+            # clean). The kind itself (set above) is always overwritten, so it
+            # has no equivalent stale hazard.
+            runner(
+                ["tmux", "set-option", "-uq", "@ps_agent_profile"],
+                check=False,
+            )
     except Exception:
         # Recording the kind is best-effort; never block the launch on it.
         return False
@@ -522,7 +541,8 @@ def _resolve_config_dir(
     tree can tell a z.ai Claude apart from a default Claude. The engine's
     default profile, ``--config-dir`` (which carries no named profile), and
     omitting both flags all resolve ``profile_label`` to ``None`` — so a
-    default session records no ``@ps_agent_profile`` option.
+    default launch clears any stale ``@ps_agent_profile`` option (issue
+    #889) rather than leaving a profile label behind.
     """
     if config_dir is not None and profile is not None:
         click.echo(

{pocketshell-0.4.13 → pocketshell-0.4.17}/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
 # ---------------------------------------------------------------------------
@@ -661,3 +717,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}")

{pocketshell-0.4.13 → pocketshell-0.4.17}/tests/test_agents.py

@@ -470,11 +470,11 @@ def test_record_agent_kind_sets_session_option_inside_tmux(kind):
         runner=lambda argv, **kw: calls.append((argv, kw)),
     )
     assert ok is True
-    assert len(calls) == 1
-    argv, _kw = calls[0]
-    # Session-scoped (no -g): tmux applies it to the current session, which
-    # is the one the agent was launched into.
-    assert argv == ["tmux", "set-option", "@ps_agent_kind", kind]
+    # No profile passed -> the kind is set (session-scoped, no -g), and the
+    # @ps_agent_profile option is reconciled away by an unset (issue #889).
+    argvs = [argv for argv, _kw in calls]
+    assert ["tmux", "set-option", "@ps_agent_kind", kind] in argvs
+    assert ["tmux", "set-option", "-uq", "@ps_agent_profile"] in argvs
 
 
 def test_record_agent_kind_noop_when_not_in_tmux():
@@ -594,9 +594,12 @@ def test_record_agent_kind_writes_profile_option_when_profile_set():
     ]
 
 
-def test_record_agent_kind_no_profile_writes_only_kind():
-    # A default / no-profile launch records the kind but NO profile option,
-    # so a default session shows the plain kind with no spurious chip.
+def test_record_agent_kind_no_profile_clears_profile_option():
+    # A default / no-profile launch records the kind AND reconciles the
+    # @ps_agent_profile option by UNSETTING it (issue #889), so a session
+    # previously launched with a non-default profile cannot keep a stale
+    # label. ``-uq`` makes unsetting an already-absent option a no-op, so a
+    # fresh default session stays clean.
     calls = []
     ok = agents.record_agent_kind(
         "claude",
@@ -605,11 +608,15 @@ def test_record_agent_kind_no_profile_writes_only_kind():
         profile=None,
     )
     assert ok is True
-    assert calls == [["tmux", "set-option", "@ps_agent_kind", "claude"]]
+    assert calls == [
+        ["tmux", "set-option", "@ps_agent_kind", "claude"],
+        ["tmux", "set-option", "-uq", "@ps_agent_profile"],
+    ]
 
 
-def test_record_agent_kind_empty_profile_writes_only_kind():
-    # An empty-string profile is treated like no profile (no option written).
+def test_record_agent_kind_empty_profile_clears_profile_option():
+    # An empty-string profile is treated like no profile: kind recorded, the
+    # @ps_agent_profile option unset (issue #889).
     calls = []
     agents.record_agent_kind(
         "codex",
@@ -617,7 +624,45 @@ def test_record_agent_kind_empty_profile_writes_only_kind():
         runner=lambda argv, **kw: calls.append(argv),
         profile="",
     )
-    assert calls == [["tmux", "set-option", "@ps_agent_kind", "codex"]]
+    assert calls == [
+        ["tmux", "set-option", "@ps_agent_kind", "codex"],
+        ["tmux", "set-option", "-uq", "@ps_agent_profile"],
+    ]
+
+
+def test_record_agent_kind_default_relaunch_clears_stale_profile():
+    # REPRODUCE-FIRST (issue #889): the reported false-z.ai-label bug. A tmux
+    # session is launched once with the z.ai profile (sets @ps_agent_profile),
+    # then the agent is killed and RELAUNCHED as a regular default Claude in
+    # the SAME session. tmux session options persist, so without the #889 fix
+    # the stale "Claude (Z.AI)" lingers and the tree mislabels the session.
+    # The default relaunch must emit the unset that clears it.
+    #
+    # Launch 1: z.ai profile.
+    zai_calls = []
+    agents.record_agent_kind(
+        "claude",
+        env={"TMUX": "/tmp/tmux-1000/default,1234,0"},
+        runner=lambda argv, **kw: zai_calls.append(argv),
+        profile="Claude (Z.AI)",
+    )
+    assert ["tmux", "set-option", "@ps_agent_profile", "Claude (Z.AI)"] in zai_calls
+
+    # Launch 2: default relaunch in the same session. It MUST issue the unset
+    # so the previously-set @ps_agent_profile is reconciled away.
+    default_calls = []
+    agents.record_agent_kind(
+        "claude",
+        env={"TMUX": "/tmp/tmux-1000/default,1234,0"},
+        runner=lambda argv, **kw: default_calls.append(argv),
+        profile=None,
+    )
+    assert ["tmux", "set-option", "-uq", "@ps_agent_profile"] in default_calls
+    # And it must NOT re-set a profile value.
+    assert not any(
+        argv[:3] == ["tmux", "set-option", "@ps_agent_profile"]
+        for argv in default_calls
+    )
 
 
 def test_launch_agent_records_profile_before_exec(tmp_path, monkeypatch):
@@ -669,9 +714,10 @@ def test_cli_agent_named_profile_records_profile_option(tmp_path, monkeypatch):
     assert ["tmux", "set-option", "@ps_agent_profile", "Claude (Z.AI)"] in calls
 
 
-def test_cli_agent_default_profile_records_no_profile_option(tmp_path, monkeypatch):
-    """A default Claude profile records the kind but no profile option, so a
-    default session is the plain kind with no spurious label."""
+def test_cli_agent_default_profile_clears_profile_option(tmp_path, monkeypatch):
+    """A default Claude profile records the kind and reconciles the profile
+    option by UNSETTING it (issue #889), so a default launch never carries a
+    stale label and never sets a spurious one."""
     _seed_zlaude_home(tmp_path, monkeypatch)
     workdir = tmp_path / "work"
     workdir.mkdir()
@@ -684,13 +730,15 @@ def test_cli_agent_default_profile_records_no_profile_option(tmp_path, monkeypat
     )
     assert rc == 0
     assert ["tmux", "set-option", "@ps_agent_kind", "claude"] in calls
+    assert ["tmux", "set-option", "-uq", "@ps_agent_profile"] in calls
     assert not any(
         argv[:3] == ["tmux", "set-option", "@ps_agent_profile"] for argv in calls
     )
 
 
-def test_cli_agent_no_profile_records_no_profile_option(tmp_path, monkeypatch):
-    """A bare launch (no --profile/--config-dir) records the kind only."""
+def test_cli_agent_no_profile_clears_profile_option(tmp_path, monkeypatch):
+    """A bare launch (no --profile/--config-dir) records the kind and unsets
+    @ps_agent_profile (issue #889)."""
     workdir = tmp_path / "work"
     workdir.mkdir()
     monkeypatch.setenv("HOME", str(tmp_path))
@@ -701,11 +749,54 @@ def test_cli_agent_no_profile_records_no_profile_option(tmp_path, monkeypatch):
     rc = main(["agent", "codex", "--dir", str(workdir)])
     assert rc == 0
     assert ["tmux", "set-option", "@ps_agent_kind", "codex"] in calls
+    assert ["tmux", "set-option", "-uq", "@ps_agent_profile"] in calls
     assert not any(
         argv[:3] == ["tmux", "set-option", "@ps_agent_profile"] for argv in calls
     )
 
 
+def test_cli_agent_default_then_zai_relaunch_sets_profile(tmp_path, monkeypatch):
+    """Class coverage (issue #889): default-then-relaunched-z.ai. A default
+    launch in the session unsets the profile; relaunching the SAME session as
+    z.ai sets the correct label (the chip appears)."""
+    _seed_zlaude_home(tmp_path, monkeypatch)
+    workdir = tmp_path / "work"
+    workdir.mkdir()
+    monkeypatch.setenv("TMUX", "/tmp/tmux-1000/default,1234,0")
+    monkeypatch.setattr(agents.os, "execvpe", lambda f, a, e: None)
+
+    # Launch 1: default -> unset.
+    default_calls = []
+    monkeypatch.setattr(
+        agents.subprocess, "run", lambda argv, **kw: default_calls.append(argv)
+    )
+    assert main(["agent", "claude", "--dir", str(workdir), "--profile", "Claude"]) == 0
+    assert ["tmux", "set-option", "-uq", "@ps_agent_profile"] in default_calls
+
+    # Launch 2: z.ai relaunch in the same session -> sets the label.
+    zai_calls = []
+    monkeypatch.setattr(
+        agents.subprocess, "run", lambda argv, **kw: zai_calls.append(argv)
+    )
+    assert (
+        main(
+            [
+                "agent",
+                "claude",
+                "--dir",
+                str(workdir),
+                "--profile",
+                "Claude (Z.AI)",
+            ]
+        )
+        == 0
+    )
+    assert ["tmux", "set-option", "@ps_agent_profile", "Claude (Z.AI)"] in zai_calls
+    assert not any(
+        argv[:3] == ["tmux", "set-option", "-uq"] for argv in zai_calls
+    )
+
+
 def test_resolve_config_dir_default_profile_label_is_none(tmp_path, monkeypatch):
     """The default Claude profile resolves to a None profile label."""
     _seed_zlaude_home(tmp_path, monkeypatch)

{pocketshell-0.4.13 → pocketshell-0.4.17}/tests/test_cards.py

@@ -389,3 +389,139 @@ def test_cli_check_unknown_item_errors(tmp_path: Path) -> None:
     )
     assert res.exit_code != 0
     assert "unknown item" in res.output
+
+
+# ----- note card type (#859 Slice B — registry is genuinely generic) ----
+
+
+def test_note_card_type_is_registered() -> None:
+    """AC: the host registers a REAL `note` CardType (not just the stub test)."""
+    handler = cards_mod.get_card_type("note")
+    assert handler is not None
+    assert handler.name == "note"
+
+
+def test_build_upsert_read_note(tmp_path: Path) -> None:
+    """AC: note `body={text}`, `state={read:false, read_at:None}` round-trips."""
+    paths = _paths(tmp_path)
+    card = cards_mod.build_card(
+        card_type="note",
+        card_id="note",
+        title="Heads up",
+        build_kwargs={"text": "deploy finished"},
+    )
+    cards_mod.upsert_card("demo", card, paths=paths)
+    got = cards_mod.read_cards("demo", paths=paths)
+    assert len(got) == 1
+    assert got[0]["type"] == "note"
+    assert got[0]["title"] == "Heads up"
+    assert got[0]["body"] == {"text": "deploy finished"}
+    assert got[0]["state"] == {"read": False, "read_at": None}
+
+
+def test_note_apply_interaction_marks_read_and_unread(tmp_path: Path) -> None:
+    """AC: mark-as-read interaction sets read + read_at; unread clears read_at."""
+    paths = _paths(tmp_path)
+    card = cards_mod.build_card(
+        card_type="note", card_id="note", title=None,
+        build_kwargs={"text": "hi"},
+    )
+    cards_mod.upsert_card("demo", card, paths=paths)
+
+    read = cards_mod.apply_interaction("demo", "note", {"read": True}, paths=paths)
+    assert read["state"]["read"] is True
+    assert read["state"]["read_at"]  # a timestamp, not None
+
+    unread = cards_mod.apply_interaction("demo", "note", {"read": False}, paths=paths)
+    assert unread["state"]["read"] is False
+    assert unread["state"]["read_at"] is None
+
+
+def test_note_and_checklist_coexist_in_one_session(tmp_path: Path) -> None:
+    """The store is type-agnostic: a note + a checklist live side by side."""
+    paths = _paths(tmp_path)
+    checklist = cards_mod.build_card(
+        card_type="checklist", card_id="checklist", title="Deploy",
+        build_kwargs={"items": [{"id": "build-0", "text": "build"}]},
+    )
+    note = cards_mod.build_card(
+        card_type="note", card_id="note", title=None,
+        build_kwargs={"text": "fyi"},
+    )
+    cards_mod.upsert_card("demo", checklist, paths=paths)
+    cards_mod.upsert_card("demo", note, paths=paths)
+    got = cards_mod.read_cards("demo", paths=paths)
+    assert {c["type"] for c in got} == {"checklist", "note"}
+
+
+def test_cli_note_set_get_read_status_flow(tmp_path: Path) -> None:
+    """AC: push note (stdin) → get --json → read → status reflects read."""
+    runner = CliRunner()
+    env = _env(tmp_path)
+
+    res = runner.invoke(
+        cli,
+        ["push", "note", "--title", "Heads up", "--session", "demo"],
+        input="deploy finished\n",
+        env=env,
+    )
+    assert res.exit_code == 0, res.output
+    assert "note 'note'" in res.output
+
+    res = runner.invoke(cli, ["push", "get", "--json", "--session", "demo"], env=env)
+    assert res.exit_code == 0, res.output
+    payload = json.loads(res.output)
+    card = payload["cards"][0]
+    assert card["type"] == "note"
+    assert card["title"] == "Heads up"
+    assert card["body"]["text"] == "deploy finished"
+    assert card["state"]["read"] is False
+
+    # Human marks it read (this is what the app's "mark read" calls).
+    res = runner.invoke(
+        cli, ["push", "read", "--id", "note", "--session", "demo"], env=env
+    )
+    assert res.exit_code == 0, res.output
+    assert "note: read" in res.output
+
+    # Agent reads the acknowledgement via status.
+    res = runner.invoke(cli, ["push", "status", "--json", "--session", "demo"], env=env)
+    assert res.exit_code == 0, res.output
+    status = json.loads(res.output)
+    assert status["status"][0]["state"]["read"] is True
+
+    res = runner.invoke(cli, ["push", "status", "--session", "demo"], env=env)
+    assert res.exit_code == 0, res.output
+    assert "note: read" in res.output
+
+
+def test_cli_note_text_via_flag(tmp_path: Path) -> None:
+    runner = CliRunner()
+    env = _env(tmp_path)
+    res = runner.invoke(
+        cli, ["push", "note", "--text", "found a flaky test", "--session", "demo"],
+        env=env,
+    )
+    assert res.exit_code == 0, res.output
+    got = cards_mod.read_cards("demo", paths=_paths(tmp_path))
+    assert got[0]["body"]["text"] == "found a flaky test"
+
+
+def test_cli_note_empty_errors(tmp_path: Path) -> None:
+    runner = CliRunner()
+    env = _env(tmp_path)
+    res = runner.invoke(
+        cli, ["push", "note", "--session", "demo"], input="", env=env
+    )
+    assert res.exit_code != 0
+    assert "empty note" in res.output
+
+
+def test_cli_read_unknown_card_errors(tmp_path: Path) -> None:
+    runner = CliRunner()
+    env = _env(tmp_path)
+    res = runner.invoke(
+        cli, ["push", "read", "--id", "ghost", "--session", "demo"], env=env
+    )
+    assert res.exit_code != 0
+    assert "no card" in res.output

{pocketshell-0.4.13 → pocketshell-0.4.17}/uv.lock

@@ -3,7 +3,8 @@ revision = 3
 requires-python = ">=3.11"
 
 [options]
-exclude-newer = "2026-12-31T23:00:00Z"
+exclude-newer = "2026-06-18T14:08:51.166593044Z"
+exclude-newer-span = "P7D"
 
 [[package]]
 name = "annotated-doc"
@@ -314,7 +315,7 @@ wheels = [
 
 [[package]]
 name = "pocketshell"
-version = "0.4.13"
+version = "0.4.16"
 source = { editable = "." }
 dependencies = [
     { name = "click" },