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

tau/settings/paths.py

@@ -0,0 +1,150 @@
+"""Configuration directory paths for Tau application.
+
+Tau stores all user configuration and session data in ~/.tau/ (global)
+and .tau/ (project-level). This module provides functions to get the
+correct paths for different data types.
+
+Global paths: ~/.tau/
+  - settings.json: user preferences
+  - auth.json: authentication credentials
+  - sessions/: persistent session data
+  - prompts/, tools/, skills/, commands/: custom extensions
+  - themes/: custom UI themes
+  - hooks/: lifecycle hooks
+
+Project paths: .tau/
+  - settings.json: project-specific overrides
+  - extensions/: project-local extensions
+"""
+from pathlib import Path
+
+APP_NAME = "Tau"
+PACKAGE_NAME = "tau-coding-agent"
+CONFIG_DIR_NAME = ".tau"
+
+CONFIG_DIR_PATH = Path.home() / CONFIG_DIR_NAME
+
+
+# ── Centralized app name helper ────────────────────────────────────────────────
+
+def get_app_name() -> str:
+    """Return the application name."""
+    return APP_NAME
+
+
+def get_package_name() -> str:
+    """Return the PyPI distribution package name."""
+    return PACKAGE_NAME
+
+
+def get_app_version() -> str:
+    """Return the installed package version, falling back to '0.1.0'."""
+    try:
+        from importlib.metadata import version
+        return version(get_package_name())
+    except Exception:
+        return "0.1.0"
+
+
+def get_config_dir(cwd: Path | None = None) -> Path:
+    if cwd is not None and cwd.exists():
+        return cwd / CONFIG_DIR_NAME
+    return CONFIG_DIR_PATH
+
+
+# ── User-facing files ────────────────────────────────────────────────────────
+
+def get_settings_path(cwd: Path | None = None) -> Path:
+    return get_config_dir(cwd) / "settings.json"
+
+
+def get_auth_path() -> Path:
+    return CONFIG_DIR_PATH / "auth.json"
+
+
+def get_system_prompt_path(cwd: Path | None = None) -> Path:
+    return get_config_dir(cwd) / "SYSTEM.md"
+
+
+def get_append_system_prompt_path(cwd: Path | None = None) -> Path:
+    return get_config_dir(cwd) / "APPEND_SYSTEM.md"
+
+
+# ── Runtime dirs (all flat under .tau/) ───────────────────────────────────────
+
+def get_sessions_dir() -> Path:
+    return CONFIG_DIR_PATH / "sessions"
+
+
+def get_logs_dir(cwd: Path | None = None) -> Path:
+    "Path to a per-run logs directory, named by the run/session id."
+    return get_config_dir(cwd) / "logs" 
+
+
+def get_themes_dir(cwd: Path | None = None) -> Path:
+    return get_config_dir(cwd) / "themes"
+
+
+def get_extensions_dir(cwd: Path | None = None) -> Path:
+    return get_config_dir(cwd) / "extensions"
+
+
+def get_prompts_dir(cwd: Path | None = None) -> Path:
+    return get_config_dir(cwd) / "prompts"
+
+
+def get_tools_dir(cwd: Path | None = None) -> Path:
+    return get_config_dir(cwd) / "tools"
+
+
+def get_skills_dir(cwd: Path | None = None) -> Path:
+    return get_config_dir(cwd) / "skills"
+
+
+def get_commands_dir(cwd: Path | None = None) -> Path:
+    return get_config_dir(cwd) / "commands"
+
+
+def get_hooks_dir(cwd: Path | None = None) -> Path:
+    return get_config_dir(cwd) / "hooks"
+
+
+def get_temp_dir(cwd: Path | None = None) -> Path:
+    return get_config_dir(cwd) / "temp"
+
+
+def get_packages_venv(cwd: Path | None = None) -> Path:
+    return get_config_dir(cwd) / "venv"
+
+
+def get_builtins_dir() -> Path:
+    return Path(__file__).parent.parent / "builtins"
+
+
+def get_docs_dir() -> Path:
+    """Get the docs directory path.
+
+    Works both when tau is installed via pip and when running from source.
+    """
+    try:
+        from importlib.resources import files
+        docs_ref = files("tau").joinpath("docs")
+        return Path(str(docs_ref))
+    except (TypeError, ModuleNotFoundError, AttributeError):
+        package_root = Path(__file__).parent.parent.parent
+        return package_root / "docs"
+
+
+def get_readme_path() -> Path:
+    """Get the README.md path.
+
+    Works both when tau is installed via pip and when running from source.
+    """
+    try:
+        from importlib.resources import files
+        readme_ref = files("tau").joinpath("README.md")
+        return Path(str(readme_ref))
+    except (TypeError, ModuleNotFoundError, AttributeError):
+        package_root = Path(__file__).parent.parent.parent
+        return package_root / "README.md"
+

tau/settings/storage.py

@@ -0,0 +1,63 @@
+from __future__ import annotations  
+from tau.settings.paths import get_settings_path
+from tau.settings.types import LockResult, SCOPE
+from abc import ABC, abstractmethod 
+from typing import Callable
+from filelock import FileLock  
+from pathlib import Path  
+  
+
+class SettingsStorage(ABC):  
+    """Abstract storage backend for settings."""  
+      
+    @abstractmethod  
+    def with_lock(self, scope: SCOPE, fn: Callable[[str | None], LockResult]) -> LockResult:  
+        """Execute fn with locked access to the storage."""  
+        pass  
+  
+class FileSettingsStorage(SettingsStorage):
+    """File-based storage backend with locking."""
+
+    def __init__(self, cwd: Path, config_dir: Path | None = None):
+        self.global_settings_path = (
+            config_dir / "settings.json" if config_dir else get_settings_path()
+        )
+        self.project_settings_path = get_settings_path(cwd)
+        self._ensure_parent_dir(self.global_settings_path)
+      
+    def _ensure_parent_dir(self, path: Path) -> None:  
+        path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+      
+    def _ensure_file_exists(self, path: Path) -> None:  
+        if not path.exists():  
+            path.write_text("{}", encoding="utf-8")  
+            path.chmod(0o600)  
+      
+    def with_lock(self, scope: SCOPE, fn: Callable[[str | None], LockResult]) -> LockResult:  
+        path = self.global_settings_path if scope == SCOPE.GLOBAL else self.project_settings_path  
+        lock_path = path.with_suffix(".lock")  
+          
+        with FileLock(lock_path):  
+            self._ensure_file_exists(path)  
+            current = path.read_text(encoding="utf-8") if path.exists() else "{}"  
+            result = fn(current)  
+            if result.next is not None:  
+                path.write_text(result.next, encoding="utf-8")  
+            return result  
+  
+class InMemorySettingsStorage(SettingsStorage):  
+    """In-memory storage backend for testing."""  
+      
+    def __init__(self):  
+        self.global_data: str = "{}"  
+        self.project_data: str = "{}"  
+      
+    def with_lock(self, scope: SCOPE, fn: Callable[[str | None], LockResult]) -> LockResult:  
+        current = self.global_data if scope == SCOPE.GLOBAL else self.project_data  
+        result = fn(current)  
+        if result.next is not None:  
+            if scope == SCOPE.GLOBAL:  
+                self.global_data = result.next  
+            else:  
+                self.project_data = result.next  
+        return result

tau/settings/types.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional, Literal, Any
+from tau.engine.types import SteeringMode, FollowupMode
+from tau.inference.types import Transport, ThinkingLevel
+
+
+class SCOPE(str, Enum):
+    GLOBAL = "global"
+    PROJECT = "project"
+
+
+@dataclass
+class LockResult:
+    result: Any
+    next: str | None = None
+
+
+@dataclass
+class SettingsError:
+    scope: SCOPE
+    error: Exception
+
+
+@dataclass
+class ProviderRetrySettings:
+    timeout_ms: Optional[int] = None
+    max_retries: Optional[int] = None
+    max_retry_delay_ms: Optional[int] = None
+
+
+@dataclass
+class RetrySettings:
+    enabled: Optional[bool] = None
+    max_retries: Optional[int] = None
+    base_delay_ms: Optional[int] = None
+    provider: Optional[ProviderRetrySettings] = None
+
+
+@dataclass
+class ThinkingBudgetsSettings:
+    minimal: Optional[int] = None
+    low: Optional[int] = None
+    medium: Optional[int] = None
+    high: Optional[int] = None
+    xhigh: Optional[int] = None
+    max: Optional[int] = None
+
+
+@dataclass
+class ImageSettings:
+    auto_resize: Optional[bool] = None    # resize images to 2000×2000 max before sending to LLM (default: True)
+    block_images: Optional[bool] = None   # prevent all images from being sent to the LLM (default: False)
+
+
+@dataclass
+class CompactionSettings:
+    enabled: Optional[bool] = None              # enable auto-compaction (default: True)
+    reserve_tokens: Optional[int] = None        # tokens reserved for LLM response (default: 16384)
+    keep_recent_tokens: Optional[int] = None    # recent tokens to keep verbatim (default: 20000)
+
+
+@dataclass
+class BranchSummarySettings:
+    enabled: Optional[bool] = None        # enable branch summarization (default: True)
+    skip_prompt: Optional[bool] = None    # always skip the "Summarize branch?" prompt (default: False)
+    reserve_tokens: Optional[int] = None  # tokens to reserve when summarizing (default: 16384)
+
+
+@dataclass
+class ExtensionEntry:
+    """Per-extension config entry stored in the ``extensions.list`` settings block."""
+    path: str
+    name: Optional[str] = None
+    enabled: bool = True
+    source: Optional[str] = None
+    author: Optional[str] = None
+    settings: Optional[dict] = field(default=None)
+
+
+@dataclass
+class ExtensionsSettings:
+    """Global extension toggle plus per-extension configuration list."""
+    enabled: Optional[bool] = None          # global on/off for all extensions
+    list: Optional[list[ExtensionEntry]] = None
+
+
+@dataclass
+class PackageEntry:
+    """A package installed via pip/uv/poetry into the tau-managed venv."""
+    source: str                             # "pypi:name@1.0", "git+https://...", "/local/path"
+    name: str                               # package name (normalised)
+    version: Optional[str] = None           # installed version, if known
+    installed_path: Optional[str] = None    # path to package dir inside the venv
+    enabled: bool = True
+
+
+@dataclass
+class PackagesSettings:
+    """Installed package list stored in settings."""
+    list: Optional[list[PackageEntry]] = None
+
+
+@dataclass
+class TerminalSettings:
+    shell_path: Optional[str] = None             # custom shell binary (default: system shell)
+    shell_command_prefix: Optional[str] = None   # lines prepended inside the shell before each command
+
+
+@dataclass
+class HTTPProxySettings:
+    url: Optional[str] = None                           # Proxy URL for both HTTP and HTTPS (overrides env vars)
+    no_proxy: Optional[str] = None                      # Comma-separated hosts to exclude from proxying
+    headers: Optional[dict[str, str]] = None            # Custom headers for proxy (e.g., authentication)
+
+
+@dataclass
+class Settings:
+    # Model / provider
+    provider: Optional[str] = None
+    model: Optional[str] = None
+    thinking_level: Optional[ThinkingLevel] = None
+    transport: Optional[Transport] = None
+    enabled_models: Optional[list[str]] = None
+
+    # UI
+    theme: Optional[str] = None
+    show_thinking: Optional[bool] = None
+    show_tool_calls: Optional[bool] = None
+    show_images: Optional[bool] = None
+    picker_max_visible: Optional[int] = None
+
+    # Queue behaviour
+    steering_mode: Optional[SteeringMode] = None
+    follow_up_mode: Optional[FollowupMode] = None
+
+    # Nested sub-settings
+    retry: Optional[RetrySettings] = None
+    thinking_budgets: Optional[ThinkingBudgetsSettings] = None
+    image: Optional[ImageSettings] = None
+    compaction: Optional[CompactionSettings] = None
+    branch_summary: Optional[BranchSummarySettings] = None
+
+    # Execution
+    terminal: Optional[TerminalSettings] = None
+
+    # Network
+    http_idle_timeout_ms: Optional[int] = None  # idle timeout for LLM HTTP streams (default: 60000)
+    websocket_connect_timeout_ms: Optional[int] = None  # WebSocket connect/open handshake timeout
+    http_proxy: Optional[HTTPProxySettings] = None  # HTTP proxy configuration (overrides env vars)
+
+    # Project trust (global only)
+    project_trust: Optional[Literal["ask", "always", "never"]] = None  # default: "ask" — controls loading of project files (.tau/ config, extensions), project context files (AGENTS.md/CLAUDE.md), and project skills
+
+    # Session
+    session_dir: Optional[str] = None
+
+    # Startup
+    quiet_startup: Optional[bool] = None  # suppress startup notices (default: False)
+
+    # UI behaviour
+    double_escape_action: Optional[Literal["fork", "tree", "none"]] = None  # action on double-Escape with empty editor (default: "fork")
+    tree_filter_mode: Optional[Literal["default", "no-tools", "user-only", "labeled-only", "all"]] = None  # default /tree filter mode
+    autocomplete_max_visible: Optional[int] = None  # max items in autocomplete dropdown (default: 5)
+    show_hardware_cursor: Optional[bool] = None  # show terminal cursor while positioning (IME support, default: False)
+    editor_padding_x: Optional[int] = None  # horizontal padding for the input editor (default: 0)
+
+    # Extensions
+    extensions: Optional[ExtensionsSettings] = None
+
+    # Packages
+    packages: Optional[PackagesSettings] = None

tau/settings/utils.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def set_nested(d: dict, key: str, value: Any) -> None:
+    """Set ``value`` at a dot-separated ``key`` path inside dict ``d``, creating intermediate dicts."""
+    parts = key.split(".", 1)
+    if len(parts) == 1:
+        d[key] = value
+    else:
+        head, rest = parts
+        if not isinstance(d.get(head), dict):
+            d[head] = {}
+        set_nested(d[head], rest, value)
+
+
+def coerce_enum(enum_cls: type, value: Any) -> Any:
+    """Coerce a raw value into ``enum_cls``; return None on failure (treated as unset)."""
+    if value is None or isinstance(value, enum_cls):
+        return value
+    try:
+        return enum_cls(value)
+    except (ValueError, KeyError):
+        return None

tau/skills/loader.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from tau.skills.types import LoadSkillsResult, Skill, SkillLoadError
+
+
+def _parse_frontmatter(text: str) -> tuple[dict[str, str], str]:
+    """Parse YAML frontmatter from skill markdown text."""
+    text = text.lstrip("\n")
+    if not text.startswith("---"):
+        return {}, text
+    end = text.find("\n---", 3)
+    if end == -1:
+        return {}, text
+    fm_text = text[3:end].strip()
+    body = text[end + 4:].lstrip("\n")
+    meta: dict[str, str] = {}
+    for line in fm_text.splitlines():
+        if ":" in line:
+            key, _, val = line.partition(":")
+            meta[key.strip().lower()] = val.strip()
+    return meta, body
+
+
+def load_skill_from_file(path: Path, name_hint: str | None = None) -> tuple[Skill | None, str | None]:
+    """Load a skill from a markdown file."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except Exception as exc:
+        return None, f"read error: {exc}"
+
+    meta, body = _parse_frontmatter(text)
+    body = body.strip()
+    if not body:
+        return None, "skill body is empty"
+
+    name = meta.get("name") or name_hint or path.stem.lower()
+    description = meta.get("description", "")
+    if not description:
+        return None, "missing 'description' field"
+
+    disable = meta.get("disable-model-invocation", "").lower() in ("true", "1", "yes")
+
+    return Skill(
+        name=name.lower(),
+        description=description,
+        content=body,
+        file_path=str(path),
+        base_dir=str(path.parent),
+        disable_model_invocation=disable,
+    ), None
+
+
+def load_skills_from_dir(directory: Path) -> LoadSkillsResult:
+    """
+    Scan a directory for skills.
+
+    Rules:
+      - If a subdir contains SKILL.md  → load it as one skill (name = dirname)
+      - If a .md file sits at the root → load it as one skill (name = stem)
+      - Recurse into subdirs that don't have SKILL.md to find nested skill dirs
+    """
+    result = LoadSkillsResult()
+    if not directory.is_dir():
+        return result
+
+    def _scan(d: Path) -> None:
+        skill_md = d / "SKILL.md"
+        if skill_md.is_file():
+            skill, err = load_skill_from_file(skill_md, name_hint=d.name.lower())
+            if err or skill is None:
+                result.errors.append(SkillLoadError(str(skill_md), err or "unknown"))
+            else:
+                result.skills[skill.name] = skill
+            return
+
+        if d == directory:
+            for path in sorted(d.glob("*.md")):
+                skill, err = load_skill_from_file(path)
+                if err or skill is None:
+                    result.errors.append(SkillLoadError(str(path), err or "unknown"))
+                else:
+                    result.skills[skill.name] = skill
+
+        for sub in sorted(d.iterdir()):
+            if sub.is_dir():
+                _scan(sub)
+
+    _scan(directory)
+    return result

tau/skills/registry.py

@@ -0,0 +1,70 @@
+"""
+Skill registry.
+
+Priority (highest wins):
+    project  (.tau/skills/ relative to cwd)
+    global   (~/.tau/skills/)
+    builtin  (tau/builtins/skills/)
+
+Skills are listed in the system prompt as <available_skills> XML so the model
+can load them on demand via the read tool, or invoked explicitly with
+/skill:name [args].
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, List
+
+from tau.core.registry import Registry
+from tau.skills.types import Skill, SkillLoadError
+from tau.skills.loader import load_skills_from_dir
+
+
+class SkillRegistry(Registry[Skill, SkillLoadError]):
+    def _load_from_dir(self, path: Path) -> Any:
+        return load_skills_from_dir(path)
+
+    def _get_dir(self, cwd: Path | None = None) -> Path:
+        from tau.settings.paths import get_skills_dir
+        return get_skills_dir(cwd)
+
+    def _builtins_subdir(self) -> str:
+        return "skills"
+
+    def _extract_items(self, result: Any) -> dict[str, Skill]:
+        return result.skills
+
+    def _extract_errors(self, result: Any) -> list[SkillLoadError]:
+        return result.errors
+
+    def list(self) -> list[Skill]:
+        """Return all skills available to the model (excluding disabled ones)."""
+        self._ensure_builtins()
+        return [s for s in self._registry.values() if not s.disable_model_invocation]
+
+    def list_all(self) -> List[Skill]:
+        """Return all registered skills, including disabled ones."""
+        self._ensure_builtins()
+        return list(self._registry.values())
+
+    def format_for_system_prompt(self, skills: List[Skill]) -> str:
+        """Format a skill list as XML for inclusion in the system prompt."""
+        if not skills:
+            return ""
+        visible = [s for s in skills if not s.disable_model_invocation]
+        if not visible:
+            return ""
+        lines = ["<available_skills>"]
+        for s in visible:
+            lines.append("  <skill>")
+            lines.append(f"    <name>{s.name}</name>")
+            lines.append(f"    <description>{s.description}</description>")
+            lines.append(f"    <location>{s.file_path}</location>")
+            lines.append("  </skill>")
+        lines.append("</available_skills>")
+        lines.append("")
+        lines.append("When a task matches a skill's description, use the read tool to load the skill file and follow its instructions.")
+        return "\n".join(lines)
+
+
+skill_registry = SkillRegistry()

tau/skills/types.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Skill:
+    name: str
+    description: str
+    content: str
+    file_path: str
+    base_dir: str
+    disable_model_invocation: bool = False
+
+
+@dataclass
+class SkillLoadError:
+    path: str
+    error: str
+
+
+@dataclass
+class LoadSkillsResult:
+    skills: dict[str, Skill] = field(default_factory=dict)
+    errors: list[SkillLoadError] = field(default_factory=list)