code-puppy-core-plugins 0.0.2__py3-none-any.whl

code_puppy_core_plugins/herdr/README.md

@@ -0,0 +1,168 @@
+# 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, no socket,
+no worker thread. If they're present it opens a background reporter that
+reports code-puppy's state **authoritatively**: herdr never has to infer
+it from the screen.
+
+## State is authoritative
+
+State is a pure function of two facts the plugin observes directly:
+
+```text
+blocked   if awaiting the human
+working   elif a run is in flight (run_depth > 0)
+idle      otherwise
+```
+
+* **run depth** comes from `agent_run_start` / `agent_run_end`, refcounted
+  so a finishing sub-agent doesn't flip the pane `idle` mid-turn (the same
+  pattern the `puppy_spinner` plugin uses).
+* **awaiting** comes from the `awaiting_user_input` callback, which fires
+  from the single process-wide choke-point
+  (`command_runner.set_awaiting_user_input`) that *every* interactive wait
+  already passes through -- shell-command approval, file-permission
+  approval, `ask_user_question`, and every menu/picker. One hook captures
+  every block, so there is nothing left for herdr to guess.
+
+User-initiated menus carry `notify=False`; the plugin suppresses their
+`blocked` report entirely so quick pickers don't spam attention.
+
+## Activity text is best-effort
+
+Alongside the authoritative state, the plugin attaches a short activity
+`message` (`thinking`, `running <tool>`, `awaiting input`) driven by
+`pre_tool_call` / `post_tool_call`. This is decorative: it rides a separate
+lane, deduplicates on the `(state, message)` pair, and can **never** delay
+or override the authoritative state, the session reference, or the final
+release. If a hook-blocked tool misses its completion callback, the next
+run / tool / wait / turn event corrects the message; state stays correct
+regardless.
+
+## Pane metadata (model / context / tokens)
+
+At the end of every interactive turn the plugin also reports pane
+metadata via `pane.report_metadata`: the current model, context-window
+fill percentage, and a compact token count. herdr stores these under the
+pane with a 24h TTL (so stale numbers self-clear after an abrupt exit),
+but it only *renders* them when your sidebar layout references the
+matching `$name` fields. Add them to `rows_by_agent` in your herdr
+config:
+
+```toml
+[ui.sidebar.agents.rows_by_agent]
+codepuppy = [
+  ["state_icon", "workspace", "tab"],
+  ["agent", "$model"],
+  ["$context", "$tokens"],
+]
+```
+
+The payload uses static keys (`model`, `context`, `tokens`) with
+string values and no indicator glyphs -- herdr rows already carry their
+own state icons. If context usage can't be computed for a turn, no
+metadata is sent and the pane keeps its last good values until the TTL
+expires.
+
+## Session reference
+
+On each prompt the plugin reports a **stable** session reference (the
+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.
+
+## Notifications are herdr's job
+
+The plugin sends no notifications itself. herdr derives attention and
+completion notifications from the agent-state transitions the plugin
+reports, and herdr's own toast / sound settings control delivery. This
+plugin's only job is to report accurate state.
+
+## Release on exit
+
+On `session_end` / `shutdown` the plugin calls `pane.release_agent` once
+(idempotent, bounded) so herdr knows code-puppy has let go of the pane --
+no lingering stale `working`. There is no intermediate `idle` report on
+shutdown; if herdr is unavailable the release is bounded and can never
+delay process exit.
+
+## 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, so even
+with this plugin disabled you still get basic detection. The plugin
+upgrades that from screen-scraped guessing to authoritative, event-driven
+state, metadata, and activity.
+
+## Design notes
+
+* **Never disturbs the agent.** All socket I/O happens on a daemon
+  worker thread; the sync file-permission and tool hot-paths just enqueue
+  and return. The tool observers always return `None`, so they can never
+  block or transform a tool call.
+* **Critical vs decorative.** State edges, session references, and the
+  release ride a critical lane that always overtakes decorative traffic
+  (activity messages, metadata). Decorative saturation can never displace
+  a critical report.
+* **Edge-triggered + deduped.** Only genuine `(state, message)` changes
+  hit the socket.
+* **Fail-soft.** A missing/closed socket, a departed herdr, an
+  unresolvable source -- 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)   |
+| `sources.py`            | fail-soft adapters (tokens / session / msg) |
+| `register_callbacks.py` | callback wiring + env activation guard       |
+| `smoke.py`              | manual live smoke test (disposable pane)     |
+
+## Live smoke test
+
+The unit tests (`tests/plugins/test_herdr_*.py`) are the CI contract. For
+an end-to-end check against a real herdr server, run the manual smoke test
+from inside a herdr pane:
+
+```bash
+python -m code_puppy_core_plugins.herdr.smoke
+```
+
+It creates its **own** disposable pane, drives the real client through
+every protocol-16 method (state edges, session reference, metadata,
+release), reads each result back with `herdr pane get`, then closes the
+disposable pane -- your working pane is never touched. Exits non-zero if
+any check fails.

code_puppy_core_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_core_plugins/herdr/client.py

@@ -0,0 +1,339 @@
+r"""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 far
+enough to call ``pane.report_agent`` / ``pane.report_agent_session`` /
+``pane.report_metadata`` / ``pane.release_agent``. 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:
+
+* **Critical lane** -- state transitions, session references, and the
+  final release. The worker drains these first.
+* **Decorative lane** -- message-only state refreshes and pane metadata.
+  These may be replaced by newer decorative work, and they are discarded
+  entirely once a release is scheduled.
+
+Each slot keeps only its newest value, so memory is bounded and the pane
+always converges on the latest authoritative facts. Request ``id`` and
+``seq`` are assigned immediately before the first wire attempt, so wire
+order stays monotonic even when critical work overtakes decorative work;
+retries reuse the same serialized envelope (herdr dedupes on ``seq``).
+
+Transport is ``AF_UNIX`` everywhere it exists. On Windows (where CPython
+still has no ``socket.AF_UNIX``), herdr's build -- via Rust's
+``interprocess`` crate -- maps the file-style ``HERDR_SOCKET_PATH`` onto a
+named pipe whose name *is* the full path (``\\.\pipe\C:\...\herdr.sock``),
+so plain stdlib file I/O on that pipe path gives the same bidirectional
+byte stream. When neither transport is available the client is simply
+inactive.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import socket
+import threading
+import time
+from typing import Any, Dict, Optional, Tuple
+
+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
+
+# Retry until herdr acks: a silently-dropped report strands the pane on a stale state.
+# Retrying the *same* envelope is safe — herdr dedupes on ``seq``, so an already-applied
+# report is harmlessly ignored.
+_SEND_ATTEMPTS = 3
+_SEND_BACKOFF_S = 0.05
+_ACK_BYTES = 4096
+
+#: Pane metadata TTL (24h) — bounds how long an abrupt process death can leave
+#: stale token/model numbers on the sidebar.
+_METADATA_TTL_MS = 86_400_000
+
+# herdr request methods.
+_M_STATE = "pane.report_agent"
+_M_SESSION = "pane.report_agent_session"
+_M_METADATA = "pane.report_metadata"
+_M_RELEASE = "pane.release_agent"
+
+
+class HerdrClient:
+    """Coalescing, two-lane reporter drained on a single 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") or os.name == "nt")
+        )
+
+        # One condition guards every mailbox slot and the lifecycle flags.
+        self._cond = threading.Condition()
+        # Critical lane (latest-wins). ``None`` == empty.
+        self._state: Optional[Dict[str, Any]] = None
+        self._session: Optional[Dict[str, Any]] = None
+        # Decorative lane (latest-wins, discarded on release).
+        self._message: Optional[Dict[str, Any]] = None
+        self._metadata: Optional[Dict[str, Any]] = None
+        # Terminal release slot.
+        self._release: Optional[Dict[str, Any]] = None
+
+        self._closing = False
+        self._release_scheduled = False
+        self._released = threading.Event()
+
+        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
+
+    # -- public API ----------------------------------------------------
+
+    def report_state(
+        self,
+        state: str,
+        agent_session_id: Optional[str] = None,
+        *,
+        message: Optional[str] = None,
+        critical: bool = True,
+    ) -> None:
+        """Report a semantic state (``working`` / ``blocked`` / ``idle``).
+
+        A genuine state *edge* is ``critical`` (default) and jumps the queue.
+        A message-only refresh (same state, new activity text) should pass
+        ``critical=False`` so it rides the decorative lane and can never
+        delay an authoritative edge, session reference, or release.
+        """
+        params: Dict[str, Any] = {"state": state}
+        if agent_session_id:
+            params["agent_session_id"] = agent_session_id
+        if message:
+            params["message"] = message
+        self._put("_state" if critical else "_message", params)
+
+    def report_session(
+        self,
+        agent_session_id: Optional[str] = None,
+        session_path: Optional[str] = None,
+    ) -> None:
+        """Report a stable session reference (critical lane)."""
+        params: Dict[str, Any] = {}
+        if agent_session_id:
+            params["agent_session_id"] = agent_session_id
+        if session_path:
+            params["agent_session_path"] = session_path
+        if not params:
+            return
+        self._put("_session", params)
+
+    def report_metadata(self, tokens: Dict[str, Any]) -> None:
+        """Report pane metadata (model / context / tokens) on the decorative lane."""
+        if not tokens:
+            return
+        params: Dict[str, Any] = {
+            "applies_to_source": SOURCE,
+            "ttl_ms": _METADATA_TTL_MS,
+            "tokens": dict(tokens),
+        }
+        self._put("_metadata", params)
+
+    def _put(self, slot: str, params: Dict[str, Any]) -> None:
+        if not self._active:
+            return
+        with self._cond:
+            # Once a release is scheduled the pane is shutting down; refuse
+            # new work so the release stays the final wire event.
+            if self._closing:
+                return
+            setattr(self, slot, params)
+            self._cond.notify()
+
+    def release_and_close(self, timeout_s: float = 1.0) -> None:
+        """Schedule one ``pane.release_agent`` and wait up to ``timeout_s``.
+
+        Idempotent: repeated calls schedule a single release. Stops
+        decorative input, discards pending decorative work, lets any pending
+        critical work flush, then releases. The wait is bounded on the
+        caller side, so an unavailable herdr can never exceed ``timeout_s``.
+        """
+        if not self._active:
+            return
+        self._schedule_release()
+        self._released.wait(timeout=timeout_s)
+
+    def close(self) -> None:
+        """Best-effort, non-blocking shutdown: schedule the release and return."""
+        if not self._active:
+            return
+        self._schedule_release()
+
+    def _schedule_release(self) -> None:
+        with self._cond:
+            if self._release_scheduled:
+                return
+            self._release_scheduled = True
+            self._closing = True
+            # Decorative work is not worth delaying shutdown for.
+            self._message = None
+            self._metadata = None
+            self._release = {}  # release_agent needs only the base params
+            self._cond.notify()
+
+    # -- worker --------------------------------------------------------
+
+    def _take_next_locked(self) -> Optional[Tuple[str, Dict[str, Any]]]:
+        """Pop the next job by priority. Caller holds ``self._cond``.
+
+        Order: critical state -> critical session -> (decorative message ->
+        decorative metadata, only while not closing) -> terminal release.
+        Critical work therefore always overtakes decorative work, and the
+        release is only taken once the critical lane is drained.
+        """
+        if self._state is not None:
+            params, self._state = self._state, None
+            return _M_STATE, params
+        if self._session is not None:
+            params, self._session = self._session, None
+            return _M_SESSION, params
+        if not self._closing:
+            if self._message is not None:
+                params, self._message = self._message, None
+                return _M_STATE, params
+            if self._metadata is not None:
+                params, self._metadata = self._metadata, None
+                return _M_METADATA, params
+        if self._closing and self._release is not None:
+            params, self._release = self._release, None
+            return _M_RELEASE, params
+        return None
+
+    def _run(self) -> None:
+        while True:
+            with self._cond:
+                job = self._take_next_locked()
+                while job is None:
+                    if self._closing:
+                        # Nothing left and shutting down -> unblock waiters.
+                        self._released.set()
+                        return
+                    self._cond.wait()
+                    job = self._take_next_locked()
+                method, params = job
+            self._send(method, params)
+            if method == _M_RELEASE:
+                self._released.set()
+                return
+
+    def _send(self, method: str, params: Dict[str, Any]) -> None:
+        # Assign id + seq at wire time so critical work that overtook
+        # decorative work still gets a higher (later) sequence number.
+        seq = self._next_seq()
+        envelope = {
+            "id": f"{SOURCE}:{seq}",
+            "method": method,
+            "params": {
+                "pane_id": self._pane_id,
+                "source": SOURCE,
+                "agent": AGENT,
+                "seq": seq,
+                **params,
+            },
+        }
+        payload = (json.dumps(envelope) + "\n").encode("utf-8")
+        last_exc: Optional[Exception] = None
+        for attempt in range(_SEND_ATTEMPTS):
+            try:
+                if self._deliver(payload):
+                    return
+            except (OSError, ValueError) as exc:
+                last_exc = exc
+            if attempt + 1 < _SEND_ATTEMPTS:
+                time.sleep(_SEND_BACKOFF_S)
+        # herdr may have exited or the pane was closed. Nothing left to do but
+        # note it on the diagnostic channel -- never raise into the agent.
+        logger.debug(
+            "herdr %s undelivered after %d attempts: %s",
+            method,
+            _SEND_ATTEMPTS,
+            last_exc,
+        )
+
+    def _deliver(self, payload: bytes) -> bool:
+        """One wire attempt. ``True`` means herdr acked the report.
+
+        Any nonempty response is an ack: herdr already treats the report as
+        taken (even a busy ``shown:false`` reply). No bytes (closed /
+        timed-out) means it may not have applied -> caller retries the
+        identical envelope.
+        """
+        if os.name == "nt":
+            return self._deliver_pipe(payload)
+        return self._deliver_unix(payload)
+
+    def _deliver_unix(self, payload: bytes) -> bool:
+        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]
+            sock.sendall(payload)
+            return bool(sock.recv(_ACK_BYTES))
+
+    def _deliver_pipe(self, payload: bytes) -> bool:
+        # Windows herdr (Rust ``interprocess``) exposes ``\\.\pipe\<full path>``; the
+        # .sock file is just a pid marker. CreateFile fails fast when herdr's gone
+        # (OSError -> retry). The ack read has no timeout, but replies are immediate,
+        # the worker is a daemon thread, and release_and_close is bounded, so a wedged
+        # herdr can't hang the agent or its shutdown.
+        pipe_name = "\\\\.\\pipe\\" + str(self._socket_path)
+        with open(pipe_name, "r+b", buffering=0) as pipe:
+            pipe.write(payload)
+            return bool(pipe.readline(_ACK_BYTES))
+
+
+__all__ = ["HerdrClient", "SOURCE", "AGENT"]

code_puppy_core_plugins/herdr/register_callbacks.py

@@ -0,0 +1,140 @@
+"""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.
+
+code-puppy reports its state **authoritatively**: herdr never infers it from
+the screen. State is a pure function of two facts the plugin observes
+directly (see reporter.py):
+
+* run depth, from ``agent_run_start`` / ``agent_run_end`` -> ``working``
+* awaiting-human, from the ``awaiting_user_input`` callback -> ``blocked``
+
+The ``awaiting_user_input`` callback is the key: it fires from the single
+process-wide choke-point (``command_runner.set_awaiting_user_input``) that
+*every* interactive wait already passes through -- shell-command approval,
+file-permission approval, ``ask_user_question``, and every menu/picker -- so
+one hook captures every block. There is no per-prompt special-casing and
+nothing for herdr to guess.
+
+Callback -> effect:
+
+* ``startup`` ......................................... resync (-> idle)
+* ``session_end`` / ``shutdown`` ..................... release pane authority
+* ``user_prompt_submit`` ............................. refresh durable session
+* ``agent_run_start`` / ``agent_run_end`` ............ run-depth +/- 1
+* ``pre_tool_call`` / ``post_tool_call`` ............. decorative activity msg
+* ``agent_run_cancel`` / ``interactive_turn_end`` .... reset -> idle
+* ``interactive_turn_cancel`` ........................ reset -> idle
+* ``awaiting_user_input`` ............................ blocked <-> not
+
+Session identity is the durable autosave (name, path) resolved by
+``sources.current_session_ref`` -- NOT the per-run ``group_id`` UUID, which
+changes every turn. Pane metadata (model / context / tokens) and the
+best-effort activity ``message`` are decorative: they never perturb the
+authoritative state and never delay a state edge, session reference, or the
+final ``pane.release_agent`` on exit.
+
+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 ``*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:
+    # The callback's per-run group_id is ignored; the reporter resolves the
+    # durable session reference itself.
+    _reporter.on_user_prompt()
+
+
+def _on_run_start(*_args, **_kw) -> None:
+    _reporter.on_run_start()
+
+
+def _on_run_end(*_args, **_kw) -> None:
+    _reporter.on_run_end()
+
+
+def _on_run_cancel(*_args, **_kw) -> None:
+    _reporter.on_run_cancel()
+
+
+def _on_turn_end(*_args, **_kw) -> None:
+    _reporter.on_turn_end()
+
+
+def _on_tool_start(*args, **kwargs):
+    # (tool_name, tool_args, context=None). Decorative only -> return None so
+    # the tool is never blocked or transformed.
+    tool_name = _arg(args, 0) if args else kwargs.get("tool_name")
+    _reporter.on_tool_start(str(tool_name) if tool_name is not None else "")
+    return None
+
+
+def _on_tool_complete(*_args, **_kw):
+    # (tool_name, tool_args, result, duration_ms, context=None). Decorative.
+    _reporter.on_tool_complete()
+    return None
+
+
+def _on_awaiting_user_input(*args, **_kw) -> None:
+    # Keep the public callback's historical one-argument signature. Notification
+    # intent is read synchronously from command_runner's current wait state.
+    from code_puppy.tools.command_runner import should_notify_awaiting_user_input
+
+    _reporter.on_awaiting_user_input(
+        bool(_arg(args, 0)),
+        notify=should_notify_awaiting_user_input(),
+    )
+
+
+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_tool_start)
+    register_callback("post_tool_call", _on_tool_complete)
+    register_callback("awaiting_user_input", _on_awaiting_user_input)
+    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"]