vtx-coding-agent 0.1.1__py3-none-any.whl

vtx/tools/__init__.py

@@ -0,0 +1,68 @@
+from ..core.types import ToolDefinition
+from .base import BaseTool
+from .bash import BashTool
+from .edit import EditTool
+from .find import FindTool
+from .read import ReadTool
+from .skill import SkillTool
+from .web import WebFetchTool, WebSearchTool
+from .write import WriteTool
+
+__all__ = [
+    "DEFAULT_TOOLS",
+    "BaseTool",
+    "BashTool",
+    "EditTool",
+    "FindTool",
+    "ReadTool",
+    "SkillTool",
+    "WebFetchTool",
+    "WebSearchTool",
+    "WriteTool",
+    "get_tool",
+    "get_tool_definitions",
+    "get_tools",
+    "tools_by_name",
+]
+
+all_tools: list[BaseTool] = [
+    ReadTool(),
+    EditTool(),
+    WriteTool(),
+    BashTool(),
+    FindTool(),
+    SkillTool(),
+    WebFetchTool(),
+    WebSearchTool(),
+]
+
+tools_by_name: dict[str, BaseTool] = {tool.name: tool for tool in all_tools}
+DEFAULT_TOOLS: list[str] = [
+    "read",
+    "edit",
+    "write",
+    "bash",
+    "find",
+    "skill",
+    "fetch_webpage",
+    "web_search",
+]
+
+
+def get_tools(names: list[str]) -> list[BaseTool]:
+    return [tool for tool in all_tools if tool.name in names]
+
+
+def get_tool(tool_name: str) -> BaseTool | None:
+    return tools_by_name.get(tool_name)
+
+
+def get_tool_definitions(tools: list[BaseTool]) -> list[ToolDefinition]:
+    return [
+        ToolDefinition(
+            name=tool.name,
+            description=tool.description,
+            parameters=tool.params.model_json_schema(),
+        )
+        for tool in tools
+    ]

vtx/tools/_read_image.py

@@ -0,0 +1,106 @@
+import base64
+import io
+import os
+
+IMAGE_EXTENSIONS = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+}
+
+MAX_DIMENSION = 2000
+MAX_BYTES = 4 * 1024 * 1024
+JPEG_QUALITY_STEPS = [85, 70, 55, 40]
+
+
+def get_mime_type(path: str) -> str | None:
+    ext = os.path.splitext(path)[1].lower()
+    return IMAGE_EXTENSIONS.get(ext)
+
+
+def is_image_file(path: str) -> bool:
+    return get_mime_type(path) is not None
+
+
+def resize_image(data: bytes, mime_type: str) -> tuple[bytes, str, str | None]:
+    """
+    Resize image if needed to stay within limits.
+
+    Returns (data, mime_type, resize_note).
+    If Pillow is not available, returns original image unchanged.
+    """
+    try:
+        from PIL import Image
+    except ImportError:
+        return data, mime_type, None
+
+    if len(data) <= MAX_BYTES:
+        img = Image.open(io.BytesIO(data))
+        width, height = img.size
+        if width <= MAX_DIMENSION and height <= MAX_DIMENSION:
+            return data, mime_type, f"[{width}x{height}]"
+
+    img = Image.open(io.BytesIO(data))
+    original_width, original_height = img.size
+
+    if img.mode in ("RGBA", "P"):
+        img = img.convert("RGB")
+
+    width, height = original_width, original_height
+    if width > MAX_DIMENSION:
+        height = int(height * MAX_DIMENSION / width)
+        width = MAX_DIMENSION
+    if height > MAX_DIMENSION:
+        width = int(width * MAX_DIMENSION / height)
+        height = MAX_DIMENSION
+
+    if (width, height) != (original_width, original_height):
+        img = img.resize((width, height), Image.Resampling.LANCZOS)
+
+    def encode_image(fmt: str, quality: int | None = None) -> tuple[bytes, str]:
+        buf = io.BytesIO()
+        if fmt == "JPEG" and quality:
+            img.save(buf, format=fmt, quality=quality, optimize=True)
+        elif fmt == "PNG":
+            img.save(buf, format=fmt, optimize=True)
+        else:
+            img.save(buf, format=fmt)
+        return buf.getvalue(), f"image/{fmt.lower()}"
+
+    png_data, png_mime = encode_image("PNG")
+    if len(png_data) <= MAX_BYTES:
+        if (width, height) != (original_width, original_height):
+            resize_note = f"[{width}x{height}, resized from {original_width}x{original_height}]"
+        else:
+            resize_note = f"[{width}x{height}]"
+        return png_data, png_mime, resize_note
+
+    jpeg_data, jpeg_mime = encode_image("JPEG")
+    for quality in JPEG_QUALITY_STEPS:
+        jpeg_data, jpeg_mime = encode_image("JPEG", quality)
+        if len(jpeg_data) <= MAX_BYTES:
+            resize_note = (
+                f"[{width}x{height}, resized from "
+                f"{original_width}x{original_height}, quality={quality}]"
+            )
+            return jpeg_data, jpeg_mime, resize_note
+
+    resize_note = (
+        f"[{width}x{height}, resized from "
+        f"{original_width}x{original_height}, may exceed size limit]"
+    )
+    return jpeg_data, jpeg_mime, resize_note
+
+
+def read_and_process_image(path: str) -> tuple[str, str, str | None]:
+    mime_type = get_mime_type(path)
+    if not mime_type:
+        raise ValueError(
+            f"Unsupported image format. Supported: {', '.join(IMAGE_EXTENSIONS.keys())}"
+        )
+    with open(path, "rb") as f:
+        data = f.read()
+    data, mime_type, resize_note = resize_image(data, mime_type)
+    return base64.b64encode(data).decode("utf-8"), mime_type, resize_note

vtx/tools/_tool_utils.py

@@ -0,0 +1,90 @@
+import asyncio
+import os
+from contextlib import suppress
+
+from ..async_utils import OperationCancelledError, await_or_cancel
+
+_SUBPROCESS_DRAIN_TIMEOUT_SECONDS = 1.0
+
+
+class ToolCancelledError(Exception):
+    pass
+
+
+async def await_task_or_cancel(work: asyncio.Task, cancel_event: asyncio.Event | None):
+    try:
+        return await await_or_cancel(work, cancel_event)
+    except OperationCancelledError as e:
+        raise ToolCancelledError from e
+
+
+async def communicate_or_cancel(
+    proc: asyncio.subprocess.Process, cancel_event: asyncio.Event | None
+) -> tuple[bytes, bytes]:
+    comm_task = asyncio.create_task(proc.communicate())
+    if not cancel_event:
+        return await comm_task
+
+    cancel = asyncio.create_task(cancel_event.wait())
+    try:
+        done, pending = await asyncio.wait(
+            [comm_task, cancel], return_when=asyncio.FIRST_COMPLETED
+        )
+
+        if cancel in done and cancel_event.is_set():
+            if proc.returncode is None:
+                with suppress(ProcessLookupError):
+                    proc.kill()
+                with suppress(ProcessLookupError):
+                    await asyncio.wait_for(proc.wait(), _SUBPROCESS_DRAIN_TIMEOUT_SECONDS)
+            if not comm_task.done():
+                with suppress(asyncio.CancelledError, TimeoutError):
+                    await asyncio.wait_for(
+                        asyncio.shield(comm_task), _SUBPROCESS_DRAIN_TIMEOUT_SECONDS
+                    )
+                if not comm_task.done():
+                    comm_task.cancel()
+                    with suppress(asyncio.CancelledError):
+                        await comm_task
+            raise ToolCancelledError
+
+        for task in pending:
+            task.cancel()
+            with suppress(asyncio.CancelledError):
+                await task
+
+        return comm_task.result()
+    finally:
+        if not cancel.done():
+            cancel.cancel()
+            with suppress(asyncio.CancelledError):
+                await cancel
+
+
+def shorten_path(path: str) -> str:
+    home = os.path.expanduser("~")
+    if path.startswith(home):
+        return "~" + path[len(home) :]
+    return path
+
+
+def truncate_text(text: str, n: int = 80) -> str:
+    return text[:77] + "..." if len(text) > n else text
+
+
+def truncate_lines_by_bytes(
+    lines: list[str], max_output_bytes: int, marker: str = "[output truncated]"
+) -> tuple[str, bool]:
+    total_bytes = 0
+    result_lines: list[str] = []
+
+    for line in lines:
+        line_bytes = len(line.encode("utf-8"))
+        if total_bytes + line_bytes <= max_output_bytes:
+            total_bytes += line_bytes
+            result_lines.append(line)
+        else:
+            result_lines.append(marker)
+            return "\n".join(result_lines), True
+
+    return "\n".join(result_lines), False

vtx/tools/base.py

@@ -0,0 +1,36 @@
+import asyncio
+from abc import ABC, abstractmethod
+
+from pydantic import BaseModel
+
+from ..core.types import ToolResult
+
+
+class BaseTool[T: BaseModel](ABC):
+    # UI model for tool blocks:
+    # - format_call(params): short call text shown on the tool header
+    # - ToolResult.ui_summary: one-line result summary appended to that header
+    # - ToolResult.ui_details: multiline result body shown below the header
+    # - format_preview(params): approval-time preview shown before execution
+    name: str
+    params: type[T]
+    description: str
+    mutating: bool = True
+    tool_icon: str = "→"
+    prompt_guidelines: tuple[str, ...] = ()
+
+    @abstractmethod
+    async def execute(
+        self, params: T, cancel_event: asyncio.Event | None = None
+    ) -> ToolResult: ...
+
+    def format_call(self, params: T) -> str:
+        data = params.model_dump(exclude_none=True)
+        if not data:
+            return ""
+        parts = [f"{k}={v}" for k, v in data.items()]
+        return " / ".join(parts)
+
+    def format_preview(self, params: T) -> str | None:
+        """Extended preview shown only during approval prompts. Returns None by default."""
+        return None

vtx/tools/bash.py

@@ -0,0 +1,371 @@
+import asyncio
+import contextlib
+import os
+import re
+import signal
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from vtx import config
+from vtx.ui.tool_output import truncate_tool_output_text
+
+from ..core.types import ToolResult
+from .base import BaseTool
+
+DEFAULT_TIMEOUT = 180
+MAX_OUTPUT_BYTES = 50 * 1024
+MAX_OUTPUT_LINES = 2000
+_SUBPROCESS_DRAIN_TIMEOUT_SECONDS = 1.0
+
+_IS_WINDOWS: bool = sys.platform == "win32"
+_ANSI_ESCAPE_RE = re.compile(r"\x1b\[[0-9;]*[a-zA-Z]|\x1b\][^\x07]*\x07|\x1b[()][AB012]")
+
+
+def _get_env() -> dict[str, str]:
+    return {
+        **os.environ,
+        "CI": "true",
+        "NO_COLOR": "1",
+        "TERM": "dumb",
+        "GIT_PAGER": "cat",
+        "PAGER": "cat",
+    }
+
+
+def _get_shell() -> str | None:
+    if _IS_WINDOWS:
+        program_files = os.environ.get("ProgramFiles", "")  # noqa: SIM112
+        program_files_x86 = os.environ.get("ProgramFiles(x86)", "")  # noqa: SIM112
+        paths = [
+            os.path.join(program_files, "Git", "bin", "bash.exe"),
+            os.path.join(program_files_x86, "Git", "bin", "bash.exe"),
+        ]
+        for path in paths:
+            if path and os.path.exists(path):
+                return path
+        return None
+    return os.environ.get("SHELL") or "/bin/bash"
+
+
+def _get_spawn_argv(command: str) -> list[str] | None:
+    """Return the argv to exec the command through a shell, or None to use the
+    platform's default shell mechanism.
+
+    The exec form is required on Windows: passing the shell as `executable=` to
+    create_subprocess_shell formats it unquoted into the command line, so a Git
+    bash path like "C:\\Program Files\\Git\\bin\\bash.exe" splits at the space
+    (and bash would receive cmd's /c instead of -c).
+    """
+    shell = _get_shell()
+    if shell is None:
+        return None
+    return [shell, "-c", command]
+
+
+def _sanitize_output(text: str) -> str:
+    text = _ANSI_ESCAPE_RE.sub("", text)
+    text = text.replace("\r\n", "\n").replace("\r", "")
+    text = "".join(c for c in text if c >= " " or c in "\t\n")
+    return text
+
+
+class TruncationResult:
+    def __init__(self, content: str, truncated: bool, lines_kept: int, total_lines: int):
+        self.content = content
+        self.truncated = truncated
+        self.lines_kept = lines_kept
+        self.total_lines = total_lines
+
+
+def _truncate_tail(text: str) -> TruncationResult:
+    """
+    Truncate from the head, keeping the last N lines/bytes (tail truncation).
+    Better for bash output where errors/results are at the end.
+    """
+    lines = text.split("\n")
+    total_lines = len(lines)
+
+    if total_lines <= MAX_OUTPUT_LINES and len(text.encode("utf-8")) <= MAX_OUTPUT_BYTES:
+        return TruncationResult(text, False, total_lines, total_lines)
+
+    output_lines: list[str] = []
+    output_bytes = 0
+
+    for i in range(total_lines - 1, -1, -1):
+        line = lines[i]
+        encoded_line = line.encode("utf-8")
+        line_bytes = len(encoded_line) + (1 if output_lines else 0)
+
+        if output_bytes + line_bytes > MAX_OUTPUT_BYTES:
+            if not output_lines:
+                output_lines.append(encoded_line[-MAX_OUTPUT_BYTES:].decode("utf-8", "ignore"))
+            break
+        if len(output_lines) >= MAX_OUTPUT_LINES:
+            break
+
+        output_lines.insert(0, line)
+        output_bytes += line_bytes
+
+    return TruncationResult("\n".join(output_lines), True, len(output_lines), total_lines)
+
+
+async def _kill_process_tree(proc: asyncio.subprocess.Process) -> None:
+    if proc.returncode is not None:
+        return
+
+    try:
+        if _IS_WINDOWS:
+            subprocess.run(["taskkill", "/F", "/T", "/PID", str(proc.pid)], capture_output=True)
+        else:
+            os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+        await proc.wait()
+    except (ProcessLookupError, PermissionError, OSError):
+        pass
+
+
+def _write_full_output_to_temp(output: str) -> str:
+    fd, path = tempfile.mkstemp(prefix="vtx-bash-", suffix=".log")
+    try:
+        os.write(fd, output.encode("utf-8"))
+    finally:
+        os.close(fd)
+    return path
+
+
+class BashParams(BaseModel):
+    command: str = Field(description="The bash command to execute")
+    timeout: int = Field(
+        description=f"Timeout in seconds (default {DEFAULT_TIMEOUT})", default=DEFAULT_TIMEOUT
+    )
+
+
+class BashTool(BaseTool):
+    name = "bash"
+    tool_icon = "$"
+    params = BashParams
+    prompt_guidelines = (
+        "Use bash for terminal operations (git, package managers, builds, tests, running scripts)",
+    )
+    description = (
+        "Execute a bash command in the current working directory. "
+        f"Output truncated to last {MAX_OUTPUT_LINES} lines or {MAX_OUTPUT_BYTES // 1024}KB. "
+        "If truncated, full output is saved to a temp file. "
+        "Optionally provide a timeout in seconds. "
+        "IMPORTANT: Do NOT use bash for file search (use the find tool instead), "
+        "reading files (use read), or editing files (use edit)."
+    )
+
+    # TODO: Add streaming support via an optional `on_chunk` callback parameter
+    # Implementation approach:
+    # 1. Add `on_chunk: Callable[[str], None] | None = None` parameter to execute()
+    # 2. Instead of proc.communicate(), read from proc.stdout/stderr in a loop
+    # 3. Keep a rolling buffer of chunks (max 2x MAX_OUTPUT_BYTES) for tail truncation
+    # 4. Call on_chunk(sanitized_text) for each chunk received
+    # 5. Start writing to temp file once total bytes exceed MAX_OUTPUT_BYTES
+    # 6. On completion, apply tail truncation to the rolling buffer
+
+    def format_call(self, params: BashParams) -> str:
+        return params.command
+
+    def _format_display(
+        self, output: str, max_lines: int = 5, max_line_chars: int = 500
+    ) -> tuple[str, str | None]:
+        truncation_color = config.ui.colors.dim
+
+        if not output:
+            return f"[{truncation_color}](no output)[/{truncation_color}]", None
+
+        lines = [line for line in output.split("\n") if line != ""]
+        if not lines:
+            return f"[{truncation_color}](no output)[/{truncation_color}]", None
+
+        full_formatted: list[str] = []
+        char_truncated = False
+        for line in lines:
+            if len(line) > max_line_chars:
+                visible = line[:max_line_chars].replace("[", "\\[")
+                hidden_chars = len(line) - max_line_chars
+                char_truncated = True
+                full_formatted.append(
+                    f"[dim]{visible}[/dim]"
+                    f"[{truncation_color}]... ({hidden_chars} more chars)[/{truncation_color}]"
+                )
+            else:
+                escaped = line.replace("[", "\\[")
+                full_formatted.append(f"[dim]{escaped}[/dim]")
+
+        full_display = "\n".join(full_formatted)
+        collapsed_display, line_truncated = truncate_tool_output_text(
+            full_display, max_lines=max_lines, escape_lines=False
+        )
+        expanded_display = full_display if line_truncated or char_truncated else None
+        return collapsed_display, expanded_display
+
+    async def execute(
+        self,
+        params: BashParams,
+        cancel_event: asyncio.Event | None = None,
+        inline_output: bool = False,
+    ) -> ToolResult:
+        if not params.command.strip():
+            msg = "Command cannot be empty"
+            return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+
+        command = params.command
+
+        cwd = Path.cwd()
+        if not cwd.exists():
+            return ToolResult(
+                success=False, ui_summary=f"[red]Working directory does not exist: {cwd}[/red]"
+            )
+
+        proc = None
+        try:
+            spawn_argv = _get_spawn_argv(command)
+            if spawn_argv is None:
+                proc = await asyncio.create_subprocess_shell(
+                    command,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.PIPE,
+                    stdin=asyncio.subprocess.DEVNULL,
+                    env=_get_env(),
+                    start_new_session=not _IS_WINDOWS,
+                )
+            else:
+                proc = await asyncio.create_subprocess_exec(
+                    *spawn_argv,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.PIPE,
+                    stdin=asyncio.subprocess.DEVNULL,
+                    env=_get_env(),
+                    start_new_session=not _IS_WINDOWS,
+                )
+
+            comm_task = asyncio.create_task(proc.communicate())
+
+            try:
+                if cancel_event:
+                    cancel_wait = asyncio.create_task(cancel_event.wait())
+                    done, pending = await asyncio.wait(
+                        [comm_task, cancel_wait],
+                        timeout=params.timeout,
+                        return_when=asyncio.FIRST_COMPLETED,
+                    )
+
+                    if not done:
+                        for task in pending:
+                            task.cancel()
+                            with contextlib.suppress(asyncio.CancelledError):
+                                await task
+                        await _kill_process_tree(proc)
+                        return ToolResult(
+                            success=False,
+                            ui_summary=f"[red]Command timed out after {params.timeout}s[/red]",
+                        )
+
+                    if cancel_wait in done and cancel_event.is_set():
+                        await _kill_process_tree(proc)
+                        if not comm_task.done():
+                            with contextlib.suppress(asyncio.CancelledError, TimeoutError):
+                                await asyncio.wait_for(
+                                    asyncio.shield(comm_task), _SUBPROCESS_DRAIN_TIMEOUT_SECONDS
+                                )
+                            if not comm_task.done():
+                                comm_task.cancel()
+                                with contextlib.suppress(asyncio.CancelledError):
+                                    await comm_task
+                        return ToolResult(
+                            success=False,
+                            result="Command aborted",
+                            ui_summary="[yellow]Command aborted by user[/yellow]",
+                        )
+
+                    for task in pending:
+                        task.cancel()
+                        with contextlib.suppress(asyncio.CancelledError):
+                            await task
+
+                    stdout_bytes, stderr_bytes = comm_task.result()
+                else:
+                    stdout_bytes, stderr_bytes = await asyncio.wait_for(
+                        comm_task, timeout=params.timeout
+                    )
+
+            except TimeoutError:
+                await _kill_process_tree(proc)
+                if comm_task is not None and not comm_task.done():
+                    with contextlib.suppress(asyncio.CancelledError, TimeoutError):
+                        await asyncio.wait_for(
+                            asyncio.shield(comm_task), _SUBPROCESS_DRAIN_TIMEOUT_SECONDS
+                        )
+                    if not comm_task.done():
+                        comm_task.cancel()
+                        with contextlib.suppress(asyncio.CancelledError):
+                            await comm_task
+                return ToolResult(
+                    success=False,
+                    ui_summary=f"[red]Command timed out after {params.timeout}s[/red]",
+                )
+
+            stdout = _sanitize_output(stdout_bytes.decode("utf-8", errors="replace"))
+            stderr = _sanitize_output(stderr_bytes.decode("utf-8", errors="replace"))
+
+            full_output = ""
+            if stdout:
+                full_output += stdout
+            if stderr:
+                full_output += f"\n[stderr]\n{stderr}" if full_output else f"[stderr]\n{stderr}"
+            full_output = full_output.rstrip()
+
+            trunc = _truncate_tail(full_output)
+            if trunc.truncated:
+                marker = (
+                    f"\n\n[output truncated to last {trunc.lines_kept} lines "
+                    f"of {trunc.total_lines}"
+                )
+                if inline_output:
+                    marker += "]"
+                else:
+                    temp_file_path = _write_full_output_to_temp(full_output)
+                    marker += f"; full output: {temp_file_path}]"
+                trunc.content += marker
+
+            result_text = trunc.content or "(no output)"
+
+            display_max = sys.maxsize if inline_output else 5
+            display_text, display_text_full = self._format_display(
+                trunc.content, max_lines=display_max
+            )
+
+            non_empty_lines = [line for line in (trunc.content or "").split("\n") if line.strip()]
+            is_single_line = len(non_empty_lines) <= 1
+
+            if proc.returncode == 0:
+                if is_single_line:
+                    summary_line = display_text.replace("\n", " ").strip()
+                    return ToolResult(success=True, result=result_text, ui_summary=summary_line)
+                return ToolResult(
+                    success=True,
+                    result=result_text,
+                    ui_details=display_text,
+                    ui_details_full=display_text_full,
+                )
+            else:
+                return ToolResult(
+                    success=False,
+                    result=result_text,
+                    ui_summary=f"[red]Exit code {proc.returncode}[/red]",
+                    ui_details=display_text,
+                    ui_details_full=display_text_full,
+                )
+
+        except Exception as e:
+            msg = f"Error running command: {e}"
+            return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+        finally:
+            if proc is not None:
+                await _kill_process_tree(proc)