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

tau/tool/types.py

@@ -0,0 +1,244 @@
+from __future__ import annotations
+import asyncio
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Optional, Type
+from pydantic import BaseModel
+from pathlib import Path
+
+if TYPE_CHECKING:
+    from tau.inference.api.text.service import TextLLM as LLM
+    from tau.settings.manager import SettingsManager
+
+@dataclass
+class ToolError:
+    """File-level tool load failure with optional stack trace."""
+    path: str
+    error: str
+    stack: str = ''
+
+
+@dataclass
+class LoadToolResults:
+    """Aggregate result of loading tools from one or more directories."""
+
+    tools: list[Tool] = field(default_factory=list)
+    errors: list[ToolError] = field(default_factory=list)
+
+
+class ToolKind(str, Enum):
+    """Semantic category used by the engine to apply execution policy to a tool call."""
+
+    Read = "read"
+    Edit = "edit"
+    Write = "write"
+    Execute = "execute"
+    Web = "web"
+
+
+class ToolExecutionMode(str, Enum):
+    """Controls how the engine schedules concurrent calls to the same tool."""
+
+    Sequential = "sequential"
+    Parallel = "parallel"
+    Batch = "batch"
+
+
+@dataclass
+class ToolInvocation:
+    """Complete tool call specification with resolved args and execution context."""
+    id: str
+    name: str
+    cwd: Path | None
+    params: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ToolResult:
+    """Tool execution outcome with optional error flag and early termination signal."""
+    id: str
+    content: str
+    is_error: bool = False
+    metadata: dict[str, Any] = field(default_factory=dict)
+    terminate: bool = False
+    terminate_message: str | None = None
+
+    @classmethod
+    def ok(
+        cls,
+        id: str,
+        content: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> ToolResult:
+        """Construct a successful outcome.
+
+        Args:
+            id: The tool call ID this result corresponds to.
+            content: The result content (output of the tool).
+            metadata: Optional metadata dict (default empty).
+
+        Returns:
+            A ToolResult with is_error=False.
+        """
+        return cls(id=id, content=content, is_error=False, metadata=metadata or {})
+
+    @classmethod
+    def error(
+        cls,
+        id: str,
+        content: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> ToolResult:
+        """Construct a failed outcome.
+
+        Args:
+            id: The tool call ID this result corresponds to.
+            content: The error message or description.
+            metadata: Optional metadata dict (default empty).
+
+        Returns:
+            A ToolResult with is_error=True.
+        """
+        return cls(id=id, content=content, is_error=True, metadata=metadata or {})
+
+ToolExecutionUpdateCallback = Callable[[ToolResult], Awaitable[None]]
+
+AbortSignal = asyncio.Event
+
+
+@dataclass
+class ToolContext:
+    """Runtime services available to tools during execution (LLM, agents, managers, etc)."""
+    llm: LLM | None = None
+    cwd: Path | None = None
+    settings: SettingsManager | None = None
+
+
+@dataclass
+class ToolRenderOptions:
+    """Render-time flags passed to render_result callbacks.
+
+    is_error:   True when the tool call returned an error.
+    expanded:   True when the user has toggled tool results open (Ctrl+O).
+    is_partial: True while the tool is still executing (streaming output).
+    metadata:   Arbitrary data the tool stored in ToolResult.metadata.
+    """
+    is_error: bool = False
+    expanded: bool = False
+    is_partial: bool = False
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+
+
+class Tool(ABC):
+    """Abstract base for tools: executable, schema-validated components with metadata and policy."""
+
+    # Explicit class-level annotations so Pyright infers the correct attribute
+    # types at every call site without relying on __init__ parameter inference.
+    render_call: Optional[Callable[[dict, bool], list[str]]]
+    render_result: Optional[Callable[[str, "ToolRenderOptions"], list[str]]]
+    render_shell: str
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        schema: Type[BaseModel],
+        kind: ToolKind,
+        execution_mode: ToolExecutionMode = ToolExecutionMode.Sequential,
+        *,
+        render_call: Optional[Callable[[dict, bool], list[str]]] = None,
+        render_result: Optional[Callable[[str, "ToolRenderOptions"], list[str]]] = None,
+        render_shell: str = "self",
+        prompt_snippet: Optional[str] = None,
+        prompt_guidelines: Optional[str] = None,
+        prepare_arguments: Optional[Callable[[dict], dict]] = None,
+    ) -> None:
+        """Initialize tool with name, description, schema, kind, and execution concurrency policy.
+
+        render_shell controls how the result block is framed in the TUI:
+          "self"    (default) — renderer output is used as-is, no extra framing.
+          "default" — the standard ``└ first_line`` shell is applied to the
+                      renderer output so it matches the built-in tool style.
+        """
+        self.name = name
+        self.description = description
+        self.schema = schema
+        self.kind = kind
+        self.execution_mode = execution_mode
+        self.render_call = render_call
+        self.render_result = render_result
+        self.render_shell = render_shell
+        self.prompt_snippet = prompt_snippet
+        self.prompt_guidelines = prompt_guidelines
+        self.prepare_arguments = prepare_arguments
+
+    def validate(self, params: dict[str, Any]) -> tuple[bool, list[str]]:
+        """Validate params against schema; return (success, error_list).
+
+        Args:
+            params: Tool call parameters to validate.
+
+        Returns:
+            A tuple of (success: bool, errors: list[str]).
+        """
+        try:
+            self.schema.model_validate(params)
+            return True, []
+        except Exception as e:
+            from pydantic import ValidationError
+            # Format Pydantic errors with field path for clarity
+            if isinstance(e, ValidationError):
+                errors = [
+                    f"{' -> '.join(str(loc) for loc in err['loc'])}: {err['msg']}"
+                    for err in e.errors()
+                ]
+            else:
+                errors = [str(e)]
+            return False, errors
+
+    def to_json(self) -> dict[str, Any]:
+        """Serialize to JSON schema with name, description, and input_schema.
+
+        Returns:
+            A dict with 'name', 'description', and 'input_schema' keys suitable for provider APIs.
+        """
+        return {
+            "name": self.name,
+            "description": self.description,
+            "input_schema": self.schema.model_json_schema(),
+        }
+
+    def _is_cancelled(self, signal: Optional[AbortSignal]) -> bool:
+        """Check if abort signal has been set.
+
+        Args:
+            signal: Optional asyncio.Event abort signal.
+
+        Returns:
+            True if the signal has been set, indicating cancellation requested.
+        """
+        return signal is not None and signal.is_set()
+
+    @abstractmethod
+    async def execute(
+        self,
+        invocation: ToolInvocation,
+        tool_execution_update_callback: Optional[ToolExecutionUpdateCallback] = None,
+        signal: Optional[AbortSignal] = None,
+        context: Optional[ToolContext] = None,
+    ) -> ToolResult:
+        """Execute the tool with params; subclasses must override.
+
+        Args:
+            invocation: Complete tool call specification with resolved parameters.
+            tool_execution_update_callback: Optional callback for streaming updates.
+            signal: Optional abort signal to check for user-initiated cancellation.
+            context: Optional ToolContext with runtime services available to the tool.
+
+        Returns:
+            A ToolResult with the outcome, content, and optional error details.
+        """
+        ...

tau/trust/__init__.py

@@ -0,0 +1,13 @@
+from tau.trust.types import TrustOption
+from tau.trust.utils import has_project_trust_inputs, get_trust_options, normalize, find_nearest
+from tau.trust.manager import TrustStore, trust_store
+
+__all__ = [
+    "TrustOption",
+    "TrustStore",
+    "trust_store",
+    "has_project_trust_inputs",
+    "get_trust_options",
+    "normalize",
+    "find_nearest",
+]

tau/trust/manager.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from tau.settings.paths import CONFIG_DIR_PATH
+from tau.trust.types import TrustOption
+from tau.trust.utils import normalize, find_nearest, has_project_trust_inputs, get_trust_options
+
+
+class TrustStore:
+    """Persists per-directory trust decisions in ``~/.tau/trust.json``.
+
+    Trust walks up the directory tree — trusting a parent directory implicitly
+    trusts all child directories beneath it.
+    """
+
+    def __init__(self, config_dir: Path | None = None) -> None:
+        base = config_dir or CONFIG_DIR_PATH
+        self._path = base / "trust.json"
+
+    # ── Read ──────────────────────────────────────────────────────────────────
+
+    def _read(self) -> dict[str, bool | None]:
+        try:
+            return json.loads(self._path.read_text(encoding="utf-8"))
+        except (FileNotFoundError, json.JSONDecodeError):
+            return {}
+
+    def get(self, cwd: str | Path) -> bool | None:
+        """Return the stored trust decision, or ``None`` if no decision exists."""
+        data = self._read()
+        entry = find_nearest(data, normalize(cwd))
+        return entry[1] if entry is not None else None
+
+    def get_stored_path(self, cwd: str | Path) -> str | None:
+        """Return the directory path that holds the nearest trust decision, or ``None``."""
+        data = self._read()
+        entry = find_nearest(data, normalize(cwd))
+        return entry[0] if entry is not None else None
+
+    # ── Write ─────────────────────────────────────────────────────────────────
+
+    def _write(self, data: dict[str, bool | None]) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        clean = {k: v for k, v in data.items() if v is not None}
+        self._path.write_text(json.dumps(clean, indent=2, sort_keys=True), encoding="utf-8")
+
+    def set(self, cwd: str | Path, decision: bool | None) -> None:
+        """Store a trust decision for *cwd*. Pass ``None`` to remove the entry."""
+        data = self._read()
+        key = normalize(cwd)
+        if decision is None:
+            data.pop(key, None)
+        else:
+            data[key] = decision
+        self._write(data)
+
+    def apply_option(self, option: TrustOption) -> None:
+        """Persist a :class:`TrustOption`. ``save_path=None`` means session-only — nothing is written."""
+        if option.save_path is None:
+            return
+        data = self._read()
+        data[normalize(option.save_path)] = option.trusted
+        if option.clear_child_path is not None:
+            data.pop(normalize(option.clear_child_path), None)
+        self._write(data)
+
+
+# ── Module-level singleton ────────────────────────────────────────────────────
+
+trust_store = TrustStore()
+
+__all__ = [
+    "TrustStore",
+    "TrustOption",
+    "trust_store",
+    "has_project_trust_inputs",
+    "get_trust_options",
+]

tau/trust/types.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class TrustOption:
+    """A single choice presented to the user in the trust prompt."""
+    label: str
+    trusted: bool
+    # Absolute path to persist; None means session-only (no disk write)
+    save_path: str | None = None
+    # When saving a parent path, also remove this child path from the store
+    clear_child_path: str | None = None

tau/trust/utils.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from tau.settings.paths import CONFIG_DIR_NAME
+from tau.trust.types import TrustOption
+
+
+def normalize(cwd: str | Path) -> str:
+    """Resolve *cwd* to an absolute POSIX string."""
+    return str(Path(cwd).resolve())
+
+
+def find_nearest(data: dict[str, bool | None], cwd: str) -> tuple[str, bool] | None:
+    """Walk up from *cwd* and return ``(path, decision)`` for the closest stored entry."""
+    current = normalize(cwd)
+    while True:
+        val = data.get(current)
+        if val is True:
+            return current, True
+        if val is False:
+            return current, False
+        parent = str(Path(current).parent)
+        if parent == current:
+            return None
+        current = parent
+
+
+def has_project_trust_inputs(cwd: str | Path) -> bool:
+    """Return ``True`` if *cwd* (or any ancestor) contains files that require a trust decision.
+
+    Specifically looks for:
+    - A ``.tau/`` local config directory
+    - A ``.agents/skills/`` directory (shared-skill convention)
+    """
+    current = Path(normalize(cwd))
+    while True:
+        if (current / CONFIG_DIR_NAME).exists():
+            return True
+        if (current / ".agents" / "skills").exists():
+            return True
+        parent = current.parent
+        if parent == current:
+            return False
+        current = parent
+
+
+def get_trust_options(cwd: str | Path, *, session_only: bool = True) -> list[TrustOption]:
+    """Build the ordered list of trust choices to present to the user.
+
+    Args:
+        cwd: Project working directory.
+        session_only: Include a "Trust (this session only)" option that does not
+            persist the decision to disk.
+    """
+    resolved = normalize(cwd)
+    parent = str(Path(resolved).parent)
+
+    options: list[TrustOption] = [
+        TrustOption(label="Trust", trusted=True, save_path=resolved),
+    ]
+    if parent != resolved:
+        options.append(TrustOption(
+            label=f"Trust parent folder ({parent})",
+            trusted=True,
+            save_path=parent,
+            clear_child_path=resolved,
+        ))
+    if session_only:
+        options.append(TrustOption(label="Trust (this session only)", trusted=True, save_path=None))
+    options.append(TrustOption(label="Do not trust", trusted=False, save_path=resolved))
+    return options

tau/tui/__init__.py

@@ -0,0 +1,54 @@
+# Public API — import from here instead of individual submodules.
+#
+#   Theme types:   from tau.tui import LayoutTheme, SpinnerTheme, MessageTheme
+#   Keybindings:   from tau.tui import configure_keybindings, get_keybindings
+#   Components:    from tau.tui import SelectList, SelectItem, Box
+#
+#   Themes:        from tau.themes.registry import theme_registry
+
+from tau.tui.theme import (
+    ColorFn,
+    LayoutTheme,
+    SpinnerTheme,
+    MarkdownTheme,
+    MessageTheme,
+    InputTheme,
+    SelectListTheme,
+    color,
+    rgb,
+    rgb_bold,
+    rgb_italic,
+)
+from tau.tui.keybindings import (
+    KeyMap,
+    KeybindingsManager,
+    get_keybindings,
+    configure_keybindings,
+)
+from tau.tui.components.select_list import SelectList, SelectItem
+from tau.tui.components.box import Box
+
+__all__ = [
+    # Theme types
+    "ColorFn",
+    "LayoutTheme",
+    "SpinnerTheme",
+    "MarkdownTheme",
+    "MessageTheme",
+    "InputTheme",
+    "SelectListTheme",
+    # Keybindings
+    "KeyMap",
+    "KeybindingsManager",
+    "get_keybindings",
+    "configure_keybindings",
+    # Color-function builders
+    "color",
+    "rgb",
+    "rgb_bold",
+    "rgb_italic",
+    # Components
+    "SelectList",
+    "SelectItem",
+    "Box",
+]