ripperdoc 0.1.0__py3-none-any.whl

ripperdoc/sdk/client.py

@@ -0,0 +1,309 @@
+"""Headless Python SDK for Ripperdoc.
+
+`query` helper for simple calls and a `RipperdocClient` for long-lived
+sessions that keep conversation history.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import (
+    Any,
+    AsyncIterator,
+    Awaitable,
+    Callable,
+    Dict,
+    List,
+    Optional,
+    Sequence,
+    Union,
+)
+
+from ripperdoc.core.default_tools import get_default_tools
+from ripperdoc.core.query import QueryContext, query as _core_query
+from ripperdoc.core.system_prompt import build_system_prompt
+from ripperdoc.core.tool import Tool
+from ripperdoc.tools.task_tool import TaskTool
+from ripperdoc.tools.mcp_tools import load_dynamic_mcp_tools_async, merge_tools_with_dynamic
+from ripperdoc.utils.memory import build_memory_instructions
+from ripperdoc.utils.messages import (
+    AssistantMessage,
+    ProgressMessage,
+    UserMessage,
+    create_user_message,
+)
+from ripperdoc.utils.mcp import (
+    format_mcp_instructions,
+    load_mcp_servers_async,
+    shutdown_mcp_runtime,
+)
+
+MessageType = Union[UserMessage, AssistantMessage, ProgressMessage]
+PermissionChecker = Callable[[Tool[Any, Any], Any], Union[Awaitable[Any], Any]]
+QueryRunner = Callable[
+    [
+        List[MessageType],
+        str,
+        Dict[str, str],
+        QueryContext,
+        Optional[PermissionChecker],
+    ],
+    AsyncIterator[MessageType],
+]
+
+_END_OF_STREAM = object()
+
+
+def _coerce_to_path(path: Union[str, Path]) -> Path:
+    return path if isinstance(path, Path) else Path(path)
+
+
+@dataclass
+class RipperdocOptions:
+    """Configuration for SDK usage."""
+
+    tools: Optional[Sequence[Tool[Any, Any]]] = None
+    allowed_tools: Optional[Sequence[str]] = None
+    disallowed_tools: Optional[Sequence[str]] = None
+    safe_mode: bool = False
+    verbose: bool = False
+    model: str = "main"
+    max_thinking_tokens: int = 0
+    context: Dict[str, str] = field(default_factory=dict)
+    system_prompt: Optional[str] = None
+    additional_instructions: Optional[Union[str, Sequence[str]]] = None
+    permission_checker: Optional[PermissionChecker] = None
+    cwd: Optional[Union[str, Path]] = None
+
+    def build_tools(self) -> List[Tool[Any, Any]]:
+        """Create the tool set with allow/deny filters applied."""
+        base_tools = list(self.tools) if self.tools is not None else get_default_tools()
+        allowed = set(self.allowed_tools) if self.allowed_tools is not None else None
+        disallowed = set(self.disallowed_tools or [])
+
+        filtered: List[Tool[Any, Any]] = []
+        for tool in base_tools:
+            name = getattr(tool, "name", tool.__class__.__name__)
+            if allowed is not None and name not in allowed:
+                continue
+            if name in disallowed:
+                continue
+            filtered.append(tool)
+
+        if allowed is not None and not filtered:
+            raise ValueError("No tools remain after applying allowed_tools/disallowed_tools.")
+
+        # The default Task tool captures the original base tools. If filters are
+        # applied, recreate it so the subagent only sees the filtered set.
+        if (self.allowed_tools or self.disallowed_tools) and self.tools is None:
+            has_task = any(getattr(tool, "name", None) == "Task" for tool in filtered)
+            if has_task:
+                filtered_base = [tool for tool in filtered if getattr(tool, "name", None) != "Task"]
+
+                def _filtered_base_provider() -> List[Tool[Any, Any]]:
+                    return filtered_base
+
+                filtered = [
+                    (
+                        TaskTool(_filtered_base_provider)
+                        if getattr(tool, "name", None) == "Task"
+                        else tool
+                    )
+                    for tool in filtered
+                ]
+
+        return filtered
+
+    def extra_instructions(self) -> List[str]:
+        """Normalize additional instructions to a list."""
+        if self.additional_instructions is None:
+            return []
+        if isinstance(self.additional_instructions, str):
+            return [self.additional_instructions]
+        return [text for text in self.additional_instructions if text]
+
+
+class RipperdocClient:
+    """Persistent Ripperdoc session with conversation history."""
+
+    def __init__(
+        self,
+        options: Optional[RipperdocOptions] = None,
+        query_runner: Optional[QueryRunner] = None,
+    ) -> None:
+        self.options = options or RipperdocOptions()
+        self._tools = self.options.build_tools()
+        self._query_runner = query_runner or _core_query
+
+        self._history: List[MessageType] = []
+        self._queue: asyncio.Queue = asyncio.Queue()
+        self._current_task: Optional[asyncio.Task] = None
+        self._current_context: Optional[QueryContext] = None
+        self._connected = False
+        self._previous_cwd: Optional[Path] = None
+
+    @property
+    def tools(self) -> List[Tool[Any, Any]]:
+        return self._tools
+
+    @property
+    def history(self) -> List[MessageType]:
+        return list(self._history)
+
+    async def __aenter__(self) -> "RipperdocClient":
+        await self.connect()
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:  # type: ignore[override]
+        await self.disconnect()
+
+    async def connect(self, prompt: Optional[str] = None) -> None:
+        """Prepare the session and optionally send an initial prompt."""
+        if not self._connected:
+            if self.options.cwd is not None:
+                self._previous_cwd = Path.cwd()
+                os.chdir(_coerce_to_path(self.options.cwd))
+            self._connected = True
+
+        if prompt:
+            await self.query(prompt)
+
+    async def disconnect(self) -> None:
+        """Tear down the session and restore the working directory."""
+        if self._current_context:
+            self._current_context.abort_controller.set()
+
+        if self._current_task and not self._current_task.done():
+            self._current_task.cancel()
+            try:
+                await self._current_task
+            except asyncio.CancelledError:
+                pass
+
+        if self._previous_cwd:
+            os.chdir(self._previous_cwd)
+            self._previous_cwd = None
+
+        self._connected = False
+        await shutdown_mcp_runtime()
+
+    async def query(self, prompt: str) -> None:
+        """Send a prompt and start streaming the response."""
+        if self._current_task and not self._current_task.done():
+            raise RuntimeError(
+                "A query is already in progress; wait for it to finish or interrupt it."
+            )
+
+        if not self._connected:
+            await self.connect()
+
+        self._queue = asyncio.Queue()
+
+        user_message = create_user_message(prompt)
+        history = list(self._history) + [user_message]
+        self._history.append(user_message)
+
+        system_prompt = await self._build_system_prompt(prompt)
+        context = dict(self.options.context)
+
+        query_context = QueryContext(
+            tools=self._tools,
+            max_thinking_tokens=self.options.max_thinking_tokens,
+            safe_mode=self.options.safe_mode,
+            model=self.options.model,
+            verbose=self.options.verbose,
+        )
+        self._current_context = query_context
+
+        async def _runner() -> None:
+            try:
+                async for message in self._query_runner(
+                    history,
+                    system_prompt,
+                    context,
+                    query_context,
+                    self.options.permission_checker,
+                ):
+                    if getattr(message, "type", None) in ("user", "assistant"):
+                        self._history.append(message)  # type: ignore[arg-type]
+                    await self._queue.put(message)
+            finally:
+                await self._queue.put(_END_OF_STREAM)
+
+        self._current_task = asyncio.create_task(_runner())
+
+    async def receive_messages(self) -> AsyncIterator[MessageType]:
+        """Yield messages for the active query."""
+        if self._current_task is None:
+            raise RuntimeError("No active query to receive messages from.")
+
+        while True:
+            message = await self._queue.get()
+            if message is _END_OF_STREAM:
+                break
+            yield message  # type: ignore[misc]
+
+    async def receive_response(self) -> AsyncIterator[MessageType]:
+        """Alias for receive_messages."""
+        async for message in self.receive_messages():
+            yield message
+
+    async def interrupt(self) -> None:
+        """Request cancellation of the active query."""
+        if self._current_context:
+            self._current_context.abort_controller.set()
+
+        if self._current_task and not self._current_task.done():
+            self._current_task.cancel()
+            try:
+                await self._current_task
+            except asyncio.CancelledError:
+                pass
+
+        await self._queue.put(_END_OF_STREAM)
+
+    async def _build_system_prompt(self, user_prompt: str) -> str:
+        if self.options.system_prompt:
+            return self.options.system_prompt
+
+        instructions: List[str] = []
+        instructions.extend(self.options.extra_instructions())
+        memory = build_memory_instructions()
+        if memory:
+            instructions.append(memory)
+
+        project_path = _coerce_to_path(self.options.cwd or Path.cwd())
+        dynamic_tools = await load_dynamic_mcp_tools_async(project_path)
+        if dynamic_tools:
+            self._tools = merge_tools_with_dynamic(self._tools, dynamic_tools)
+
+        servers = await load_mcp_servers_async(project_path)
+        mcp_instructions = format_mcp_instructions(servers)
+
+        return build_system_prompt(
+            self._tools,
+            user_prompt,
+            dict(self.options.context),
+            instructions or None,
+            mcp_instructions=mcp_instructions,
+        )
+
+
+async def query(
+    prompt: str,
+    options: Optional[RipperdocOptions] = None,
+    query_runner: Optional[QueryRunner] = None,
+) -> AsyncIterator[MessageType]:
+    """One-shot helper: run a prompt in a fresh session."""
+    client = RipperdocClient(options=options, query_runner=query_runner)
+    await client.connect()
+    await client.query(prompt)
+
+    try:
+        async for message in client.receive_messages():
+            yield message
+    finally:
+        await client.disconnect()

ripperdoc/tools/__init__.py

@@ -0,0 +1 @@
+"""Tool implementations for Ripperdoc."""

ripperdoc/tools/background_shell.py

@@ -0,0 +1,291 @@
+"""Lightweight background shell manager for BashTool.
+
+Allows starting shell commands that keep running while the caller continues.
+Output can be polled via the BashOutput tool and commands can be terminated
+via the KillBash tool.
+"""
+
+import asyncio
+import concurrent.futures
+import contextlib
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from ripperdoc.utils.log import get_logger
+
+
+logger = get_logger()
+
+
+@dataclass
+class BackgroundTask:
+    """In-memory record of a background shell command."""
+
+    id: str
+    command: str
+    process: asyncio.subprocess.Process
+    start_time: float
+    timeout: Optional[float] = None
+    stdout_chunks: List[str] = field(default_factory=list)
+    stderr_chunks: List[str] = field(default_factory=list)
+    exit_code: Optional[int] = None
+    killed: bool = False
+    timed_out: bool = False
+    reader_tasks: List[asyncio.Task] = field(default_factory=list)
+    done_event: asyncio.Event = field(default_factory=asyncio.Event)
+
+
+_tasks: Dict[str, BackgroundTask] = {}
+_tasks_lock = threading.Lock()
+_background_loop: Optional[asyncio.AbstractEventLoop] = None
+_background_thread: Optional[threading.Thread] = None
+_loop_lock = threading.Lock()
+
+
+def _ensure_background_loop() -> asyncio.AbstractEventLoop:
+    """Create (or return) a dedicated loop for background processes."""
+    global _background_loop, _background_thread
+
+    if _background_loop and _background_loop.is_running():
+        return _background_loop
+
+    with _loop_lock:
+        if _background_loop and _background_loop.is_running():
+            return _background_loop
+
+        loop = asyncio.new_event_loop()
+        ready = threading.Event()
+
+        def _run_loop() -> None:
+            asyncio.set_event_loop(loop)
+            ready.set()
+            loop.run_forever()
+
+        thread = threading.Thread(
+            target=_run_loop,
+            name="ripperdoc-bg-loop",
+            daemon=True,
+        )
+        thread.start()
+        ready.wait()
+
+        _background_loop = loop
+        _background_thread = thread
+        return loop
+
+
+def _submit_to_background_loop(coro: Any) -> concurrent.futures.Future:
+    """Run a coroutine on the background loop and return a thread-safe future."""
+    loop = _ensure_background_loop()
+    return asyncio.run_coroutine_threadsafe(coro, loop)
+
+
+async def _pump_stream(stream: asyncio.StreamReader, sink: List[str]) -> None:
+    """Continuously read from a stream into a buffer."""
+    try:
+        while True:
+            chunk = await stream.read(4096)
+            if not chunk:
+                break
+            text = chunk.decode("utf-8", errors="replace")
+            with _tasks_lock:
+                sink.append(text)
+    except Exception as exc:
+        # Best effort; ignore stream read errors to avoid leaking tasks.
+        logger.debug(f"Stream pump error for background task: {exc}")
+
+
+async def _finalize_reader_tasks(reader_tasks: List[asyncio.Task], timeout: float = 1.0) -> None:
+    """Wait for stream reader tasks to finish, cancelling if they hang."""
+    if not reader_tasks:
+        return
+
+    try:
+        await asyncio.wait_for(
+            asyncio.gather(*reader_tasks, return_exceptions=True), timeout=timeout
+        )
+    except asyncio.TimeoutError:
+        for task in reader_tasks:
+            if not task.done():
+                task.cancel()
+        await asyncio.gather(*reader_tasks, return_exceptions=True)
+
+
+async def _monitor_task(task: BackgroundTask) -> None:
+    """Wait for a background process to finish or timeout, then mark status."""
+    try:
+        if task.timeout:
+            await asyncio.wait_for(task.process.wait(), timeout=task.timeout)
+        else:
+            await task.process.wait()
+        with _tasks_lock:
+            task.exit_code = task.process.returncode
+    except asyncio.TimeoutError:
+        logger.warning(f"Background task {task.id} timed out after {task.timeout}s: {task.command}")
+        with _tasks_lock:
+            task.timed_out = True
+        task.process.kill()
+        await task.process.wait()
+        with _tasks_lock:
+            task.exit_code = -1
+    except asyncio.CancelledError:
+        return
+    except Exception as exc:
+        logger.error(f"Error monitoring background task {task.id}: {exc}")
+        with _tasks_lock:
+            task.exit_code = -1
+    finally:
+        # Ensure readers are finished before marking done.
+        await _finalize_reader_tasks(task.reader_tasks)
+        task.done_event.set()
+
+
+async def _start_background_command(
+    command: str, timeout: Optional[float] = None, shell_executable: Optional[str] = None
+) -> str:
+    """Launch a background shell command on the dedicated loop."""
+    if shell_executable:
+        process = await asyncio.create_subprocess_exec(
+            shell_executable,
+            "-c",
+            command,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            stdin=asyncio.subprocess.DEVNULL,
+            start_new_session=False,
+        )
+    else:
+        process = await asyncio.create_subprocess_shell(
+            command,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            stdin=asyncio.subprocess.DEVNULL,
+            start_new_session=False,
+        )
+
+    task_id = f"bash_{uuid.uuid4().hex[:8]}"
+    record = BackgroundTask(
+        id=task_id,
+        command=command,
+        process=process,
+        start_time=_loop_time(),
+        timeout=timeout,
+    )
+    with _tasks_lock:
+        _tasks[task_id] = record
+
+    # Start stream pumps and monitor task.
+    if process.stdout:
+        record.reader_tasks.append(
+            asyncio.create_task(_pump_stream(process.stdout, record.stdout_chunks))
+        )
+    if process.stderr:
+        record.reader_tasks.append(
+            asyncio.create_task(_pump_stream(process.stderr, record.stderr_chunks))
+        )
+    asyncio.create_task(_monitor_task(record))
+
+    return task_id
+
+
+async def start_background_command(
+    command: str, timeout: Optional[float] = None, shell_executable: Optional[str] = None
+) -> str:
+    """Launch a background shell command and return its task id."""
+    future = _submit_to_background_loop(
+        _start_background_command(command, timeout, shell_executable)
+    )
+    return await asyncio.wrap_future(future)
+
+
+def _compute_status(task: BackgroundTask) -> str:
+    """Return a human-friendly status string."""
+    if task.killed:
+        return "killed"
+    if task.timed_out:
+        return "failed"
+    if task.exit_code is None:
+        return "running"
+    return "completed" if task.exit_code == 0 else "failed"
+
+
+def _loop_time() -> float:
+    """Return a monotonic timestamp without requiring a running event loop."""
+    try:
+        return asyncio.get_running_loop().time()
+    except RuntimeError:
+        return time.monotonic()
+
+
+def get_background_status(task_id: str, consume: bool = True) -> dict:
+    """Fetch the current status and buffered output of a background command.
+
+    If consume is True, buffered stdout/stderr are cleared after reading.
+    """
+    with _tasks_lock:
+        if task_id not in _tasks:
+            raise KeyError(f"No background task found with id '{task_id}'")
+
+        task = _tasks[task_id]
+        stdout = "".join(task.stdout_chunks)
+        stderr = "".join(task.stderr_chunks)
+
+        if consume:
+            task.stdout_chunks.clear()
+            task.stderr_chunks.clear()
+
+        return {
+            "id": task.id,
+            "command": task.command,
+            "status": _compute_status(task),
+            "stdout": stdout,
+            "stderr": stderr,
+            "exit_code": task.exit_code,
+            "timed_out": task.timed_out,
+            "killed": task.killed,
+            "duration_ms": (_loop_time() - task.start_time) * 1000.0,
+        }
+
+
+async def kill_background_task(task_id: str) -> bool:
+    """Attempt to kill a running background task."""
+    KILL_WAIT_SECONDS = 2.0
+
+    async def _kill(task_id: str) -> bool:
+        with _tasks_lock:
+            task = _tasks.get(task_id)
+            if not task:
+                return False
+
+            if task.exit_code is not None:
+                return False
+
+        try:
+            task.killed = True
+            task.process.kill()
+            try:
+                await asyncio.wait_for(task.process.wait(), timeout=KILL_WAIT_SECONDS)
+            except asyncio.TimeoutError:
+                # Best effort: force kill and don't block.
+                with contextlib.suppress(ProcessLookupError, PermissionError):
+                    task.process.kill()
+                await asyncio.wait_for(task.process.wait(), timeout=1.0)
+
+            with _tasks_lock:
+                task.exit_code = task.process.returncode or -1
+            return True
+        finally:
+            await _finalize_reader_tasks(task.reader_tasks)
+            task.done_event.set()
+
+    future = _submit_to_background_loop(_kill(task_id))
+    return await asyncio.wrap_future(future)
+
+
+def list_background_tasks() -> List[str]:
+    """Return known background task ids."""
+    with _tasks_lock:
+        return list(_tasks.keys())

ripperdoc/tools/bash_output_tool.py

@@ -0,0 +1,98 @@
+"""Tool to retrieve output from background bash tasks."""
+
+from typing import Any, AsyncGenerator, Optional
+from pydantic import BaseModel, Field
+
+from ripperdoc.core.tool import Tool, ToolUseContext, ToolResult, ValidationResult
+from ripperdoc.tools.background_shell import get_background_status
+
+
+class BashOutputInput(BaseModel):
+    """Input schema for BashOutput."""
+
+    task_id: str = Field(
+        description="Background task id returned by BashTool when run_in_background is true"
+    )
+    consume: bool = Field(
+        default=True, description="Whether to clear buffered output after reading (default: True)"
+    )
+
+
+class BashOutputData(BaseModel):
+    """Snapshot of a background task."""
+
+    task_id: str
+    command: str
+    status: str
+    stdout: str
+    stderr: str
+    exit_code: Optional[int]
+    duration_ms: float
+
+
+class BashOutputTool(Tool[BashOutputInput, BashOutputData]):
+    """Read buffered output from a background bash task."""
+
+    @property
+    def name(self) -> str:
+        return "BashOutput"
+
+    async def description(self) -> str:
+        return "Read output and status from a background bash command started with BashTool(run_in_background=True)."
+
+    async def prompt(self, safe_mode: bool = False) -> str:
+        return "Fetch buffered output and status for a background bash task by id."
+
+    @property
+    def input_schema(self) -> type[BashOutputInput]:
+        return BashOutputInput
+
+    def is_read_only(self) -> bool:
+        return True
+
+    def is_concurrency_safe(self) -> bool:
+        return True
+
+    def needs_permissions(self, input_data: Any = None) -> bool:
+        return False
+
+    async def validate_input(
+        self, input_data: BashOutputInput, context: Optional[ToolUseContext] = None
+    ) -> ValidationResult:
+        try:
+            get_background_status(input_data.task_id, consume=False)
+        except KeyError:
+            return ValidationResult(
+                result=False, message=f"No background task found with id '{input_data.task_id}'"
+            )
+        return ValidationResult(result=True)
+
+    def render_result_for_assistant(self, output: BashOutputData) -> str:
+        parts = [
+            f"status: {output.status}",
+            f"exit code: {output.exit_code if output.exit_code is not None else 'running'}",
+        ]
+        if output.stdout:
+            parts.append(f"stdout:\n{output.stdout}")
+        if output.stderr:
+            parts.append(f"stderr:\n{output.stderr}")
+        return "\n\n".join(parts)
+
+    def render_tool_use_message(self, input_data: BashOutputInput, verbose: bool = False) -> str:
+        suffix = " (consume=0)" if not input_data.consume else ""
+        return f"$ bash-output {input_data.task_id}{suffix}"
+
+    async def call(
+        self, input_data: BashOutputInput, context: ToolUseContext
+    ) -> AsyncGenerator[ToolResult, None]:
+        status = get_background_status(input_data.task_id, consume=input_data.consume)
+        output = BashOutputData(
+            task_id=status["id"],
+            command=status["command"],
+            status=status["status"],
+            stdout=status["stdout"],
+            stderr=status["stderr"],
+            exit_code=status["exit_code"],
+            duration_ms=status["duration_ms"],
+        )
+        yield ToolResult(data=output, result_for_assistant=self.render_result_for_assistant(output))