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

ripperdoc/core/providers/openai.py

@@ -2,8 +2,10 @@
 
 from __future__ import annotations
 
+import asyncio
 import time
 from typing import Any, Dict, List, Optional, cast
+from uuid import uuid4
 
 from openai import AsyncOpenAI
 
@@ -13,12 +15,14 @@ from ripperdoc.core.providers.base import (
     ProviderClient,
     ProviderResponse,
     call_with_timeout_and_retries,
+    iter_with_timeout,
     sanitize_tool_history,
 )
 from ripperdoc.core.query_utils import (
     build_openai_tool_schemas,
     content_blocks_from_openai_choice,
     estimate_cost_usd,
+    _normalize_tool_args,
     openai_usage_tokens,
 )
 from ripperdoc.core.tool import Tool
@@ -50,26 +54,46 @@ class OpenAIClient(ProviderClient):
             {"role": "system", "content": system_prompt}
         ] + sanitize_tool_history(list(normalized_messages))
         collected_text: List[str] = []
+        streamed_tool_calls: Dict[int, Dict[str, Optional[str]]] = {}
+        streamed_tool_text: List[str] = []
+        streamed_usage: Dict[str, int] = {}
 
-        can_stream = stream and tool_mode == "text" and not openai_tools
+        can_stream_text = stream and tool_mode == "text" and not openai_tools
+        can_stream_tools = stream and tool_mode != "text" and bool(openai_tools)
+        can_stream = can_stream_text or can_stream_tools
 
         async with AsyncOpenAI(
             api_key=model_profile.api_key, base_url=model_profile.api_base
         ) as client:
 
             async def _stream_request() -> Dict[str, Dict[str, int]]:
-                stream_resp = await client.chat.completions.create(  # type: ignore[call-overload]
+                announced_tool_indexes: set[int] = set()
+                stream_coro = client.chat.completions.create(  # type: ignore[call-overload]
                     model=model_profile.model,
                     messages=cast(Any, openai_messages),
-                    tools=None,
+                    tools=openai_tools if can_stream_tools else None,
                     temperature=model_profile.temperature,
                     max_tokens=model_profile.max_tokens,
                     stream=True,
+                    stream_options={"include_usage": True},
                 )
-                usage_tokens: Dict[str, int] = {}
-                async for chunk in stream_resp:
+                stream_resp = (
+                    await asyncio.wait_for(stream_coro, timeout=request_timeout)
+                    if request_timeout and request_timeout > 0
+                    else await stream_coro
+                )
+                async for chunk in iter_with_timeout(stream_resp, request_timeout):
+                    if getattr(chunk, "usage", None):
+                        streamed_usage.update(openai_usage_tokens(chunk.usage))
+
+                    if not getattr(chunk, "choices", None):
+                        continue
                     delta = getattr(chunk.choices[0], "delta", None)
-                    delta_content = getattr(delta, "content", None) if delta else None
+                    if not delta:
+                        continue
+
+                    # Text deltas (rare in native tool mode but supported)
+                    delta_content = getattr(delta, "content", None)
                     text_delta = ""
                     if delta_content:
                         if isinstance(delta_content, list):
@@ -82,15 +106,50 @@ class OpenAIClient(ProviderClient):
                         elif isinstance(delta_content, str):
                             text_delta += delta_content
                     if text_delta:
-                        collected_text.append(text_delta)
+                        target_collector = streamed_tool_text if can_stream_tools else collected_text
+                        target_collector.append(text_delta)
                         if progress_callback:
                             try:
                                 await progress_callback(text_delta)
                             except Exception:
                                 logger.exception("[openai_client] Stream callback failed")
-                    if getattr(chunk, "usage", None):
-                        usage_tokens = openai_usage_tokens(chunk.usage)
-                return {"usage": usage_tokens}
+
+                    # Tool call deltas for native tool mode
+                    if not can_stream_tools:
+                        continue
+
+                    for tool_delta in getattr(delta, "tool_calls", []) or []:
+                        idx = getattr(tool_delta, "index", 0) or 0
+                        state = streamed_tool_calls.get(idx, {"id": None, "name": None, "arguments": ""})
+
+                        if getattr(tool_delta, "id", None):
+                            state["id"] = tool_delta.id
+
+                        function_delta = getattr(tool_delta, "function", None)
+                        if function_delta:
+                            fn_name = getattr(function_delta, "name", None)
+                            if fn_name:
+                                state["name"] = fn_name
+                            args_delta = getattr(function_delta, "arguments", None)
+                            if args_delta:
+                                state["arguments"] = (state.get("arguments") or "") + args_delta
+                                if progress_callback:
+                                    try:
+                                        await progress_callback(args_delta)
+                                    except Exception:
+                                        logger.exception("[openai_client] Stream callback failed")
+
+                        if idx not in announced_tool_indexes and state.get("name"):
+                            announced_tool_indexes.add(idx)
+                            if progress_callback:
+                                try:
+                                    await progress_callback(f"[tool:{state['name']}]")
+                                except Exception:
+                                    logger.exception("[openai_client] Stream callback failed")
+
+                        streamed_tool_calls[idx] = state
+
+                return {"usage": streamed_usage}
 
             async def _non_stream_request() -> Any:
                 return await client.chat.completions.create(  # type: ignore[call-overload]
@@ -101,23 +160,75 @@ class OpenAIClient(ProviderClient):
                     max_tokens=model_profile.max_tokens,
                 )
 
+            timeout_for_call = None if can_stream else request_timeout
             openai_response: Any = await call_with_timeout_and_retries(
                 _stream_request if can_stream else _non_stream_request,
-                request_timeout,
+                timeout_for_call,
                 max_retries,
             )
 
+            if (
+                can_stream_text
+                and not collected_text
+                and not streamed_tool_calls
+                and not streamed_tool_text
+            ):
+                logger.debug(
+                    "[openai_client] Streaming returned no content; retrying without stream",
+                    extra={"model": model_profile.model},
+                )
+                can_stream = False
+                can_stream_text = False
+                can_stream_tools = False
+                openai_response = await call_with_timeout_and_retries(
+                    _non_stream_request, request_timeout, max_retries
+                )
+
         duration_ms = (time.time() - start_time) * 1000
-        usage_tokens = openai_usage_tokens(getattr(openai_response, "usage", None))
+        usage_tokens = streamed_usage if can_stream else openai_usage_tokens(
+            getattr(openai_response, "usage", None)
+        )
         cost_usd = estimate_cost_usd(model_profile, usage_tokens)
         record_usage(
             model_profile.model, duration_ms=duration_ms, cost_usd=cost_usd, **usage_tokens
         )
 
-        finish_reason: Optional[str]
-        if can_stream:
+        if not can_stream and (not openai_response or not getattr(openai_response, "choices", None)):
+            logger.warning(
+                "[openai_client] No choices returned from OpenAI response",
+                extra={"model": model_profile.model},
+            )
+            empty_text = "Model returned no content."
+            return ProviderResponse(
+                content_blocks=[{"type": "text", "text": empty_text}],
+                usage_tokens=usage_tokens,
+                cost_usd=cost_usd,
+                duration_ms=duration_ms,
+            )
+
+        content_blocks: List[Dict[str, Any]] = []
+        finish_reason: Optional[str] = None
+        if can_stream_text:
             content_blocks = [{"type": "text", "text": "".join(collected_text)}]
             finish_reason = "stream"
+        elif can_stream_tools:
+            if streamed_tool_text:
+                content_blocks.append({"type": "text", "text": "".join(streamed_tool_text)})
+            for idx in sorted(streamed_tool_calls.keys()):
+                call = streamed_tool_calls[idx]
+                name = call.get("name")
+                if not name:
+                    continue
+                tool_use_id = call.get("id") or str(uuid4())
+                content_blocks.append(
+                    {
+                        "type": "tool_use",
+                        "tool_use_id": tool_use_id,
+                        "name": name,
+                        "input": _normalize_tool_args(call.get("arguments")),
+                    }
+                )
+            finish_reason = "stream"
         else:
             choice = openai_response.choices[0]
             content_blocks = content_blocks_from_openai_choice(choice, tool_mode)

ripperdoc/core/query.py

@@ -58,7 +58,7 @@ from ripperdoc.utils.messages import (
 logger = get_logger()
 
 DEFAULT_REQUEST_TIMEOUT_SEC = float(os.getenv("RIPPERDOC_API_TIMEOUT", "120"))
-MAX_LLM_RETRIES = 1
+MAX_LLM_RETRIES = int(os.getenv("RIPPERDOC_MAX_RETRIES", "10"))
 
 
 def _resolve_tool(
@@ -377,6 +377,8 @@ class QueryContext:
         safe_mode: bool = False,
         model: str = "main",
         verbose: bool = False,
+        pause_ui: Optional[Callable[[], None]] = None,
+        resume_ui: Optional[Callable[[], None]] = None,
     ) -> None:
         self.tool_registry = ToolRegistry(tools)
         self.max_thinking_tokens = max_thinking_tokens
@@ -385,6 +387,8 @@ class QueryContext:
         self.verbose = verbose
         self.abort_controller = asyncio.Event()
         self.file_state_cache: Dict[str, FileSnapshot] = {}
+        self.pause_ui = pause_ui
+        self.resume_ui = resume_ui
 
     @property
     def tools(self) -> List[Tool[Any, Any]]:
@@ -714,6 +718,8 @@ async def query(
                 tool_registry=query_context.tool_registry,
                 file_state_cache=query_context.file_state_cache,
                 abort_signal=query_context.abort_controller,
+                pause_ui=query_context.pause_ui,
+                resume_ui=query_context.resume_ui,
             )
 
             validation = await tool.validate_input(parsed_input, tool_context)

ripperdoc/core/query_utils.py

@@ -7,7 +7,7 @@ import re
 from typing import Any, Dict, List, Mapping, Optional, Union
 from uuid import uuid4
 
-from json_repair import repair_json
+from json_repair import repair_json  # type: ignore[import-not-found]
 from pydantic import ValidationError
 
 from ripperdoc.core.config import ModelProfile, ProviderType, get_global_config

ripperdoc/core/system_prompt.py

@@ -8,7 +8,19 @@ from pathlib import Path
 from textwrap import dedent
 from typing import Any, Dict, Iterable, List, Optional
 
-from ripperdoc.core.agents import clear_agent_cache, load_agent_definitions, summarize_agent
+from ripperdoc.core.agents import (
+    ASK_USER_QUESTION_TOOL_NAME,
+    BASH_TOOL_NAME,
+    FILE_EDIT_TOOL_NAME,
+    FILE_WRITE_TOOL_NAME,
+    TASK_TOOL_NAME,
+    TODO_WRITE_TOOL_NAME,
+    TOOL_SEARCH_TOOL_NAME,
+    VIEW_TOOL_NAME,
+    clear_agent_cache,
+    load_agent_definitions,
+    summarize_agent,
+)
 from ripperdoc.core.tool import Tool
 from ripperdoc.utils.log import get_logger
 
@@ -174,10 +186,18 @@ def build_system_prompt(
 ) -> str:
     _ = user_prompt, context
     tool_names = {tool.name for tool in tools}
-    todo_tool_name = "TodoWrite"
+    todo_tool_name = TODO_WRITE_TOOL_NAME
     todo_available = todo_tool_name in tool_names
-    task_available = "Task" in tool_names
-    shell_tool_name = next((tool.name for tool in tools if tool.name.lower() == "bash"), "Bash")
+    task_available = TASK_TOOL_NAME in tool_names
+    ask_tool_name = ASK_USER_QUESTION_TOOL_NAME
+    ask_available = ask_tool_name in tool_names
+    view_tool_name = VIEW_TOOL_NAME
+    file_edit_tool_name = FILE_EDIT_TOOL_NAME
+    file_write_tool_name = FILE_WRITE_TOOL_NAME
+    shell_tool_name = next(
+        (tool.name for tool in tools if tool.name.lower() == BASH_TOOL_NAME.lower()),
+        BASH_TOOL_NAME,
+    )
 
     main_prompt = dedent(
         f"""\
@@ -190,61 +210,25 @@ def build_system_prompt(
         - /help: Get help with using {APP_NAME}
         - To give feedback, users should report the issue at {FEEDBACK_URL}
 
-        # Tone and style
-        You should be concise, direct, and to the point.
-        You MUST answer concisely with fewer than 4 lines (not including tool use or code generation), unless user asks for detail.
-        IMPORTANT: You should minimize output tokens as much as possible while maintaining helpfulness, quality, and accuracy. Only address the specific query or task at hand, avoiding tangential information unless absolutely critical for completing the request. If you can answer in 1-3 sentences or a short paragraph, please do.
-        IMPORTANT: You should NOT answer with unnecessary preamble or postamble (such as explaining your code or summarizing your action), unless the user asks you to.
-        Do not add additional code explanation summary unless requested by the user. After working on a file, just stop, rather than providing an explanation of what you did.
-        Answer the user's question directly, without elaboration, explanation, or details. One word answers are best. Avoid introductions, conclusions, and explanations. You MUST avoid text before/after your response, such as "The answer is <answer>.", "Here is the content of the file..." or "Based on the information provided, the answer is..." or "Here is what I will do next...". Here are some examples to demonstrate appropriate verbosity:
-        <example>
-        user: 2 + 2
-        assistant: 4
-        </example>
-
-        <example>
-        user: what is 2+2?
-        assistant: 4
-        </example>
-
-        <example>
-        user: is 11 a prime number?
-        assistant: Yes
-        </example>
-
-        <example>
-        user: what command should I run to list files in the current directory?
-        assistant: ls
-        </example>
+        # Looking up your own documentation
+        When the user asks what {APP_NAME} can do, how to use it (hooks, slash commands, MCP, SDKs), or requests SDK code samples, use the {TASK_TOOL_NAME} tool with a documentation-focused subagent (for example, subagent_type="docs") if available to consult official docs before answering.
 
-        <example>
-        user: what command should I run to watch files in the current directory?
-        assistant: [use the ls tool to list the files in the current directory, then read docs/commands in the relevant file to find out how to watch files]
-        npm run dev
-        </example>
-
-        <example>
-        user: How many golf balls fit inside a jetta?
-        assistant: 150000
-        </example>
-
-        <example>
-        user: what files are in the directory src/?
-        assistant: [runs ls and sees foo.c, bar.c, baz.c]
-        user: which file contains the implementation of foo?
-        assistant: src/foo.c
-        </example>
-
-        <example>
-        user: write tests for new feature
-        assistant: [uses grep and glob search tools to find where similar tests are defined, uses concurrent read file tool use blocks in one tool call to read relevant files at the same time, uses edit file tool to write new tests]
-        </example>
+        # Tone and style
+        - Only use emojis if the user explicitly requests it. Avoid using emojis in all communication unless asked.
+        - Your output will be displayed on a command line interface. Your responses should be short and concise. You can use Github-flavored markdown for formatting, and will be rendered in a monospace font using the CommonMark specification.
+        - Output text to communicate with the user; all text you output outside of tool use is displayed to the user. Only use tools to complete tasks. Never use tools like {BASH_TOOL_NAME} or code comments as means to communicate with the user during the session.
+        - NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one. This includes markdown files.
+
+        # Professional objectivity
+        Prioritize technical accuracy and truthfulness over validating the user's beliefs. Focus on facts and problem-solving, providing direct, objective technical info without any unnecessary superlatives, praise, or emotional validation. It is best for the user if Claude honestly applies the same rigorous standards to all ideas and disagrees when necessary, even if it may not be what the user wants to hear. Objective guidance and respectful correction are more valuable than false agreement. Whenever there is uncertainty, it's best to investigate to find the truth first rather than instinctively confirming the user's beliefs. Avoid using over-the-top validation or excessive praise when responding to users such as "You're absolutely right" or similar phrases.
+
+        # Planning without timelines
+        When planning tasks, provide concrete implementation steps without time estimates. Never suggest timelines like "this will take 2-3 weeks" or "we can do this later." Focus on what needs to be done, not when. Break work into actionable steps and let users decide scheduling.
+      
+        # Explain Your Code: Bash Command Transparency
         When you run a non-trivial bash command, you should explain what the command does and why you are running it, to make sure the user understands what you are doing (this is especially important when you are running a command that will make changes to the user's system).
         Remember that your output will be displayed on a command line interface. Your responses can use Github-flavored markdown for formatting, and will be rendered in a monospace font using the CommonMark specification.
-        Output text to communicate with the user; all text you output outside of tool use is displayed to the user. Only use tools to complete tasks. Never use tools like {shell_tool_name} or code comments as means to communicate with the user during the session.
         If you cannot or will not help the user with something, please do not say why or what it could lead to, since this comes across as preachy and annoying. Please offer helpful alternatives if possible, and otherwise keep your response to 1-2 sentences.
-        Only use emojis if the user explicitly requests it. Avoid using emojis in all communication unless asked.
-        IMPORTANT: Keep your responses short, since they will be displayed on a command line interface.  
 
         # Proactiveness
         You are allowed to be proactive, but only when the user asks you to do something. You should strive to strike a balance between:
@@ -260,7 +244,7 @@ def build_system_prompt(
         - Always follow security best practices. Never introduce code that exposes or logs secrets and keys. Never commit secrets or keys to the repository.
 
         # Code style
-        - IMPORTANT: DO NOT ADD ***ANY*** COMMENTS unless asked"""
+        - Only add comments when the logic is not self-evident and within code you changed. Do not add docstrings, comments, or type annotations to code you did not modify."""
     ).strip()
 
     if mcp_instructions:
@@ -318,6 +302,15 @@ def build_system_prompt(
             </example>"""
         ).strip()
 
+    ask_questions_section = ""
+    if ask_available:
+        ask_questions_section = dedent(
+            f"""\
+            # Asking questions as you work
+
+            You have access to the {ask_tool_name} tool to ask the user questions when you need clarification, want to validate assumptions, or need to make a decision you're unsure about. When presenting options or plans, do not include time estimates—focus on what each option involves."""
+        ).strip()
+
     hooks_section = dedent(
         """\
         Users may configure 'hooks', shell commands that execute in response to events like tool calls, in settings. Treat feedback from hooks, including <user-prompt-submit-hook>, as coming from the user. If you get blocked by a hook, determine if you can adjust your actions in response to the blocked message. If not, ask the user to check their hooks configuration."""
@@ -329,15 +322,26 @@ def build_system_prompt(
     ]
     if todo_available:
         doing_tasks_lines.append(f"- Use the {todo_tool_name} tool to plan the task if required")
+    if ask_available:
+        doing_tasks_lines.append(
+            f"- Use the {ask_tool_name} tool to ask questions, clarify, and gather information as needed."
+        )
     doing_tasks_lines.extend(
         [
+            "- NEVER propose changes to code you haven't read. If a user asks about or wants you to modify a file, read it first.",
             "- Use the available search tools to understand the codebase and the user's query. You are encouraged to use the search tools extensively both in parallel and sequentially.",
-            "- Implement the solution using all tools available to you",
+            "- When exploring the codebase beyond a needle query, prefer using the Task tool with an exploration subagent if available instead of running raw search commands directly.",
+            "- Implement the solution using all tools available to you.",
+            "- Be careful not to introduce security vulnerabilities such as command injection, XSS, SQL injection, and other OWASP top 10 vulnerabilities. If you notice that you wrote insecure code, immediately fix it.",
+            "- Avoid over-engineering. Only make changes that are directly requested or clearly necessary. Keep solutions simple and focused.",
+            "  - Don't add features, refactor code, or make improvements beyond what was asked. Don't add docstrings, comments, or type annotations to code you didn't change. Only add comments where the logic isn't self-evident.",
+            "  - Don't add error handling, fallbacks, or validation for scenarios that can't happen. Validate only at system boundaries (user input, external APIs).",
+            "  - Don't create helpers, utilities, or abstractions for one-time operations. Avoid feature flags or backwards-compatibility shims when a direct change is sufficient. If something is unused, delete it completely.",
             "- Verify the solution if possible with tests. NEVER assume specific test framework or test script. Check the README or search codebase to determine the testing approach.",
             f"- VERY IMPORTANT: When you have completed a task, you MUST run the lint and typecheck commands (eg. npm run lint, npm run typecheck, ruff, etc.) with {shell_tool_name} if they were provided to you to ensure your code is correct. If you are unable to find the correct command, ask the user for the command to run and if they supply it, proactively suggest writing it to AGENTS.md so that you will know to run it next time.",
             "NEVER commit changes unless the user explicitly asks you to. It is VERY IMPORTANT to only commit when explicitly asked, otherwise the user will feel that you are being too proactive.",
-            "",
             "- Tool results and user messages may include <system-reminder> tags. <system-reminder> tags contain useful information and reminders. They are NOT part of the user's provided input or the tool result.",
+            "- The conversation has unlimited context through automatic summarization. Complete tasks fully; do not stop mid-task or claim context limits.",
         ]
     )
     doing_tasks_section = "\n".join(doing_tasks_lines)
@@ -345,7 +349,8 @@ def build_system_prompt(
     tool_usage_lines = [
         "# Tool usage policy",
         '- You have the capability to call multiple tools in a single response. When multiple independent pieces of information are requested, batch your tool calls together for optimal performance. When making multiple bash tool calls, you MUST send a single message with multiple tools calls to run the calls in parallel. For example, if you need to run "git status" and "git diff", send a single message with two tool calls to run the calls in parallel.',
-        "",
+        "- If the user asks to run tools in parallel and there are no dependencies, include multiple tool calls in a single message; sequence dependent calls instead of guessing values.",
+        f"- Use specialized tools instead of bash when possible: use {view_tool_name} for reading files, {file_edit_tool_name} for editing, and {file_write_tool_name} for creating files. Do not use bash echo or other command-line tools to communicate with the user; reply in text.",
         "You MUST answer concisely with fewer than 4 lines of text (not including tool use or code generation), unless user asks for detail.",
     ]
     if task_available:
@@ -353,7 +358,7 @@ def build_system_prompt(
             1,
             "- Use the Task tool with configured subagents when the task matches an agent's description. Always set subagent_type.",
         )
-    if "ToolSearch" in tool_names:
+    if TOOL_SEARCH_TOOL_NAME in tool_names:
         tool_usage_lines.insert(
             1,
             "- Use the ToolSearch tool to discover and activate deferred or MCP tools. Keep searches focused and load only 3-5 relevant tools.",
@@ -402,6 +407,7 @@ def build_system_prompt(
     sections: List[str] = [
         main_prompt,
         task_management_section,
+        ask_questions_section,
         hooks_section,
         doing_tasks_section,
         tool_usage_section,
@@ -409,7 +415,7 @@ def build_system_prompt(
         build_environment_prompt(),
         DEFENSIVE_SECURITY_GUIDELINE,
         always_use_todo,
-        build_commit_workflow_prompt(shell_tool_name, todo_tool_name, "Task"),
+        build_commit_workflow_prompt(shell_tool_name, todo_tool_name, TASK_TOOL_NAME),
         code_references,
     ]
 

ripperdoc/core/tool.py

@@ -44,6 +44,13 @@ class ToolUseContext(BaseModel):
     file_state_cache: Dict[str, "FileSnapshot"] = Field(default_factory=dict)
     tool_registry: Optional[Any] = None
     abort_signal: Optional[Any] = None
+    # UI control callbacks for tools that need user interaction
+    pause_ui: Optional[Any] = Field(default=None, description="Callback to pause UI spinner")
+    resume_ui: Optional[Any] = Field(default=None, description="Callback to resume UI spinner")
+    # Plan mode control callback
+    on_exit_plan_mode: Optional[Any] = Field(
+        default=None, description="Callback invoked when exiting plan mode"
+    )
     model_config = ConfigDict(arbitrary_types_allowed=True)