code-puppy 0.0.597__tar.gz → 0.0.598__tar.gz

{code_puppy-0.0.597 → code_puppy-0.0.598}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-puppy
-Version: 0.0.597
+Version: 0.0.598
 Summary: Code generation agent
 Project-URL: repository, https://github.com/mpfaffenberger/code_puppy
 Project-URL: HomePage, https://github.com/mpfaffenberger/code_puppy

code_puppy-0.0.598/code_puppy/plugins/herdr/README.md

@@ -0,0 +1,81 @@
+# herdr integration
+
+Makes code-puppy a first-class citizen in
+[**herdr**](https://herdr.dev), a terminal workspace manager for coding
+agents. When you run several agents at once, herdr's sidebar rolls each
+one up to a single glanceable state -- who's **working**, who's
+**blocked** waiting on you, and who's **done** -- so you always know
+which pane needs attention.
+
+This plugin teaches code-puppy to report that state authoritatively.
+
+## What it does
+
+herdr injects three environment variables into every pane it owns:
+
+| variable            | meaning                                   |
+| ------------------- | ----------------------------------------- |
+| `HERDR_ENV=1`       | this shell is running inside a herdr pane |
+| `HERDR_SOCKET_PATH` | herdr's local control socket              |
+| `HERDR_PANE_ID`     | the pane this process owns (e.g. `w1:p1`) |
+
+On startup the plugin checks for those. If they're absent it does
+**nothing** -- zero overhead, zero output, no behaviour change. If
+they're present it opens a background reporter that maps code-puppy's
+lifecycle callbacks onto herdr's three semantic states:
+
+| code-puppy event                                | herdr state |
+| ----------------------------------------------- | ----------- |
+| `agent_run_start`, `user_prompt_submit`         | `working`   |
+| `pre_tool_call` (most tools), `post_tool_call`  | `working`   |
+| `ask_user_question`, file-permission prompts    | `blocked`   |
+| `interactive_turn_end`, `agent_run_cancel`      | `idle`      |
+| `startup`, `session_end`, `shutdown`            | `idle`      |
+
+Sub-agent runs fire the same start/end hooks as the root run, so the
+reporter refcounts active runs and only falls `idle` when the whole turn
+hands control back to you (mirroring the `puppy_spinner` plugin).
+
+## No install needed on the herdr side
+
+Because this plugin ships with code-puppy and self-activates inside a
+pane, there is nothing to run -- `herdr integration install` is **not**
+required for code-puppy. Just start code-puppy inside herdr:
+
+```bash
+herdr           # start / attach herdr
+code-puppy      # (or: pup) -- herdr picks up its state automatically
+```
+
+herdr also recognises the `code-puppy` / `pup` process on its own and
+reads the on-screen approval prompts, so even with this plugin disabled
+you still get detection. The plugin upgrades that from screen-scraped
+guessing to authoritative, event-driven state.
+
+## Blocked detection is shared with herdr
+
+Not every interactive prompt in code-puppy flows through a callback
+(shell-command approval, for instance, prompts from inside the tool).
+The plugin reports the prompts it *can* see, and herdr's screen manifest
+independently detects any visible approval UI and overrides a stale
+`working` -- which is exactly why this plugin does **not** claim herdr
+"full lifecycle authority". Belt and suspenders.
+
+## Design notes
+
+* **Never disturbs the agent.** All socket I/O happens on a daemon
+  worker thread; the sync file-permission hot-path just enqueues and
+  returns. The permission observer always returns `None`, so it can
+  never accidentally veto a file operation.
+* **Edge-triggered + deduped.** Only state *changes* hit the socket.
+* **Fail-soft.** A missing/closed socket, a departed herdr, a full
+  queue -- all are swallowed to the debug log. Reporting your state is
+  never worth crashing your agent over.
+
+## Files
+
+| file                    | responsibility                              |
+| ----------------------- | ------------------------------------------- |
+| `client.py`             | herdr socket transport (JSON, worker thread)|
+| `reporter.py`           | event -> state machine (refcount + dedup)   |
+| `register_callbacks.py` | callback wiring + env activation guard       |

code_puppy-0.0.598/code_puppy/plugins/herdr/__init__.py

@@ -0,0 +1,9 @@
+"""herdr integration plugin for code-puppy.
+
+Reports semantic agent state (working / blocked / idle) to a herdr pane
+over herdr's local socket. Inert unless running inside herdr.
+
+See ``register_callbacks.py`` for the wiring and ``README.md`` for docs.
+"""
+
+__all__: list[str] = []

code_puppy-0.0.598/code_puppy/plugins/herdr/client.py

@@ -0,0 +1,157 @@
+"""Fire-and-forget client for the herdr pane socket.
+
+herdr (https://herdr.dev) is a terminal workspace manager for coding
+agents. When code-puppy runs inside a herdr pane, herdr injects three
+environment variables:
+
+* ``HERDR_ENV=1``          -- marks the pane as herdr-managed
+* ``HERDR_SOCKET_PATH``    -- path to herdr's local control socket
+* ``HERDR_PANE_ID``        -- the pane this process owns (e.g. ``w1:p1``)
+
+This module speaks herdr's newline-delimited JSON socket protocol just
+far enough to call ``pane.report_agent`` / ``pane.report_agent_session``.
+It never reads a reply and never raises into the caller: reporting agent
+state must never be able to disturb the agent itself. Delivery happens on
+a single daemon worker thread so the (sync) permission hot-path and the
+async run loop both enqueue in O(1) and move on.
+
+Windows named-pipe transport is intentionally out of scope; herdr's
+Windows build is beta and ``AF_UNIX`` is the contract everywhere else.
+When the socket is unavailable the client is simply inactive.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import queue
+import socket
+import threading
+import time
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+#: source tag herdr attributes these reports to. The ``herdr:`` prefix is
+#: the convention herdr uses for its own official integrations.
+SOURCE = "herdr:codepuppy"
+#: agent label; must match herdr's ``agent_label(Agent::CodePuppy)``.
+AGENT = "codepuppy"
+
+_CONNECT_TIMEOUT_S = 0.5
+_QUEUE_MAX = 256
+
+
+class HerdrClient:
+    """Enqueues agent-state reports and drains them on a worker thread."""
+
+    def __init__(
+        self,
+        socket_path: Optional[str] = None,
+        pane_id: Optional[str] = None,
+    ) -> None:
+        self._socket_path = socket_path or os.environ.get("HERDR_SOCKET_PATH")
+        self._pane_id = pane_id or os.environ.get("HERDR_PANE_ID")
+        self._active = bool(
+            os.environ.get("HERDR_ENV") == "1"
+            and self._socket_path
+            and self._pane_id
+            and hasattr(socket, "AF_UNIX")
+        )
+        self._queue: "queue.Queue[Optional[Dict[str, Any]]]" = queue.Queue(
+            maxsize=_QUEUE_MAX
+        )
+        self._seq_lock = threading.Lock()
+        # Monotonic, process-unique sequence. herdr uses seq to discard
+        # out-of-order reports, so it must only ever increase.
+        self._seq = int(time.time() * 1000) * 1000
+        self._worker: Optional[threading.Thread] = None
+        if self._active:
+            self._start_worker()
+
+    @property
+    def active(self) -> bool:
+        return self._active
+
+    def _start_worker(self) -> None:
+        self._worker = threading.Thread(
+            target=self._run,
+            name="herdr-reporter",
+            daemon=True,
+        )
+        self._worker.start()
+
+    def _next_seq(self) -> int:
+        with self._seq_lock:
+            self._seq += 1
+            return self._seq
+
+    def _enqueue(self, method: str, params: Dict[str, Any]) -> None:
+        if not self._active:
+            return
+        envelope = {
+            "id": f"{SOURCE}:{self._next_seq()}",
+            "method": method,
+            "params": {
+                "pane_id": self._pane_id,
+                "source": SOURCE,
+                "agent": AGENT,
+                "seq": self._next_seq(),
+                **params,
+            },
+        }
+        try:
+            self._queue.put_nowait(envelope)
+        except queue.Full:
+            # State is edge-triggered and deduped upstream; dropping a
+            # report under extreme backpressure is harmless (herdr keeps
+            # the last state it saw).
+            logger.debug("herdr report queue full; dropping report")
+
+    def report_state(self, state: str, agent_session_id: Optional[str] = None) -> None:
+        """Report a semantic state: ``working`` / ``blocked`` / ``idle``."""
+        params: Dict[str, Any] = {"state": state}
+        if agent_session_id:
+            params["agent_session_id"] = agent_session_id
+        self._enqueue("pane.report_agent", params)
+
+    def report_session(self, agent_session_id: str) -> None:
+        """Report native session identity so herdr can restore context."""
+        if not agent_session_id:
+            return
+        self._enqueue(
+            "pane.report_agent_session",
+            {"agent_session_id": agent_session_id},
+        )
+
+    def close(self) -> None:
+        """Signal the worker to drain and stop. Best-effort, non-blocking."""
+        if not self._active:
+            return
+        try:
+            self._queue.put_nowait(None)
+        except queue.Full:
+            pass
+
+    def _run(self) -> None:
+        while True:
+            envelope = self._queue.get()
+            if envelope is None:
+                return
+            self._send(envelope)
+
+    def _send(self, envelope: Dict[str, Any]) -> None:
+        try:
+            with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as sock:
+                sock.settimeout(_CONNECT_TIMEOUT_S)
+                sock.connect(self._socket_path)  # type: ignore[arg-type]
+                payload = (json.dumps(envelope) + "\n").encode("utf-8")
+                sock.sendall(payload)
+        except (OSError, ValueError) as exc:
+            # herdr may have exited, or the pane was closed. Neither is
+            # our problem to solve; stay quiet on the diagnostic channel.
+            logger.debug("herdr report failed: %s", exc)
+
+
+__all__ = ["HerdrClient", "SOURCE", "AGENT"]

code_puppy-0.0.598/code_puppy/plugins/herdr/register_callbacks.py

@@ -0,0 +1,116 @@
+"""herdr integration -- report code-puppy's state to a herdr pane.
+
+This built-in plugin is a no-op unless code-puppy is running inside a
+`herdr <https://herdr.dev>`_ pane (detected via the ``HERDR_ENV`` /
+``HERDR_SOCKET_PATH`` / ``HERDR_PANE_ID`` environment variables herdr
+injects). When it is, it reports semantic agent state -- ``working`` /
+``blocked`` / ``idle`` -- over herdr's local socket so herdr's sidebar
+can roll code-puppy up alongside every other agent in the fleet.
+
+Because the integration ships with code-puppy and self-activates, there
+is nothing to install on the herdr side: ``herdr integration install``
+is not needed for code-puppy.
+
+Callback -> state mapping (see reporter.py for the arbitration rules):
+
+* ``startup`` / ``session_end`` / ``shutdown`` .......... idle
+* ``user_prompt_submit`` / ``agent_run_start`` ......... working
+* ``pre_tool_call`` (non-ask) / ``post_tool_call`` ..... working
+* ``pre_tool_call`` (ask_user_question) / permission ... blocked
+* ``interactive_turn_end`` / ``interactive_turn_cancel`` idle
+* ``agent_run_cancel`` ................................. idle
+* ``agent_run_end`` ................................... idle (depth 0)
+
+Handlers are plain sync functions that swallow every argument: the
+callback dispatcher passes hook args positionally and runs sync
+callbacks happily from both async and worker-thread contexts, so
+signature-proofing with ``*args`` is the robust choice.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from code_puppy.callbacks import register_callback
+
+from .client import HerdrClient
+from .reporter import HerdrReporter
+
+logger = logging.getLogger(__name__)
+
+_client = HerdrClient()
+_reporter = HerdrReporter(_client)
+
+
+def _arg(args: tuple, index: int):
+    return args[index] if len(args) > index else None
+
+
+def _on_startup(*_args, **_kw) -> None:
+    _reporter.on_startup()
+
+
+def _on_user_prompt(*args, **_kw) -> None:
+    # (prompt, session_id=None)
+    _reporter.on_user_prompt(_arg(args, 1))
+
+
+def _on_run_start(*args, **_kw) -> None:
+    # (agent_name, model_name, session_id=None)
+    _reporter.on_run_start(_arg(args, 2))
+
+
+def _on_run_end(*args, **_kw) -> None:
+    # (agent_name, model_name, session_id=None, ...)
+    _reporter.on_run_end(_arg(args, 2))
+
+
+def _on_run_cancel(*_args, **_kw) -> None:
+    _reporter.on_run_cancel()
+
+
+def _on_turn_end(*_args, **_kw) -> None:
+    _reporter.on_turn_end()
+
+
+def _on_pre_tool_call(*args, **_kw) -> None:
+    # (tool_name, tool_args, context=None)
+    tool_name = _arg(args, 0) or ""
+    _reporter.on_tool_call(str(tool_name))
+
+
+def _on_post_tool_call(*_args, **_kw) -> None:
+    _reporter.on_tool_done()
+
+
+def _on_file_permission(*_args, **_kw):
+    # SYNC callback. code-puppy treats every non-None result as a
+    # grant/deny vote (``any(not r for r in results if r is not None)``),
+    # so we MUST return None -- we only observe, never veto.
+    _reporter.on_permission_prompt()
+    return None
+
+
+def _on_shutdown(*_args, **_kw) -> None:
+    _reporter.on_shutdown()
+
+
+if _reporter.active:
+    register_callback("startup", _on_startup)
+    register_callback("user_prompt_submit", _on_user_prompt)
+    register_callback("agent_run_start", _on_run_start)
+    register_callback("agent_run_end", _on_run_end)
+    register_callback("agent_run_cancel", _on_run_cancel)
+    register_callback("interactive_turn_end", _on_turn_end)
+    register_callback("interactive_turn_cancel", _on_turn_end)
+    register_callback("pre_tool_call", _on_pre_tool_call)
+    register_callback("post_tool_call", _on_post_tool_call)
+    register_callback("file_permission", _on_file_permission)
+    register_callback("session_end", _on_shutdown)
+    register_callback("shutdown", _on_shutdown)
+    logger.debug("herdr plugin active for pane %s", _client._pane_id)
+else:
+    logger.debug("herdr plugin inactive (not running inside a herdr pane)")
+
+
+__all__ = ["HerdrClient", "HerdrReporter"]

code_puppy-0.0.598/code_puppy/plugins/herdr/reporter.py

@@ -0,0 +1,130 @@
+"""Map code-puppy lifecycle events onto herdr's three semantic states.
+
+herdr models every agent as ``working`` / ``blocked`` / ``idle``. This
+reporter is the single writer of that state for the pane, so it keeps the
+edge-triggering and arbitration rules in one place:
+
+* **working**  -- a top-level run or a tool call is in flight.
+* **blocked**  -- code-puppy is waiting on the human (permission prompt,
+  ``ask_user_question``). This is best-effort: not every interactive
+  prompt routes through a callback (shell-command approval does not), so
+  herdr's screen manifest remains the authority that can override a stale
+  ``working`` when a prompt is visible. We deliberately do **not** claim
+  herdr full-lifecycle authority for exactly this reason.
+* **idle**     -- the turn handed control back to the human.
+
+Sub-agents fire the same ``agent_run_start`` / ``agent_run_end`` hooks as
+the root agent, so a naive "end == idle" mapping would flip the pane idle
+while the root run is still going. We refcount active runs (the same
+pattern the puppy_spinner plugin uses) and only trust the interactive
+turn boundary for idle.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from typing import Optional
+
+from .client import HerdrClient
+
+logger = logging.getLogger(__name__)
+
+WORKING = "working"
+BLOCKED = "blocked"
+IDLE = "idle"
+
+
+class HerdrReporter:
+    """Thread-safe, dedup-ing bridge from callbacks to :class:`HerdrClient`."""
+
+    def __init__(self, client: HerdrClient) -> None:
+        self._client = client
+        self._lock = threading.Lock()
+        self._run_depth = 0
+        self._last_state: Optional[str] = None
+        self._session_id: Optional[str] = None
+
+    @property
+    def active(self) -> bool:
+        return self._client.active
+
+    # -- state emission -------------------------------------------------
+
+    def _emit(self, state: str) -> None:
+        """Send *state* only when it changes (edge-triggered)."""
+        with self._lock:
+            if state == self._last_state:
+                return
+            self._last_state = state
+            session_id = self._session_id
+        self._client.report_state(state, session_id)
+
+    def _remember_session(self, session_id: Optional[str]) -> None:
+        if not session_id:
+            return
+        with self._lock:
+            new = session_id != self._session_id
+            self._session_id = session_id
+        if new:
+            self._client.report_session(session_id)
+
+    # -- lifecycle handlers (all sync; safe from async or worker threads) --
+
+    def on_startup(self) -> None:
+        self._emit(IDLE)
+
+    def on_user_prompt(self, session_id: Optional[str] = None) -> None:
+        self._remember_session(session_id)
+        self._emit(WORKING)
+
+    def on_run_start(self, session_id: Optional[str] = None) -> None:
+        self._remember_session(session_id)
+        with self._lock:
+            self._run_depth += 1
+        self._emit(WORKING)
+
+    def on_run_end(self, session_id: Optional[str] = None) -> None:
+        self._remember_session(session_id)
+        with self._lock:
+            self._run_depth = max(0, self._run_depth - 1)
+            depth = self._run_depth
+        # Only the outermost run finishing means the model stopped. The
+        # interactive turn boundary is the true idle signal, but headless
+        # (`-p`) runs never fire it, so falling idle at depth 0 keeps
+        # non-interactive panes honest too.
+        if depth == 0:
+            self._emit(IDLE)
+
+    def on_run_cancel(self) -> None:
+        with self._lock:
+            self._run_depth = 0
+        self._emit(IDLE)
+
+    def on_turn_end(self) -> None:
+        with self._lock:
+            self._run_depth = 0
+        self._emit(IDLE)
+
+    def on_tool_call(self, tool_name: str) -> None:
+        # ask_user_question parks the agent on the human -> blocked.
+        # Everything else is active work.
+        if tool_name == "ask_user_question":
+            self._emit(BLOCKED)
+        else:
+            self._emit(WORKING)
+
+    def on_tool_done(self) -> None:
+        # A tool completing means we are moving again (this is also what
+        # clears a blocked ask_user_question / a resolved file prompt).
+        self._emit(WORKING)
+
+    def on_permission_prompt(self) -> None:
+        self._emit(BLOCKED)
+
+    def on_shutdown(self) -> None:
+        self._emit(IDLE)
+        self._client.close()
+
+
+__all__ = ["HerdrReporter", "WORKING", "BLOCKED", "IDLE"]

{code_puppy-0.0.597 → code_puppy-0.0.598}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "code-puppy"
-version = "0.0.597"
+version = "0.0.598"
 description = "Code generation agent"
 readme = "README.md"
 requires-python = ">=3.11,<3.15"