tunacode-cli 0.1.21__py3-none-any.whl

tunacode/tools/react.py

@@ -0,0 +1,111 @@
+"""Lightweight ReAct-style scratchpad tool."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Literal
+
+from pydantic_ai.exceptions import ModelRetry
+
+from tunacode.core.state import StateManager
+
+
+def create_react_tool(state_manager: StateManager) -> Callable:
+    """Factory to create a react tool bound to a state manager.
+
+    Args:
+        state_manager: The state manager instance to use.
+
+    Returns:
+        An async function that implements the react tool.
+    """
+
+    async def react(
+        action: Literal["think", "observe", "get", "clear"],
+        thoughts: str | None = None,
+        next_action: str | None = None,
+        result: str | None = None,
+    ) -> str:
+        """ReAct scratchpad for tracking think/observe steps.
+
+        Args:
+            action: The action to perform (think/observe/get/clear).
+            thoughts: Thought content for think action.
+            next_action: Planned next action for think action.
+            result: Observation message for observe action.
+
+        Returns:
+            Status message or scratchpad contents.
+        """
+        scratchpad = state_manager.get_react_scratchpad()
+        scratchpad.setdefault("timeline", [])
+
+        if action == "think":
+            if not thoughts:
+                raise ModelRetry("Provide thoughts when using react think action")
+            if not next_action:
+                raise ModelRetry("Specify next_action when recording react thoughts")
+
+            entry = {"type": "think", "thoughts": thoughts, "next_action": next_action}
+            state_manager.append_react_entry(entry)
+            return "Recorded think step"
+
+        if action == "observe":
+            if not result:
+                raise ModelRetry("Provide result when using react observe action")
+
+            entry = {"type": "observe", "result": result}
+            state_manager.append_react_entry(entry)
+            return "Recorded observation"
+
+        if action == "get":
+            timeline = scratchpad.get("timeline", [])
+            if not timeline:
+                return "React scratchpad is empty"
+
+            formatted = [
+                f"{i + 1}. {item['type']}: {_format_entry(item)}" for i, item in enumerate(timeline)
+            ]
+            return "\n".join(formatted)
+
+        if action == "clear":
+            state_manager.clear_react_scratchpad()
+            return "React scratchpad cleared"
+
+        raise ModelRetry("Invalid react action. Use one of: think, observe, get, clear")
+
+    return react
+
+
+def _format_entry(item: dict[str, Any]) -> str:
+    """Format a scratchpad entry for display."""
+    if item["type"] == "think":
+        return f"thoughts='{item['thoughts']}', next_action='{item['next_action']}'"
+    if item["type"] == "observe":
+        return f"result='{item['result']}'"
+    return str(item)
+
+
+# Backwards compatibility: ReactTool class wrapper
+class ReactTool:
+    """Wrapper class for backwards compatibility with existing code."""
+
+    def __init__(self, state_manager: StateManager) -> None:
+        self.state_manager = state_manager
+        self._react = create_react_tool(state_manager)
+
+    @property
+    def tool_name(self) -> str:
+        return "react"
+
+    async def execute(
+        self,
+        action: Literal["think", "observe", "get", "clear"],
+        thoughts: str | None = None,
+        next_action: str | None = None,
+        result: str | None = None,
+    ) -> str:
+        """Execute the react tool."""
+        return await self._react(
+            action=action, thoughts=thoughts, next_action=next_action, result=result
+        )

tunacode/tools/read_file.py

@@ -0,0 +1,68 @@
+"""File reading tool for agent operations."""
+
+import asyncio
+import os
+
+from tunacode.constants import (
+    DEFAULT_READ_LIMIT,
+    ERROR_FILE_TOO_LARGE,
+    MAX_FILE_SIZE,
+    MAX_LINE_LENGTH,
+    MSG_FILE_SIZE_LIMIT,
+)
+from tunacode.exceptions import ToolExecutionError
+from tunacode.tools.decorators import file_tool
+
+
+@file_tool
+async def read_file(
+    filepath: str,
+    offset: int = 0,
+    limit: int | None = None,
+) -> str:
+    """Read the contents of a file with line limiting and truncation.
+
+    Args:
+        filepath: The absolute path to the file to read.
+        offset: The line number to start reading from (0-based). Defaults to 0.
+        limit: The number of lines to read. Defaults to DEFAULT_READ_LIMIT (2000).
+
+    Returns:
+        The formatted file contents with line numbers.
+    """
+    if os.path.getsize(filepath) > MAX_FILE_SIZE:
+        raise ToolExecutionError(
+            tool_name="read_file",
+            message=ERROR_FILE_TOO_LARGE.format(filepath=filepath) + MSG_FILE_SIZE_LIMIT,
+        )
+
+    effective_limit = limit if limit is not None else DEFAULT_READ_LIMIT
+
+    def _read_sync(path: str) -> str:
+        with open(path, encoding="utf-8") as f:
+            lines = f.readlines()
+
+        total_lines = len(lines)
+        raw = lines[offset : offset + effective_limit]
+
+        content_lines = []
+        for i, line in enumerate(raw):
+            line = line.rstrip("\n")
+            if len(line) > MAX_LINE_LENGTH:
+                line = line[:MAX_LINE_LENGTH] + "..."
+            line_num = str(i + offset + 1).zfill(5)
+            content_lines.append(f"{line_num}| {line}")
+
+        output = "<file>\n"
+        output += "\n".join(content_lines)
+
+        last_line = offset + len(content_lines)
+        if total_lines > last_line:
+            output += f"\n\n(File has more lines. Use 'offset' to read beyond line {last_line})"
+        else:
+            output += f"\n\n(End of file - total {total_lines} lines)"
+        output += "\n</file>"
+
+        return output
+
+    return await asyncio.to_thread(_read_sync, filepath)

tunacode/tools/todo.py

@@ -0,0 +1,222 @@
+"""Todo list tools for tracking task progress during complex operations."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from pydantic_ai.exceptions import ModelRetry
+
+from tunacode.core.state import StateManager
+from tunacode.tools.xml_helper import load_prompt_from_xml
+
+# Heavily yoinked from https://github.com/sst/opencode/blob/dev/packages/opencode/src/tool/todo.ts
+# and adapted for python.
+
+TODO_FIELD_ACTIVE_FORM = "activeForm"
+TODO_FIELD_CONTENT = "content"
+TODO_FIELD_STATUS = "status"
+
+TODO_STATUS_COMPLETED = "completed"
+TODO_STATUS_IN_PROGRESS = "in_progress"
+TODO_STATUS_PENDING = "pending"
+
+MAX_IN_PROGRESS_TODOS = 1
+NO_TODOS_MESSAGE = "No todos in list."
+TODO_LIST_CLEARED_MESSAGE = "Todo list cleared."
+
+# Valid status values
+VALID_STATUSES = frozenset({TODO_STATUS_PENDING, TODO_STATUS_IN_PROGRESS, TODO_STATUS_COMPLETED})
+
+# Status display symbols
+STATUS_SYMBOLS = {
+    TODO_STATUS_PENDING: "[ ]",
+    TODO_STATUS_IN_PROGRESS: "[>]",
+    TODO_STATUS_COMPLETED: "[x]",
+}
+
+
+def _validate_todo(todo: Any, index: int) -> dict[str, Any]:
+    """Validate a single todo item has required fields.
+
+    Args:
+        todo: The todo dictionary to validate.
+        index: The index of the todo in the list (for error messages).
+
+    Raises:
+        ModelRetry: If validation fails.
+    """
+    if not isinstance(todo, dict):
+        raise ModelRetry(f"Todo at index {index} must be a dictionary, got {type(todo).__name__}")
+
+    required_fields = (TODO_FIELD_CONTENT, TODO_FIELD_STATUS, TODO_FIELD_ACTIVE_FORM)
+    missing = [f for f in required_fields if f not in todo]
+    if missing:
+        raise ModelRetry(f"Todo at index {index} missing required fields: {', '.join(missing)}")
+
+    status = todo[TODO_FIELD_STATUS]
+    if not isinstance(status, str) or not status:
+        raise ModelRetry(f"Todo at index {index} must have non-empty string '{TODO_FIELD_STATUS}'")
+    if status not in VALID_STATUSES:
+        raise ModelRetry(
+            f"Todo at index {index} has invalid status '{status}'. "
+            f"Must be one of: {', '.join(sorted(VALID_STATUSES))}"
+        )
+
+    content = todo[TODO_FIELD_CONTENT]
+    if not isinstance(content, str) or not content:
+        raise ModelRetry(f"Todo at index {index} must have non-empty string '{TODO_FIELD_CONTENT}'")
+
+    active_form = todo[TODO_FIELD_ACTIVE_FORM]
+    if not isinstance(active_form, str) or not active_form:
+        raise ModelRetry(
+            f"Todo at index {index} must have non-empty string '{TODO_FIELD_ACTIVE_FORM}'"
+        )
+
+    return todo
+
+
+def _validate_todos(todos: Any) -> list[dict[str, Any]]:
+    if not isinstance(todos, list):
+        raise ModelRetry(f"todos must be a list, got {type(todos).__name__}")
+
+    validated = [_validate_todo(todo, index) for index, todo in enumerate(todos)]
+
+    in_progress_count = sum(
+        1 for todo in validated if todo[TODO_FIELD_STATUS] == TODO_STATUS_IN_PROGRESS
+    )
+    if in_progress_count > MAX_IN_PROGRESS_TODOS:
+        raise ModelRetry(
+            f"Only {MAX_IN_PROGRESS_TODOS} todo may be '{TODO_STATUS_IN_PROGRESS}' at a time, "
+            f"got {in_progress_count}"
+        )
+
+    return validated
+
+
+def _format_todos(todos: list[dict[str, Any]]) -> str:
+    """Format todos for display output.
+
+    Args:
+        todos: List of todo dictionaries.
+
+    Returns:
+        Formatted string representation of the todo list.
+    """
+    if not todos:
+        return NO_TODOS_MESSAGE
+
+    lines = []
+    for i, todo in enumerate(todos, 1):
+        status = todo[TODO_FIELD_STATUS]
+        symbol = STATUS_SYMBOLS[status]
+        content = todo[TODO_FIELD_CONTENT]
+        active_form = todo[TODO_FIELD_ACTIVE_FORM]
+
+        if status == TODO_STATUS_IN_PROGRESS:
+            lines.append(f"{i}. {symbol} {content} ({active_form})")
+        else:
+            lines.append(f"{i}. {symbol} {content}")
+
+    return "\n".join(lines)
+
+
+def create_todowrite_tool(state_manager: StateManager) -> Callable:
+    # Heavily yoinked from https://github.com/sst/opencode/blob/dev/packages/opencode/src/tool/todo.ts
+    # and adapted for python.
+    """Factory to create a todowrite tool bound to a state manager.
+
+    Args:
+        state_manager: The state manager instance to use.
+
+    Returns:
+        An async function that implements the todowrite tool.
+    """
+
+    async def todowrite(todos: list[dict[str, Any]]) -> str:
+        """Create or update the todo list for tracking task progress.
+
+        Use this tool to manage and display tasks during complex multi-step operations.
+        The entire todo list is replaced with each call.
+
+        Args:
+            todos: List of todo items. Each item must have:
+                - content: Task description in imperative form (e.g., "Fix the bug")
+                - status: One of "pending", "in_progress", or "completed"
+                - activeForm: Present continuous form for display (e.g., "Fixing the bug")
+
+        Returns:
+            Formatted display of the updated todo list.
+        """
+        validated = _validate_todos(todos)
+
+        state_manager.set_todos(validated)
+        return _format_todos(validated)
+
+    # Load prompt from XML if available
+    prompt = load_prompt_from_xml("todowrite")
+    if prompt:
+        todowrite.__doc__ = prompt
+
+    return todowrite
+
+
+def create_todoread_tool(state_manager: StateManager) -> Callable:
+    # Heavily yoinked from https://github.com/sst/opencode/blob/dev/packages/opencode/src/tool/todo.ts
+    # and adapted for python.
+    """Factory to create a todoread tool bound to a state manager.
+
+    Args:
+        state_manager: The state manager instance to use.
+
+    Returns:
+        An async function that implements the todoread tool.
+    """
+
+    async def todoread() -> str:
+        """Read the current todo list.
+
+        Use this tool to check the current state of all tasks.
+
+        Returns:
+            Formatted display of the current todo list, or a message if empty.
+        """
+        todos = state_manager.get_todos()
+        validated = _validate_todos(todos)
+        return _format_todos(validated)
+
+    # Load prompt from XML if available
+    prompt = load_prompt_from_xml("todoread")
+    if prompt:
+        todoread.__doc__ = prompt
+
+    return todoread
+
+
+def create_todoclear_tool(state_manager: StateManager) -> Callable:
+    """Factory to create a todoclear tool bound to a state manager.
+
+    Args:
+        state_manager: The state manager instance to use.
+
+    Returns:
+        An async function that implements the todoclear tool.
+    """
+
+    async def todoclear() -> str:
+        """Clear the entire todo list.
+
+        Use this tool when starting fresh or when all tasks are complete.
+
+        Returns:
+            Confirmation message.
+        """
+        state_manager.clear_todos()
+        return TODO_LIST_CLEARED_MESSAGE
+
+    # Load prompt from XML if available
+    prompt = load_prompt_from_xml("todoclear")
+    if prompt:
+        todoclear.__doc__ = prompt
+
+    return todoclear

tunacode/tools/update_file.py

@@ -0,0 +1,62 @@
+"""File update tool for agent operations."""
+
+import difflib
+import os
+
+from pydantic_ai.exceptions import ModelRetry
+
+from tunacode.tools.decorators import file_tool
+from tunacode.tools.utils.text_match import replace
+
+
+@file_tool(writes=True)
+async def update_file(filepath: str, old_text: str, new_text: str) -> str:
+    """Update an existing file by replacing old_text with new_text.
+
+    Args:
+        filepath: The path to the file to update.
+        old_text: The entire, exact block of text to be replaced.
+        new_text: The new block of text to insert.
+
+    Returns:
+        A message indicating success and the diff of changes.
+    """
+    if not os.path.exists(filepath):
+        raise ModelRetry(
+            f"File '{filepath}' not found. Cannot update. "
+            "Verify the filepath or use `write_file` if it's a new file."
+        )
+
+    with open(filepath, encoding="utf-8") as f:
+        original = f.read()
+
+    try:
+        new_content = replace(original, old_text, new_text, replace_all=False)
+    except ValueError as e:
+        lines = original.splitlines()
+        preview_lines = min(20, len(lines))
+        snippet = "\n".join(lines[:preview_lines])
+        raise ModelRetry(
+            f"{e}\n\nFile '{filepath}' preview ({preview_lines} lines):\n---\n{snippet}\n---"
+        ) from e
+
+    if original == new_content:
+        raise ModelRetry(
+            f"Update old_text found, but replacement resulted in no changes to '{filepath}'. "
+            "Was the `old_text` identical to the `new_text`? Please check the file content."
+        )
+
+    with open(filepath, "w", encoding="utf-8") as f:
+        f.write(new_content)
+
+    diff_lines = list(
+        difflib.unified_diff(
+            original.splitlines(keepends=True),
+            new_content.splitlines(keepends=True),
+            fromfile=f"a/{filepath}",
+            tofile=f"b/{filepath}",
+        )
+    )
+    diff_text = "".join(diff_lines)
+
+    return f"File '{filepath}' updated successfully.\n\n{diff_text}"

tunacode/tools/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility modules for tools."""