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

{code_puppy_core_plugins-0.0.5 → 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.5
+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.5 → 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.5 → 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.5 → 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.5 → code_puppy_core_plugins-0.0.6}/code_puppy_core_plugins/spill/register_callbacks.py

@@ -23,12 +23,13 @@ Config (puppy.cfg, also settable with ``/set``):
 
 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
+from code_puppy.callbacks import register_callback, unregister_callback
 
 from . import store
 
@@ -129,7 +130,9 @@ def _build_replacement(
         budget = max(0, budget - max(1, replacement_bytes - limit))
 
 
-def _spill_result(tool_name: str, result: dict[Any, Any]) -> None:
+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
@@ -158,7 +161,9 @@ def _spill_result(tool_name: str, result: dict[Any, Any]) -> None:
         if total <= cap:
             break
         try:
-            path = store.save_text(original, tool_name, _get_root())
+            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",
@@ -192,25 +197,40 @@ def _spill_result(tool_name: str, result: dict[Any, Any]) -> None:
         result.update(replacements)
 
 
-def _on_post_tool_call(
+async def _on_post_tool_call(
     tool_name: str,
     tool_args: dict,
     result: Any,
     duration_ms: float,
     context: Any = None,
 ) -> None:
-    """Spill oversized top-level string fields without breaking tool calls."""
+    """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
-        _spill_result(tool_name, result)
+        # 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()
@@ -230,6 +250,7 @@ __all__ = [
     "_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.5 → 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.5"
+version = "0.0.6"
 description = "Official plugin bundle for Code Puppy"
 readme = "README.md"
 requires-python = ">=3.11,<3.15"

code_puppy_core_plugins-0.0.5/code_puppy_core_plugins/spill/store.py

@@ -1,97 +0,0 @@
-"""Private local storage for spilled tool-result text."""
-
-from __future__ import annotations
-
-import hashlib
-import os
-import re
-import secrets
-import tempfile
-import uuid
-from pathlib import Path
-
-_default_root: Path | None = None
-_process_session_id: str | None = None
-_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
-    if _default_root is None:
-        _default_root = Path(tempfile.mkdtemp(prefix="code-puppy-spill-"))
-    return _default_root
-
-
-def current_session_id() -> str:
-    """Return the active agent session id, with a stable process fallback."""
-    global _process_session_id
-    try:
-        from code_puppy.messaging import get_session_context
-
-        session_id = get_session_context()
-        if session_id:
-            return str(session_id)
-    except Exception:
-        pass
-    if _process_session_id is None:
-        _process_session_id = uuid.uuid4().hex
-    return _process_session_id
-
-
-def session_dir(root: Path, session_id: str) -> Path:
-    """Create and return a private, hashed session directory under ``root``."""
-    digest = hashlib.sha256(session_id.encode("utf-8")).hexdigest()[:12]
-    directory = root / f"session-{digest}"
-    directory.mkdir(mode=0o700, parents=True, exist_ok=True)
-    os.chmod(directory, 0o700)
-    return directory
-
-
-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) -> Path:
-    """Persist ``content`` verbatim with exclusive owner-only creation."""
-    root = private_root(configured_root)
-    directory = session_dir(root, current_session_id())
-    path = directory / f"{secrets.token_hex(6)}-{safe_filename(tool_name)}"
-    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
-    descriptor = os.open(path, flags, 0o600)
-    try:
-        with os.fdopen(descriptor, "w", encoding="utf-8", newline="") as spill_file:
-            descriptor = -1
-            spill_file.write(content)
-        os.chmod(path, 0o600)
-    finally:
-        if descriptor >= 0:
-            os.close(descriptor)
-    return path
-
-
-def _reset_state() -> None:
-    """Forget lazy process state; test cleanup remains the caller's job."""
-    global _default_root, _process_session_id
-    _default_root = None
-    _process_session_id = None
-
-
-__all__ = [
-    "_reset_state",
-    "current_session_id",
-    "private_root",
-    "safe_filename",
-    "save_text",
-    "session_dir",
-]