ripperdoc 0.2.4__py3-none-any.whl → 0.2.5__py3-none-any.whl

ripperdoc/tools/multi_edit_tool.py

@@ -4,6 +4,7 @@ Allows performing multiple exact string replacements in a single file atomically
 """
 
 import difflib
+import os
 from pathlib import Path
 from typing import AsyncGenerator, Optional, List
 from textwrap import dedent
@@ -168,6 +169,7 @@ class MultiEditTool(Tool[MultiEditToolInput, MultiEditToolOutput]):
         path = Path(input_data.file_path).expanduser()
         if not path.is_absolute():
             path = Path.cwd() / path
+        resolved_path = str(path.resolve())
 
         # Ensure edits differ.
         for edit in input_data.edits:
@@ -175,6 +177,7 @@ class MultiEditTool(Tool[MultiEditToolInput, MultiEditToolOutput]):
                 return ValidationResult(
                     result=False,
                     message="old_string and new_string must be different",
+                    error_code=1,
                 )
 
         # If the file exists, ensure it is not a directory.
@@ -182,8 +185,41 @@ class MultiEditTool(Tool[MultiEditToolInput, MultiEditToolOutput]):
             return ValidationResult(
                 result=False,
                 message=f"Path is a directory, not a file: {path}",
+                error_code=2,
             )
 
+        # Check if this is a file creation (first edit has empty old_string)
+        is_creation = (
+            not path.exists()
+            and len(input_data.edits) > 0
+            and input_data.edits[0].old_string == ""
+        )
+
+        # If file exists, check if it has been read before editing
+        if path.exists() and not is_creation:
+            file_state_cache = getattr(context, "file_state_cache", {}) if context else {}
+            file_snapshot = file_state_cache.get(resolved_path)
+
+            if not file_snapshot:
+                return ValidationResult(
+                    result=False,
+                    message="File has not been read yet. Read it first before editing.",
+                    error_code=3,
+                )
+
+            # Check if file has been modified since it was read
+            try:
+                current_mtime = os.path.getmtime(resolved_path)
+                if current_mtime > file_snapshot.timestamp:
+                    return ValidationResult(
+                        result=False,
+                        message="File has been modified since read, either by the user or by a linter. "
+                        "Read it again before attempting to edit it.",
+                        error_code=4,
+                    )
+            except OSError:
+                pass  # File mtime check failed, proceed anyway
+
         return ValidationResult(result=True)
 
     def render_result_for_assistant(self, output: MultiEditToolOutput) -> str:
@@ -310,9 +346,11 @@ class MultiEditTool(Tool[MultiEditToolInput, MultiEditToolOutput]):
         try:
             if existing:
                 original_content = file_path.read_text(encoding="utf-8")
-        except Exception as exc:  # pragma: no cover - unlikely permission issue
-            logger.exception(
-                "[multi_edit_tool] Error reading file before edits",
+        except (OSError, IOError, PermissionError) as exc:
+            # pragma: no cover - unlikely permission issue
+            logger.warning(
+                "[multi_edit_tool] Error reading file before edits: %s: %s",
+                type(exc).__name__, exc,
                 extra={"file_path": str(file_path)},
             )
             output = MultiEditToolOutput(
@@ -367,14 +405,16 @@ class MultiEditTool(Tool[MultiEditToolInput, MultiEditToolOutput]):
                     updated_content,
                     getattr(context, "file_state_cache", {}),
                 )
-            except Exception:
-                logger.exception(
-                    "[multi_edit_tool] Failed to record file snapshot",
+            except (OSError, IOError, RuntimeError) as exc:
+                logger.warning(
+                    "[multi_edit_tool] Failed to record file snapshot: %s: %s",
+                    type(exc).__name__, exc,
                     extra={"file_path": str(file_path)},
                 )
-        except Exception as exc:
-            logger.exception(
-                "[multi_edit_tool] Error writing edited file",
+        except (OSError, IOError, PermissionError, UnicodeDecodeError) as exc:
+            logger.warning(
+                "[multi_edit_tool] Error writing edited file: %s: %s",
+                type(exc).__name__, exc,
                 extra={"file_path": str(file_path)},
             )
             output = MultiEditToolOutput(

ripperdoc/tools/notebook_edit_tool.py

@@ -4,6 +4,7 @@ Allows performing insert/replace/delete operations on Jupyter notebook cells.
 """
 
 import json
+import os
 import random
 import string
 from pathlib import Path
@@ -137,39 +138,79 @@ class NotebookEditTool(Tool[NotebookEditInput, NotebookEditOutput]):
         self, input_data: NotebookEditInput, context: Optional[ToolUseContext] = None
     ) -> ValidationResult:
         path = _resolve_path(input_data.notebook_path)
+        resolved_path = str(path.resolve())
 
         if not path.exists():
-            return ValidationResult(result=False, message="Notebook file does not exist.")
+            return ValidationResult(
+                result=False,
+                message="Notebook file does not exist.",
+                error_code=1,
+            )
         if path.suffix != ".ipynb":
             return ValidationResult(
                 result=False,
                 message="File must be a Jupyter notebook (.ipynb file). Use Edit for other file types.",
+                error_code=2,
             )
 
         mode = (input_data.edit_mode or "replace").lower()
         if mode not in {"replace", "insert", "delete"}:
             return ValidationResult(
-                result=False, message="edit_mode must be replace, insert, or delete."
+                result=False,
+                message="edit_mode must be replace, insert, or delete.",
+                error_code=3,
             )
         if mode == "insert" and not input_data.cell_type:
             return ValidationResult(
                 result=False,
                 message="cell_type is required when using edit_mode=insert.",
+                error_code=4,
             )
         if mode != "insert" and not input_data.cell_id:
             return ValidationResult(
                 result=False,
                 message="cell_id must be specified when using edit_mode=replace or delete.",
+                error_code=5,
+            )
+
+        # Check if file has been read before editing
+        file_state_cache = getattr(context, "file_state_cache", {}) if context else {}
+        file_snapshot = file_state_cache.get(resolved_path)
+
+        if not file_snapshot:
+            return ValidationResult(
+                result=False,
+                message="Notebook has not been read yet. Read it first before editing.",
+                error_code=6,
             )
 
+        # Check if file has been modified since it was read
+        try:
+            current_mtime = os.path.getmtime(resolved_path)
+            if current_mtime > file_snapshot.timestamp:
+                return ValidationResult(
+                    result=False,
+                    message="Notebook has been modified since read, either by the user or by a linter. "
+                    "Read it again before attempting to edit it.",
+                    error_code=7,
+                )
+        except OSError:
+            pass  # File mtime check failed, proceed anyway
+
         # Validate notebook structure and target cell.
         try:
             raw = path.read_text(encoding="utf-8")
             nb_json = json.loads(raw)
-        except Exception:
-            logger.exception("Failed to parse notebook", extra={"path": str(path)})
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError) as exc:
+            logger.warning(
+                "Failed to parse notebook: %s: %s",
+                type(exc).__name__, exc,
+                extra={"path": str(path)},
+            )
             return ValidationResult(
-                result=False, message="Notebook is not valid JSON.", error_code=6
+                result=False,
+                message="Notebook is not valid JSON.",
+                error_code=8,
             )
 
         cells = nb_json.get("cells", [])
@@ -180,7 +221,7 @@ class NotebookEditTool(Tool[NotebookEditInput, NotebookEditOutput]):
             return ValidationResult(
                 result=False,
                 message=f"Cell '{input_data.cell_id}' not found in notebook.",
-                error_code=7,
+                error_code=9,
             )
 
         return ValidationResult(result=True)
@@ -279,9 +320,10 @@ class NotebookEditTool(Tool[NotebookEditInput, NotebookEditOutput]):
                     json.dumps(nb_json, indent=1),
                     getattr(context, "file_state_cache", {}),
                 )
-            except Exception:
-                logger.exception(
-                    "[notebook_edit_tool] Failed to record file snapshot",
+            except (OSError, IOError, RuntimeError) as exc:
+                logger.warning(
+                    "[notebook_edit_tool] Failed to record file snapshot: %s: %s",
+                    type(exc).__name__, exc,
                     extra={"file_path": input_data.notebook_path},
                 )
 
@@ -296,10 +338,12 @@ class NotebookEditTool(Tool[NotebookEditInput, NotebookEditOutput]):
             yield ToolResult(
                 data=output, result_for_assistant=self.render_result_for_assistant(output)
             )
-        except Exception as exc:  # pragma: no cover - error path
-            logger.exception(
-                "Error editing notebook",
-                extra={"path": input_data.notebook_path, "error": str(exc)},
+        except (OSError, json.JSONDecodeError, ValueError, KeyError) as exc:
+            # pragma: no cover - error path
+            logger.warning(
+                "Error editing notebook: %s: %s",
+                type(exc).__name__, exc,
+                extra={"path": input_data.notebook_path},
             )
             output = NotebookEditOutput(
                 new_source=new_source,

ripperdoc/tools/skill_tool.py

@@ -0,0 +1,205 @@
+"""Skill loader tool.
+
+Loads SKILL.md content from .ripperdoc/skills or ~/.ripperdoc/skills so the
+assistant can pull in specialized instructions only when needed.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import AsyncGenerator, List, Optional
+
+from pydantic import BaseModel, Field
+
+from ripperdoc.core.skills import SkillDefinition, find_skill
+from ripperdoc.core.tool import (
+    Tool,
+    ToolOutput,
+    ToolResult,
+    ToolUseContext,
+    ToolUseExample,
+    ValidationResult,
+)
+from ripperdoc.utils.log import get_logger
+
+logger = get_logger()
+
+
+class SkillToolInput(BaseModel):
+    """Input schema for the Skill tool."""
+
+    skill: str = Field(description='The skill name (e.g. "pdf-processing").')
+
+
+class SkillToolOutput(BaseModel):
+    """Structured output for a loaded skill."""
+
+    success: bool = True
+    skill: str
+    description: str
+    location: str
+    base_dir: str
+    path: str
+    allowed_tools: List[str] = Field(default_factory=list)
+    model: Optional[str] = None
+    max_thinking_tokens: Optional[int] = None
+    skill_type: str = "prompt"
+    disable_model_invocation: bool = False
+    content: str
+
+
+class SkillTool(Tool[SkillToolInput, SkillToolOutput]):
+    """Load a skill's instructions by name."""
+
+    def __init__(self, project_path: Optional[Path] = None, home: Optional[Path] = None) -> None:
+        self._project_path = project_path
+        self._home = home
+
+    @property
+    def name(self) -> str:
+        return "Skill"
+
+    async def description(self) -> str:
+        return (
+            "Execute a skill by name to load its SKILL.md instructions. "
+            "Use this only when the skill description clearly matches the user's request. "
+            "Skill metadata may include allowed-tools, model, or max-thinking-tokens hints."
+        )
+
+    @property
+    def input_schema(self) -> type[SkillToolInput]:
+        return SkillToolInput
+
+    def input_examples(self) -> List[ToolUseExample]:
+        return [
+            ToolUseExample(
+                description="Load PDF processing guidance",
+                example={"skill": "pdf-processing"},
+            ),
+            ToolUseExample(
+                description="Load commit message helper instructions",
+                example={"skill": "generating-commit-messages"},
+            ),
+        ]
+
+    async def prompt(self, safe_mode: bool = False) -> str:  # noqa: ARG002
+        return (
+            "Load a skill by name to read its SKILL.md content. "
+            "Only call this when the skill description is clearly relevant. "
+            "If the skill specifies allowed-tools, model, or max-thinking-tokens in frontmatter, "
+            "assume those hints apply for subsequent reasoning. "
+            "Skill files may reference additional files under the same directory; "
+            "use file tools to read them if needed."
+        )
+
+    def is_read_only(self) -> bool:
+        return True
+
+    def is_concurrency_safe(self) -> bool:
+        return False
+
+    def needs_permissions(self, input_data: Optional[SkillToolInput] = None) -> bool:  # noqa: ARG002
+        return False
+
+    async def validate_input(
+        self,
+        input_data: SkillToolInput,
+        context: Optional[ToolUseContext] = None,  # noqa: ARG002
+    ) -> ValidationResult:
+        skill_name = (input_data.skill or "").strip().lstrip("/")
+        if not skill_name:
+            return ValidationResult(
+                result=False, message="Provide a skill name to load.", error_code=1
+            )
+        skill = find_skill(skill_name, project_path=self._project_path, home=self._home)
+        if not skill:
+            return ValidationResult(
+                result=False, message=f"Unknown skill: {skill_name}", error_code=2
+            )
+        if skill.disable_model_invocation:
+            return ValidationResult(
+                result=False,
+                message=f"Skill {skill_name} is blocked by disable-model-invocation.",
+                error_code=4,
+            )
+        if skill.skill_type and skill.skill_type != "prompt":
+            return ValidationResult(
+                result=False,
+                message=f"Skill {skill_name} is not a prompt-based skill (type={skill.skill_type}).",
+                error_code=5,
+                meta={"skill_type": skill.skill_type},
+            )
+        return ValidationResult(result=True)
+
+    def _render_result(self, skill: SkillDefinition) -> str:
+        allowed = ", ".join(skill.allowed_tools) if skill.allowed_tools else "no specific limit"
+        model_hint = f"\nModel hint: {skill.model}" if skill.model else ""
+        max_tokens = (
+            f"\nMax thinking tokens hint: {skill.max_thinking_tokens}"
+            if skill.max_thinking_tokens is not None
+            else ""
+        )
+        lines = [
+            f"Skill loaded: {skill.name} ({skill.location.value})",
+            f"Description: {skill.description}",
+            f"Skill directory: {skill.base_dir}",
+            f"Allowed tools (if specified): {allowed}{model_hint}{max_tokens}",
+            "SKILL.md content:",
+            skill.content,
+        ]
+        return "\n".join(lines)
+
+    def _to_output(self, skill: SkillDefinition) -> SkillToolOutput:
+        return SkillToolOutput(
+            success=True,
+            skill=skill.name,
+            description=skill.description,
+            location=skill.location.value,
+            base_dir=str(skill.base_dir),
+            path=str(skill.path),
+            allowed_tools=list(skill.allowed_tools),
+            model=skill.model,
+            max_thinking_tokens=skill.max_thinking_tokens,
+            skill_type=skill.skill_type,
+            disable_model_invocation=skill.disable_model_invocation,
+            content=skill.content,
+        )
+
+    async def call(
+        self, input_data: SkillToolInput, context: ToolUseContext
+    ) -> AsyncGenerator[ToolOutput, None]:  # noqa: ARG002
+        skill_name = (input_data.skill or "").strip().lstrip("/")
+        skill = find_skill(skill_name, project_path=self._project_path, home=self._home)
+        if not skill:
+            error_text = (
+                f"Skill '{skill_name}' not found. Ensure it exists under "
+                "~/.ripperdoc/skills or ./.ripperdoc/skills."
+            )
+            yield ToolResult(data={"error": error_text}, result_for_assistant=error_text)
+            return
+        if skill.allowed_tools and context.tool_registry is not None:
+            # Ensure preferred tools for this skill are activated in the registry.
+            context.tool_registry.activate_tools(skill.allowed_tools)
+
+        output = self._to_output(skill)
+        yield ToolResult(data=output, result_for_assistant=self._render_result(skill))
+
+    def render_result_for_assistant(self, output: SkillToolOutput) -> str:
+        allowed = ", ".join(output.allowed_tools) if output.allowed_tools else "no specific limit"
+        model_hint = f"\nModel hint: {output.model}" if output.model else ""
+        max_tokens = (
+            f"\nMax thinking tokens hint: {output.max_thinking_tokens}"
+            if output.max_thinking_tokens is not None
+            else ""
+        )
+        return (
+            f"Skill loaded: {output.skill} ({output.location})\n"
+            f"Description: {output.description}\n"
+            f"Skill directory: {output.base_dir}\n"
+            f"Allowed tools (if specified): {allowed}{model_hint}{max_tokens}\n"
+            "SKILL.md content:\n"
+            f"{output.content}"
+        )
+
+    def render_tool_use_message(self, input_data: SkillToolInput, verbose: bool = False) -> str:  # noqa: ARG002
+        return f"Load skill '{input_data.skill}'"

ripperdoc/tools/task_tool.py

@@ -83,9 +83,7 @@ class TaskTool(Tool[TaskToolInput, TaskToolOutput]):
             )
             tools_label = "All tools"
             if getattr(agent, "tools", None):
-                tools_label = (
-                    "All tools" if "*" in agent.tools else ", ".join(agent.tools)
-                )
+                tools_label = "All tools" if "*" in agent.tools else ", ".join(agent.tools)
             agent_lines.append(
                 f"- {agent.agent_type}: {agent.when_to_use} ({properties}Tools: {tools_label})"
             )
@@ -157,7 +155,7 @@ class TaskTool(Tool[TaskToolInput, TaskToolOutput]):
             "<commentary>\n"
             "Since the user is greeting, use the greeting-responder agent to respond with a friendly joke\n"
             "</commentary>\n"
-            f'assistant: "I\'m going to use the {task_tool_name} tool to launch the greeting-responder agent\"\n'
+            f'assistant: "I\'m going to use the {task_tool_name} tool to launch the greeting-responder agent"\n'
             "</example>"
         )
 
@@ -369,10 +367,11 @@ class TaskTool(Tool[TaskToolInput, TaskToolOutput]):
 
             try:
                 serialized = json.dumps(inp, ensure_ascii=False)
-            except Exception:
-                logger.exception(
-                    "[task_tool] Failed to serialize tool_use input",
-                    extra={"tool_use_input": str(inp)},
+            except (TypeError, ValueError) as exc:
+                logger.warning(
+                    "[task_tool] Failed to serialize tool_use input: %s: %s",
+                    type(exc).__name__, exc,
+                    extra={"tool_use_input": str(inp)[:200]},
                 )
                 serialized = str(inp)
             return serialized if len(serialized) <= 120 else serialized[:117] + "..."

ripperdoc/tools/todo_tool.py

@@ -309,7 +309,7 @@ class TodoWriteTool(Tool[TodoWriteToolInput, TodoToolOutput]):
             ),
         ]
 
-    async def prompt(self, safe_mode: bool = False) -> str:
+    async def prompt(self, _safe_mode: bool = False) -> str:
         return TODO_WRITE_PROMPT
 
     def is_read_only(self) -> bool:
@@ -318,13 +318,13 @@ class TodoWriteTool(Tool[TodoWriteToolInput, TodoToolOutput]):
     def is_concurrency_safe(self) -> bool:
         return False
 
-    def needs_permissions(self, input_data: Optional[TodoWriteToolInput] = None) -> bool:
+    def needs_permissions(self, _input_data: Optional[TodoWriteToolInput] = None) -> bool:
         return False
 
     async def validate_input(
         self,
         input_data: TodoWriteToolInput,
-        context: Optional[ToolUseContext] = None,
+        _context: Optional[ToolUseContext] = None,
     ) -> ValidationResult:
         todos = [TodoItem(**todo.model_dump()) for todo in input_data.todos]
         ok, message = validate_todos(todos)
@@ -338,14 +338,14 @@ class TodoWriteTool(Tool[TodoWriteToolInput, TodoToolOutput]):
     def render_tool_use_message(
         self,
         input_data: TodoWriteToolInput,
-        verbose: bool = False,
+        _verbose: bool = False,
     ) -> str:
         return f"Updating todo list with {len(input_data.todos)} item(s)"
 
     async def call(
         self,
         input_data: TodoWriteToolInput,
-        context: ToolUseContext,
+        _context: ToolUseContext,
     ) -> AsyncGenerator[ToolOutput, None]:
         try:
             todos = [TodoItem(**todo.model_dump()) for todo in input_data.todos]
@@ -360,8 +360,8 @@ class TodoWriteTool(Tool[TodoWriteToolInput, TodoToolOutput]):
                 next_todo=get_next_actionable(updated),
             )
             yield ToolResult(data=output, result_for_assistant=result_text)
-        except Exception as exc:
-            logger.exception("[todo_tool] Error updating todos", extra={"error": str(exc)})
+        except (OSError, ValueError, KeyError, TypeError) as exc:
+            logger.warning("[todo_tool] Error updating todos: %s: %s", type(exc).__name__, exc)
             error = f"Error updating todos: {exc}"
             yield ToolResult(
                 data=TodoToolOutput(
@@ -403,7 +403,7 @@ class TodoReadTool(Tool[TodoReadToolInput, TodoToolOutput]):
             ),
         ]
 
-    async def prompt(self, safe_mode: bool = False) -> str:
+    async def prompt(self, _safe_mode: bool = False) -> str:
         return (
             "Use TodoRead to fetch the current todo list before making progress or when you need "
             "to confirm the next action. You can request only the next actionable item or filter "
@@ -416,13 +416,13 @@ class TodoReadTool(Tool[TodoReadToolInput, TodoToolOutput]):
     def is_concurrency_safe(self) -> bool:
         return True
 
-    def needs_permissions(self, input_data: Optional[TodoReadToolInput] = None) -> bool:
+    def needs_permissions(self, _input_data: Optional[TodoReadToolInput] = None) -> bool:
         return False
 
     async def validate_input(
         self,
         input_data: TodoReadToolInput,
-        context: Optional[ToolUseContext] = None,
+        _context: Optional[ToolUseContext] = None,
     ) -> ValidationResult:
         if input_data.limit < 0:
             return ValidationResult(result=False, message="limit cannot be negative")
@@ -445,7 +445,7 @@ class TodoReadTool(Tool[TodoReadToolInput, TodoToolOutput]):
     def render_tool_use_message(
         self,
         input_data: TodoReadToolInput,
-        verbose: bool = False,
+        _verbose: bool = False,
     ) -> str:
         if input_data.next_only:
             return "Reading next actionable todo"
@@ -454,7 +454,7 @@ class TodoReadTool(Tool[TodoReadToolInput, TodoToolOutput]):
     async def call(
         self,
         input_data: TodoReadToolInput,
-        context: ToolUseContext,
+        _context: ToolUseContext,
     ) -> AsyncGenerator[ToolOutput, None]:
         all_todos = load_todos()
         filtered = all_todos

ripperdoc/tools/tool_search_tool.py

@@ -119,9 +119,7 @@ class ToolSearchTool(Tool[ToolSearchInput, ToolSearchOutput]):
     def is_concurrency_safe(self) -> bool:
         return True
 
-    def needs_permissions(
-        self, input_data: Optional[ToolSearchInput] = None
-    ) -> bool:  # noqa: ARG002
+    def needs_permissions(self, input_data: Optional[ToolSearchInput] = None) -> bool:  # noqa: ARG002
         return False
 
     async def validate_input(
@@ -191,10 +189,11 @@ class ToolSearchTool(Tool[ToolSearchInput, ToolSearchOutput]):
                 description = await build_tool_description(
                     tool, include_examples=include_examples, max_examples=2
                 )
-            except Exception:
+            except (OSError, RuntimeError, ValueError, TypeError, AttributeError, KeyError) as exc:
                 description = ""
-                logger.exception(
-                    "[tool_search] Failed to build tool description",
+                logger.warning(
+                    "[tool_search] Failed to build tool description: %s: %s",
+                    type(exc).__name__, exc,
                     extra={"tool_name": getattr(tool, "name", None)},
                 )
             doc_text = " ".join([name, tool.user_facing_name(), description])

ripperdoc/utils/coerce.py

@@ -0,0 +1,34 @@
+"""Lightweight parsing helpers for permissive type coercion."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+def parse_boolish(value: object, default: bool = False) -> bool:
+    """Parse a truthy/falsey value from common representations."""
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, (int, float)):
+        return bool(value)
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        if normalized in {"1", "true", "yes", "on"}:
+            return True
+        if normalized in {"0", "false", "no", "off"}:
+            return False
+    return default
+
+
+def parse_optional_int(value: object) -> Optional[int]:
+    """Best-effort int parsing; returns None on failure."""
+    try:
+        if value is None:
+            return None
+        if isinstance(value, bool):
+            return int(value)
+        return int(str(value).strip())
+    except (ValueError, TypeError):
+        return None