tau-coding-agent 0.1.0__py3-none-any.whl

tau/builtins/tools/glob.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import glob as _glob
+from pathlib import Path
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+from tau.tool.types import (
+    Tool, ToolKind, ToolExecutionMode,
+    ToolInvocation, ToolResult,
+    ToolExecutionUpdateCallback, AbortSignal, ToolContext,
+)
+from tau.tool.render import call_line
+
+
+def _render_glob_call(args: dict, _streaming: bool) -> list[str]:
+    return call_line("glob", args.get("pattern", ""))
+
+_MAX_RESULTS = 1000
+_PREVIEW_LINES = 5
+
+
+def _render_glob_result(content: str, opts: Any) -> list[str]:
+    from tau.tui.ansi import DIM, RESET
+    metadata = opts.metadata or {}
+    match_count = metadata.get("match_count", 0)
+    truncated   = metadata.get("truncated", False)
+
+    if match_count == 0:
+        return ["No files matched"]
+
+    file_word = "file" if match_count == 1 else "files"
+    summary = f"Found {match_count} {file_word}"
+    if truncated:
+        summary += f"  {DIM}(truncated){RESET}"
+
+    lines = [l for l in content.splitlines() if l and not l.startswith("[")]
+    result = [summary]
+
+    show = lines if opts.expanded else lines[:_PREVIEW_LINES]
+    for path in show:
+        result.append(path)
+
+    if opts.expanded and len(lines) > _PREVIEW_LINES:
+        result.append(f"{DIM}  (ctrl+o to collapse){RESET}")
+    elif not opts.expanded and len(lines) > _PREVIEW_LINES:
+        result.append(f"{DIM}  ···  (ctrl+o to expand){RESET}")
+
+    return result
+
+
+class GlobParams(BaseModel):
+    """Parameters for the glob tool."""
+    pattern: str = Field(description="Glob pattern (e.g. 'src/**/*.py').")
+    path: str = Field(default="", description="Base directory to search from. Defaults to the agent's cwd.")
+
+
+class GlobTool(Tool):
+    """Tool for finding files matching glob patterns."""
+    def __init__(self) -> None:
+        super().__init__(
+            name="glob",
+            description=(
+                "Find files matching a glob pattern. Returns absolute paths, one per line, "
+                f"up to {_MAX_RESULTS} results. Supports ** for recursive matching."
+            ),
+            schema=GlobParams,
+            kind=ToolKind.Read,
+            execution_mode=ToolExecutionMode.Parallel,
+            render_result=_render_glob_result,
+            render_call=_render_glob_call,
+            render_shell="default",
+            prompt_guidelines="Use to discover files by pattern before reading or editing them.",
+        )
+
+    def get_display_name(self, args: dict[str, Any]) -> str:
+        """Get a short display name for the glob operation."""
+        return args.get("pattern", "glob")
+
+    async def execute(
+        self,
+        invocation: ToolInvocation,
+        tool_execution_update_callback: Optional[ToolExecutionUpdateCallback] = None,
+        signal: Optional[AbortSignal] = None,
+        context: Optional[ToolContext] = None,
+    ) -> ToolResult:
+        """Execute the glob pattern matching operation."""
+        params = GlobParams.model_validate(invocation.params)
+        base = Path(params.path or invocation.cwd or ".").resolve()
+
+        if not base.is_dir():
+            return ToolResult.error(invocation.id, f"Base path is not a directory: {base}")
+
+        matches = sorted(_glob.glob(str(base / params.pattern), recursive=True))
+        truncated = len(matches) > _MAX_RESULTS
+        matches = matches[:_MAX_RESULTS]
+
+        metadata = {
+            "pattern": params.pattern,
+            "match_count": len(matches),
+            "truncated": truncated,
+        }
+
+        if not matches:
+            return ToolResult.ok(invocation.id, f"No files matched pattern: {params.pattern}", metadata=metadata)
+
+        result = "\n".join(matches)
+        if truncated:
+            result += f"\n\n[Results truncated at {_MAX_RESULTS}. Narrow your pattern.]"
+
+        return ToolResult.ok(invocation.id, result, metadata=metadata)

tau/builtins/tools/grep.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+from tau.tool.types import (
+    Tool, ToolKind, ToolExecutionMode,
+    ToolInvocation, ToolResult,
+    ToolExecutionUpdateCallback, AbortSignal, ToolContext,
+)
+from tau.tool.render import call_line
+
+
+def _render_grep_call(args: dict, _streaming: bool) -> list[str]:
+    pattern = args.get("pattern", "")
+    path    = args.get("path", "")
+    return call_line("grep", pattern, path)
+
+_MAX_MATCHES = 500
+_PREVIEW_LINES = 5
+
+
+def _render_grep_result(content: str, opts: Any) -> list[str]:
+    from tau.tui.ansi import DIM, RESET
+    metadata = opts.metadata or {}
+    match_count   = metadata.get("match_count", 0)
+    files_searched = metadata.get("files_searched", 0)
+    truncated     = metadata.get("truncated", False)
+
+    if match_count == 0:
+        return ["No matches found"]
+
+    file_word  = "file" if files_searched == 1 else "files"
+    match_word = "match" if match_count == 1 else "matches"
+    summary = f"Found {match_count} {match_word} in {files_searched} {file_word}"
+    if truncated:
+        summary += f"  {DIM}(truncated){RESET}"
+
+    lines = [l for l in content.splitlines() if ":" in l]
+    result = [summary]
+
+    show = lines if opts.expanded else lines[:_PREVIEW_LINES]
+    for line in show:
+        file_part, _, rest = line.partition(":")
+        lineno, _, text = rest.partition(": ")
+        result.append(f"{DIM}{file_part}:{lineno.strip()}{RESET}  {text}")
+
+    if opts.expanded and len(lines) > _PREVIEW_LINES:
+        result.append(f"{DIM}  (ctrl+o to collapse){RESET}")
+    elif not opts.expanded and len(lines) > _PREVIEW_LINES:
+        result.append(f"{DIM}  ···  (ctrl+o to expand){RESET}")
+
+    return result
+
+
+class GrepParams(BaseModel):
+    """Parameters for the grep tool."""
+    pattern: str = Field(description="Regular expression to search for.")
+    path: str = Field(default="", description="File or directory to search. Defaults to the agent's cwd.")
+    include: str = Field(default="", description="Glob pattern to filter files (e.g. '*.py'). Only used when path is a directory.")
+    case_sensitive: bool = Field(default=True, description="Whether the pattern is case-sensitive.")
+
+
+class GrepTool(Tool):
+    """Tool for searching files by regex pattern."""
+    def __init__(self) -> None:
+        super().__init__(
+            name="grep",
+            description=(
+                "Search for a regex pattern in files. Returns matches as 'file:line: content', "
+                f"up to {_MAX_MATCHES} matches. When path is a directory, searches recursively."
+            ),
+            schema=GrepParams,
+            kind=ToolKind.Read,
+            execution_mode=ToolExecutionMode.Parallel,
+            render_result=_render_grep_result,
+            render_call=_render_grep_call,
+            render_shell="default",
+            prompt_guidelines="Prefer over read when searching for a symbol, function, or pattern across the codebase.",
+        )
+
+    def get_display_name(self, args: dict[str, Any]) -> str:
+        """Get a short display name for the grep operation."""
+        return args.get("pattern", "grep")
+
+    async def execute(
+        self,
+        invocation: ToolInvocation,
+        tool_execution_update_callback: Optional[ToolExecutionUpdateCallback] = None,
+        signal: Optional[AbortSignal] = None,
+        context: Optional[ToolContext] = None,
+    ) -> ToolResult:
+        """Execute the regex pattern search operation."""
+        params = GrepParams.model_validate(invocation.params)
+
+        flags = 0 if params.case_sensitive else re.IGNORECASE
+        try:
+            regex = re.compile(params.pattern, flags)
+        except re.error as e:
+            return ToolResult.error(invocation.id, f"Invalid regex pattern: {e}")
+
+        target = Path(params.path or invocation.cwd or ".").resolve()
+        files: list[Path] = []
+
+        if target.is_file():
+            files = [target]
+        elif target.is_dir():
+            glob_pat = f"**/{params.include}" if params.include else "**/*"
+            files = [p for p in target.glob(glob_pat) if p.is_file()]
+        else:
+            return ToolResult.error(invocation.id, f"Path not found: {target}")
+
+        matches: list[str] = []
+        truncated = False
+
+        for file in sorted(files):
+            if truncated:
+                break
+            try:
+                for lineno, line in enumerate(file.read_text(encoding="utf-8", errors="replace").splitlines(), 1):
+                    if regex.search(line):
+                        matches.append(f"{file}:{lineno}: {line}")
+                        if len(matches) >= _MAX_MATCHES:
+                            truncated = True
+                            break
+            except OSError:
+                continue
+
+        metadata = {
+            "pattern": params.pattern,
+            "files_searched": len(files),
+            "match_count": len(matches),
+            "truncated": truncated,
+        }
+
+        if not matches:
+            return ToolResult.ok(invocation.id, f"No matches for pattern: {params.pattern}", metadata=metadata)
+
+        result = "\n".join(matches)
+        if truncated:
+            result += f"\n\n[Results truncated at {_MAX_MATCHES} matches.]"
+
+        return ToolResult.ok(invocation.id, result, metadata=metadata)

tau/builtins/tools/ls.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+from tau.tool.types import (
+    Tool, ToolKind, ToolExecutionMode,
+    ToolInvocation, ToolResult,
+    ToolExecutionUpdateCallback, AbortSignal, ToolContext,
+)
+from tau.tool.render import call_line
+
+
+def _render_ls_call(args: dict, _streaming: bool) -> list[str]:
+    return call_line("ls", args.get("path", ""))
+
+_PREVIEW_LINES = 5
+
+
+class LsParams(BaseModel):
+    """Parameters for the ls tool."""
+    path: str = Field(default="", description="Directory path to list. Defaults to the agent's cwd.")
+
+
+def _render_ls_result(content: str, opts: Any) -> list[str]:
+    from tau.tui.ansi import DIM, RESET
+    metadata = opts.metadata or {}
+    path      = metadata.get("path", "")
+    file_count = metadata.get("file_count", 0)
+    dir_count  = metadata.get("dir_count", 0)
+    entries    = metadata.get("entries", [])
+
+    parts = []
+    if dir_count:
+        parts.append(f"{dir_count} {'dir' if dir_count == 1 else 'dirs'}")
+    if file_count:
+        parts.append(f"{file_count} {'file' if file_count == 1 else 'files'}")
+    summary = f"Found {', '.join(parts)}" if parts else (path or "empty directory")
+    result = [summary]
+
+    if not entries:
+        return result
+
+    show = entries if opts.expanded else entries[:_PREVIEW_LINES]
+    for entry in show:
+        name     = entry["name"]
+        is_dir   = entry["is_dir"]
+        size_str = entry.get("size_str", "")
+        if is_dir:
+            result.append(f"{name}/")
+        else:
+            tail = f"  {DIM}{size_str}{RESET}" if size_str else ""
+            result.append(f"{name}{tail}")
+
+    if opts.expanded and len(entries) > _PREVIEW_LINES:
+        result.append(f"{DIM}  (ctrl+o to collapse){RESET}")
+    elif not opts.expanded and len(entries) > _PREVIEW_LINES:
+        result.append(f"{DIM}  ···  (ctrl+o to expand){RESET}")
+
+    return result
+
+
+class LsTool(Tool):
+    """Tool for listing directory contents."""
+    def __init__(self) -> None:
+        super().__init__(
+            name="ls",
+            description="List the contents of a directory, showing files and subdirectories.",
+            schema=LsParams,
+            kind=ToolKind.Read,
+            execution_mode=ToolExecutionMode.Parallel,
+            render_result=_render_ls_result,
+            render_call=_render_ls_call,
+            render_shell="default",
+            prompt_guidelines="Use to get an overview of a directory before diving into files. Use glob for targeted file discovery.",
+        )
+
+    def get_display_name(self, args: dict[str, Any]) -> str:
+        return args.get("path", ".") or "."
+
+    async def execute(
+        self,
+        invocation: ToolInvocation,
+        tool_execution_update_callback: Optional[ToolExecutionUpdateCallback] = None,
+        signal: Optional[AbortSignal] = None,
+        context: Optional[ToolContext] = None,
+    ) -> ToolResult:
+        params = LsParams.model_validate(invocation.params)
+        target = Path(params.path or invocation.cwd or ".").resolve()
+
+        if not target.exists():
+            return ToolResult.error(invocation.id, f"Path not found: {target}")
+        if not target.is_dir():
+            return ToolResult.error(invocation.id, f"Not a directory: {target}")
+
+        try:
+            raw_entries = sorted(target.iterdir(), key=lambda p: (p.is_file(), p.name.lower()))
+        except PermissionError:
+            return ToolResult.error(invocation.id, f"Permission denied: {target}")
+
+        file_count = dir_count = 0
+        entries = []
+        lines = [f"{target}/"]
+        for entry in raw_entries:
+            is_dir = entry.is_dir()
+            if is_dir:
+                dir_count += 1
+            else:
+                file_count += 1
+            try:
+                size_str = _human_size(entry.stat().st_size) if entry.is_file() else ""
+            except OSError:
+                size_str = ""
+            entries.append({"name": entry.name, "is_dir": is_dir, "size_str": size_str})
+            suffix = "/" if is_dir else ""
+            lines.append(f"  {entry.name}{suffix}{f'  {size_str}' if size_str else ''}")
+
+        metadata = {
+            "path": str(target),
+            "file_count": file_count,
+            "dir_count": dir_count,
+            "entries": entries,
+        }
+        return ToolResult.ok(invocation.id, "\n".join(lines), metadata=metadata)
+
+
+def _human_size(n: int) -> str:
+    """Convert byte count to human-readable format (B, KB, MB, GB, TB)."""
+    for unit in ("B", "KB", "MB", "GB"):
+        if n < 1024:
+            return f"{n}{unit}" if unit == "B" else f"{n:.1f}{unit}"
+        n //= 1024
+    return f"{n:.1f}TB"

tau/builtins/tools/read.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+from tau.tool.types import (
+    Tool, ToolKind, ToolExecutionMode,
+    ToolInvocation, ToolResult,
+    ToolExecutionUpdateCallback, AbortSignal, ToolContext,
+)
+from tau.tool.render import call_line
+
+
+def _render_read_call(args: dict, _streaming: bool) -> list[str]:
+    return call_line("read", args.get("path", ""))
+
+
+class ReadParams(BaseModel):
+    """Parameters for the read tool."""
+    path: str = Field(description="Absolute path to the file to read.")
+    offset: int = Field(default=0, ge=0, description="Line number to start reading from (0-based).")
+    limit: int = Field(default=2000, ge=1, description="Maximum number of lines to read.")
+
+
+_PREVIEW_LINES = 5
+
+
+def _render_read_result(content: str, opts: Any) -> list[str]:
+    from tau.tui.ansi import DIM, RESET
+    metadata = opts.metadata or {}
+    lines_returned = metadata.get("lines_returned", 0)
+    truncated = metadata.get("truncated", False)
+
+    line_word = "line" if lines_returned == 1 else "lines"
+    result = [f"Read {lines_returned} {line_word}"]
+
+    parsed = []
+    for raw in content.splitlines():
+        if "\t" in raw:
+            num, _, text = raw.partition("\t")
+            parsed.append((num.strip(), text))
+
+    if not parsed:
+        return result
+
+    show = parsed if opts.expanded else parsed[:_PREVIEW_LINES]
+    for num, text in show:
+        result.append(f"{DIM}{num}{RESET}  {text}")
+
+    if opts.expanded and (len(parsed) > _PREVIEW_LINES or truncated):
+        result.append(f"{DIM}  (ctrl+o to collapse){RESET}")
+    elif not opts.expanded and (len(parsed) > _PREVIEW_LINES or truncated):
+        result.append(f"{DIM}  ···  (ctrl+o to expand){RESET}")
+
+    return result
+
+
+class ReadTool(Tool):
+    """Tool for reading file contents with line numbers."""
+    def __init__(self) -> None:
+        super().__init__(
+            name="read",
+            description=(
+                "Read the contents of a file. Returns lines with 1-based line numbers in the format "
+                "'<n>\\t<content>'. Use offset and limit to read large files in chunks."
+            ),
+            schema=ReadParams,
+            kind=ToolKind.Read,
+            execution_mode=ToolExecutionMode.Parallel,
+            render_result=_render_read_result,
+            render_call=_render_read_call,
+            render_shell="default",
+            prompt_guidelines="Use grep first to locate the relevant section, then read with offset/limit instead of loading the entire file.",
+        )
+
+    def get_display_name(self, args: dict[str, Any]) -> str:
+        """Get a short display name for the read operation."""
+        return args.get("path", "read")
+
+    async def execute(
+        self,
+        invocation: ToolInvocation,
+        tool_execution_update_callback: Optional[ToolExecutionUpdateCallback] = None,
+        signal: Optional[AbortSignal] = None,
+        context: Optional[ToolContext] = None,
+    ) -> ToolResult:
+        """Execute the file read operation."""
+        params = ReadParams.model_validate(invocation.params)
+        path = Path(params.path)
+
+        if not path.exists():
+            return ToolResult.error(invocation.id, f"File not found: {params.path}")
+        if not path.is_file():
+            return ToolResult.error(invocation.id, f"Not a file: {params.path}")
+
+        try:
+            lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+        except OSError as e:
+            return ToolResult.error(invocation.id, f"Cannot read file: {e}")
+
+        total = len(lines)
+        start = params.offset
+        end = min(start + params.limit, total)
+        chunk = lines[start:end]
+
+        numbered = "\n".join(f"{start + i + 1}\t{line}" for i, line in enumerate(chunk))
+
+        footer = ""
+        truncated = end < total
+        if truncated:
+            footer = f"\n\n[Showing lines {start + 1}–{end} of {total}. Use offset={end} to read more.]"
+
+        metadata = {
+            "file_path": str(path),
+            "total_lines": total,
+            "lines_returned": len(chunk),
+            "offset": start,
+            "truncated": truncated,
+        }
+        return ToolResult.ok(invocation.id, numbered + footer, metadata=metadata)

tau/builtins/tools/terminal.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+from tau.tool.types import (
+    Tool, ToolKind, ToolExecutionMode,
+    ToolInvocation, ToolResult,
+    ToolExecutionUpdateCallback, AbortSignal, ToolContext,
+)
+from tau.tool.render import call_line
+
+_DEFAULT_TIMEOUT = 120
+
+
+def _render_terminal_call(args: dict, _streaming: bool) -> list[str]:
+    return call_line("terminal", args.get("command", ""))
+_PREVIEW_LINES = 5
+
+
+def _render_terminal_result(content: str, opts: Any) -> list[str]:
+    from tau.tui.ansi import RED, DIM, RESET
+    metadata = opts.metadata or {}
+    exit_code = metadata.get("exit_code", 0)
+    timed_out = metadata.get("timed_out", False)
+    failed    = timed_out or exit_code != 0
+
+    if timed_out:
+        return [f"{RED}Timed out{RESET}"]
+
+    lines = content.splitlines() if content else []
+    if not lines:
+        return [f"{RED}Failed (exit {exit_code}, no output){RESET}" if failed else "(no output)"]
+
+    def fmt(line: str) -> str:
+        return f"{RED}{line}{RESET}" if failed else line
+
+    show = lines if opts.expanded else lines[:_PREVIEW_LINES]
+    result = [fmt(show[0])]
+    for line in show[1:]:
+        result.append(fmt(line))
+
+    if opts.expanded and len(lines) > _PREVIEW_LINES:
+        result.append(f"{DIM}  (ctrl+o to collapse){RESET}")
+    elif not opts.expanded and len(lines) > _PREVIEW_LINES:
+        result.append(f"{DIM}  ···  (ctrl+o to expand){RESET}")
+
+    return result
+
+
+class TerminalParams(BaseModel):
+    """Parameters for terminal command execution."""
+    command: str = Field(description="Shell command to execute.")
+    timeout: int = Field(
+        default=_DEFAULT_TIMEOUT,
+        ge=1,
+        le=600,
+        description=f"Timeout in seconds (default {_DEFAULT_TIMEOUT}, max 600).",
+    )
+
+
+class TerminalTool(Tool):
+    """Tool for executing shell commands."""
+    def __init__(self) -> None:
+        super().__init__(
+            name="terminal",
+            description=(
+                "Execute a shell command and return its combined stdout+stderr output. "
+                "Commands run in the agent's working directory. "
+                "Avoid interactive commands or those that require user input."
+            ),
+            schema=TerminalParams,
+            kind=ToolKind.Execute,
+            render_result=_render_terminal_result,
+            render_call=_render_terminal_call,
+            render_shell="default",
+            prompt_guidelines="Run tests or the build after making code changes to verify correctness.",
+        )
+
+    def get_display_name(self, args: dict[str, Any]) -> str:
+        """Get a short display name for the command."""
+        cmd = args.get("command", "")
+        return cmd[:60] + ("…" if len(cmd) > 60 else "")
+
+    async def execute(
+        self,
+        invocation: ToolInvocation,
+        tool_execution_update_callback: Optional[ToolExecutionUpdateCallback] = None,
+        signal: Optional[AbortSignal] = None,
+        context: Optional[ToolContext] = None,
+    ) -> ToolResult:
+        """Execute a shell command and return the output."""
+        params = TerminalParams.model_validate(invocation.params)
+        cwd = invocation.cwd or None
+
+        sm = context.settings if context is not None else None
+        shell_path = sm.get_shell_path() if sm is not None else None
+        shell_prefix = sm.get_shell_command_prefix() if sm is not None else None
+
+        command = params.command
+        if shell_prefix:
+            command = f"{shell_prefix}\n{command}"
+
+        try:
+            if shell_path:
+                proc = await asyncio.create_subprocess_exec(
+                    shell_path, "-c", command,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.STDOUT,
+                    cwd=cwd,
+                )
+            else:
+                proc = await asyncio.create_subprocess_shell(
+                    command,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.STDOUT,
+                    cwd=cwd,
+                )
+            try:
+                stdout, _ = await asyncio.wait_for(proc.communicate(), timeout=params.timeout)
+            except asyncio.TimeoutError:
+                proc.kill()
+                await proc.communicate()
+                return ToolResult.error(
+                    invocation.id,
+                    f"Command timed out after {params.timeout}s: {params.command}",
+                    metadata={"command": params.command, "exit_code": -1, "timed_out": True, "output_length": 0},
+                )
+        except OSError as e:
+            return ToolResult.error(invocation.id, f"Failed to start command: {e}")
+
+        output = stdout.decode("utf-8", errors="replace")
+        rc = proc.returncode or 0
+        metadata = {
+            "command": params.command,
+            "exit_code": rc,
+            "timed_out": False,
+            "output_length": len(output),
+        }
+
+        if rc != 0:
+            return ToolResult(
+                id=invocation.id,
+                content=output or f"(exit code {rc}, no output)",
+                is_error=True,
+                metadata=metadata,
+            )
+        return ToolResult.ok(invocation.id, output or "(no output)", metadata=metadata)