code-puppy-core-plugins 0.0.58__tar.gz → 0.0.59__tar.gz

{code_puppy_core_plugins-0.0.58 → code_puppy_core_plugins-0.0.59}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: code-puppy-core-plugins
-Version: 0.0.58
+Version: 0.0.59
 Summary: Official plugin bundle for Code Puppy
 Project-URL: Repository, https://github.com/mpfaffenberger/code_puppy_core_plugins
 Project-URL: Homepage, https://github.com/mpfaffenberger/code_puppy_core_plugins

{code_puppy_core_plugins-0.0.58 → code_puppy_core_plugins-0.0.59}/code_puppy_core_plugins/herdr/README.md

@@ -92,8 +92,41 @@ durable autosave name and pickle path) via `pane.report_agent_session` --
 not the per-run `group_id`, which changes every turn. It re-reports only
 when the reference actually changes (after `/clear`, `/session new`,
 `/autosave_load`, `/load_context`, a quick resume, or an agent switch).
-This is a stable *reference*; automatic process restoration from it is
-**unverified** and not claimed here.
+
+## Auto-resume on launch
+
+A herdr server restart kills pane processes, and herdr only *restores*
+panes whose agent reported a native session reference through an **official**
+herdr integration. code-puppy is not one of those today, so herdr stores
+nothing for us -- verified against herdr 0.9.1: `pane.report_agent_session`
+is accepted, but `pane.get` exposes no `agent_session` for the `codepuppy`
+agent (the identical call for `codex` does).
+
+So the plugin is self-sufficient. Whenever it reports a session reference it
+also records a tiny **pane -> session map** (`herdr_pane_sessions.json`) under
+`XDG_STATE_HOME` -- never inside the plugin dir, which would self-tamper the
+trust hash. On startup inside a pane it resolves the previous session and
+loads it into the agent, exactly like `-r`:
+
+1. herdr's own stored reference via `pane.get` (forward-compatible: the day
+   herdr recognises codepuppy, or grows a custom-integration hook, this wins);
+2. else the local pane map.
+
+An explicit `-r` / `--quick-resume` always wins (the plugin captures the
+intent from the `handle_cli_args` hook), and headless `-p` runs never
+auto-resume. Set `HERDR_NO_AUTO_RESUME=1` for a deliberately fresh session
+in a reused pane. Everything is fail-soft: a missing socket, a vanished
+session file, or an unreadable map simply yields a fresh session.
+
+Net effect: restart herdr, start code-puppy in the restored pane, and your
+conversation is already back on screen.
+
+> This ships in the `code-puppy-core-plugins` bundle. Most people run code-puppy
+> through `uvx`, so nothing to install locally: the change reaches them on the
+> next PyPI release. Because `code-puppy` depends on the bundle by range
+> (`>=0.0.58`), a fresh resolve picks the new version up automatically -- but
+> `uvx` reuses a warm cache, so a user may need `uvx --refresh code-puppy`
+> (or `uvx -U code-puppy`) once.
 
 ## Conversation titles
 
@@ -199,6 +232,7 @@ state, metadata, and activity.
 | `client.py`             | herdr socket transport (JSON, worker thread)|
 | `reporter.py`           | event -> state machine (refcount + dedup)   |
 | `sources.py`            | fail-soft adapters (tokens / title / session / msg) |
+| `restore.py`            | pane -> session map + auto-resume on startup |
 | `register_callbacks.py` | callback wiring + env activation guard       |
 | `smoke.py`              | manual live smoke test (disposable pane + tab) |
 

{code_puppy_core_plugins-0.0.58 → code_puppy_core_plugins-0.0.59}/code_puppy_core_plugins/herdr/client.py

@@ -13,10 +13,11 @@ This module speaks herdr's newline-delimited JSON socket protocol far
 enough to call ``pane.report_agent`` / ``pane.report_agent_session`` /
 ``pane.report_metadata`` / ``pane.release_agent`` -- plus ``tab.get`` /
 ``tab.rename`` for the workspace-tab label (only while the tab holds a
-single pane). It reads herdr's ack (and retries a few times if it
-doesn't come) so an authoritative state edge is never silently lost, but
-it never raises into the caller: reporting agent state must never be
-able to disturb the agent itself.
+single pane), and ``pane.get`` to read back a stored native session
+reference (:meth:`HerdrClient.get_agent_session`). It reads herdr's ack
+(and retries a few times if it doesn't come) so an authoritative state
+edge is never silently lost, but it never raises into the caller:
+reporting agent state must never be able to disturb the agent itself.
 
 Delivery runs on a single daemon worker thread fed by **coalescing
 mailbox slots** rather than an unbounded queue:
@@ -78,6 +79,7 @@ _M_STATE = "pane.report_agent"
 _M_SESSION = "pane.report_agent_session"
 _M_METADATA = "pane.report_metadata"
 _M_RELEASE = "pane.release_agent"
+_M_PANE_GET = "pane.get"
 _M_TAB_GET = "tab.get"
 _M_TAB_RENAME = "tab.rename"
 
@@ -135,6 +137,10 @@ class HerdrClient:
     def active(self) -> bool:
         return self._active
 
+    @property
+    def pane_id(self) -> Optional[str]:
+        return self._pane_id
+
     def _start_worker(self) -> None:
         self._worker = threading.Thread(
             target=self._run,
@@ -172,6 +178,31 @@ class HerdrClient:
             params["message"] = message
         self._put("_state" if critical else "_message", params)
 
+    def get_agent_session(self) -> Optional[Dict[str, Any]]:
+        """Read herdr's stored native session reference for this pane.
+
+        Returns the ``agent_session`` object (``{"source", "agent", "kind",
+        "value"}``) when herdr has one stored for this pane, else ``None``.
+
+        This is the only *read* the plugin performs for restore. It is
+        bounded (one request/response on a fresh connection, 0.5s timeout)
+        and degrades to ``None`` on any failure -- a herdr version that does
+        not store a reference for us (code-puppy is not an *official* herdr
+        agent, so herdr 0.9.x stores nothing here) simply returns ``None``
+        and the caller falls back to its own store.
+        """
+        if not self._active:
+            return None
+        reply = self._request(_M_PANE_GET, {"pane_id": self._pane_id})
+        if not isinstance(reply, dict):
+            return None
+        result = reply.get("result")
+        pane = result.get("pane") if isinstance(result, dict) else None
+        if not isinstance(pane, dict):
+            return None
+        session = pane.get("agent_session")
+        return session if isinstance(session, dict) else None
+
     def report_session(
         self,
         agent_session_id: Optional[str] = None,

{code_puppy_core_plugins-0.0.58 → code_puppy_core_plugins-0.0.59}/code_puppy_core_plugins/herdr/register_callbacks.py

@@ -23,7 +23,8 @@ nothing for herdr to guess.
 
 Callback -> effect:
 
-* ``startup`` ......................................... resync (-> idle)
+* ``startup`` ......................................... resync (-> idle) + auto-resume
+* ``handle_cli_args`` ................................ capture -r / --quick-resume intent
 * ``session_end`` / ``shutdown`` ..................... release pane authority
 * ``user_prompt_submit`` ............................. refresh durable session
 * ``agent_run_start`` / ``agent_run_end`` ............ run-depth +/- 1
@@ -62,6 +63,7 @@ import signal
 
 from code_puppy.callbacks import register_callback
 
+from . import restore
 from .client import HerdrClient
 from .reporter import HerdrReporter
 
@@ -82,13 +84,58 @@ _TERMINATING_SIGNALS = tuple(
 _client = HerdrClient()
 _reporter = HerdrReporter(_client)
 
+#: Set from ``handle_cli_args`` so startup auto-resume yields to an explicit
+#: ``-r`` / ``--quick-resume``. The plugin cannot see the parsed args from the
+#: ``startup`` callback, and that hook fires *before* ``-r`` is applied -- so
+#: we capture the intent here rather than re-parsing ``sys.argv`` (DRY).
+_cli_resume_requested = False
+_cli_headless = False
+
 
 def _arg(args: tuple, index: int):
     return args[index] if len(args) > index else None
 
 
+def _on_handle_cli_args(args) -> None:
+    """Record whether the user asked for an explicit resume / headless run.
+
+    Runs after ``parse_args()`` and before ``startup``. Never handles the args
+    itself; returning ``None`` lets normal startup proceed.
+    """
+    global _cli_resume_requested, _cli_headless
+    try:
+        _cli_resume_requested = bool(getattr(args, "resume", None)) or (
+            getattr(args, "quick_resume", None) is not None
+        )
+        _cli_headless = bool(getattr(args, "prompt", None))
+    except Exception:
+        _cli_resume_requested = False
+        _cli_headless = False
+    return None
+
+
+def _maybe_auto_resume() -> None:
+    """Resume this pane's previous session unless the user asked otherwise.
+
+    Yields to an explicit ``-r`` / ``--quick-resume``, skips headless ``-p``
+    runs, and honours ``HERDR_NO_AUTO_RESUME=1`` as an escape hatch for
+    anyone who wants a deliberately fresh session in a reused pane.
+    """
+    if _cli_resume_requested or _cli_headless:
+        return
+    if os.environ.get("HERDR_NO_AUTO_RESUME", "").strip().lower() in {
+        "1",
+        "true",
+        "yes",
+        "on",
+    }:
+        return
+    restore.resume_session(_client)
+
+
 def _on_startup(*_args, **_kw) -> None:
     _reporter.on_startup()
+    _maybe_auto_resume()
 
 
 def _on_user_prompt(*_args, **_kw) -> None:
@@ -209,6 +256,7 @@ def _install_exit_guards() -> None:
 
 
 if _reporter.active:
+    register_callback("handle_cli_args", _on_handle_cli_args)
     register_callback("startup", _on_startup)
     register_callback("user_prompt_submit", _on_user_prompt)
     register_callback("agent_run_start", _on_run_start)

{code_puppy_core_plugins-0.0.58 → code_puppy_core_plugins-0.0.59}/code_puppy_core_plugins/herdr/reporter.py

@@ -41,8 +41,9 @@ import threading
 import time
 from typing import Optional, Tuple
 
-from .client import HerdrClient
+from . import restore
 from . import sources
+from .client import HerdrClient
 
 logger = logging.getLogger(__name__)
 
@@ -149,6 +150,10 @@ class HerdrReporter:
             self._session_ref = ref
         if changed:
             self._client.report_session(ref[0], ref[1])
+            # Keep a local pane -> session map so a restored pane can resume
+            # this conversation even though herdr itself stores no reference
+            # for a non-official agent. See restore.py.
+            restore.remember_session(self._client.pane_id, ref[0], ref[1])
 
     # -- lifecycle handlers (all sync; safe from async or worker threads) --
 

code_puppy_core_plugins-0.0.59/code_puppy_core_plugins/herdr/restore.py

@@ -0,0 +1,284 @@
+"""Resume the previous code-puppy session when re-entering a herdr pane.
+
+herdr can resume *official* agent panes after a server restart by reading the
+native session reference an integration reported -- but code-puppy is not an
+official herdr integration today, so herdr stores nothing for us. (Verified
+against herdr 0.9.1: ``pane.report_agent_session`` is accepted, but
+``pane.get`` exposes no ``agent_session`` for the ``codepuppy`` agent, while
+the same call for ``codex`` does.) This module makes code-puppy
+self-sufficient:
+
+* it keeps a tiny local **pane -> session map** under ``XDG_STATE_HOME``,
+  written whenever we report a session reference, so a restored pane can find
+  the conversation it was last running;
+* on startup inside a herdr pane it resolves the previous session -- first
+  from herdr's own stored reference (forward-compatible with a future herdr
+  that recognises codepuppy), then from the local map -- and loads it into the
+  current agent, exactly like ``-r`` does.
+
+State deliberately lives under ``XDG_STATE_HOME`` and never inside the plugin
+directory: runtime state next to plugin code would self-tamper the plugin's
+trust hash and demand re-acceptance on every boot.
+
+Everything here is fail-soft. Restoring a session is a convenience; a broken
+socket, a missing file, or an unreadable store must never block startup.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Callable, Optional, Tuple
+
+from .client import HerdrClient
+
+try:  # pragma: no cover - POSIX only
+    import fcntl
+except ImportError:  # pragma: no cover - Windows
+    fcntl = None
+
+logger = logging.getLogger(__name__)
+
+_STATE_FILENAME = "herdr_pane_sessions.json"
+
+#: ``(session_name, session_dir)`` -- the durable autosave name plus the
+#: directory its ``.json``/``.pkl`` file lives in.
+SessionRef = Tuple[str, str]
+
+
+def _state_path() -> Optional[Path]:
+    """The pane->session store path, or ``None`` when the dir is unavailable."""
+    try:
+        from code_puppy.config import STATE_DIR
+
+        return Path(STATE_DIR) / _STATE_FILENAME
+    except Exception:
+        logger.debug("herdr: state dir unavailable", exc_info=True)
+        return None
+
+
+def _read_store() -> dict:
+    """Read the pane->session map. ``{}`` on any failure (never raises)."""
+    path = _state_path()
+    if path is None:
+        return {}
+    try:
+        with path.open(encoding="utf-8") as file:
+            data = json.load(file)
+        return data if isinstance(data, dict) else {}
+    except FileNotFoundError:
+        return {}
+    except Exception:
+        logger.debug("herdr: pane-session store unreadable", exc_info=True)
+        return {}
+
+
+def _write_store(store: dict) -> None:
+    """Atomically write the map through a writer-private temp file.
+
+    Never raises: fail-soft is this module's contract, and both callers treat a
+    failed write as "we simply do not auto-resume next boot".
+
+    The temp name is scoped by PID on purpose. A shared ``.tmp`` name lets two
+    code-puppy processes interleave writes into the same file before either
+    renames it, which silently drops *other* panes' entries -- and herdr's
+    whole point is running many panes at once.
+    """
+    path = _state_path()
+    if path is None:
+        return
+    tmp: Optional[Path] = None
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_name(f"{path.name}.{os.getpid()}.tmp")
+        with tmp.open("w", encoding="utf-8") as file:
+            json.dump(store, file)
+        tmp.replace(path)
+    except Exception:
+        logger.debug("herdr: could not write pane-session store", exc_info=True)
+        if tmp is not None:
+            try:
+                tmp.unlink(missing_ok=True)
+            except Exception:
+                logger.debug("herdr: could not clean temp store", exc_info=True)
+
+
+def _locked_update(mutate: Callable[[dict], None]) -> None:
+    """Run a read-modify-write of the store under an exclusive lock.
+
+    The store is shared by every code-puppy process on the box, so concurrent
+    writers are the *normal* case here. Without the lock a stale reader
+    clobbers a newer writer's entry, and that pane silently loses its
+    auto-resume -- the exact feature this module exists to provide. The lock
+    lives in a sibling ``.lock`` file so ``replace()`` never swaps it out from
+    under us. ``fcntl`` is POSIX-only; elsewhere we degrade to best effort
+    rather than crash. Never raises.
+    """
+    path = _state_path()
+    if path is None:
+        return
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.with_name(path.name + ".lock").open("a+") as lock_file:
+            if fcntl is not None:
+                fcntl.flock(lock_file, fcntl.LOCK_EX)
+            try:
+                store = _read_store()
+                mutate(store)
+                _write_store(store)
+            finally:
+                if fcntl is not None:
+                    fcntl.flock(lock_file, fcntl.LOCK_UN)
+    except Exception:
+        logger.debug("herdr: could not update pane-session map", exc_info=True)
+
+
+def remember_session(
+    pane_id: Optional[str], session_name: str, session_path: str
+) -> None:
+    """Record ``pane_id -> (session_name, session_path)``.
+
+    Called from the reporter every time it reports a session reference, so the
+    map always reflects the pane's *current* session (a new session after
+    ``/clear`` or ``/resume`` overwrites the stale entry). Any failure is
+    swallowed -- a missing map only costs us one auto-resume.
+    """
+    if not pane_id or not session_name:
+        return
+
+    def _mutate(store: dict) -> None:
+        store[pane_id] = {
+            "session_name": session_name,
+            "session_path": str(session_path or ""),
+        }
+
+    _locked_update(_mutate)
+
+
+def forget_session(pane_id: Optional[str]) -> None:
+    """Drop ``pane_id``'s entry (used when its session is gone). Fail-soft."""
+    if not pane_id:
+        return
+
+    def _mutate(store: dict) -> None:
+        store.pop(pane_id, None)
+
+    _locked_update(_mutate)
+
+
+def _from_herdr(client: HerdrClient) -> Optional[SessionRef]:
+    """herdr's own stored reference, if it has one for this pane.
+
+    Forward-compatible: on a herdr that recognises codepuppy (or grows a
+    custom-integration hook) this is the authoritative source. ``kind`` tells
+    us whether ``value`` is a bare session id or a file path.
+    """
+    info = client.get_agent_session()
+    if not info:
+        return None
+    value = info.get("value")
+    if not isinstance(value, str) or not value:
+        return None
+    kind = info.get("kind")
+    if kind == "path":
+        path = Path(value)
+        return path.stem, str(path.parent)
+    # ``kind == "id"`` (or an unknown kind): a bare session name resolved
+    # against the standard autosave directory.
+    return value, ""
+
+
+def _from_store(pane_id: Optional[str]) -> Optional[SessionRef]:
+    """Our local pane->session map entry, if any."""
+    if not pane_id:
+        return None
+    entry = _read_store().get(pane_id)
+    if not isinstance(entry, dict):
+        return None
+    name = entry.get("session_name")
+    if not isinstance(name, str) or not name:
+        return None
+    stored_path = entry.get("session_path")
+    parent = ""
+    if isinstance(stored_path, str) and stored_path:
+        parent = str(Path(stored_path).parent)
+    return name, parent
+
+
+def resolve_stored_session(client: HerdrClient) -> Optional[SessionRef]:
+    """Resolve the session this pane last ran: herdr ref first, local map second."""
+    return _from_herdr(client) or _from_store(client.pane_id)
+
+
+def resume_session(client: HerdrClient) -> bool:
+    """Load this pane's previous session into the current agent.
+
+    Returns ``True`` only when history was actually restored. Any failure --
+    no stored reference, a vanished file, an unreadable store -- returns
+    ``False`` so startup simply proceeds as a fresh session. Never raises.
+    """
+    if not client.active:
+        return False
+    ref = resolve_stored_session(client)
+    if ref is None:
+        return False
+    session_name, session_dir = ref
+
+    try:
+        from code_puppy.agents.agent_manager import get_current_agent
+        from code_puppy.config import AUTOSAVE_DIR, pin_current_session_name
+        from code_puppy.session_storage import load_session
+
+        base_dir = Path(session_dir) if session_dir else Path(AUTOSAVE_DIR)
+        history = load_session(session_name, base_dir)
+    except FileNotFoundError:
+        logger.debug("herdr: stored session %s is gone", session_name)
+        forget_session(client.pane_id)
+        return False
+    except Exception:
+        logger.debug("herdr: could not load stored session", exc_info=True)
+        return False
+
+    if not history:
+        # An empty lazy-created session is not worth "resuming".
+        return False
+
+    try:
+        agent = get_current_agent()
+        agent.set_message_history(list(history))
+        pin_current_session_name(session_name)
+    except Exception:
+        logger.debug("herdr: could not adopt stored session", exc_info=True)
+        return False
+
+    _announce(session_name, history)
+    return True
+
+
+def _announce(session_name: str, history: list) -> None:
+    """Tell the user their pane's session came back. Best-effort."""
+    try:
+        from code_puppy.messaging import emit_success
+
+        emit_success(
+            f"herdr: resumed session '{session_name}' ({len(history)} messages)"
+        )
+    except Exception:
+        logger.debug("herdr: could not announce resume", exc_info=True)
+    try:
+        from code_puppy.command_line.autosave_menu import display_resumed_history
+
+        display_resumed_history(history)
+    except Exception:
+        logger.debug("herdr: could not display resumed history", exc_info=True)
+
+
+__all__ = [
+    "SessionRef",
+    "remember_session",
+    "forget_session",
+    "resolve_stored_session",
+    "resume_session",
+]

{code_puppy_core_plugins-0.0.58 → code_puppy_core_plugins-0.0.59}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "code-puppy-core-plugins"
-version = "0.0.58"
+version = "0.0.59"
 description = "Official plugin bundle for Code Puppy"
 readme = "README.md"
 requires-python = ">=3.11,<3.15"