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

code_puppy_core_plugins/quick_resume/register_callbacks.py

@@ -0,0 +1,77 @@
+"""Quick-resume workspace observation hooks.
+
+The autosave layer records a quick-resume pointer for cwd. This plugin teaches
+Code Puppy about *child* workspaces touched through tools, so a later
+``code-puppy -qr ./child`` (or ``/quick-resume ./child``) resolves the session
+even when the process was launched from the parent directory the whole time.
+
+Observation is a pure convenience: it only registers hashed pointer keys and
+never blocks or alters tool output.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from code_puppy.callbacks import register_callback
+
+# Map tools to plain local-path args; ``path_kind`` tells the resolver whether
+# to probe the file's parent. Nested/non-string payloads are intentionally omitted.
+_LOCAL_PATH_TOOL_ARGS: dict[str, tuple[tuple[str, str], ...]] = {
+    "agent_run_shell_command": (("cwd", "directory"),),
+    "create_file": (("file_path", "file"),),
+    "delete_file": (("file_path", "file"),),
+    "delete_snippet": (("file_path", "file"),),
+    "grep": (("directory", "directory"),),
+    "list_files": (("directory", "directory"),),
+    "read_file": (("file_path", "file"),),
+    "replace_in_file": (("file_path", "file"),),
+}
+
+
+def _result_failed(result: Any) -> bool:
+    """Return True when a tool result clearly represents a failure.
+
+    Handles both dict results and objects exposing ``error``/``success``.
+    """
+    if isinstance(result, dict):
+        if result.get("error"):
+            return True
+        if result.get("success") is False:
+            return True
+    error = getattr(result, "error", None)
+    if error:
+        return True
+    success = getattr(result, "success", None)
+    return success is False
+
+
+def _observe_tool_paths(
+    tool_name: str,
+    tool_args: dict[str, Any],
+    result: Any,
+    duration_ms: float,
+    context: Any = None,
+) -> None:
+    """Record local workspace paths from successful tool calls (best-effort)."""
+    _ = duration_ms, context  # unused; kept for the post_tool_call signature
+    if _result_failed(result):
+        return
+
+    path_specs = _LOCAL_PATH_TOOL_ARGS.get(tool_name)
+    if not path_specs:
+        return
+
+    try:
+        from code_puppy.config import observe_quick_resume_path
+
+        for arg_name, path_kind in path_specs:
+            raw_path = tool_args.get(arg_name)
+            if isinstance(raw_path, str) and raw_path.strip():
+                observe_quick_resume_path(raw_path, path_kind=path_kind)
+    except Exception:
+        # Observation is a convenience pointer, never worth breaking tool output.
+        return
+
+
+register_callback("post_tool_call", _observe_tool_paths)

code_puppy_core_plugins/review_pr/__init__.py

@@ -0,0 +1 @@
+"""/review-pr custom slash command plugin."""

code_puppy_core_plugins/review_pr/register_callbacks.py

@@ -0,0 +1,162 @@
+"""Plugin: `/review-pr` — hand the agent a structured PR review mission.
+
+Usage:
+    /review-pr                  Review the PR for the current branch
+    /review-pr 123              Review PR #123 in the current repo
+    /review-pr <github-url>     Review the PR at the given URL
+    /review-pr --help           Show usage
+
+The command itself is dumb on purpose (YAGNI): it just builds a beefy prompt
+and returns it. The *agent* does the heavy lifting via `gh` + shell tools.
+That keeps responsibilities clean (SRP) — plugin = command framing, agent =
+code review.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional, Tuple
+
+from code_puppy.callbacks import register_callback
+from code_puppy.messaging import emit_error, emit_info
+
+
+COMMAND_NAME = "review-pr"
+
+
+_USAGE = (
+    "Usage: /review-pr [PR_NUMBER | GITHUB_PR_URL]\n"
+    "  /review-pr               → review the current branch's open PR\n"
+    "  /review-pr 123           → review PR #123 in the current repo\n"
+    "  /review-pr <url>         → review the PR at that GitHub URL"
+)
+
+
+def _custom_help() -> List[Tuple[str, str]]:
+    return [
+        (
+            COMMAND_NAME,
+            "Review a GitHub PR (uses `gh`). Optional arg: PR number or URL.",
+        )
+    ]
+
+
+def _parse_target(command: str) -> Optional[str]:
+    """Return the raw PR target (number, URL, or '' for current branch).
+
+    Returns None if the user asked for --help (already handled).
+    """
+    parts = command.split(maxsplit=1)
+    if len(parts) == 1:
+        return ""
+
+    arg = parts[1].strip()
+    if arg in {"--help", "-h", "help"}:
+        emit_info(_USAGE)
+        return None
+    return arg
+
+
+def _build_prompt(target: str) -> str:
+    """Compose the review instructions sent to the agent."""
+    if target:
+        target_clause = (
+            f"The user wants you to review this PR: **{target}**.\n"
+            "Resolve it with the `gh` CLI (number → current repo, URL → that repo)."
+        )
+    else:
+        target_clause = (
+            "No PR was specified — review the PR associated with the **current branch**.\n"
+            "Use `gh pr view --json number,url,title,headRefName,baseRefName` to discover it.\n"
+            "If no PR exists for the current branch, stop and tell the user."
+        )
+
+    return f"""You are doing a **pull request review**. Be thorough, fair, and a little spicy.
+
+{target_clause}
+
+## Step 1 — Gather context
+Run (in order, only what you need):
+  1. `gh pr view <target> --json number,title,author,url,baseRefName,headRefName,body,additions,deletions,changedFiles,labels,isDraft,mergeable,reviewDecision`
+  2. `gh pr diff <target>` to read the actual diff
+  3. `gh pr checks <target>` for CI status
+  4. (Optional) `gh pr view <target> --comments` if you need existing discussion
+
+If any command fails (auth, not-a-repo, no PR), surface a clean error and stop.
+
+## Step 2 — Analyze
+Walk the diff and judge it on:
+  - **Correctness** — bugs, off-by-ones, race conditions, error handling, edge cases
+  - **Design** — SOLID, DRY, YAGNI violations; leaky abstractions; tight coupling
+  - **Readability** — naming, function size, comments where the *why* is non-obvious
+  - **Tests** — coverage for new logic, missing edge cases, brittle mocks
+  - **Security** — injection, secrets, unvalidated input, authz gaps
+  - **Performance** — obvious quadratic loops, N+1 queries, needless allocations
+  - **Style/Lint** — only call out if it's actually wrong, not just taste
+
+Honor the Zen of Python even for non-Python code.
+
+## Step 3 — Report
+Output a single markdown report with these sections (omit empty ones):
+
+### 🐶 PR Review: <title> (#<number>)
+- **Author:** …  **Base ← Head:** …  **CI:** …  **Mergeable:** …
+- **TL;DR:** one-sentence verdict.
+
+### ✅ What's good
+Bullet list. Be specific — point at files/functions.
+
+### 🔴 Blocking issues
+Things that *must* be fixed before merge. Each item:
+- **File:line** — what's wrong, why, and a concrete fix.
+
+### 🟡 Suggestions (non-blocking)
+Nice-to-haves, refactors, follow-ups.
+
+### 🧪 Test gaps
+Specific scenarios that should have tests.
+
+### 🏁 Recommendation
+One of: **APPROVE**, **REQUEST CHANGES**, or **COMMENT** — with a one-line justification.
+
+## Rules
+- Do **NOT** post the review to GitHub. Just print it. The user decides whether to submit.
+- Don't run mutating `gh` commands (no `gh pr review --approve`, no merges, no closes).
+- If the diff is huge (>1500 lines), say so and focus on the highest-signal files.
+- Quote short snippets (≤10 lines) when calling out specific code.
+"""
+
+
+def _handle_custom_command(command: str, name: str) -> Optional[object]:
+    if name != COMMAND_NAME:
+        return None
+
+    target = _parse_target(command)
+    if target is None:
+        # --help was shown; mark as handled without invoking the model.
+        return True
+
+    # Sanity-check gh is available so we fail fast with a friendly hint.
+    import shutil
+
+    if shutil.which("gh") is None:
+        emit_error(
+            "/review-pr: GitHub CLI (`gh`) not found on PATH. "
+            "Install it from https://cli.github.com/ and run `gh auth login`."
+        )
+        return True
+
+    emit_info(f"🐶 Fetching PR review mission for: {target or '<current branch>'}")
+    return _build_prompt(target)
+
+
+register_callback("custom_command_help", _custom_help)
+register_callback("custom_command", _handle_custom_command)
+
+
+__all__ = [
+    "COMMAND_NAME",
+    "_custom_help",
+    "_handle_custom_command",
+    "_build_prompt",
+    "_parse_target",
+]

code_puppy_core_plugins/shell_safety/__init__.py

@@ -0,0 +1,6 @@
+"""Shell command safety checking plugin.
+
+This plugin provides AI-powered safety assessment for shell commands
+executed in yolo_mode. It helps prevent accidental execution of
+dangerous commands that could cause data loss or system damage.
+"""

code_puppy_core_plugins/shell_safety/agent_shell_safety.py

@@ -0,0 +1,69 @@
+"""Shell command safety assessment agent.
+
+This agent provides rapid risk assessment of shell commands before execution.
+It's designed to be ultra-lightweight with a concise prompt (<200 tokens) and
+uses structured output for reliable parsing.
+"""
+
+from typing import TYPE_CHECKING, List
+
+from code_puppy.agents.base_agent import BaseAgent
+
+if TYPE_CHECKING:
+    pass
+
+
+class ShellSafetyAgent(BaseAgent):
+    """Lightweight agent for assessing shell command safety risks.
+
+    This agent evaluates shell commands for potential risks including:
+    - File system destruction (rm -rf, dd, format, mkfs)
+    - Database operations (DROP, TRUNCATE, unfiltered UPDATE/DELETE)
+    - Privilege escalation (sudo, su, chmod 777)
+    - Network operations (wget/curl to unknown hosts)
+    - Data exfiltration patterns
+
+    The agent returns structured output with a risk level and brief reasoning.
+    """
+
+    @property
+    def name(self) -> str:
+        """Agent name for internal use."""
+        return "shell_safety_checker"
+
+    @property
+    def display_name(self) -> str:
+        """User-facing display name."""
+        return "Shell Safety Checker 🛡️"
+
+    @property
+    def description(self) -> str:
+        """Agent description."""
+        return "Lightweight agent that assesses shell command safety risks"
+
+    def get_system_prompt(self) -> str:
+        """Get the ultra-concise system prompt for shell safety assessment.
+
+        This prompt is kept under 200 tokens for fast inference and low cost.
+        """
+        return """You are a shell command safety analyzer. Assess risk levels concisely.
+
+**Risk Levels:**
+- none: Completely safe (ls, pwd, echo, cat readonly files)
+- low: Minimal risk (mkdir, touch, git status, read-only queries)
+- medium: Moderate risk (file edits, package installs, service restarts)
+- high: Significant risk (rm files, UPDATE/DELETE without WHERE, TRUNCATE, chmod dangerous permissions)
+- critical: Severe/destructive (rm -rf, DROP TABLE/DATABASE, dd, format, mkfs, bq delete dataset, unfiltered mass deletes)
+
+**Evaluate:**
+- Scope (single file vs. entire system)
+- Reversibility (can it be undone?)
+- Data loss potential
+- Privilege requirements
+- Database destruction patterns
+
+**Output:** Risk level + reasoning (max 1 sentence)."""
+
+    def get_available_tools(self) -> List[str]:
+        """This agent uses no tools - pure reasoning only."""
+        return []

code_puppy_core_plugins/shell_safety/command_cache.py

@@ -0,0 +1,156 @@
+"""Caching layer for shell command safety assessments.
+
+This module provides an LRU cache for recently assessed commands to avoid redundant API calls.
+
+The approach is simple and secure: let the LLM assess ALL commands and cache
+those assessments. This eliminates the security risks of pre-defined whitelists
+while providing the performance benefits of caching.
+"""
+
+from collections import OrderedDict
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+# Maximum number of cached assessments (LRU eviction after this)
+MAX_CACHE_SIZE = 200
+
+
+@dataclass
+class CachedAssessment:
+    """A cached safety assessment result."""
+
+    risk: str
+    reasoning: str
+
+
+class CommandSafetyCache:
+    """LRU cache for shell command safety assessments.
+
+    This cache stores previous LLM assessments to avoid redundant API calls.
+    It uses an OrderedDict for O(1) LRU eviction.
+    """
+
+    def __init__(self, max_size: int = MAX_CACHE_SIZE):
+        self._cache: OrderedDict[Tuple[str, Optional[str]], CachedAssessment] = (
+            OrderedDict()
+        )
+        self._max_size = max_size
+        self._hits = 0
+        self._misses = 0
+
+    def _make_key(self, command: str, cwd: Optional[str]) -> Tuple[str, Optional[str]]:
+        """Create a cache key from command and cwd."""
+        # Normalize command (strip whitespace)
+        return (command.strip(), cwd)
+
+    def get(
+        self, command: str, cwd: Optional[str] = None
+    ) -> Optional[CachedAssessment]:
+        """Get a cached assessment if it exists.
+
+        Args:
+            command: The shell command
+            cwd: Optional working directory
+
+        Returns:
+            CachedAssessment if found, None otherwise
+        """
+        key = self._make_key(command, cwd)
+        if key in self._cache:
+            # Move to end (most recently used)
+            self._cache.move_to_end(key)
+            self._hits += 1
+            return self._cache[key]
+        self._misses += 1
+        return None
+
+    def put(
+        self, command: str, cwd: Optional[str], assessment: CachedAssessment
+    ) -> None:
+        """Store an assessment in the cache.
+
+        Args:
+            command: The shell command
+            cwd: Optional working directory
+            assessment: The assessment result to cache
+        """
+        key = self._make_key(command, cwd)
+
+        # If already exists, update and move to end
+        if key in self._cache:
+            self._cache.move_to_end(key)
+            self._cache[key] = assessment
+            return
+
+        # Evict oldest if at capacity
+        while len(self._cache) >= self._max_size:
+            self._cache.popitem(last=False)
+
+        self._cache[key] = assessment
+
+    def clear(self) -> None:
+        """Clear all cached assessments."""
+        self._cache.clear()
+        self._hits = 0
+        self._misses = 0
+
+    @property
+    def stats(self) -> dict:
+        """Get cache statistics."""
+        total = self._hits + self._misses
+        hit_rate = (self._hits / total * 100) if total > 0 else 0
+        return {
+            "size": len(self._cache),
+            "max_size": self._max_size,
+            "hits": self._hits,
+            "misses": self._misses,
+            "hit_rate": f"{hit_rate:.1f}%",
+        }
+
+
+# Global cache instance (singleton for the session)
+_cache = CommandSafetyCache()
+
+
+def get_cache_stats() -> dict:
+    """Get statistics about the cache performance."""
+    return _cache.stats
+
+
+def get_cached_assessment(
+    command: str, cwd: Optional[str] = None
+) -> Optional[CachedAssessment]:
+    """Get a cached command safety assessment.
+
+    Cache-only approach: use the LLM cache for speed, but let the LLM
+    determine safety for all commands. No pre-defined whitelists.
+
+    Args:
+        command: The shell command to check
+        cwd: Optional working directory
+
+    Returns:
+        CachedAssessment if found in cache, None if needs LLM assessment
+    """
+    return _cache.get(command, cwd)
+
+
+def cache_assessment(
+    command: str, cwd: Optional[str], risk: str, reasoning: str
+) -> None:
+    """Cache an LLM assessment result.
+
+    Cache all LLM assessments since the same command should get
+    the same assessment, providing both security and performance.
+
+    Args:
+        command: The shell command
+        cwd: Optional working directory
+        risk: The assessed risk level
+        reasoning: The assessment reasoning
+    """
+    assessment = CachedAssessment(
+        risk=risk,
+        reasoning=reasoning,
+    )
+    _cache.put(command, cwd, assessment)

code_puppy_core_plugins/shell_safety/register_callbacks.py

@@ -0,0 +1,203 @@
+"""Callback registration for shell command safety checking.
+
+This module registers a callback that intercepts shell commands in yolo_mode
+and assesses their safety risk before execution.
+"""
+
+from typing import Any, Dict, Optional
+
+from code_puppy.callbacks import register_callback
+from code_puppy.config import (
+    get_global_model_name,
+    get_safety_permission_level,
+    get_yolo_mode,
+)
+from code_puppy.messaging import emit_info
+from code_puppy_core_plugins.shell_safety.command_cache import (
+    cache_assessment,
+    get_cached_assessment,
+)
+from code_puppy.tools.command_runner import ShellSafetyAssessment
+
+# OAuth model prefixes - these models have their own safety mechanisms
+OAUTH_MODEL_PREFIXES = (
+    "claude-code-",  # Anthropic OAuth
+    "codex-",  # OpenAI OAuth
+    "chatgpt-",  # Legacy OpenAI OAuth
+    "gemini-oauth",  # Google OAuth
+)
+
+
+def is_oauth_model(model_name: str | None) -> bool:
+    """Check if the model is an OAuth model that should skip safety checks.
+
+    OAuth models have their own built-in safety mechanisms, so we skip
+    the shell safety callback to avoid redundant checks and potential bugs.
+
+    Args:
+        model_name: The name of the current model
+
+    Returns:
+        True if the model is an OAuth model, False otherwise
+    """
+    if not model_name:
+        return False
+    return model_name.startswith(OAUTH_MODEL_PREFIXES)
+
+
+# Numeric risk hierarchy: lower values are safer.
+RISK_LEVELS: Dict[str, int] = {
+    "none": 0,
+    "low": 1,
+    "medium": 2,
+    "high": 3,
+    "critical": 4,
+}
+
+
+def compare_risk_levels(assessed_risk: Optional[str], threshold: str) -> bool:
+    """Compare assessed risk against threshold.
+
+    Args:
+        assessed_risk: The risk level from the agent (can be None)
+        threshold: The configured risk threshold
+
+    Returns:
+        True if the command should be blocked (risk exceeds threshold)
+        False if the command is acceptable
+    """
+    # If assessment failed (None), treat as high risk (fail-safe behavior)
+    if assessed_risk is None:
+        assessed_risk = "high"
+
+    # Map risk names to numeric values; unknown defaults are conservative.
+    assessed_level = RISK_LEVELS.get(assessed_risk, 4)  # Default to critical if unknown
+    threshold_level = RISK_LEVELS.get(threshold, 2)  # Default to medium if unknown
+
+    # Block if assessed risk is GREATER than threshold
+    # Note: Commands AT the threshold level are allowed (>, not >=)
+    return assessed_level > threshold_level
+
+
+async def shell_safety_callback(
+    context: Any, command: str, cwd: Optional[str] = None, timeout: int = 60
+) -> Optional[Dict[str, Any]]:
+    """Callback to assess shell command safety before execution.
+
+    This callback is only active when yolo_mode is True. When yolo_mode is False,
+    the user manually reviews every command, so we don't need the agent.
+
+    Args:
+        context: The execution context
+        command: The shell command to execute
+        cwd: Optional working directory
+        timeout: Command timeout (unused here)
+
+    Returns:
+        None if command is safe to proceed
+        Dict with rejection info if command should be blocked
+    """
+    # Skip safety checks for OAuth models - they have their own safety mechanisms
+    current_model = get_global_model_name()
+    if is_oauth_model(current_model):
+        return None
+
+    # Only check safety in yolo_mode - otherwise user is reviewing manually
+    yolo_mode = get_yolo_mode()
+    if not yolo_mode:
+        return None
+
+    # Get configured risk threshold
+    threshold = get_safety_permission_level()
+
+    try:
+        # Check cache first (fast path - no LLM call)
+        cached = get_cached_assessment(command, cwd)
+
+        if cached:
+            # Got a cached result - check against threshold
+            if compare_risk_levels(cached.risk, threshold):
+                # Cached result says it's too risky
+                risk_display = cached.risk or "unknown"
+                concise_reason = cached.reasoning or "No reasoning provided"
+                error_msg = (
+                    f"🛑 Command blocked (risk {risk_display.upper()} > permission {threshold.upper()}).\n"
+                    f"Reason: {concise_reason}\n"
+                    f"Override: /set yolo_mode true or /set safety_permission_level {risk_display}"
+                )
+                emit_info(error_msg)
+                return {
+                    "blocked": True,
+                    "risk": cached.risk,
+                    "reasoning": cached.reasoning,
+                    "error_message": error_msg,
+                }
+            # Cached result is within threshold - allow silently
+            return None
+
+        # Cache miss - need LLM assessment
+        # Import here to avoid circular imports
+        from code_puppy_core_plugins.shell_safety.agent_shell_safety import (
+            ShellSafetyAgent,
+        )
+
+        # Create agent and assess command
+        agent = ShellSafetyAgent()
+
+        # Build the assessment prompt with optional cwd context
+        prompt = f"Assess this shell command:\n\nCommand: {command}"
+        if cwd:
+            prompt += f"\nWorking directory: {cwd}"
+
+        # Run async assessment with structured output type
+        result = await agent.run_with_mcp(prompt, output_type=ShellSafetyAssessment)
+        assessment = result.output
+
+        # Cache the result for future use, but only if it's not a fallback assessment
+        if not getattr(assessment, "is_fallback", False):
+            cache_assessment(command, cwd, assessment.risk, assessment.reasoning)
+
+        # Check if risk exceeds threshold (commands at threshold are allowed)
+        if compare_risk_levels(assessment.risk, threshold):
+            risk_display = assessment.risk or "unknown"
+            concise_reason = assessment.reasoning or "No reasoning provided"
+            error_msg = (
+                f"🛑 Command blocked (risk {risk_display.upper()} > permission {threshold.upper()}).\n"
+                f"Reason: {concise_reason}\n"
+                f"Override: /set yolo_mode true or /set safety_permission_level {risk_display}"
+            )
+            emit_info(error_msg)
+
+            # Return rejection info for the command runner
+            return {
+                "blocked": True,
+                "risk": assessment.risk,
+                "reasoning": assessment.reasoning,
+                "error_message": error_msg,
+            }
+
+        # Command is within acceptable risk threshold - remain silent
+        return None  # Allow command to proceed
+
+    except Exception as e:
+        # On any error, fail safe by blocking the command
+        error_msg = (
+            f"🛑 Command blocked (risk HIGH > permission {threshold.upper()}).\n"
+            f"Reason: Safety assessment error: {str(e)}\n"
+            f"Override: /set yolo_mode true or /set safety_permission_level high"
+        )
+        return {
+            "blocked": True,
+            "risk": "high",
+            "reasoning": f"Safety assessment error: {str(e)}",
+            "error_message": error_msg,
+        }
+
+
+def register():
+    """Register the shell safety callback."""
+    register_callback("run_shell_command", shell_safety_callback)
+
+
+# Auto-register the callback when this module is imported
+register()

code_puppy_core_plugins/stack_dump/__init__.py

@@ -0,0 +1 @@
+"""Stack-dump plugin: SIGUSR1 dumps every thread's stack to a log."""