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

ripperdoc/tools/mcp_tools.py

@@ -30,6 +30,7 @@ from ripperdoc.utils.mcp import (
     load_mcp_servers_async,
     shutdown_mcp_runtime,
 )
+from ripperdoc.utils.token_estimation import estimate_tokens
 
 
 logger = get_logger()
@@ -40,6 +41,55 @@ except Exception:  # pragma: no cover - SDK may be missing at runtime
     mcp_types = None  # type: ignore[assignment]
     logger.exception("[mcp_tools] MCP SDK unavailable during import")
 
+DEFAULT_MAX_MCP_OUTPUT_TOKENS = 25_000
+MIN_MCP_OUTPUT_TOKENS = 1_000
+DEFAULT_MCP_WARNING_FRACTION = 0.8
+
+
+def _get_mcp_token_limits() -> tuple[int, int]:
+    """Compute warning and hard limits for MCP output size."""
+    max_tokens = os.getenv("RIPPERDOC_MCP_MAX_OUTPUT_TOKENS")
+    try:
+        max_tokens_int = int(max_tokens) if max_tokens else DEFAULT_MAX_MCP_OUTPUT_TOKENS
+    except (TypeError, ValueError):
+        max_tokens_int = DEFAULT_MAX_MCP_OUTPUT_TOKENS
+    max_tokens_int = max(MIN_MCP_OUTPUT_TOKENS, max_tokens_int)
+
+    warn_env = os.getenv("RIPPERDOC_MCP_WARNING_TOKENS")
+    try:
+        warn_tokens_int = int(warn_env) if warn_env else int(max_tokens_int * DEFAULT_MCP_WARNING_FRACTION)
+    except (TypeError, ValueError):
+        warn_tokens_int = int(max_tokens_int * DEFAULT_MCP_WARNING_FRACTION)
+    warn_tokens_int = max(MIN_MCP_OUTPUT_TOKENS, min(warn_tokens_int, max_tokens_int))
+    return warn_tokens_int, max_tokens_int
+
+
+def _evaluate_mcp_output_size(
+    result_text: Optional[str],
+    server_name: str,
+    tool_name: str,
+) -> tuple[Optional[str], Optional[str], int]:
+    """Return (warning, error, token_estimate) for an MCP result text."""
+    warn_tokens, max_tokens = _get_mcp_token_limits()
+    token_estimate = estimate_tokens(result_text or "")
+
+    if token_estimate > max_tokens:
+        error_text = (
+            f"MCP response from {server_name}:{tool_name} is ~{token_estimate:,} tokens, "
+            f"which exceeds the configured limit of {max_tokens}. "
+            "Refine the request (pagination/filtering) or raise RIPPERDOC_MCP_MAX_OUTPUT_TOKENS."
+        )
+        return None, error_text, token_estimate
+
+    warning_text = None
+    if result_text and token_estimate >= warn_tokens:
+        line_count = result_text.count("\n") + 1
+        warning_text = (
+            f"WARNING: Large MCP response (~{token_estimate:,} tokens, {line_count:,} lines). "
+            "This can fill the context quickly; consider pagination or filters."
+        )
+    return warning_text, None, token_estimate
+
 
 def _content_block_to_text(block: Any) -> str:
     block_type = getattr(block, "type", None) or (
@@ -370,6 +420,9 @@ class ReadMcpResourceOutput(BaseModel):
     uri: str
     content: Optional[str] = None
     contents: List[ResourceContentPart] = Field(default_factory=list)
+    token_estimate: Optional[int] = None
+    warning: Optional[str] = None
+    is_error: bool = False
 
 
 class McpToolCallOutput(BaseModel):
@@ -382,6 +435,8 @@ class McpToolCallOutput(BaseModel):
     content_blocks: Optional[List[Any]] = None
     structured_content: Optional[dict] = None
     is_error: bool = False
+    token_estimate: Optional[int] = None
+    warning: Optional[str] = None
 
 
 class ReadMcpResourceTool(Tool[ReadMcpResourceInput, ReadMcpResourceOutput]):
@@ -552,9 +607,35 @@ class ReadMcpResourceTool(Tool[ReadMcpResourceInput, ReadMcpResourceOutput]):
         read_result: Any = ReadMcpResourceOutput(
             server=input_data.server, uri=input_data.uri, content=content_text, contents=parts
         )
+        assistant_text = self.render_result_for_assistant(read_result)  # type: ignore[arg-type]
+        warning_text, error_text, token_estimate = _evaluate_mcp_output_size(
+            assistant_text, input_data.server, f"resource:{input_data.uri}"
+        )
+
+        if error_text:
+            limited_result = ReadMcpResourceOutput(
+                server=input_data.server,
+                uri=input_data.uri,
+                content=None,
+                contents=[],
+                token_estimate=token_estimate,
+                warning=None,
+                is_error=True,
+            )
+            yield ToolResult(data=limited_result, result_for_assistant=error_text)
+            return
+
+        annotated_result = read_result.model_copy(
+            update={"token_estimate": token_estimate, "warning": warning_text}
+        )
+
+        final_text = assistant_text or ""
+        if not final_text and warning_text:
+            final_text = warning_text
+
         yield ToolResult(
-            data=read_result,
-            result_for_assistant=self.render_result_for_assistant(read_result),  # type: ignore[arg-type]
+            data=annotated_result,
+            result_for_assistant=final_text,  # type: ignore[arg-type]
         )
 
 
@@ -715,9 +796,37 @@ class DynamicMcpTool(Tool[BaseModel, McpToolCallOutput]):
                 structured_content=structured,
                 is_error=getattr(call_result, "isError", False),
             )
+            base_result_text = self.render_result_for_assistant(output)
+            warning_text, error_text, token_estimate = _evaluate_mcp_output_size(
+                base_result_text, self.server_name, self.tool_info.name
+            )
+
+            if error_text:
+                limited_output = McpToolCallOutput(
+                    server=self.server_name,
+                    tool=self.tool_info.name,
+                    content=None,
+                    text=None,
+                    content_blocks=None,
+                    structured_content=None,
+                    is_error=True,
+                    token_estimate=token_estimate,
+                    warning=None,
+                )
+                yield ToolResult(data=limited_output, result_for_assistant=error_text)
+                return
+
+            annotated_output = output.model_copy(
+                update={"token_estimate": token_estimate, "warning": warning_text}
+            )
+
+            final_text = base_result_text or ""
+            if not final_text and warning_text:
+                final_text = warning_text
+
             yield ToolResult(
-                data=output,
-                result_for_assistant=self.render_result_for_assistant(output),
+                data=annotated_output,
+                result_for_assistant=final_text,
             )
         except Exception as exc:  # pragma: no cover - runtime errors
             output = McpToolCallOutput(

ripperdoc/tools/multi_edit_tool.py

@@ -18,6 +18,7 @@ from ripperdoc.core.tool import (
     ValidationResult,
 )
 from ripperdoc.utils.log import get_logger
+from ripperdoc.utils.file_watch import record_snapshot
 
 logger = get_logger()
 
@@ -360,6 +361,17 @@ class MultiEditTool(Tool[MultiEditToolInput, MultiEditToolOutput]):
         file_path.parent.mkdir(parents=True, exist_ok=True)
         try:
             file_path.write_text(updated_content, encoding="utf-8")
+            try:
+                record_snapshot(
+                    str(file_path),
+                    updated_content,
+                    getattr(context, "file_state_cache", {}),
+                )
+            except Exception:
+                logger.exception(
+                    "[multi_edit_tool] Failed to record file snapshot",
+                    extra={"file_path": str(file_path)},
+                )
         except Exception as exc:
             logger.exception(
                 "[multi_edit_tool] Error writing edited file",

ripperdoc/tools/notebook_edit_tool.py

@@ -20,6 +20,7 @@ from ripperdoc.core.tool import (
     ValidationResult,
 )
 from ripperdoc.utils.log import get_logger
+from ripperdoc.utils.file_watch import record_snapshot
 
 
 logger = get_logger()
@@ -272,6 +273,17 @@ class NotebookEditTool(Tool[NotebookEditInput, NotebookEditOutput]):
             )
 
             path.write_text(json.dumps(nb_json, indent=1), encoding="utf-8")
+            try:
+                record_snapshot(
+                    input_data.notebook_path,
+                    json.dumps(nb_json, indent=1),
+                    getattr(context, "file_state_cache", {}),
+                )
+            except Exception:
+                logger.exception(
+                    "[notebook_edit_tool] Failed to record file snapshot",
+                    extra={"file_path": input_data.notebook_path},
+                )
 
             output = NotebookEditOutput(
                 new_source=new_source,

ripperdoc/tools/task_tool.py

@@ -10,6 +10,9 @@ from pydantic import BaseModel, Field
 from ripperdoc.core.agents import (
     AgentDefinition,
     AgentLoadResult,
+    FILE_EDIT_TOOL_NAME,
+    GREP_TOOL_NAME,
+    VIEW_TOOL_NAME,
     clear_agent_cache,
     load_agent_definitions,
     resolve_agent_tools,
@@ -70,12 +73,92 @@ class TaskTool(Tool[TaskToolInput, TaskToolOutput]):
         del safe_mode
         clear_agent_cache()
         agents: AgentLoadResult = load_agent_definitions()
-        agent_lines = "\n".join(summarize_agent(agent) for agent in agents.active_agents)
+
+        agent_lines: List[str] = []
+        for agent in agents.active_agents:
+            properties = (
+                "Properties: access to current context; "
+                if getattr(agent, "fork_context", False)
+                else ""
+            )
+            tools_label = "All tools"
+            if getattr(agent, "tools", None):
+                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})"
+            )
+
+        agent_block = "\n".join(agent_lines) or "- general-purpose (built-in)"
+
+        task_tool_name = self.name
+        file_read_tool_name = VIEW_TOOL_NAME
+        search_tool_name = GREP_TOOL_NAME
+        code_tool_name = FILE_EDIT_TOOL_NAME
+        background_fetch_tool_name = task_tool_name
+
         return (
-            "Use this tool to delegate a well-scoped task to a subagent. "
-            "Always set subagent_type to one of the available agent types below. "
-            "Provide a detailed prompt so the agent can work autonomously and return a single, concise report.\n\n"
-            f"Available agents:\n{agent_lines or '- general-purpose (built-in)'}"
+            f"Launch a new agent to handle complex, multi-step tasks autonomously. \n\n"
+            f"The {task_tool_name} tool launches specialized agents (subprocesses) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.\n\n"
+            f"Available agent types and the tools they have access to:\n"
+            f"{agent_block}\n\n"
+            f"When using the {task_tool_name} tool, you must specify a subagent_type parameter to select which agent type to use.\n\n"
+            f"When NOT to use the {task_tool_name} tool:\n"
+            f"- If you want to read a specific file path, use the {file_read_tool_name} or {search_tool_name} tool instead of the {task_tool_name} tool, to find the match more quickly\n"
+            f'- If you are searching for a specific class definition like "class Foo", use the {search_tool_name} tool instead, to find the match more quickly\n'
+            f"- If you are searching for code within a specific file or set of 2-3 files, use the {file_read_tool_name} tool instead of the {task_tool_name} tool, to find the match more quickly\n"
+            "- Other tasks that are not related to the agent descriptions above\n"
+            "\n"
+            "\n"
+            "Usage notes:\n"
+            "- Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses\n"
+            "- When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.\n"
+            f"- You can optionally run agents in the background using the run_in_background parameter. When an agent runs in the background, you will need to use {background_fetch_tool_name} to retrieve its results once it's done. You can continue to work while background agents run - When you need their results to continue you can use {background_fetch_tool_name} in blocking mode to pause and wait for their results.\n"
+            "- Agents can be resumed using the `resume` parameter by passing the agent ID from a previous invocation. When resumed, the agent continues with its full previous context preserved. When NOT resuming, each invocation starts fresh and you should provide a detailed task description with all necessary context.\n"
+            "- When the agent is done, it will return a single message back to you along with its agent ID. You can use this ID to resume the agent later if needed for follow-up work.\n"
+            "- Provide clear, detailed prompts so the agent can work autonomously and return exactly the information you need.\n"
+            '- Agents with "access to current context" can see the full conversation history before the tool call. When using these agents, you can write concise prompts that reference earlier context (e.g., "investigate the error discussed above") instead of repeating information. The agent will receive all prior messages and understand the context.\n'
+            "- The agent's outputs should generally be trusted\n"
+            "- Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent\n"
+            "- If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.\n"
+            f'- If the user specifies that they want you to run agents "in parallel", you MUST send a single message with multiple {task_tool_name} tool use content blocks. For example, if you need to launch both a code-reviewer agent and a test-runner agent in parallel, send a single message with both tool calls.\n'
+            "\n"
+            "Example usage:\n"
+            "\n"
+            "<example_agent_descriptions>\n"
+            '"code-reviewer": use this agent after you are done writing a signficant piece of code\n'
+            '"greeting-responder": use this agent when to respond to user greetings with a friendly joke\n'
+            "</example_agent_description>\n"
+            "\n"
+            "<example>\n"
+            'user: "Please write a function that checks if a number is prime"\n'
+            "assistant: Sure let me write a function that checks if a number is prime\n"
+            f"assistant: First let me use the {code_tool_name} tool to write a function that checks if a number is prime\n"
+            f"assistant: I'm going to use the {code_tool_name} tool to write the following code:\n"
+            "<code>\n"
+            "function isPrime(n) {\n"
+            "  if (n <= 1) return false\n"
+            "  for (let i = 2; i * i <= n; i++) {\n"
+            "    if (n % i === 0) return false\n"
+            "  }\n"
+            "  return true\n"
+            "}\n"
+            "</code>\n"
+            "<commentary>\n"
+            "Since a signficant piece of code was written and the task was completed, now use the code-reviewer agent to review the code\n"
+            "</commentary>\n"
+            "assistant: Now let me use the code-reviewer agent to review the code\n"
+            f"assistant: Uses the {task_tool_name} tool to launch the code-reviewer agent \n"
+            "</example>\n"
+            "\n"
+            "<example>\n"
+            'user: "Hello"\n'
+            "<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'
+            "</example>"
         )
 
     def is_read_only(self) -> bool:

ripperdoc/tools/todo_tool.py

@@ -361,9 +361,7 @@ class TodoWriteTool(Tool[TodoWriteToolInput, TodoToolOutput]):
             )
             yield ToolResult(data=output, result_for_assistant=result_text)
         except Exception as exc:
-            logger.exception(
-                "[todo_tool] Error updating todos", extra={"error": str(exc)}
-            )
+            logger.exception("[todo_tool] Error updating todos", extra={"error": str(exc)})
             error = f"Error updating todos: {exc}"
             yield ToolResult(
                 data=TodoToolOutput(

ripperdoc/tools/tool_search_tool.py

@@ -119,7 +119,9 @@ 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(
@@ -280,9 +282,11 @@ class ToolSearchTool(Tool[ToolSearchInput, ToolSearchOutput]):
                     "name": name,
                     "user_facing_name": tool.user_facing_name(),
                     "description": description,
-                    "active": getattr(registry, "is_active", lambda *_: False)(name)
-                    if hasattr(registry, "is_active")
-                    else False,
+                    "active": (
+                        getattr(registry, "is_active", lambda *_: False)(name)
+                        if hasattr(registry, "is_active")
+                        else False
+                    ),
                     "deferred": name in getattr(registry, "deferred_names", set()),
                     "score": 0.0,
                 }

ripperdoc/utils/file_watch.py

@@ -0,0 +1,134 @@
+"""Lightweight file-change tracking for notifying the model about user edits."""
+
+from __future__ import annotations
+
+import difflib
+import os
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+from ripperdoc.utils.log import get_logger
+
+logger = get_logger()
+
+
+@dataclass
+class FileSnapshot:
+    """Snapshot of a file read by the agent."""
+
+    content: str
+    timestamp: float
+    offset: int = 0
+    limit: Optional[int] = None
+
+
+@dataclass
+class ChangedFileNotice:
+    """Information about a file that changed after it was read."""
+
+    file_path: str
+    summary: str
+
+
+def record_snapshot(
+    file_path: str,
+    content: str,
+    cache: Dict[str, FileSnapshot],
+    *,
+    offset: int = 0,
+    limit: Optional[int] = None,
+) -> None:
+    """Store the current contents and mtime for a file."""
+    try:
+        timestamp = os.path.getmtime(file_path)
+    except OSError:
+        timestamp = 0.0
+    cache[file_path] = FileSnapshot(
+        content=content, timestamp=timestamp, offset=offset, limit=limit
+    )
+
+
+def _read_portion(file_path: str, offset: int, limit: Optional[int]) -> str:
+    with open(file_path, "r", encoding="utf-8", errors="replace") as handle:
+        lines = handle.readlines()
+    start = max(offset, 0)
+    if limit is None:
+        selected = lines[start:]
+    else:
+        selected = lines[start : start + limit]
+    return "".join(selected)
+
+
+def _build_diff_summary(old_content: str, new_content: str, file_path: str, max_lines: int) -> str:
+    diff = list(
+        difflib.unified_diff(
+            old_content.splitlines(),
+            new_content.splitlines(),
+            fromfile=file_path,
+            tofile=file_path,
+            lineterm="",
+        )
+    )
+    if not diff:
+        return "File was modified but contents appear unchanged."
+
+    # Keep the diff short to avoid flooding the model.
+    if len(diff) > max_lines:
+        diff = diff[:max_lines] + ["... (diff truncated)"]
+    return "\n".join(diff)
+
+
+def detect_changed_files(
+    cache: Dict[str, FileSnapshot], *, max_diff_lines: int = 80
+) -> List[ChangedFileNotice]:
+    """Return notices for files whose mtime increased since they were read."""
+    notices: List[ChangedFileNotice] = []
+
+    # Iterate over a static list so we can mutate cache safely.
+    for file_path, snapshot in list(cache.items()):
+        try:
+            current_mtime = os.path.getmtime(file_path)
+        except OSError:
+            notices.append(
+                ChangedFileNotice(
+                    file_path=file_path, summary="File was deleted or is no longer accessible."
+                )
+            )
+            cache.pop(file_path, None)
+            continue
+
+        if current_mtime <= snapshot.timestamp:
+            continue
+
+        try:
+            new_content = _read_portion(file_path, snapshot.offset, snapshot.limit)
+        except Exception as exc:  # pragma: no cover - best-effort telemetry
+            logger.exception(
+                "[file_watch] Failed reading changed file",
+                extra={"file_path": file_path, "error": str(exc)},
+            )
+            notices.append(
+                ChangedFileNotice(
+                    file_path=file_path,
+                    summary=f"File changed but could not be read: {exc}",
+                )
+            )
+            # Avoid spamming repeated errors by updating timestamp.
+            snapshot.timestamp = current_mtime
+            cache[file_path] = snapshot
+            continue
+
+        diff_summary = _build_diff_summary(
+            snapshot.content, new_content, file_path, max_lines=max_diff_lines
+        )
+        notices.append(ChangedFileNotice(file_path=file_path, summary=diff_summary))
+        # Update snapshot so we only notify on subsequent changes.
+        record_snapshot(
+            file_path,
+            new_content,
+            cache,
+            offset=snapshot.offset,
+            limit=snapshot.limit,
+        )
+
+    return notices