code-puppy-core-plugins 0.0.40__tar.gz → 0.0.41__tar.gz

{code_puppy_core_plugins-0.0.40 → code_puppy_core_plugins-0.0.41}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: code-puppy-core-plugins
-Version: 0.0.40
+Version: 0.0.41
 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
@@ -55,6 +55,34 @@ The package deliberately does not depend on `code-puppy` in its own metadata.
 `code-puppy` depends on this bundle; adding the reverse edge would create a
 packaging dependency cycle. Plugin CI installs the core runtime separately.
 
+## Completion notifications
+
+The `completion_notification` plugin is disabled by default. Enable a native,
+best-effort desktop notification after a successful top-level response with:
+
+```text
+/set completion_notifications=true
+```
+
+Notifications use a sanitized, shortened copy of the latest user prompt as the
+title and a shortened response preview as the body, with Apple Terminal, iTerm2,
+or Warp labeled through `TERM_PROGRAM` when available. Unknown terminals omit
+the terminal label. Sub-agent completions are intentionally silent. Desktop
+notification centers may retain visible prompt and response previews.
+
+Optional sound configuration is platform-aware:
+
+```text
+/set completion_notification_sound=Frog
+```
+
+On macOS, a simple name selects a system sound (`Frog`, `Glass`, `Ping`, etc.).
+Preview one with `afplay /System/Library/Sounds/Frog.aiff`. On any platform, an
+absolute path to a local sound file is accepted when an available platform
+player can play it. Linux uses `notify-send` for desktop notifications when it
+is installed; Windows uses a best-effort PowerShell toast. No external Python
+dependencies are required.
+
 ## Releases
 
 Pushes to `main` run lint and tests, bump the patch version, build, publish to

{code_puppy_core_plugins-0.0.40 → code_puppy_core_plugins-0.0.41}/README.md

@@ -35,6 +35,34 @@ The package deliberately does not depend on `code-puppy` in its own metadata.
 `code-puppy` depends on this bundle; adding the reverse edge would create a
 packaging dependency cycle. Plugin CI installs the core runtime separately.
 
+## Completion notifications
+
+The `completion_notification` plugin is disabled by default. Enable a native,
+best-effort desktop notification after a successful top-level response with:
+
+```text
+/set completion_notifications=true
+```
+
+Notifications use a sanitized, shortened copy of the latest user prompt as the
+title and a shortened response preview as the body, with Apple Terminal, iTerm2,
+or Warp labeled through `TERM_PROGRAM` when available. Unknown terminals omit
+the terminal label. Sub-agent completions are intentionally silent. Desktop
+notification centers may retain visible prompt and response previews.
+
+Optional sound configuration is platform-aware:
+
+```text
+/set completion_notification_sound=Frog
+```
+
+On macOS, a simple name selects a system sound (`Frog`, `Glass`, `Ping`, etc.).
+Preview one with `afplay /System/Library/Sounds/Frog.aiff`. On any platform, an
+absolute path to a local sound file is accepted when an available platform
+player can play it. Linux uses `notify-send` for desktop notifications when it
+is installed; Windows uses a best-effort PowerShell toast. No external Python
+dependencies are required.
+
 ## Releases
 
 Pushes to `main` run lint and tests, bump the patch version, build, publish to

code_puppy_core_plugins-0.0.41/code_puppy_core_plugins/completion_notification/__init__.py

@@ -0,0 +1 @@
+"""Opt-in desktop notifications for completed top-level agent runs."""

code_puppy_core_plugins-0.0.41/code_puppy_core_plugins/completion_notification/config.py

@@ -0,0 +1,19 @@
+"""Configuration accessors for the completion-notification plugin."""
+
+from __future__ import annotations
+
+from code_puppy.config import get_value
+
+KEY_ENABLED = "completion_notifications"
+KEY_SOUND = "completion_notification_sound"
+_TRUTHY = {"1", "true", "yes", "on"}
+
+
+def is_enabled() -> bool:
+    """Return whether completion notifications are explicitly enabled."""
+    return str(get_value(KEY_ENABLED) or "").strip().lower() in _TRUTHY
+
+
+def get_sound() -> str:
+    """Return an optional named macOS sound or absolute local sound-file path."""
+    return str(get_value(KEY_SOUND) or "").strip()

code_puppy_core_plugins-0.0.41/code_puppy_core_plugins/completion_notification/locales/en-US.json

@@ -0,0 +1,7 @@
+{
+  "completion_notification.title": "Code Puppy",
+  "completion_notification.title_with_context": "Code Puppy — {context}",
+  "completion_notification.response_complete": "Response complete.",
+  "completion_notification.response_complete_in_terminal": "Response complete in {terminal}.",
+  "completion_notification.response_preview_in_terminal": "{preview} · {terminal}"
+}

code_puppy_core_plugins-0.0.41/code_puppy_core_plugins/completion_notification/locales/es.json

@@ -0,0 +1,7 @@
+{
+  "completion_notification.title": "Code Puppy",
+  "completion_notification.title_with_context": "Code Puppy — {context}",
+  "completion_notification.response_complete": "Respuesta completada.",
+  "completion_notification.response_complete_in_terminal": "Respuesta completada en {terminal}.",
+  "completion_notification.response_preview_in_terminal": "{preview} · {terminal}"
+}

code_puppy_core_plugins-0.0.41/code_puppy_core_plugins/completion_notification/locales/fr-CA.json

@@ -0,0 +1,7 @@
+{
+  "completion_notification.title": "Code Puppy",
+  "completion_notification.title_with_context": "Code Puppy — {context}",
+  "completion_notification.response_complete": "Réponse terminée.",
+  "completion_notification.response_complete_in_terminal": "Réponse terminée dans {terminal}.",
+  "completion_notification.response_preview_in_terminal": "{preview} · {terminal}"
+}

code_puppy_core_plugins-0.0.41/code_puppy_core_plugins/completion_notification/notifier.py

@@ -0,0 +1,231 @@
+"""Best-effort, dependency-free desktop completion notifications."""
+
+from __future__ import annotations
+
+import logging
+import ntpath
+import os
+import platform
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+from code_puppy.i18n import add_catalog_dir, t
+
+logger = logging.getLogger(__name__)
+
+_TIMEOUT_SECONDS = 3
+_CATALOG_DIR = Path(__file__).parent / "locales"
+add_catalog_dir(str(_CATALOG_DIR))
+_MACOS_SOUND_NAME = re.compile(r"^[A-Za-z0-9 _-]+$")
+# Control characters cannot survive intact inside AppleScript/PowerShell/XML
+# source and are never meaningful in a single-line notification, so drop them.
+_CONTROL_CHARS = re.compile(r"[\x00-\x1f\x7f]")
+_WHITESPACE = re.compile(r"\s+")
+_TITLE_PREVIEW_CHARS = 88
+_BODY_PREVIEW_CHARS = 180
+_TERMINAL_NAMES = {
+    "apple_terminal": "Terminal",
+    "iterm.app": "iTerm2",
+    "warpterminal": "Warp",
+}
+
+
+def _title(prompt: str = "") -> str:
+    context = prompt_preview(prompt)
+    if context:
+        return t("completion_notification.title_with_context", context=context)
+    return t("completion_notification.title")
+
+
+def notify_completion(
+    sound: str = "", prompt: str = "", response_text: str = ""
+) -> None:
+    """Show a contextual platform-native completion notification."""
+    try:
+        system = platform.system()
+        title = _title(prompt)
+        message = _completion_message(response_text)
+        if system == "Darwin":
+            _notify_macos(title, message, sound)
+        elif system == "Linux":
+            _notify_linux(title, message, sound)
+        elif system == "Windows":
+            _notify_windows(title, message, sound)
+    except Exception:
+        logger.debug("completion notification failed", exc_info=True)
+
+
+def _completion_message(response_text: str = "") -> str:
+    terminal = _TERMINAL_NAMES.get(os.environ.get("TERM_PROGRAM", "").casefold())
+    preview = response_preview(response_text)
+    if preview:
+        return (
+            preview
+            if terminal is None
+            else t(
+                "completion_notification.response_preview_in_terminal",
+                preview=preview,
+                terminal=terminal,
+            )
+        )
+    return (
+        t("completion_notification.response_complete")
+        if terminal is None
+        else t(
+            "completion_notification.response_complete_in_terminal", terminal=terminal
+        )
+    )
+
+
+def response_preview(response_text: str) -> str:
+    """Return a safe, bounded body preview for an agent response."""
+    return _preview(response_text, _BODY_PREVIEW_CHARS)
+
+
+def prompt_preview(prompt: str) -> str:
+    """Return a safe, bounded title preview for a user prompt."""
+    return _preview(prompt, _TITLE_PREVIEW_CHARS)
+
+
+def _preview(text: str, limit: int) -> str:
+    """Collapse dynamic content into a readable, bounded notification line."""
+    compact = _WHITESPACE.sub(" ", _CONTROL_CHARS.sub(" ", text or "")).strip()
+    if len(compact) <= limit:
+        return compact
+    shortened = compact[: limit - 1].rsplit(" ", 1)[0].rstrip(".,;:!?")
+    return f"{shortened or compact[: limit - 1]}…"
+
+
+def _notify_macos(title: str, message: str, sound: str) -> None:
+    body = _escape_applescript(message)
+    title = _escape_applescript(title)
+    script = f'display notification "{body}" with title "{title}"'
+    if _is_macos_sound_name(sound):
+        script += f' sound name "{sound}"'
+    _run(["/usr/bin/osascript", "-e", script])
+    _play_file(sound, players=(("/usr/bin/afplay",),))
+
+
+def _notify_linux(title: str, message: str, sound: str) -> None:
+    notify_send = shutil.which("notify-send")
+    if notify_send:
+        # "--" stops option parsing so a title/message starting with "-" is
+        # never misread as a flag.
+        _run([notify_send, "--app-name", _title(), "--", title, message])
+    _play_file(sound, players=(("paplay",), ("aplay",)))
+
+
+def _notify_windows(title: str, message: str, sound: str) -> None:
+    # Windows Runtime toast APIs are available on current Windows releases. This
+    # remains best-effort: restricted hosts can reject the call without affecting
+    # the completed Code Puppy run.
+    toast_xml = (
+        '<toast><visual><binding template="ToastGeneric">'
+        f"<text>{_escape_xml(title)}</text><text>{_escape_xml(message)}</text>"
+        "</binding></visual></toast>"
+    )
+    # XML-escaping already removes single quotes, but escape the assembled
+    # literal defensively before it enters the single-quoted PowerShell string.
+    toast_literal = toast_xml.replace("'", "''")
+    notifier_title = _title().replace("'", "''")
+    script = (
+        "$xml = New-Object Windows.Data.Xml.Dom.XmlDocument; "
+        f"$xml.LoadXml('{toast_literal}'); "
+        "[Windows.UI.Notifications.ToastNotificationManager]::"
+        f"CreateToastNotifier('{notifier_title}').Show("
+        "[Windows.UI.Notifications.ToastNotification]::new($xml))"
+    )
+    powershell = _powershell_executable()
+    _run([powershell, "-NoProfile", "-NonInteractive", "-Command", script])
+    _play_file(
+        sound,
+        players=((powershell, "-NoProfile", "-NonInteractive", "-Command"),),
+    )
+
+
+def _powershell_executable() -> str:
+    """Return Windows PowerShell by trusted absolute path, never PATH lookup."""
+    system_root = os.environ.get("SystemRoot", r"C:\Windows")
+    return ntpath.join(
+        system_root, "System32", "WindowsPowerShell", "v1.0", "powershell.exe"
+    )
+
+
+def _is_macos_sound_name(sound: str) -> bool:
+    return bool(sound) and "/" not in sound and bool(_MACOS_SOUND_NAME.fullmatch(sound))
+
+
+def _escape_applescript(text: str) -> str:
+    """Escape text for a double-quoted AppleScript string literal.
+
+    i18n catalogs are an untrusted plugin/community seam, so translated text is
+    treated as hostile input. Escaping backslash and double-quote (after dropping
+    control characters) prevents breaking out of the literal into ``do shell
+    script`` and neutralizes the injection class entirely.
+    """
+    text = _CONTROL_CHARS.sub(" ", text)
+    return text.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def _escape_xml(text: str) -> str:
+    """Escape text for a Windows toast XML text node (untrusted i18n input)."""
+    text = _CONTROL_CHARS.sub(" ", text)
+    return (
+        text.replace("&", "&amp;")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+        .replace('"', "&quot;")
+        .replace("'", "&apos;")
+    )
+
+
+def _play_file(sound: str, *, players: tuple[tuple[str, ...], ...]) -> None:
+    path = _sound_file(sound)
+    if path is None:
+        return
+    for player in players:
+        if Path(player[0]).is_absolute() or ntpath.isabs(player[0]):
+            executable = player[0]
+        else:
+            executable = shutil.which(player[0]) or (
+                player[0] if Path(player[0]).is_file() else None
+            )
+        if executable is None:
+            continue
+        if ntpath.basename(player[0]).casefold() == "powershell.exe":
+            escaped_path = str(path).replace("'", "''")
+            _run(
+                [
+                    *player,
+                    f"(New-Object System.Media.SoundPlayer '{escaped_path}').PlaySync()",
+                ]
+            )
+        else:
+            _run([executable, *player[1:], str(path)])
+        return
+
+
+def _sound_file(sound: str) -> Path | None:
+    if not sound or _is_macos_sound_name(sound):
+        return None
+    path = Path(sound).expanduser()
+    if not path.is_absolute() or not path.is_file():
+        return None
+    return path
+
+
+def _run(command: list[str]) -> None:
+    try:
+        subprocess.run(
+            command,
+            capture_output=True,
+            check=False,
+            timeout=_TIMEOUT_SECONDS,
+            text=True,
+        )
+    except (OSError, subprocess.SubprocessError):
+        logger.debug(
+            "completion notification command failed: %s", command[0], exc_info=True
+        )

code_puppy_core_plugins-0.0.41/code_puppy_core_plugins/completion_notification/register_callbacks.py

@@ -0,0 +1,135 @@
+"""Register opt-in desktop notifications for completed top-level agent runs."""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+
+from code_puppy.callbacks import register_callback
+
+from .config import get_sound, is_enabled
+from .notifier import notify_completion, prompt_preview
+
+logger = logging.getLogger(__name__)
+_WORKER_JOIN_TIMEOUT_SECONDS = 3
+_lock = threading.Lock()
+_run_depth = 0
+_workers: set[threading.Thread] = set()
+_prompts: dict[str, str] = {}
+
+
+def _on_user_prompt_submit(prompt: str, session_id: str | None = None) -> None:
+    """Keep an opted-in prompt only until its run finishes."""
+    if not session_id or not is_enabled() or _is_subagent():
+        return
+    with _lock:
+        _prompts[session_id] = prompt_preview(prompt)
+
+
+def _is_subagent() -> bool:
+    try:
+        from code_puppy.tools.subagent_context import is_subagent
+
+        return is_subagent()
+    except Exception:
+        logger.debug(
+            "sub-agent status could not be determined; suppressing notification",
+            exc_info=True,
+        )
+        return True
+
+
+def _on_agent_run_start(*_args, **_kwargs) -> None:
+    """Track public lifecycle depth so internal nested runs never notify."""
+    global _run_depth
+    with _lock:
+        _run_depth += 1
+
+
+def _on_agent_run_end(
+    agent_name: str | None = None,
+    model_name: str | None = None,
+    session_id: str | None = None,
+    success: bool = True,
+    error: Exception | None = None,
+    response_text: str | None = None,
+    metadata: dict | None = None,
+) -> None:
+    """Notify only when the outermost successful textual run completes."""
+    del agent_name, model_name, error, metadata
+    global _run_depth
+    with _lock:
+        _run_depth = max(0, _run_depth - 1)
+        is_outermost_run = _run_depth == 0
+        prompt = _prompts.pop(session_id, "") if session_id else ""
+
+    if (
+        not is_outermost_run
+        or not success
+        or not response_text
+        or not is_enabled()
+        or _is_subagent()
+    ):
+        return
+
+    try:
+        _start_notification_worker(get_sound(), prompt, response_text)
+    except Exception:
+        logger.debug("completion notification worker could not start", exc_info=True)
+
+
+def _start_notification_worker(
+    sound: str, prompt: str = "", response_text: str = ""
+) -> None:
+    worker: threading.Thread
+
+    def notify() -> None:
+        try:
+            notify_completion(sound, prompt, response_text)
+        finally:
+            with _lock:
+                _workers.discard(worker)
+
+    worker = threading.Thread(
+        target=notify,
+        daemon=True,
+        name="code-puppy-completion-notification",
+    )
+    with _lock:
+        _workers.add(worker)
+    worker.start()
+
+
+def _drain_workers(*_args, **_kwargs) -> None:
+    """Give notification workers a bounded chance to finish before exit.
+
+    Joins share a single deadline so total wall time stays within the timeout
+    regardless of how many workers are in flight, rather than N x timeout.
+    """
+    with _lock:
+        workers = tuple(_workers)
+        _workers.clear()
+    deadline = time.monotonic() + _WORKER_JOIN_TIMEOUT_SECONDS
+    for worker in workers:
+        remaining = max(0.0, deadline - time.monotonic())
+        try:
+            worker.join(timeout=remaining)
+        except RuntimeError:
+            logger.debug(
+                "completion notification worker could not be joined", exc_info=True
+            )
+
+
+register_callback("user_prompt_submit", _on_user_prompt_submit)
+register_callback("agent_run_start", _on_agent_run_start)
+register_callback("agent_run_end", _on_agent_run_end)
+register_callback("session_end", _drain_workers)
+register_callback("shutdown", _drain_workers)
+
+__all__ = [
+    "_drain_workers",
+    "_on_agent_run_end",
+    "_on_agent_run_start",
+    "_on_user_prompt_submit",
+]

{code_puppy_core_plugins-0.0.40 → code_puppy_core_plugins-0.0.41}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "code-puppy-core-plugins"
-version = "0.0.40"
+version = "0.0.41"
 description = "Official plugin bundle for Code Puppy"
 readme = "README.md"
 requires-python = ">=3.11,<3.15"
@@ -40,6 +40,7 @@ claude_code_hooks = "code_puppy_core_plugins.claude_code_hooks.register_callback
 claude_code_oauth = "code_puppy_core_plugins.claude_code_oauth.register_callbacks"
 code_puppy_agent = "code_puppy_core_plugins.code_puppy_agent.register_callbacks"
 computer_use = "code_puppy_core_plugins.computer_use.register_callbacks"
+completion_notification = "code_puppy_core_plugins.completion_notification.register_callbacks"
 context_indicator = "code_puppy_core_plugins.context_indicator.register_callbacks"
 copilot_auth = "code_puppy_core_plugins.copilot_auth.register_callbacks"
 customizable_commands = "code_puppy_core_plugins.customizable_commands.register_callbacks"