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

code_puppy_core_plugins/puppy_kennel/packer.py

@@ -0,0 +1,152 @@
+"""Tiered budget-aware packing for the system-prompt recall block.
+
+Three priority classes, fed from the kennel, sized to fit a configurable
+token budget without ever calling an LLM or shipping a tokenizer:
+
+* **P0 - user preferences**: every drawer in ``user:default``. Short,
+  durable, pervasive ("Mike hates emojis"). Capped at ~30% of budget.
+* **P1 - sticky repo notes**: drawers in ``repo:<cwd>`` with ``role='note'``,
+  i.e. content written via the ``kennel_remember`` tool. Highest signal-to-
+  token ratio in the kennel. Capped at ~30% of budget.
+* **P2 - recent assistant responses**: drawers in ``repo:<cwd>`` with
+  ``role='assistant'``. Fills whatever budget remains after P0 + P1.
+
+Token budget is enforced via the well-known 1-token approximate-4-chars
+heuristic. Cheap, zero-dep, accurate to plus-or-minus 20% which is fine
+for "do not blow the context."
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from . import kennel
+from .config import (
+    CHARS_PER_TOKEN,
+    MIN_DRAWER_CHARS,
+    PROMPT_BUDGET_CHARS,
+    PROMPT_BUDGET_TOKENS,
+    STICKY_QUOTA,
+    USER_PREFS_QUOTA,
+)
+from .kennel import Drawer
+from .wings import USER_WING, detect_cwd, repo_wing
+
+# Reserve ~50 tokens for rendered headers and section dividers.
+_HEADER_SLACK_CHARS = 50 * CHARS_PER_TOKEN
+
+# We over-fetch from SQLite then truncate to fit. Cheap, simple.
+_FETCH_LIMIT = 50
+
+# Below this remainder, a new drawer would be mostly "...truncated]".
+_MIN_REMAINING_CHARS = 120
+
+
+@dataclass(slots=True)
+class PackSection:
+    title: str
+    lines: list[str]
+    used_chars: int
+
+
+def _agent_label(d: Drawer) -> str:
+    meta = d.metadata or {}
+    return str(meta.get("agent") or d.role or "?")
+
+
+def _format_drawer(d: Drawer, max_chars: int) -> str:
+    """Render one drawer to a markdown bullet, fitting within ``max_chars``.
+
+    The bullet looks like ``- [ts] _agent_ : content...`` with the content
+    truncated as needed. Returns an empty string if the bullet skeleton
+    alone wouldn't fit.
+    """
+    head = f"- [{d.ts}] _{_agent_label(d)}_ : "
+    if max_chars <= len(head) + 20:
+        return ""
+    body_budget = max_chars - len(head)
+    body = d.content.strip().replace("\n", " ")
+    if len(body) > body_budget:
+        body = body[: body_budget - 1].rstrip() + "..."
+    return head + body
+
+
+def _pack_class(
+    drawers: list[Drawer],
+    budget_chars: int,
+    min_chars: int = MIN_DRAWER_CHARS,
+) -> PackSection:
+    """Greedily pack drawers into ``budget_chars``, newest first.
+
+    Skips drawers smaller than ``min_chars`` (probably noise). Truncates
+    the last drawer if it would otherwise push us over. Stops once the
+    remaining budget gets too small to be useful.
+    """
+    lines: list[str] = []
+    used = 0
+    for d in drawers:
+        if len(d.content.strip()) < min_chars:
+            continue
+        remaining = budget_chars - used
+        if remaining < _MIN_REMAINING_CHARS:
+            break
+        rendered = _format_drawer(d, max_chars=remaining)
+        if not rendered:
+            break
+        lines.append(rendered)
+        used += len(rendered) + 1  # +1 for the newline that joins them
+    return PackSection(title="", lines=lines, used_chars=used)
+
+
+def pack(cwd_override: str | None = None) -> str | None:
+    """Build the system-prompt recall block under the configured budget.
+
+    Returns ``None`` when there is nothing useful to surface (empty kennel,
+    every drawer too short, etc.) - the ``load_prompt`` callback contract
+    interprets ``None`` as "skip me".
+    """
+    cwd = cwd_override if cwd_override is not None else detect_cwd()
+    repo_w = repo_wing(cwd)
+
+    total_budget = max(0, PROMPT_BUDGET_CHARS - _HEADER_SLACK_CHARS)
+    p0_budget = int(total_budget * USER_PREFS_QUOTA)
+    p1_budget = int(total_budget * STICKY_QUOTA)
+
+    # P0: user preferences; include every role because user notes may be assistant-authored.
+    user_drawers = kennel.recent_drawers(USER_WING, limit=_FETCH_LIMIT)
+    p0 = _pack_class(user_drawers, p0_budget)
+    p0.title = "User Preferences"
+
+    # P1: repo sticky notes (role='note' only).
+    sticky = kennel.recent_drawers(repo_w, limit=_FETCH_LIMIT, role="note")
+    p1 = _pack_class(sticky, p1_budget)
+    p1.title = "Project Decisions"
+
+    # P2: recent assistant responses fill the remainder.
+    p2_budget = total_budget - p0.used_chars - p1.used_chars
+    assistant = kennel.recent_drawers(repo_w, limit=_FETCH_LIMIT, role="assistant")
+    p2 = _pack_class(assistant, max(0, p2_budget))
+    p2.title = "Recent Context"
+
+    sections = [s for s in (p0, p1, p2) if s.lines]
+    if not sections:
+        return None
+
+    return _render(sections, repo_w)
+
+
+def _render(sections: list[PackSection], repo_w: str) -> str:
+    """Render the packed sections into the final markdown block."""
+    out: list[str] = [
+        "## Puppy Kennel - Memory",
+        (
+            f"_Repo wing: `{repo_w}` | token budget: "
+            f"{PROMPT_BUDGET_TOKENS} (~{PROMPT_BUDGET_CHARS} chars)_"
+        ),
+        "",
+    ]
+    for s in sections:
+        out.append(f"### {s.title}")
+        out.extend(s.lines)
+        out.append("")
+    return "\n".join(out)

code_puppy_core_plugins/puppy_kennel/recorder.py

@@ -0,0 +1,83 @@
+"""Recorder — captures agent runs into the kennel.
+
+Fires on ``agent_run_end``. The recorder writes the agent's response to
+**one** wing: the current repo wing. The autosave path treats every
+response as "a conversation that happened in this project" — that's the
+honest framing.
+
+Cross-project agent reflections belong in ``agent:<name>`` and are an
+opt-in concern handled by the ``kennel_remember`` tool, not autosave.
+User preferences likewise live in ``user:default`` and only land there
+via explicit ``kennel_remember`` calls.
+
+Capturing user input is a phase-2 concern that will hook ``stream_event``
+instead.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from code_puppy.messaging.bus import emit_debug
+
+from . import kennel
+from .state import is_enabled
+from .wings import detect_cwd, repo_wing
+
+
+def _room_name(session_id: str | None) -> str:
+    """Rooms partition a wing by session. Keep the name human-scannable."""
+    if not session_id:
+        return "session-unknown"
+    short = session_id.split("-")[0][:12] if "-" in session_id else session_id[:12]
+    return f"session-{short}"
+
+
+def record_run_end(
+    agent_name: str,
+    model_name: str,
+    session_id: str | None = None,
+    success: bool = True,
+    error: Exception | None = None,
+    response_text: str | None = None,
+    metadata: dict | None = None,
+) -> None:
+    """Persist the agent's final response into the kennel.
+
+    Writes a single drawer to the repo wing (shared project memory).
+    Failures here must never crash the host app — the kennel is best-
+    effort memory, not a transactional system of record.
+    """
+    if not response_text or not response_text.strip():
+        return
+    if not success:
+        # Don't memorialize broken runs. The error log is the right place.
+        return
+    if not is_enabled():
+        # Memory is toggled off — silently skip. Slash commands surface state.
+        return
+
+    try:
+        cwd = detect_cwd()
+        room = _room_name(session_id)
+        drawer_meta: dict[str, Any] = {
+            "agent": agent_name,
+            "model": model_name,
+            "cwd": str(cwd),
+        }
+        if metadata:
+            drawer_meta["run_metadata"] = metadata
+
+        # Shared project memory — the only autosave destination.
+        repo_w = repo_wing(cwd)
+        repo_wing_id = kennel.ensure_wing(repo_w)
+        repo_room_id = kennel.ensure_room(repo_wing_id, room)
+        kennel.add_drawer(
+            repo_room_id,
+            content=response_text,
+            role="assistant",
+            session_id=session_id,
+            metadata=drawer_meta,
+        )
+    except Exception as exc:  # noqa: BLE001 — best-effort memory.
+        emit_debug(f"[puppy_kennel] recorder skipped: {exc!r}")

code_puppy_core_plugins/puppy_kennel/register_callbacks.py

@@ -0,0 +1,109 @@
+"""Register puppy_kennel with Code Puppy's callback system.
+
+Hooks wired:
+* ``load_prompt``         -> passive recall block in the system prompt
+* ``agent_run_end``       -> record the agent's response as a verbatim drawer
+* ``register_tools``      -> defines kennel tools in ``TOOL_REGISTRY``
+* ``register_agent_tools``-> advertises kennel tools to every agent's tool list
+* ``custom_command``      -> handles ``/kennel`` and subcommands
+* ``custom_command_help`` -> advertises ``/kennel`` in the /help menu
+"""
+
+from __future__ import annotations
+
+from code_puppy.callbacks import register_callback
+from code_puppy.messaging.bus import emit_debug
+
+from . import commands, kennel, tools
+from .recorder import record_run_end
+from .retriever import build_recall_block
+from .state import is_enabled
+
+
+def _initialize_once() -> bool:
+    """Create the SQLite schema on first import. Idempotent + fail-soft."""
+    try:
+        kennel.initialize()
+        return True
+    except Exception as exc:  # noqa: BLE001 — plugin must never crash boot.
+        emit_debug(f"[puppy_kennel] init failed, disabling: {exc!r}")
+        return False
+
+
+def _on_load_prompt() -> str | None:
+    """Sync hook — returns a text fragment or None."""
+    try:
+        return build_recall_block()
+    except Exception as exc:  # noqa: BLE001
+        emit_debug(f"[puppy_kennel] load_prompt skipped: {exc!r}")
+        return None
+
+
+def _on_agent_run_end(
+    agent_name: str,
+    model_name: str,
+    session_id: str | None = None,
+    success: bool = True,
+    error: Exception | None = None,
+    response_text: str | None = None,
+    metadata: dict | None = None,
+) -> None:
+    """Async-compatible hook (sync body, runner accepts either)."""
+    record_run_end(
+        agent_name=agent_name,
+        model_name=model_name,
+        session_id=session_id,
+        success=success,
+        error=error,
+        response_text=response_text,
+        metadata=metadata,
+    )
+
+
+_KENNEL_TOOL_NAMES = (
+    "kennel_recall",
+    "kennel_remember",
+    "kennel_recent",
+    "kennel_list_wings",
+    "kennel_stats",
+)
+
+
+def _register_kennel_memory():
+    """Expose the recall block through the neutral provider seam.
+
+    Returned to core via the ``register_kennel_memory`` callback phase; core
+    consumes it through ``code_puppy.kennel_provider``. Disabling the kennel
+    makes ``build_recall_block`` return ``None``, so providers are resolved
+    per call and the stale-registration problem never appears.
+    """
+    if not is_enabled():
+        return None
+    return build_recall_block
+
+
+def _advertise_tools_to_agent(agent_name: str | None = None) -> list[str]:
+    """``register_agent_tools`` callback — advertise kennel tools to every agent.
+
+    Agnostic to ``agent_name`` for now: memory is universally useful, no
+    agent currently has a reason to opt out. If that changes, branch here.
+
+    When the kennel is toggled off via ``/kennel disable``, we advertise
+    NO tools — the agent shouldn't see (and definitely shouldn't try to
+    call) memory tools that will just bounce with ``DISABLED_TOOL_ERROR``.
+    The slash command pairs this with an agent reload so the tool list
+    actually shrinks/grows live.
+    """
+    if not is_enabled():
+        return []
+    return list(_KENNEL_TOOL_NAMES)
+
+
+if _initialize_once():
+    register_callback("load_prompt", _on_load_prompt)
+    register_callback("agent_run_end", _on_agent_run_end)
+    register_callback("register_tools", tools.register_tools_callback)
+    register_callback("register_agent_tools", _advertise_tools_to_agent)
+    register_callback("register_kennel_memory", _register_kennel_memory)
+    register_callback("custom_command", commands.handle)
+    register_callback("custom_command_help", commands.help_entries)

code_puppy_core_plugins/puppy_kennel/retriever.py

@@ -0,0 +1,28 @@
+"""Retriever - surfaces kennel context into the system prompt.
+
+Fires on ``load_prompt``. The actual packing logic lives in ``packer.py``;
+this module is a thin wrapper that enforces the enable/disable toggle and
+swallows any storage-layer hiccups so the host app never breaks.
+"""
+
+from __future__ import annotations
+
+from . import packer
+from .state import is_enabled
+
+_EMPTY_RETURN = None  # Returning None tells the callback system "skip me."
+
+
+def build_recall_block() -> str | None:
+    """Return a system-prompt fragment built by the tiered packer.
+
+    Returns ``None`` when the kennel is disabled, empty, or otherwise has
+    nothing worth surfacing this turn.
+    """
+    if not is_enabled():
+        return _EMPTY_RETURN
+    try:
+        return packer.pack()
+    except Exception:
+        # Storage isn't ready yet, or the kennel is unhappy. Stay quiet.
+        return _EMPTY_RETURN

code_puppy_core_plugins/puppy_kennel/schema.py

@@ -0,0 +1,78 @@
+"""SQLite schema for the puppy_kennel.
+
+Three core tables mirror MemKennel's mental model:
+
+* ``wings``   — top-level partitions (typically a repo / project / agent)
+* ``rooms``   — topical sub-partitions within a wing (one per session, usually)
+* ``drawers`` — verbatim content chunks (a message, a response, etc.)
+
+An FTS5 virtual table indexes drawer content for BM25 keyword retrieval.
+Triggers keep the FTS table in sync with the base table automatically.
+"""
+
+from __future__ import annotations
+
+SCHEMA_SQL = """
+CREATE TABLE IF NOT EXISTS wings (
+    id           INTEGER PRIMARY KEY,
+    name         TEXT NOT NULL UNIQUE,
+    created_at   TEXT NOT NULL,
+    metadata     TEXT
+);
+
+CREATE TABLE IF NOT EXISTS rooms (
+    id           INTEGER PRIMARY KEY,
+    wing_id      INTEGER NOT NULL REFERENCES wings(id) ON DELETE CASCADE,
+    name         TEXT NOT NULL,
+    created_at   TEXT NOT NULL,
+    metadata     TEXT,
+    UNIQUE(wing_id, name)
+);
+
+CREATE TABLE IF NOT EXISTS drawers (
+    id           INTEGER PRIMARY KEY,
+    room_id      INTEGER NOT NULL REFERENCES rooms(id) ON DELETE CASCADE,
+    role         TEXT,
+    content      TEXT NOT NULL,
+    ts           TEXT NOT NULL,
+    session_id   TEXT,
+    metadata     TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_drawers_room    ON drawers(room_id);
+CREATE INDEX IF NOT EXISTS idx_drawers_session ON drawers(session_id);
+CREATE INDEX IF NOT EXISTS idx_drawers_ts      ON drawers(ts);
+CREATE INDEX IF NOT EXISTS idx_rooms_wing      ON rooms(wing_id);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS drawers_fts USING fts5(
+    content,
+    content='drawers',
+    content_rowid='id',
+    tokenize='porter unicode61'
+);
+
+-- Keep FTS in sync with drawers. Triggers are the SQLite-blessed way.
+CREATE TRIGGER IF NOT EXISTS drawers_ai AFTER INSERT ON drawers BEGIN
+    INSERT INTO drawers_fts(rowid, content) VALUES (new.id, new.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS drawers_ad AFTER DELETE ON drawers BEGIN
+    INSERT INTO drawers_fts(drawers_fts, rowid, content)
+        VALUES('delete', old.id, old.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS drawers_au AFTER UPDATE ON drawers BEGIN
+    INSERT INTO drawers_fts(drawers_fts, rowid, content)
+        VALUES('delete', old.id, old.content);
+    INSERT INTO drawers_fts(rowid, content) VALUES (new.id, new.content);
+END;
+"""
+
+# Apply PRAGMAs on every connection. Set busy_timeout first: WAL's exclusive
+# lock can collide during concurrent initialization and otherwise raises immediately.
+PRAGMAS = (
+    "PRAGMA busy_timeout=5000",  # 5s grace for writers waiting on the lock.
+    "PRAGMA journal_mode=WAL",
+    "PRAGMA synchronous=NORMAL",  # WAL durability is fine at NORMAL; faster.
+    "PRAGMA foreign_keys=ON",
+)

code_puppy_core_plugins/puppy_kennel/state.py

@@ -0,0 +1,68 @@
+"""Runtime state for the puppy_kennel plugin.
+
+Single source of truth for whether the kennel is on. Flipped by the
+``/kennel enable`` and ``/kennel disable`` slash commands. Persisted in
+``puppy.cfg`` under the key ``kennel_enabled`` so the front end can read
+and write the same value.
+
+Default is **disabled** -- a missing key, blank value, or garbage value
+all leave the kennel off. Only the explicit-truthy tokens
+``{"true", "1", "yes", "on"}`` (case-insensitive) turn it on. That
+asymmetry is on purpose: on a default-off system, a typo like
+``kennel_enabled = yeas`` must not silently enable memory. In the face
+of ambiguity, refuse to guess.
+
+Reads and writes go through ``code_puppy.config.get_value`` /
+``set_config_value``, the same helpers every other plugin (statusline,
+prompt_newline, ...) uses for puppy.cfg interop.
+
+An environment override, ``PUPPY_KENNEL_ENABLED``, takes precedence over
+the persisted cfg value. This mirrors ``PUPPY_KENNEL_ROOT`` in
+``config.py`` and -- crucially -- is the only knob that survives a
+``multiprocessing`` *spawn*. Spawned children start a fresh interpreter
+and re-read the developer's REAL ``puppy.cfg`` (the test harness's config
+isolation lives in the parent process only), so without an env override a
+child silently inherits whatever the developer happens to have toggled.
+Env vars, by contrast, are inherited across the spawn boundary.
+"""
+
+from __future__ import annotations
+
+import os
+
+from code_puppy.config import get_value, set_config_value
+
+_CFG_KEY = "kennel_enabled"
+_ENV_KEY = "PUPPY_KENNEL_ENABLED"
+_TRUTHY = frozenset({"true", "1", "yes", "on"})
+
+DISABLED_TOOL_ERROR = (
+    "Puppy Kennel memory is currently disabled. "
+    "Ask the user to run `/kennel enable` to turn it back on."
+)
+
+
+def is_enabled() -> bool:
+    """Return True if the kennel is on.
+
+    Defaults to False when the key is missing, blank, or set to anything
+    that isn't one of the explicit-truthy tokens. Evaluated on every call
+    so flipping the toggle takes effect immediately -- no relaunch
+    required.
+    """
+    raw = os.environ.get(_ENV_KEY)
+    if raw is None:
+        raw = get_value(_CFG_KEY)
+    if raw is None:
+        return False
+    return str(raw).strip().lower() in _TRUTHY
+
+
+def set_enabled(value: bool) -> None:
+    """Persist the kennel enable flag to puppy.cfg (positive sense).
+
+    Writes the literal string ``"true"`` or ``"false"`` so the on-disk
+    representation is stable and any future FE consumer can parse the
+    cfg directly without going through this helper.
+    """
+    set_config_value(_CFG_KEY, "true" if value else "false")