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

code_puppy_core_plugins/herdr/reporter.py

@@ -0,0 +1,212 @@
+"""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, and code-puppy
+reports it *authoritatively* -- herdr never has to infer our state from the
+screen.
+
+State is a pure function of two facts we own directly:
+
+* **run depth** -- how many agent runs are in flight (root + sub-agents).
+  ``> 0`` means the model is doing work.
+* **awaiting** -- whether code-puppy is parked on the human. This comes from
+  the ``awaiting_user_input`` callback, which fires from the *one*
+  process-wide choke-point every interactive wait passes through
+  (shell-command approval, file-permission approval, ``ask_user_question``,
+  and every menu/picker). Because that single source covers every prompt --
+  including shell-command approval, which prompts from inside the tool -- the
+  plugin sees every block directly. There is nothing left for herdr to guess.
+
+Effective state::
+
+    blocked   if awaiting              (parked on the human)
+    working   elif run_depth > 0       (a run is in flight)
+    idle      otherwise                (control is the human's)
+
+Sub-agents fire the same ``agent_run_start`` / ``agent_run_end`` hooks as the
+root agent, so we refcount active runs (the same pattern the puppy_spinner
+plugin uses) rather than flipping idle when a sub-agent finishes.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from typing import Optional, Tuple
+
+from .client import HerdrClient
+from . import sources
+
+logger = logging.getLogger(__name__)
+
+WORKING = "working"
+BLOCKED = "blocked"
+IDLE = "idle"
+
+# Decorative activity strings (the ``message`` field on ``pane.report_agent``).
+# State stays authoritative; these are best-effort colour commentary.
+THINKING = "thinking"
+AWAITING = "awaiting input"
+
+
+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._awaiting = False
+        self._awaiting_notify = True
+        self._last_reported_state: Optional[str] = None
+        self._last_reported_message: Optional[str] = None
+        # Latest working activity (``thinking`` / ``running <tool>``). Only
+        # surfaces while WORKING; BLOCKED and IDLE derive their own message.
+        self._activity: Optional[str] = None
+        # Durable session reference (name, pickle_path) — NOT the per-run group_id UUID,
+        # which changes every turn and can't identify a resumable session.
+        self._session_ref: Optional[Tuple[str, str]] = None
+
+    @property
+    def active(self) -> bool:
+        return self._client.active
+
+    # -- state derivation ----------------------------------------------
+
+    def _recompute_locked(self) -> Optional[str]:
+        """Return the effective state from the facts we hold. Caller holds lock."""
+        if self._awaiting:
+            return BLOCKED
+        if self._run_depth > 0:
+            return WORKING
+        return IDLE
+
+    def _message_for_locked(self, state: str) -> Optional[str]:
+        """Derive the decorative message for a state. Caller holds lock."""
+        if state == BLOCKED:
+            return AWAITING
+        if state == WORKING:
+            return self._activity or THINKING
+        return None
+
+    def _sync(self) -> None:
+        """Report a changed (state, message) pair, optionally suppressing blocked.
+
+        A genuine state edge rides the critical lane; a message-only change
+        (same state, new activity) rides the decorative lane so it can never
+        delay an authoritative edge. User-initiated menus retain
+        ``notify=False`` for their whole lifetime: their internal ``blocked``
+        state must not touch the edge trackers, so closing the menu does not
+        re-send an unchanged state.
+        """
+        with self._lock:
+            state = self._recompute_locked()
+            if state == BLOCKED and not self._awaiting_notify:
+                return
+            message = self._message_for_locked(state)
+            state_changed = state != self._last_reported_state
+            message_changed = message != self._last_reported_message
+            if not state_changed and not message_changed:
+                return
+            self._last_reported_state = state
+            self._last_reported_message = message
+            session_id = self._session_ref[0] if self._session_ref else None
+            critical = state_changed
+        self._client.report_state(state, session_id, message=message, critical=critical)
+
+    def _refresh_session(self) -> None:
+        """Resolve the durable session reference and report it on change.
+
+        Ignores per-run group_ids entirely. Resolution happens OUTSIDE the
+        lock (guardrail). The next prompt after ``/clear``, ``/session new``,
+        ``/autosave_load``, ``/load_context``, a quick resume, or an agent
+        switch refreshes herdr with no core session callback.
+        """
+        ref = sources.current_session_ref()
+        if ref is None:
+            return
+        with self._lock:
+            changed = ref != self._session_ref
+            self._session_ref = ref
+        if changed:
+            self._client.report_session(ref[0], ref[1])
+
+    # -- lifecycle handlers (all sync; safe from async or worker threads) --
+
+    def on_startup(self) -> None:
+        self._sync()  # depth 0, not awaiting -> idle
+
+    def on_user_prompt(self, *_ignored) -> None:
+        # Ignore the callback's per-run group_id; resolve the durable session.
+        self._refresh_session()
+
+    def on_run_start(self, *_ignored) -> None:
+        with self._lock:
+            self._run_depth += 1
+            # The OUTER run starting is the canonical "thinking" edge. Nested
+            # sub-agent runs keep whatever activity is already showing.
+            if self._run_depth == 1:
+                self._activity = THINKING
+        self._sync()
+
+    def on_run_end(self, *_ignored) -> None:
+        with self._lock:
+            self._run_depth = max(0, self._run_depth - 1)
+        # Depth 0 = model stopped. The turn boundary is the canonical idle signal but
+        # headless (`-p`) runs never fire it, so depth-0 idle keeps panes honest too.
+        self._sync()
+
+    def on_run_cancel(self) -> None:
+        with self._lock:
+            self._run_depth = 0
+            self._awaiting = False
+            self._activity = None
+        self._sync()
+
+    def on_tool_start(self, tool_name: str) -> None:
+        """A tool call started -> decorative ``running <tool>`` activity."""
+        # Resolve the message OUTSIDE the lock (guardrail: reporter locks
+        # never cover source resolution).
+        activity = sources.activity_message(tool_name)
+        with self._lock:
+            self._activity = activity
+        self._sync()
+
+    def on_tool_complete(self) -> None:
+        """A tool call finished -> back to ``thinking`` while the run continues."""
+        with self._lock:
+            self._activity = THINKING
+        self._sync()
+
+    def on_turn_end(self) -> None:
+        with self._lock:
+            self._run_depth = 0
+            self._awaiting = False
+            self._activity = None
+        self._sync()
+        # A completed turn is the canonical metadata refresh point: payload computed
+        # once, outside the reporter lock, on the decorative lane. Sending every turn
+        # also refreshes the TTL; tool callbacks / blocked edges do no token math.
+        self._emit_metadata()
+
+    def _emit_metadata(self) -> None:
+        """Compute and enqueue pane metadata. Never holds the reporter lock."""
+        payload = sources.current_tokens_payload()
+        if payload:
+            self._client.report_metadata(payload)
+
+    def on_awaiting_user_input(self, awaiting: bool, *, notify: bool = True) -> None:
+        """Track an interactive wait, notifying only when requested."""
+        with self._lock:
+            self._awaiting = bool(awaiting)
+            self._awaiting_notify = bool(notify)
+        self._sync()
+
+    def on_shutdown(self) -> None:
+        # Release pane authority directly (no intermediate idle report).
+        # release_and_close() is idempotent and bounded, so calling it from both
+        # session_end and shutdown can never delay process exit.
+        self._client.release_and_close()
+
+
+__all__ = ["HerdrReporter", "WORKING", "BLOCKED", "IDLE", "THINKING", "AWAITING"]

code_puppy_core_plugins/herdr/smoke.py

@@ -0,0 +1,143 @@
+"""Live smoke test for the herdr integration against a real herdr pane.
+
+This is a **manual** verification tool, not part of the CI contract (the
+unit tests in ``tests/plugins/test_herdr_*.py`` are). It exercises every
+protocol-16 method the plugin uses -- ``pane.report_agent``,
+``pane.report_agent_session``, ``pane.report_metadata``, and
+``pane.release_agent`` -- against a live herdr server, and reads each result
+back with ``herdr pane get`` to prove herdr actually stored it.
+
+It is safe to run: it creates its OWN disposable pane, drives the real
+``HerdrClient`` against that pane, and always closes it again -- your
+working pane is never touched.
+
+Usage (from inside a herdr pane)::
+
+    python -m code_puppy_core_plugins.herdr.smoke
+
+Requires the ``herdr`` CLI on ``PATH`` and the ``HERDR_ENV`` /
+``HERDR_SOCKET_PATH`` / ``HERDR_PANE_ID`` variables herdr injects. Exits 0
+on success, 1 on any failed check, 2 on setup failure.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import time
+from typing import Any, Dict, Optional
+
+_SPLIT_RATIO = 0.12
+_SETTLE_S = 0.6
+
+
+def _herdr(*args: str) -> Dict[str, Any]:
+    """Run a herdr CLI command and parse its JSON reply."""
+    proc = subprocess.run(["herdr", *args], capture_output=True, text=True, timeout=10)
+    if not proc.stdout.strip():
+        raise RuntimeError(f"herdr {' '.join(args)} produced no output: {proc.stderr}")
+    return json.loads(proc.stdout)
+
+
+def _pane_field(pane_id: str, field: str) -> Any:
+    pane = _herdr("pane", "get", pane_id)["result"]["pane"]
+    return pane.get(field)
+
+
+def _create_disposable_pane(parent: str) -> str:
+    reply = _herdr(
+        "pane",
+        "split",
+        parent,
+        "--direction",
+        "down",
+        "--ratio",
+        str(_SPLIT_RATIO),
+        "--no-focus",
+    )
+    return reply["result"]["pane"]["pane_id"]
+
+
+def _make_client(pane_id: str):
+    # Point a real client at the disposable pane. HERDR_SOCKET_PATH is
+    # inherited from the surrounding pane.
+    os.environ["HERDR_ENV"] = "1"
+    os.environ["HERDR_PANE_ID"] = pane_id
+    from code_puppy_core_plugins.herdr.client import HerdrClient
+
+    return HerdrClient()
+
+
+def _run_checks(client, pane_id: str) -> Dict[str, bool]:
+    results: Dict[str, bool] = {}
+
+    client.report_state("working")
+    client.report_session("smoke_session_x", "/tmp/smoke_session_x.pkl")
+    client.report_metadata(
+        {"model": "claude-smoke", "context": "42%", "tokens": "48k/200k"}
+    )
+    time.sleep(_SETTLE_S)
+    results["state_working"] = _pane_field(pane_id, "agent_status") == "working"
+    results["metadata_tokens"] = bool(_pane_field(pane_id, "tokens"))
+
+    client.report_state("blocked")
+    time.sleep(_SETTLE_S)
+    results["state_blocked"] = _pane_field(pane_id, "agent_status") == "blocked"
+
+    client.report_state("idle")
+    time.sleep(_SETTLE_S)
+    results["state_idle"] = _pane_field(pane_id, "agent_status") == "idle"
+
+    started = time.monotonic()
+    client.release_and_close(timeout_s=1.0)
+    elapsed = time.monotonic() - started
+    results["release_bounded"] = elapsed < 1.5
+    time.sleep(_SETTLE_S)
+    # Releasing authority drops the pane back to 'unknown'.
+    results["release_clears_state"] = _pane_field(pane_id, "agent_status") == "unknown"
+
+    return results
+
+
+def main() -> int:
+    if os.environ.get("HERDR_ENV") != "1":
+        print("Not inside a herdr pane (HERDR_ENV != 1). Aborting.", file=sys.stderr)
+        return 2
+    parent = os.environ.get("HERDR_PANE_ID")
+    if not parent:
+        print("HERDR_PANE_ID is unset. Aborting.", file=sys.stderr)
+        return 2
+
+    pane_id: Optional[str] = None
+    try:
+        pane_id = _create_disposable_pane(parent)
+        print(f"Created disposable pane {pane_id} (from {parent})")
+        client = _make_client(pane_id)
+        if not client.active:
+            print("HerdrClient did not activate. Aborting.", file=sys.stderr)
+            return 2
+        results = _run_checks(client, pane_id)
+    except Exception as exc:  # pragma: no cover - manual tool
+        print(f"Smoke setup/run error: {exc}", file=sys.stderr)
+        return 2
+    finally:
+        if pane_id:
+            try:
+                _herdr("pane", "close", pane_id)
+                print(f"Closed disposable pane {pane_id}")
+            except Exception as exc:  # pragma: no cover - manual tool
+                print(f"WARNING: could not close {pane_id}: {exc}", file=sys.stderr)
+
+    print("\nResults:")
+    ok = True
+    for name, passed in results.items():
+        print(f"  {'PASS' if passed else 'FAIL'}  {name}")
+        ok = ok and passed
+    print("\nSMOKE " + ("PASSED" if ok else "FAILED"))
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

code_puppy_core_plugins/herdr/sources.py

@@ -0,0 +1,133 @@
+"""Fail-soft adapters from code-puppy internals to herdr report payloads.
+
+This is the single seam between the herdr plugin and the rest of
+code-puppy. Every function here catches ordinary runtime failures, logs at
+debug level, and returns a safe fallback -- reporting to herdr must never
+be able to disturb the agent. Reporter/client code depends only on this
+module's return shapes, and its tests mock this module.
+
+Three adapters:
+
+* :func:`current_tokens_payload` -- a static-keyed, string-valued map of
+  ``model`` / ``context`` / ``tokens`` for ``pane.report_metadata``.
+* :func:`current_session_ref` -- a stable ``(session_id, session_path)``
+  reference for ``pane.report_agent_session``.
+* :func:`activity_message` -- a short human-readable activity string for
+  the decorative ``message`` field on ``pane.report_agent``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Dict, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+#: herdr caps metadata values; keep every value comfortably short.
+_MAX_VALUE_LEN = 128
+
+
+def _compact_tokens(n: int) -> str:
+    """Render a token count compactly: 999 -> ``999``; 48200 -> ``48k``."""
+    n = int(n)
+    if n < 1000:
+        return str(n)
+    if n < 1_000_000:
+        return f"{n // 1000}k"
+    return f"{n // 1_000_000}M"
+
+
+def _clip(value: object) -> str:
+    """Coerce to a string and cap length so a payload can't balloon."""
+    text = str(value)
+    return text[:_MAX_VALUE_LEN]
+
+
+def _current_model() -> Optional[str]:
+    try:
+        from code_puppy.agents.agent_manager import get_current_agent
+
+        agent = get_current_agent()
+        if agent is None:
+            return None
+        return agent.get_model_name()
+    except Exception:
+        logger.debug("herdr: could not resolve current model", exc_info=True)
+        return None
+
+
+def current_tokens_payload() -> Optional[Dict[str, str]]:
+    """Return a static-keyed metadata map, or ``None`` when unavailable.
+
+    Keys are always ``model``, ``context``, and ``tokens``; values are
+    coerced to strings and clipped. Indicator glyphs are omitted on purpose
+    -- herdr rows already carry their own state icons. Returns ``None`` if
+    context usage can't be computed so the pane keeps its last good values
+    (which the metadata TTL eventually clears).
+    """
+    try:
+        from code_puppy.token_usage import get_current_usage
+
+        usage = get_current_usage()
+        if usage is None:
+            return None
+        payload: Dict[str, str] = {
+            "context": _clip(f"{round(usage.percent)}%"),
+            "tokens": _clip(
+                f"{_compact_tokens(usage.total_tokens)}/{_compact_tokens(usage.capacity)}"
+            ),
+        }
+        model = _current_model()
+        if model:
+            payload["model"] = _clip(model)
+        return payload
+    except Exception:
+        logger.debug("herdr: token payload unavailable", exc_info=True)
+        return None
+
+
+def current_session_ref() -> Optional[Tuple[str, str]]:
+    """Return ``(session_id, session_path)`` for the process's autosave.
+
+    The name is stable for the life of a session (until ``/clear``,
+    ``/session new``, resume, load, or rotation), and the pickle path stays
+    canonical because the CLI pins the resolved stem and writes later saves
+    to ``AUTOSAVE_DIR``. Returns ``None`` on any failure.
+    """
+    try:
+        from pathlib import Path
+
+        from code_puppy.config import AUTOSAVE_DIR, get_current_session_name
+        from code_puppy.session_storage import build_session_paths
+
+        name = get_current_session_name()
+        if not name:
+            return None
+        paths = build_session_paths(Path(AUTOSAVE_DIR), name)
+        return name, str(paths.pickle_path)
+    except Exception:
+        logger.debug("herdr: session ref unavailable", exc_info=True)
+        return None
+
+
+def activity_message(tool_name: str) -> str:
+    """Return a short activity string for a starting tool call.
+
+    ``read_file`` -> ``running read file``. Fail-soft: an odd or missing
+    name degrades to a generic ``running tool``.
+    """
+    try:
+        humanized = str(tool_name).replace("_", " ").strip()
+        if not humanized:
+            return "running tool"
+        return f"running {humanized}"
+    except Exception:
+        logger.debug("herdr: could not humanize tool name", exc_info=True)
+        return "running tool"
+
+
+__all__ = [
+    "current_tokens_payload",
+    "current_session_ref",
+    "activity_message",
+]

code_puppy_core_plugins/hook_creator/__init__.py

@@ -0,0 +1 @@
+# Hook Creator Plugin

code_puppy_core_plugins/hook_creator/register_callbacks.py

@@ -0,0 +1,33 @@
+"""
+Hook Creator Plugin - Simple command that injects MCP prompt
+"""
+
+from code_puppy.callbacks import register_callback
+from code_puppy.mcp_prompts.hook_creator import HOOK_CREATION_PROMPT
+from code_puppy.messaging import emit_info
+
+
+def _custom_help():
+    """Help entries for create-hook commands."""
+    return [
+        ("create-hook", "Get help creating Code Puppy hooks"),
+    ]
+
+
+def _handle_custom_command(command: str, name: str):
+    """Handle /create-hook command.
+
+    Displays hook creation documentation and sends to model with context.
+    """
+    if name != "create-hook":
+        return None
+
+    emit_info(HOOK_CREATION_PROMPT)
+
+    # Send the prompt to the model with the hook docs as context
+    return "I need help creating a hook for Code Puppy. Here's the documentation above. Can you help me?"
+
+
+# Register the custom command
+register_callback("custom_command_help", _custom_help)
+register_callback("custom_command", _handle_custom_command)

code_puppy_core_plugins/hook_manager/__init__.py

@@ -0,0 +1 @@
+"""Hook Manager plugin – interactive TUI for managing Claude Code hooks."""