code-puppy-core-plugins 0.0.4__tar.gz → 0.0.6__tar.gz

{code_puppy_core_plugins-0.0.4 → code_puppy_core_plugins-0.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: code-puppy-core-plugins
-Version: 0.0.4
+Version: 0.0.6
 Summary: Official plugin bundle for Code Puppy
 Project-URL: Repository, https://github.com/mpfaffenberger/code_puppy_core_plugins
 Project-URL: Homepage, https://github.com/mpfaffenberger/code_puppy_core_plugins

{code_puppy_core_plugins-0.0.4 → code_puppy_core_plugins-0.0.6}/code_puppy_core_plugins/code_puppy_agent/PLUGINS_AND_CALLBACKS.md

@@ -36,13 +36,27 @@ time. All hooks accept sync or async functions.
 | `get_model_system_prompt` | Per-model prompt patch | `dict` with `instructions`/`handled` or `None` |
 | `custom_command` | Unknown `/slash` command | `True` (handled), `str` (message), or `None` (not mine) |
 | `pre_tool_call` | Before tool executes | Can modify args |
-| `post_tool_call` | After tool finishes | Observes result + duration |
+| `post_tool_call` | After tool finishes | Observes result + duration; can mutate dict results in place |
 | `run_shell_command` | Before shell exec | Return `{"blocked": True}` to block |
 | `file_permission` | Before file op | `bool` — allow/deny |
 | `agent_run_start` / `agent_run_end` | Agent lifecycle | Observes name, model, session |
 
 The full list is in `callbacks.py` — `PhaseType` has ~45 phases.
 
+### Mutating results from `post_tool_call`
+
+The patched tool runner evaluates the result reference before awaiting
+`post_tool_call`. A callback can therefore mutate a plain dict result in
+place and the model sees the change. It cannot replace a string or other
+non-dict result by rebinding its local argument. Tool exceptions arrive
+as error-only dicts and should remain intact.
+
+Mutation is order-sensitive: result-bounding callbacks must run after
+callbacks that append content. Sync callbacks also execute on the event
+loop, so blocking work belongs in an async callback via
+`asyncio.to_thread()`. The builtin `spill` plugin is the canonical
+implementation.
+
 ## Minimal plugin example
 
 ```

{code_puppy_core_plugins-0.0.4 → code_puppy_core_plugins-0.0.6}/code_puppy_core_plugins/code_puppy_agent/SKILL.md

@@ -89,11 +89,11 @@ Plugins hook into every stage via callbacks.
 | File | Read this for |
 |------|----------------|
 | `AGENTS_AND_TOOLS.md` | How agents are structured/discovered (Python, JSON, plugin agents, precedence). How tools get registered and wired to an agent. Async-tool blocking-I/O gotcha. |
-| `PLUGINS_AND_CALLBACKS.md` | Plugin discovery tiers, the full callback hook table, a minimal plugin example, and **two hook-system gotchas** (`get_model_system_prompt` last-write-wins; don't do real work at import time) worth reading before writing any new plugin. |
+| `PLUGINS_AND_CALLBACKS.md` | Plugin discovery tiers, the callback hook table, in-place tool-result mutation and ordering, a minimal plugin example, and hook-system gotchas (`get_model_system_prompt` last-write-wins; don't do real work at import time). |
 | `MODELS_AND_MCP.md` | ModelFactory, model config precedence, model types. MCP server lifecycle, agent bindings, and a known gap (MCP servers can't yet provide skills). |
 | `SESSIONS_AND_HISTORY.md` | Message history, context-window compaction, session save/load commands. |
 | `SKILLS_SYSTEM.md` | Skill discovery/activation, bundled-resource-file gotcha for plugin-registered skills, and **skill namespaces** — how `namespace_skill_search` groups large skill catalogs and replaces the flat prompt list. |
-| `SYSTEM_PROMPT_CONFIG_AND_I18N.md` | Exact system-prompt assembly order (which layer skills/rules/patches land in), `puppy.cfg` + key directories, the messaging bus, and an i18n quick-reference (full guide: `docs/I18N.md`). |
+| `SYSTEM_PROMPT_CONFIG_AND_I18N.md` | Exact system-prompt assembly order, `puppy.cfg` + key directories, spill configuration, the messaging bus, and an i18n quick-reference (full guide: `docs/I18N.md`). |
 
 Don't guess which file has what you need — the table above is exhaustive
 for this skill's scope. If a question doesn't map cleanly to one row, it's

{code_puppy_core_plugins-0.0.4 → code_puppy_core_plugins-0.0.6}/code_puppy_core_plugins/code_puppy_agent/SYSTEM_PROMPT_CONFIG_AND_I18N.md

@@ -76,6 +76,23 @@ turning off `frontmatter_in_system_prompt` on its first run) does **not**
 automatically revert. Disabling the plugin and undoing what it already
 did to your config are two separate actions.
 
+### Bounding oversized tool results with `spill`
+
+The builtin `spill` plugin saves oversized top-level string fields to
+private files and substitutes bounded head/tail previews with retrieval
+guidance. It leaves error-only and non-dict results untouched and skips
+`read_file` by default to avoid a read → spill → read loop.
+
+| `puppy.cfg` key | Default | Meaning |
+|-----------------|---------|---------|
+| `spill_max_inline_bytes` | `32768` | Aggregate inline string-byte cap; `0` or negative disables spilling |
+| `spill_preview_bytes` | `4096` | Head-plus-tail source-byte budget per spilled field |
+| `spill_root` | unset | Storage root override; otherwise use a private OS temp directory |
+| `spill_skip_tools` | `read_file` | Comma-separated tool names that must remain inline |
+
+Storage is best-effort: any spill failure keeps the original successful
+tool result inline.
+
 ---
 
 ## Messaging & UI

code_puppy_core_plugins-0.0.6/code_puppy_core_plugins/spill/LICENSE.deepseek

@@ -0,0 +1,28 @@
+DeepSeek Harness spill attribution
+
+The spill functionality in this package is based on the spill packages from
+DeepSeek Harness:
+
+https://github.com/deepseek-ai/DeepSeek-Harness
+
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

code_puppy_core_plugins-0.0.6/code_puppy_core_plugins/spill/__init__.py

@@ -0,0 +1 @@
+"""Keep oversized dict-shaped tool results out of model context."""

code_puppy_core_plugins-0.0.6/code_puppy_core_plugins/spill/register_callbacks.py

@@ -0,0 +1,256 @@
+"""Plugin: spill oversized dict-shaped tool results to private files.
+
+Ported from DeepSeek Harness's MIT-licensed spill design. See
+``LICENSE.deepseek`` in this package for its copyright and license notice.
+
+The post-tool hook receives the same dict reference that Code Puppy later
+serializes for the model, so this plugin can replace top-level string fields
+in place. Non-dict results (notably plain strings) cannot be replaced through
+this hook and are deliberately left untouched.
+
+When the combined UTF-8 size of top-level string values exceeds the configured
+cap, fields are considered largest-first. Their full text is saved verbatim,
+then replaced by a bounded byte-sliced head/tail preview and a retrieval notice.
+``read_file`` is skipped by default to avoid a read -> spill -> read loop.
+Every failure is best-effort: the successful tool result stays available inline.
+
+Config (puppy.cfg, also settable with ``/set``):
+    spill_max_inline_bytes = 32768  # 0 or negative disables
+    spill_preview_bytes = 4096      # source bytes retained per field
+    spill_root =                    # unset uses a private OS temp directory
+    spill_skip_tools = read_file    # comma-separated tool names
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import math
+from pathlib import Path
+from typing import Any
+
+from code_puppy.callbacks import register_callback, unregister_callback
+
+from . import store
+
+logger = logging.getLogger(__name__)
+
+MAX_INLINE_KEY = "spill_max_inline_bytes"
+PREVIEW_KEY = "spill_preview_bytes"
+ROOT_KEY = "spill_root"
+SKIP_TOOLS_KEY = "spill_skip_tools"
+DEFAULT_MAX_INLINE_BYTES = 32768
+DEFAULT_PREVIEW_BYTES = 4096
+DEFAULT_SKIP_TOOLS = frozenset({"read_file"})
+OMISSION_MARKER = "\n\n[...]\n\n"
+
+
+def _get_value(key: str) -> Any:
+    try:
+        from code_puppy.config import get_value
+
+        return get_value(key)
+    except Exception:
+        return None
+
+
+def _get_int(key: str, default: int) -> int:
+    raw = _get_value(key)
+    if raw is None or str(raw).strip() == "":
+        return default
+    try:
+        return int(str(raw).strip())
+    except (TypeError, ValueError):
+        logger.warning("Invalid %s value; falling back to %d", key, default)
+        return default
+
+
+def _get_root() -> str | None:
+    raw = _get_value(ROOT_KEY)
+    if raw is None or not str(raw).strip():
+        return None
+    return str(raw).strip()
+
+
+def _get_skip_tools() -> frozenset[str]:
+    raw = _get_value(SKIP_TOOLS_KEY)
+    if raw is None or not str(raw).strip():
+        return DEFAULT_SKIP_TOOLS
+    return frozenset(name.strip() for name in str(raw).split(",") if name.strip())
+
+
+def _byte_size(text: str) -> int:
+    return len(text.encode("utf-8"))
+
+
+def _preview(text: str, budget: int) -> tuple[str, int]:
+    """Return a byte-sliced preview and the count of omitted source bytes."""
+    encoded = text.encode("utf-8")
+    kept_bytes = min(max(0, budget), len(encoded))
+    if kept_bytes == 0:
+        return "", len(encoded)
+    head_bytes = math.ceil(kept_bytes / 2)
+    tail_bytes = math.floor(kept_bytes / 2)
+    head = encoded[:head_bytes].decode("utf-8", errors="replace")
+    tail = encoded[-tail_bytes:].decode("utf-8", errors="replace") if tail_bytes else ""
+    return f"{head}{OMISSION_MARKER}{tail}", len(encoded) - kept_bytes
+
+
+def _notice(omitted: int, path: Path) -> str:
+    return (
+        f"(~{omitted} bytes omitted. Full output stored at: {path}. "
+        "Retrieve it with read_file using start_line/num_lines, or grep this path.)"
+    )
+
+
+def _build_replacement(
+    text: str,
+    path: Path,
+    preview_bytes: int,
+    max_bytes: int | None,
+) -> str | None:
+    """Build a strictly smaller replacement, optionally fitting ``max_bytes``."""
+    original_bytes = _byte_size(text)
+    budget = min(max(0, preview_bytes), original_bytes)
+    limit = original_bytes - 1
+    if max_bytes is not None:
+        limit = min(limit, max_bytes)
+    if limit < 0:
+        return None
+
+    while True:
+        preview, omitted = _preview(text, budget)
+        notice = _notice(omitted, path)
+        replacement = f"{preview}\n\n{notice}" if preview else notice
+        replacement_bytes = _byte_size(replacement)
+        if replacement_bytes <= limit:
+            return replacement
+        if budget == 0:
+            return None
+        budget = max(0, budget - max(1, replacement_bytes - limit))
+
+
+def _spill_result(
+    tool_name: str, result: dict[Any, Any], session_id: str | None = None
+) -> None:
+    cap = _get_int(MAX_INLINE_KEY, DEFAULT_MAX_INLINE_BYTES)
+    if cap <= 0 or tool_name in _get_skip_tools():
+        return
+    preview_bytes = _get_int(PREVIEW_KEY, DEFAULT_PREVIEW_BYTES)
+    if preview_bytes < 0:
+        logger.warning(
+            "Invalid %s value; falling back to %d",
+            PREVIEW_KEY,
+            DEFAULT_PREVIEW_BYTES,
+        )
+        preview_bytes = DEFAULT_PREVIEW_BYTES
+
+    fields = [
+        (key, value, _byte_size(value))
+        for key, value in result.items()
+        if isinstance(value, str)
+    ]
+    total = sum(size for _, _, size in fields)
+    if total <= cap:
+        return
+
+    replacements: dict[Any, str] = {}
+    for key, original, original_bytes in sorted(
+        fields, key=lambda item: item[2], reverse=True
+    ):
+        if total <= cap:
+            break
+        try:
+            path = store.save_text(
+                original, tool_name, _get_root(), session_id=session_id
+            )
+        except Exception:
+            logger.warning(
+                "Failed to spill %s result field %r; keeping it inline",
+                tool_name,
+                key,
+                exc_info=True,
+            )
+            continue
+
+        other_bytes = total - original_bytes
+        field_limit = cap - other_bytes if other_bytes < cap else None
+        replacement = _build_replacement(
+            original,
+            path,
+            preview_bytes,
+            field_limit,
+        )
+        if replacement is None:
+            logger.warning(
+                "Spill notice for %s result field %r cannot fit; keeping it inline",
+                tool_name,
+                key,
+            )
+            continue
+        replacements[key] = replacement
+        total = other_bytes + _byte_size(replacement)
+
+    # Commit atomically. A partial preview set that still exceeds the cap is
+    # neither bounded nor graceful; keep every original inline in that case.
+    if total <= cap:
+        result.update(replacements)
+
+
+async def _on_post_tool_call(
+    tool_name: str,
+    tool_args: dict,
+    result: Any,
+    duration_ms: float,
+    context: Any = None,
+) -> None:
+    """Spill oversized string fields off the event loop without breaking calls."""
+    _ = tool_args, duration_ms, context
+    try:
+        if not isinstance(result, dict) or set(result) == {"error"}:
+            return
+        # Capture session attribution before entering the worker. The result
+        # reference remains valid and the callback dispatcher awaits us before
+        # the model serializes it.
+        session_id = store.current_session_id()
+        await asyncio.to_thread(_spill_result, tool_name, result, session_id)
+    except Exception:
+        logger.debug(
+            "spill plugin failed; keeping the tool result inline", exc_info=True
+        )
+
+
+def _on_startup() -> None:
+    """Move spill behind result-mutating plugins so the final result is capped."""
+    if unregister_callback("post_tool_call", _on_post_tool_call):
+        # unregister_callback intentionally preserves callback ownership, so
+        # disabled-plugin filtering still recognizes this as the spill hook.
+        register_callback("post_tool_call", _on_post_tool_call)
+
+
+register_callback("startup", _on_startup)
+
+
+def _reset_state() -> None:
+    """Reset lazy process storage state for tests and defensive re-init."""
+    store._reset_state()
+
+
+register_callback("post_tool_call", _on_post_tool_call)
+
+
+__all__ = [
+    "DEFAULT_MAX_INLINE_BYTES",
+    "DEFAULT_PREVIEW_BYTES",
+    "DEFAULT_SKIP_TOOLS",
+    "MAX_INLINE_KEY",
+    "PREVIEW_KEY",
+    "ROOT_KEY",
+    "SKIP_TOOLS_KEY",
+    "_build_replacement",
+    "_get_int",
+    "_on_post_tool_call",
+    "_on_startup",
+    "_reset_state",
+    "_spill_result",
+]

code_puppy_core_plugins-0.0.6/code_puppy_core_plugins/spill/store.py

@@ -0,0 +1,173 @@
+"""Private local storage for spilled tool-result text."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import secrets
+import stat
+import tempfile
+import threading
+import uuid
+from pathlib import Path
+
+_default_root: Path | None = None
+_process_session_id: str | None = None
+_state_lock = threading.Lock()
+_UNSAFE_NAME = re.compile(r"[^A-Za-z0-9._-]+")
+
+
+def private_root(configured_root: str | None = None) -> Path:
+    """Return the configured root or a lazy private per-process temp root."""
+    global _default_root
+    if configured_root:
+        root = Path(configured_root).expanduser().resolve()
+        root.mkdir(mode=0o700, parents=True, exist_ok=True)
+        return root
+    with _state_lock:
+        if _default_root is None:
+            _default_root = Path(tempfile.mkdtemp(prefix="code-puppy-spill-"))
+        return _default_root
+
+
+def _process_fallback_session_id() -> str:
+    global _process_session_id
+    with _state_lock:
+        if _process_session_id is None:
+            _process_session_id = uuid.uuid4().hex
+        return _process_session_id
+
+
+def current_session_id() -> str:
+    """Return an async-safe session scope, with a stable process fallback."""
+    try:
+        from code_puppy.tools.subagent_context import get_conversation_root_id
+
+        conversation_id = get_conversation_root_id()
+        if conversation_id:
+            return str(conversation_id)
+    except Exception:
+        pass
+
+    # MessageBus session state is process-global and can be overwritten by any
+    # concurrent agent task. If no async-safe conversation root is available,
+    # prefer the honest process fallback over confidently misattributing a spill.
+    return _process_fallback_session_id()
+
+
+def _session_name(session_id: str) -> str:
+    digest = hashlib.sha256(session_id.encode("utf-8")).hexdigest()[:12]
+    return f"session-{digest}"
+
+
+def session_dir(root: Path, session_id: str) -> Path:
+    """Create a private real directory under ``root``, rejecting symlinks."""
+    directory = root / _session_name(session_id)
+    directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+    metadata = directory.lstat()
+    if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISDIR(metadata.st_mode):
+        raise OSError(f"Unsafe spill session directory: {directory}")
+    if os.chmod in os.supports_follow_symlinks:
+        os.chmod(directory, 0o700, follow_symlinks=False)
+    else:
+        # Platforms without no-follow chmod also lack the directory-fd path
+        # below. Re-check immediately before the best available fallback.
+        if directory.is_symlink():
+            raise OSError(f"Unsafe spill session directory: {directory}")
+        os.chmod(directory, 0o700)
+    return directory
+
+
+def _open_session_dir(root: Path, session_id: str) -> tuple[Path, int | None]:
+    """Open a session directory without following a pre-planted symlink."""
+    supports_safe_open = (
+        os.open in os.supports_dir_fd
+        and os.mkdir in os.supports_dir_fd
+        and hasattr(os, "O_DIRECTORY")
+        and hasattr(os, "O_NOFOLLOW")
+        and hasattr(os, "fchmod")
+    )
+    if not supports_safe_open:
+        return session_dir(root, session_id), None
+
+    name = _session_name(session_id)
+    root_flags = os.O_RDONLY | os.O_DIRECTORY
+    root_fd = os.open(root, root_flags)
+    try:
+        try:
+            os.mkdir(name, 0o700, dir_fd=root_fd)
+        except FileExistsError:
+            pass
+        flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW
+        directory_fd = os.open(name, flags, dir_fd=root_fd)
+    finally:
+        os.close(root_fd)
+
+    try:
+        os.fchmod(directory_fd, 0o700)
+    except Exception:
+        os.close(directory_fd)
+        raise
+    return root / name, directory_fd
+
+
+def safe_filename(tool_name: str) -> str:
+    """Convert an untrusted tool name into one harmless filename segment."""
+    raw = f"{tool_name}.txt".replace("\x00", "_")
+    safe = _UNSAFE_NAME.sub("_", raw.replace("/", "_").replace("\\", "_"))
+    while ".." in safe:
+        safe = safe.replace("..", "_")
+    safe = safe.strip(".")
+    return safe or "tool.txt"
+
+
+def save_text(
+    content: str,
+    tool_name: str,
+    configured_root: str | None = None,
+    session_id: str | None = None,
+) -> Path:
+    """Persist ``content`` verbatim with exclusive owner-only creation."""
+    root = private_root(configured_root)
+    directory, directory_fd = _open_session_dir(
+        root, session_id or current_session_id()
+    )
+    filename = f"{secrets.token_hex(6)}-{safe_filename(tool_name)}"
+    path = directory / filename
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+    descriptor = -1
+    try:
+        if directory_fd is None:
+            descriptor = os.open(path, flags, 0o600)
+        else:
+            descriptor = os.open(filename, flags, 0o600, dir_fd=directory_fd)
+        if hasattr(os, "fchmod"):
+            os.fchmod(descriptor, 0o600)
+        with os.fdopen(descriptor, "w", encoding="utf-8", newline="") as spill_file:
+            descriptor = -1
+            spill_file.write(content)
+    finally:
+        if descriptor >= 0:
+            os.close(descriptor)
+        if directory_fd is not None:
+            os.close(directory_fd)
+    return path
+
+
+def _reset_state() -> None:
+    """Forget lazy process state; test cleanup remains the caller's job."""
+    global _default_root, _process_session_id
+    with _state_lock:
+        _default_root = None
+        _process_session_id = None
+
+
+__all__ = [
+    "_reset_state",
+    "current_session_id",
+    "private_root",
+    "safe_filename",
+    "save_text",
+    "session_dir",
+]

{code_puppy_core_plugins-0.0.4 → code_puppy_core_plugins-0.0.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "code-puppy-core-plugins"
-version = "0.0.4"
+version = "0.0.6"
 description = "Official plugin bundle for Code Puppy"
 readme = "README.md"
 requires-python = ">=3.11,<3.15"
@@ -69,6 +69,7 @@ puppy_spinner = "code_puppy_core_plugins.puppy_spinner.register_callbacks"
 quick_resume = "code_puppy_core_plugins.quick_resume.register_callbacks"
 review_pr = "code_puppy_core_plugins.review_pr.register_callbacks"
 shell_safety = "code_puppy_core_plugins.shell_safety.register_callbacks"
+spill = "code_puppy_core_plugins.spill.register_callbacks"
 stack_dump = "code_puppy_core_plugins.stack_dump.register_callbacks"
 statusline = "code_puppy_core_plugins.statusline.register_callbacks"
 steer_queue = "code_puppy_core_plugins.steer_queue.register_callbacks"