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

code_puppy_core_plugins/prune/register_callbacks.py

@@ -0,0 +1,388 @@
+"""Plugin that adds /prune for surgical history pruning.
+
+/prune opens a multi-select TUI of conversation history. Unlike /pop
+(which slices a contiguous tail), /prune lets the user cherry-pick
+arbitrary whole messages and rip them out. Selection granularity is
+at the message level only — individual tool calls within a message
+cannot be removed in isolation; they always travel with their parent
+message (and their matching tool returns elsewhere in history are
+cascaded out via the orphan-cleanup pass).
+
+The system prompt is always preserved.
+
+Usage:
+    /prune              Open interactive multi-select TUI
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional, Set, Tuple
+
+from code_puppy.callbacks import register_callback
+
+
+# ── messaging wrappers ──────────────────────────────────────────────────────
+
+
+def emit_error(message: Any) -> None:
+    from code_puppy.messaging import emit_error as _emit_error
+
+    _emit_error(message)
+
+
+def emit_info(message: Any) -> None:
+    from code_puppy.messaging import emit_info as _emit_info
+
+    _emit_info(message)
+
+
+def emit_success(message: Any) -> None:
+    from code_puppy.messaging import emit_success as _emit_success
+
+    _emit_success(message)
+
+
+def emit_warning(message: Any) -> None:
+    from code_puppy.messaging import emit_warning as _emit_warning
+
+    _emit_warning(message)
+
+
+# ── /help integration ───────────────────────────────────────────────────────
+
+
+def _custom_help() -> List[Tuple[str, str]]:
+    return [
+        (
+            "prune",
+            "Multi-select pruner — cherry-pick whole messages to remove",
+        )
+    ]
+
+
+# Tool-fragment pruning: remove unmatched tool parts after message drops.
+
+
+def _collect_tool_ids(history: List[Any]) -> Tuple[Set[str], Set[str]]:
+    call_ids: Set[str] = set()
+    return_ids: Set[str] = set()
+    try:
+        from pydantic_ai.messages import ToolCallPart, ToolReturnPart
+    except Exception:
+        return call_ids, return_ids
+
+    for message in history:
+        for part in getattr(message, "parts", []) or []:
+            if isinstance(part, ToolCallPart):
+                tcid = getattr(part, "tool_call_id", None)
+                if tcid:
+                    call_ids.add(tcid)
+            elif isinstance(part, ToolReturnPart):
+                tcid = getattr(part, "tool_call_id", None)
+                if tcid:
+                    return_ids.add(tcid)
+    return call_ids, return_ids
+
+
+def _has_orphaned_returns(message: Any, call_ids: Set[str]) -> bool:
+    try:
+        from pydantic_ai.messages import ModelRequest, ToolReturnPart
+
+        if not isinstance(message, ModelRequest):
+            return False
+        parts = getattr(message, "parts", []) or []
+        if not parts:
+            return False
+        if not all(isinstance(p, ToolReturnPart) for p in parts):
+            return False
+        return any(
+            not getattr(p, "tool_call_id", None) or p.tool_call_id not in call_ids
+            for p in parts
+        )
+    except Exception:
+        return False
+
+
+def _has_orphaned_calls(message: Any, return_ids: Set[str]) -> bool:
+    try:
+        from pydantic_ai.messages import ModelResponse, ToolCallPart
+
+        if not isinstance(message, ModelResponse):
+            return False
+        for part in getattr(message, "parts", []) or []:
+            if isinstance(part, ToolCallPart):
+                tcid = getattr(part, "tool_call_id", None)
+                if not tcid or tcid not in return_ids:
+                    return True
+        return False
+    except Exception:
+        return False
+
+
+def _prune_dangling_tool_fragments(history: List[Any]) -> Tuple[List[Any], int]:
+    """Strip genuinely orphaned tool-call sequences from the tail."""
+    pruned = 0
+    while history:
+        call_ids, return_ids = _collect_tool_ids(history)
+        tail = history[-1]
+        if _has_orphaned_returns(tail, call_ids):
+            history.pop()
+            pruned += 1
+            continue
+        if _has_orphaned_calls(tail, return_ids):
+            history.pop()
+            pruned += 1
+            continue
+        break
+    return history, pruned
+
+
+# ── core mutation ──────────────────────────────────────────────────────────
+
+
+def _collect_removed_tool_call_ids(
+    history: List[Any],
+    drop_indices: Set[int],
+) -> Set[str]:
+    """Compute the full set of tool_call_ids whose returns must also go.
+
+    Collects every ToolCallPart id living inside the messages we're
+    dropping wholesale, so the matching ToolReturnPart fragments
+    elsewhere in history can be cascaded out as orphans.
+    """
+    removed: Set[str] = set()
+    try:
+        from pydantic_ai.messages import ModelResponse, ToolCallPart
+    except Exception:
+        return removed
+
+    for hist_idx in drop_indices:
+        if hist_idx < 0 or hist_idx >= len(history):
+            continue
+        msg = history[hist_idx]
+        if not isinstance(msg, ModelResponse):
+            continue
+        for part in getattr(msg, "parts", []) or []:
+            if isinstance(part, ToolCallPart):
+                tcid = getattr(part, "tool_call_id", None)
+                if tcid:
+                    removed.add(tcid)
+    return removed
+
+
+def _message_carries_system_prompt(message: Any) -> bool:
+    """True if ``message`` is a ModelRequest containing a SystemPromptPart.
+
+    Matches both a standalone system message and pydantic-ai's bundled
+    ``SystemPromptPart + UserPromptPart`` request.
+    """
+    try:
+        from pydantic_ai.messages import ModelRequest, SystemPromptPart
+    except Exception:
+        return False
+    if not isinstance(message, ModelRequest):
+        return False
+    for part in getattr(message, "parts", []) or []:
+        if isinstance(part, SystemPromptPart):
+            return True
+    return False
+
+
+def _message_has_orphan_tool_return(message: Any, orphan_call_ids: Set[str]) -> bool:
+    """True if ``message`` is a ModelRequest carrying a ToolReturnPart
+    whose ``tool_call_id`` is in ``orphan_call_ids``.
+
+    Used to cascade-drop messages that would otherwise leave the model
+    looking at a tool result with no matching tool call (which providers
+    like Anthropic reject outright).
+    """
+    if not orphan_call_ids:
+        return False
+    try:
+        from pydantic_ai.messages import ModelRequest, ToolReturnPart
+
+        try:
+            from pydantic_ai.messages import RetryPromptPart  # type: ignore
+        except Exception:  # pragma: no cover — older pydantic-ai
+            RetryPromptPart = None  # type: ignore[assignment]
+    except Exception:
+        return False
+    if not isinstance(message, ModelRequest):
+        return False
+    reply_kinds: tuple = (ToolReturnPart,)
+    if RetryPromptPart is not None:
+        reply_kinds = (ToolReturnPart, RetryPromptPart)
+    for part in getattr(message, "parts", []) or []:
+        if isinstance(part, reply_kinds):
+            tcid = getattr(part, "tool_call_id", None)
+            if tcid and tcid in orphan_call_ids:
+                return True
+    return False
+
+
+def _perform_prune(drop_indices: Set[int]) -> None:
+    """Apply the prune selection to current agent history.
+
+    Operates on whole messages only: each index in ``drop_indices`` is
+    removed from history, any ToolReturnPart messages whose matching
+    ToolCallPart was dropped are cascade-removed, and orphaned
+    tool-call/return fragments at the tail are cleaned up.
+    """
+    from code_puppy.agents.agent_manager import get_current_agent
+
+    try:
+        agent = get_current_agent()
+    except Exception as exc:
+        emit_error(f"/prune: could not get current agent – {exc}")
+        return
+
+    history: List[Any] = list(agent.get_message_history())
+    if not history:
+        emit_warning("/prune: conversation history is empty – nothing to remove")
+        return
+
+    # Ignore invalid indices and SystemPromptPart messages; the system identity
+    # must never be pruned.
+    drop_indices = {
+        i
+        for i in drop_indices
+        if 0 <= i < len(history) and not _message_carries_system_prompt(history[i])
+    }
+
+    if not drop_indices:
+        emit_info("/prune: nothing selected – history unchanged")
+        return
+
+    # First pass: figure out which tool_call_ids belonged to dropped
+    # messages so we can cascade-drop their orphaned returns elsewhere.
+    orphan_call_ids = _collect_removed_tool_call_ids(history, drop_indices)
+
+    before_count = len(history)
+
+    new_history: List[Any] = []
+    msgs_dropped = 0
+    cascade_dropped = 0
+
+    for hist_idx, msg in enumerate(history):
+        if hist_idx in drop_indices:
+            msgs_dropped += 1
+            continue
+        if _message_has_orphan_tool_return(msg, orphan_call_ids):
+            cascade_dropped += 1
+            continue
+        new_history.append(msg)
+
+    new_history, extra_pruned = _prune_dangling_tool_fragments(new_history)
+    after_count = len(new_history)
+
+    try:
+        agent.set_message_history(new_history)
+    except Exception as exc:
+        emit_error(f"/prune: failed to update message history – {exc}")
+        return
+
+    summary_lines = [
+        ":scissors: Prune complete.",
+        f"  · {msgs_dropped} message(s) removed by selection",
+    ]
+    if cascade_dropped:
+        summary_lines.append(
+            f"  · {cascade_dropped} message(s) cascade-dropped (orphaned tool returns)"
+        )
+    if extra_pruned:
+        summary_lines.append(
+            f"  · {extra_pruned} dangling tool fragment(s) cleaned from tail"
+        )
+    summary_lines.append(
+        f":scroll: History: {before_count - 1} → {max(after_count - 1, 0)} message(s) "
+        f"(excluding system prompt)"
+    )
+
+    emit_success("\n".join(summary_lines))
+
+    if after_count <= 1:
+        emit_info(":bulb: History is now empty (system prompt only). Starting fresh!")
+
+
+# ── /prune dispatch ────────────────────────────────────────────────────────
+
+
+def _handle_prune_command(command: str) -> bool:
+    del command  # /prune takes no arguments anymore
+    _launch_menu()
+    return True
+
+
+def _launch_menu() -> None:
+    from code_puppy.agents.agent_manager import get_current_agent
+
+    try:
+        agent = get_current_agent()
+    except Exception as exc:
+        emit_error(f"/prune: could not get current agent – {exc}")
+        return
+
+    raw_history: List[Any] = list(agent.get_message_history())
+
+    # Sibling modules within the same package.
+    from code_puppy_core_plugins.prune.prune_menu import PruneMenu
+    from code_puppy_core_plugins.prune.prune_model import (
+        ContextBudget,
+        annotate_context_window,
+        build_message_entries,
+    )
+
+    entries = build_message_entries(raw_history)
+    # Locked rows are non-prunable, so an all-locked list has nothing to toggle.
+    if not entries or all(e.is_locked for e in entries):
+        emit_info("/prune: no prunable messages")
+        return
+
+    # Annotate token counts and in-context flags. Failures are silent —
+    # the menu just won't show the indicators.
+    try:
+        budget = annotate_context_window(entries, raw_history, agent)
+    except Exception:
+        budget = ContextBudget()
+
+    try:
+        menu = PruneMenu(entries=entries, budget=budget)
+    except ValueError as exc:
+        emit_info(f"/prune: {exc}")
+        return
+
+    selection = menu.run()
+
+    if selection is None:
+        emit_info("/prune: cancelled")
+        return
+
+    if selection.is_empty:
+        emit_info("/prune: nothing selected – history unchanged")
+        return
+
+    _perform_prune(selection.history_indices_to_drop)
+
+
+# ── custom_command plumbing ────────────────────────────────────────────────
+
+
+def _handle_custom_command(command: str, name: str) -> Optional[bool]:
+    if name != "prune":
+        return None
+    return _handle_prune_command(command)
+
+
+register_callback("custom_command_help", _custom_help)
+register_callback("custom_command", _handle_custom_command)
+
+
+__all__ = [
+    "_collect_removed_tool_call_ids",
+    "_custom_help",
+    "_handle_custom_command",
+    "_handle_prune_command",
+    "_message_has_orphan_tool_return",
+    "_perform_prune",
+    "_prune_dangling_tool_fragments",
+]

code_puppy_core_plugins/puppy_kennel/README.md

@@ -0,0 +1,203 @@
+# Puppy Kennel
+
+Local-first memory for Code Puppy. Inspired by [MemKennel](https://github.com/MemKennel/memkennel)'s
+wings → rooms → drawers model, but backed by **SQLite + FTS5** instead of
+ChromaDB. No daemon, no API key, no cloud, multi-process safe via WAL mode.
+
+## Why not just use MemKennel / Mem0 / Chroma?
+
+We looked. Hard. The summary:
+
+- **MemKennel** — Beautiful concepts, but ChromaDB's embedded `PersistentClient`
+  is not safe across multiple processes hitting the same kennel. Upstream issues
+  #1581, #948, #1646 are all flavors of "we need a daemon to make this work."
+  We run 20 puppies sometimes. A daemon is not in the cards.
+- **Mem0** — Open issue #4892: "concurrent AsyncMemory writes corrupt Qdrant
+  HNSW index." Same disease. Also requires an LLM API key just to *store*
+  memories, and phones home to PostHog by default. No thanks.
+- **ChromaDB / Qdrant / Faiss directly** — All ANN-index-backed; all multi-
+  process-hostile in embedded mode. ANN is only worth the trouble at >100K
+  vectors. We're nowhere near that.
+
+SQLite has had production-grade full-text search (FTS5, BM25-ranked) since
+2015 and has been multi-process safe via WAL since 2010. We do not need
+anything fancier.
+
+## Wing namespacing — compartmentalization without isolation walls
+
+Three wing namespaces, all in one shared kennel:
+
+| Wing | Example | Purpose |
+|---|---|---|
+| `repo:<path>` | `repo:/Users/mike/code/foo` | Project memory, shared across agents |
+| `agent:<name>` | `agent:code-puppy` | Per-agent diary, private by convention |
+| `user:default` | `user:default` | Cross-cutting user preferences |
+
+Privacy is by convention, not encryption. If you need cryptographic
+isolation for a sensitive-data agent, run that agent with
+`PUPPY_KENNEL_ROOT` pointed at a private directory.
+
+## What it does today
+
+**Phase 1 — passive memory:**
+- **`load_prompt`** — injects a tiered, budget-aware recall block (see
+  [the packer](#the-packer) below) into the system prompt.
+- **`agent_run_end`** — writes the agent's response to a single drawer
+  in the current ``repo:<cwd>`` wing.
+
+## Wing semantics (Phase 5)
+
+The three wings model **who the memory is for**, not who wrote it:
+
+| Wing | Active when... | Filled by... |
+|---|---|---|
+| ``user:default`` | always (cross-cutting) | explicit ``kennel_remember(wing="user")`` only |
+| ``repo:<cwd>`` | cwd matches | autosave + ``kennel_remember(wing="repo")`` (default) |
+| ``agent:<name>`` | selected agent matches | explicit ``kennel_remember(wing="agent")`` only |
+
+Autosave goes **only** to the repo wing — every response is "a
+conversation that happened in this project," which is genuinely
+repo-scoped. The agent wing is reserved for deliberate cross-project
+reflections; ``user:default`` is for facts about the human.
+
+This kills the previous dual-write design (where each response wrote
+twice, once per wing). Search-time dedup is still in place for any
+legacy duplicates and for content the agent explicitly mirrors into a
+second wing.
+
+## The packer
+
+The recall block is assembled by `packer.py` under a configurable token
+budget. Three priority classes, no LLM, no embeddings:
+
+| Tier | Source | Quota (default) | Why |
+|---|---|---|---|
+| **P0** User Preferences | `user:default` wing, any role | ~30% | Short, durable, pervasive ('Mike hates emojis') |
+| **P1** Project Decisions | `repo:<cwd>` wing, `role='note'` | ~30% | Sticky writes from `kennel_remember` — highest signal-to-token ratio |
+| **P2** Recent Context | `repo:<cwd>` wing, `role='assistant'` | remainder | Orientation, freshness |
+
+Drawers below `PUPPY_KENNEL_MIN_DRAWER_CHARS` (default 80) are skipped
+as noise. Token estimation uses the well-known 1-token ≈ 4-chars
+heuristic — accurate to ±20%, zero deps.
+
+**Config knobs:**
+
+| Env var | Default | Effect |
+|---|---|---|
+| `PUPPY_KENNEL_PROMPT_BUDGET` | `1500` | Total token budget for the block |
+| `PUPPY_KENNEL_USER_PREFS_QUOTA` | `0.30` | P0 fraction |
+| `PUPPY_KENNEL_STICKY_QUOTA` | `0.30` | P1 fraction |
+| `PUPPY_KENNEL_MIN_DRAWER_CHARS` | `80` | Noise filter |
+
+**Phase 2 — active tooling:**
+
+Five agent-callable tools registered via ``register_tools``:
+
+| Tool | Purpose |
+|---|---|
+| `kennel_recall(query, wing?, top_k=5, scope=?)` | BM25 search across wings, deduplicated. |
+| `kennel_remember(content, wing="repo", room="notes")` | Explicit verbatim write to a chosen wing. |
+| `kennel_recent(wing?, top_k=5, scope=?)` | Time-ordered drawer browsing (no query needed). |
+| `kennel_list_wings()` | Discover all wings + drawer counts. |
+| `kennel_stats()` | Kennel-wide totals + on-disk size. |
+
+Wing shortcuts accepted by every tool: ``"repo"`` (current project,
+default for writes), ``"agent"`` (this agent's diary), ``"user"``
+(cross-cutting preferences), or an explicit wing name like
+``"team:platform"``.
+
+Scope shortcuts for multi-wing reads: ``"default"`` (repo+agent+user),
+``"repo"``, ``"agent"``, ``"user"``, ``"all"``.
+
+Plus a **`/kennel`** slash command suite for humans:
+
+| Command | What it does |
+|---|---|
+| `/kennel` | stats + recent context preview |
+| `/kennel search <q>` | BM25 search across default scope |
+| `/kennel wings` | list wings + drawer counts |
+| `/kennel stats` | DB size, totals, current enabled state |
+| `/kennel status` | is memory currently on or off? |
+| `/kennel enable` (or `on`) | turn memory on at runtime |
+| `/kennel disable` (or `off`) | turn memory off at runtime (drawers preserved) |
+| `/kennel help` | usage hint |
+
+## Enable / disable
+
+The plugin is **disabled by default** — running in the background on
+noise is off until you opt in. Flip it with the slash commands:
+
+- ``/kennel enable`` (or ``/kennel on``) — turn memory on
+- ``/kennel disable`` (or ``/kennel off``) — turn memory off
+
+State is persisted to ``puppy.cfg`` under ``kennel_enabled`` and read on
+every callback, so the toggle is live — no restart needed, and the
+front end can read or write the same value.
+
+**When disabled:**
+
+- ``load_prompt`` returns ``None`` (no recall block in system prompt)
+- ``agent_run_end`` is a no-op (nothing recorded)
+- Agent-facing tools return a friendly ``error`` field explaining memory is off
+- **The ``/kennel`` slash suite stays available** — ``/kennel stats``,
+  ``/kennel wings``, ``/kennel search`` all still work so the operator
+  can see what's stored, and ``/kennel enable`` is always reachable to
+  turn it back on.
+
+## Known tech debt
+
+- **Legacy duplicates.** Kennels that pre-date Phase 5 may contain
+  dual-written drawers (same content in repo + agent wings).
+  ``search_drawers_multi`` deduplicates by content so reads are sane;
+  they'll age out naturally once retention/pruning ships.
+
+## What's still coming
+
+- `stream_event` hook to also capture user input (not just agent output).
+- Optional `fastembed` semantic re-ranking on top of FTS5 BM25.
+- `/kennel prune` retention policy.
+
+## Environment
+
+| Variable | Default | Effect |
+|---|---|---|
+| `PUPPY_KENNEL_ROOT` | `~/.code_puppy/kennel` | Where the SQLite file lives |
+| `PUPPY_KENNEL_PASSIVE_LIMIT` | `5` | Drawers surfaced in passive recall |
+| `PUPPY_KENNEL_MAX_DRAWER_CHARS` | `32000` | Cap on stored drawer size |
+
+## puppy.cfg keys
+
+| Key | Default | Effect |
+|---|---|---|
+| `kennel_enabled` | unset → disabled | Single source of truth for the on/off toggle. Set to `true`/`1`/`yes`/`on` (case-insensitive) to enable. Anything else — missing, blank, or garbage — leaves the kennel off. Flipped live by `/kennel enable` and `/kennel disable`. |
+
+## How tools reach the agent
+
+Code Puppy agents expose a hardcoded ``get_available_tools()`` list. To get
+plugin tools onto that list without editing every agent, this plugin uses
+the ``register_agent_tools`` hook — a small piece of core architecture
+added alongside this plugin specifically to avoid that pattern.
+
+``register_tools`` defines tools and drops them into ``TOOL_REGISTRY``;
+``register_agent_tools`` says *which* tools to advertise to *which* agent.
+The puppy_kennel plugin always returns all five tool names regardless of
+agent — memory is universally useful. Other plugins can scope per-agent by
+branching on the ``agent_name`` argument.
+
+## Files
+
+```
+puppy_kennel/
+├── __init__.py
+├── config.py              # paths, env vars, limits
+├── schema.py              # CREATE TABLE + PRAGMA strings
+├── kennel.py              # storage layer (wings, rooms, drawers)
+├── wings.py               # wing-naming convention
+├── recorder.py            # agent_run_end -> drawer
+├── retriever.py           # load_prompt -> recall block
+├── register_callbacks.py  # hook wiring (entry point)
+└── README.md              # you are here
+```
+
+All files under 200 lines, every concern its own module, no SQL leaking
+outside `kennel.py`. SOLID, DRY, Zen-of-Python-compatible. Cheers.

code_puppy_core_plugins/puppy_kennel/__init__.py

@@ -0,0 +1,6 @@
+"""Puppy Kennel — local-first memory for Code Puppy.
+
+Inspired by MemKennel's wings → rooms → drawers model, but backed by
+SQLite + FTS5 instead of ChromaDB. No daemon, no API key, no cloud,
+multi-process safe via WAL mode.
+"""