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

vtx/tools/skill.py

@@ -0,0 +1,278 @@
+import asyncio
+import os
+import shutil
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from ..context.skills import (
+    get_config_dir,
+    load_builtin_cmd_skills,
+    load_skills,
+    merge_registered_skills,
+)
+from .base import BaseTool, ToolResult
+
+
+class SkillParams(BaseModel):
+    action: Literal["list", "view", "create", "patch", "edit", "delete"] = Field(
+        description=(
+            "The action to perform: list (shows all loaded skills), "
+            "view (reads full instructions), create (creates new), "
+            "patch (find-and-replace), edit (overwrites file), "
+            "delete (deletes skill folder)."
+        ),
+        default="view",
+    )
+    name: str | None = Field(
+        description=(
+            "Name of the skill (lowercase, alphanumeric, and hyphens only). "
+            "Required for all actions except 'list'."
+        ),
+        default=None,
+    )
+    content: str | None = Field(
+        description=(
+            "Full SKILL.md content (YAML frontmatter + markdown body). "
+            "Required for 'create' and 'edit'."
+        ),
+        default=None,
+    )
+    old_string: str | None = Field(
+        description="Text to search for (required for 'patch'). Must be a unique match.",
+        default=None,
+    )
+    new_string: str | None = Field(
+        description="Replacement text (required for 'patch').", default=None
+    )
+    file_path: str | None = Field(
+        description=(
+            "Relative path of a supporting file to target (e.g., 'templates/prompt.md'). "
+            "Defaults to 'SKILL.md' if omitted."
+        ),
+        default=None,
+    )
+    scope: Literal["project", "global"] = Field(
+        description=(
+            "For 'create': whether to create project-level skill in "
+            ".agents/skills/ (default) or user-global skill in ~/.agents/skills/."
+        ),
+        default="project",
+    )
+
+
+class SkillTool(BaseTool):
+    name = "skill"
+    tool_icon = "⚙"
+    params = SkillParams
+    mutating = True  # Can modify skills, though list/view are read-only
+    prompt_guidelines = (
+        "Use skill to list, view, create, patch, edit, or delete skill workflows.",
+    )
+    description = (
+        "Manage or view the AI's skills. Actions: list, view, create, patch, edit, delete. "
+        "Allows progressive loading, targeting specific parts of instructions, or self-evolution."
+    )
+
+    def format_call(self, params: SkillParams) -> str:
+        name_str = f" name={params.name}" if params.name else ""
+        file_str = f" file={params.file_path}" if params.file_path else ""
+        return f"{params.action}{name_str}{file_str}"
+
+    async def execute(
+        self, params: SkillParams, cancel_event: asyncio.Event | None = None
+    ) -> ToolResult:
+        cwd = os.getcwd()
+
+        # Handle 'list' action
+        if params.action == "list":
+            result = load_skills(cwd)
+            builtin = load_builtin_cmd_skills()
+            all_skills = merge_registered_skills(result.skills, builtin.skills)
+            lines = ["Available skills:"]
+            for skill in sorted(all_skills, key=lambda s: s.name):
+                path_str = str(skill.path)
+                if skill.bundled:
+                    scope = "bundled"
+                elif "skills" in path_str and ("~" in path_str or "/.agents/" not in path_str):
+                    scope = "global"
+                else:
+                    scope = "project"
+                lines.append(f"- {skill.name} [{scope}]: {skill.description}")
+            result_text = "\n".join(lines)
+            return ToolResult(
+                success=True,
+                result=result_text,
+                ui_summary=f"[dim]({len(all_skills)} skills)[/dim]",
+            )
+
+        if not params.name:
+            msg = "Parameter 'name' is required for this action."
+            return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+
+        # Helper to find skill directory
+        def find_skill_dir(name: str) -> tuple[Path | None, bool]:
+            # 1. Project skills
+            from ..context.skills import _project_skill_dirs
+
+            project_dirs = _project_skill_dirs(Path(cwd))
+            for skills_dir in project_dirs:
+                if skills_dir.exists():
+                    skill_dir = skills_dir / name
+                    if (skill_dir / "SKILL.md").is_file():
+                        return skill_dir, False
+
+            # 2. User global skills
+            user_skills_dir = (get_config_dir() / "skills").resolve(strict=False)
+            skill_dir = user_skills_dir / name
+            if (skill_dir / "SKILL.md").is_file():
+                return skill_dir, False
+
+            # 3. Builtin skills
+            from importlib import resources
+
+            try:
+                builtin_resource = resources.files("vtx").joinpath("builtin_skills")
+                with resources.as_file(builtin_resource) as builtin_root:
+                    skill_dir = builtin_root / name
+                    if (skill_dir / "SKILL.md").is_file():
+                        return skill_dir, True
+            except Exception:
+                pass
+
+            return None, False
+
+        skill_dir, is_builtin = find_skill_dir(params.name)
+
+        # Handle 'view' action
+        if params.action == "view":
+            if not skill_dir:
+                msg = f"Skill '{params.name}' not found."
+                return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+
+            target_file = params.file_path or "SKILL.md"
+            target_path = skill_dir / target_file
+            try:
+                content = target_path.read_text(encoding="utf-8")
+                return ToolResult(
+                    success=True,
+                    result=content,
+                    ui_summary=f"[dim]({len(content.splitlines())} lines)[/dim]",
+                )
+            except Exception as e:
+                msg = f"Failed to read skill file: {e}"
+                return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+
+        # Mutating actions: 'create', 'edit', 'patch', 'delete'
+        if is_builtin:
+            msg = f"Cannot modify built-in skill '{params.name}'."
+            return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+
+        # Handle 'create' action
+        if params.action == "create":
+            if not params.content:
+                msg = "Parameter 'content' is required to create a skill."
+                return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+
+            # Validate name format
+            if not params.name.islower() or not params.name.replace("-", "").isalnum():
+                msg = "Skill name must be lowercase, alphanumeric, and hyphens only."
+                return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+
+            # Resolve target path based on scope
+            if params.scope == "global":
+                target_skills_dir = (get_config_dir() / "skills").resolve(strict=False)
+            else:
+                target_skills_dir = Path(cwd) / ".agents" / "skills"
+
+            new_skill_dir = target_skills_dir / params.name
+            new_skill_dir.mkdir(parents=True, exist_ok=True)
+            skill_md_path = new_skill_dir / "SKILL.md"
+
+            try:
+                skill_md_path.write_text(params.content, encoding="utf-8")
+                return ToolResult(
+                    success=True,
+                    result=f"Skill '{params.name}' created at {skill_md_path}.",
+                    ui_summary=f"Created '{params.name}'",
+                )
+            except Exception as e:
+                msg = f"Failed to create skill: {e}"
+                return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+
+        # For edit, patch, delete, we need the skill to exist
+        if not skill_dir:
+            msg = f"Skill '{params.name}' not found."
+            return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+
+        # Handle 'delete' action
+        if params.action == "delete":
+            try:
+                shutil.rmtree(skill_dir)
+                return ToolResult(
+                    success=True,
+                    result=f"Skill '{params.name}' deleted.",
+                    ui_summary=f"Deleted '{params.name}'",
+                )
+            except Exception as e:
+                msg = f"Failed to delete skill: {e}"
+                return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+
+        target_file = params.file_path or "SKILL.md"
+        target_path = skill_dir / target_file
+
+        # Handle 'edit' action
+        if params.action == "edit":
+            if not params.content:
+                msg = "Parameter 'content' is required for edit."
+                return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+
+            try:
+                target_path.parent.mkdir(parents=True, exist_ok=True)
+                target_path.write_text(params.content, encoding="utf-8")
+                return ToolResult(
+                    success=True,
+                    result=f"Skill '{params.name}' updated at {target_file}.",
+                    ui_summary=f"Edited {target_file}",
+                )
+            except Exception as e:
+                msg = f"Failed to edit skill: {e}"
+                return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+
+        # Handle 'patch' action
+        if params.action == "patch":
+            if params.old_string is None or params.new_string is None:
+                msg = "Parameters 'old_string' and 'new_string' are required for patch."
+                return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+
+            if not target_path.is_file():
+                msg = f"File {target_file} not found in skill '{params.name}'."
+                return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+
+            try:
+                content = target_path.read_text(encoding="utf-8")
+                count = content.count(params.old_string)
+                if count == 0:
+                    msg = f"Target string 'old_string' not found in {target_file}."
+                    return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+                if count > 1:
+                    msg = (
+                        f"Target string 'old_string' is not unique in {target_file} "
+                        f"(found {count} occurrences)."
+                    )
+                    return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+
+                new_content = content.replace(params.old_string, params.new_string)
+                target_path.write_text(new_content, encoding="utf-8")
+                return ToolResult(
+                    success=True,
+                    result=f"Successfully patched {target_file} in skill '{params.name}'.",
+                    ui_summary=f"Patched {target_file}",
+                )
+            except Exception as e:
+                msg = f"Failed to patch skill: {e}"
+                return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+
+        msg = f"Unsupported action '{params.action}'."
+        return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")

vtx/tools/web.py

@@ -0,0 +1,238 @@
+"""Web fetch and web search tools for vtx."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Annotated
+
+import httpx
+from pydantic import BaseModel, Field
+
+from ..core.types import ToolResult
+from .base import BaseTool
+
+# ---------------------------------------------------------------------------
+# Shared constants
+# ---------------------------------------------------------------------------
+
+_FETCH_TIMEOUT = 25.0
+
+
+# ===========================================================================
+# WebFetchTool  (Exa MCP — no API key needed)
+# ===========================================================================
+
+
+class FetchParams(BaseModel):
+    urls: Annotated[
+        list[str],
+        Field(min_length=1, description="URLs to read. Batch multiple URLs in one call."),
+    ]
+    max_characters: int = Field(
+        default=3000, ge=1, description="Maximum characters to extract per page (default: 3000)."
+    )
+
+
+class WebFetchTool(BaseTool):
+    """Read a webpage's full content as clean markdown via the Exa MCP endpoint."""
+
+    name = "fetch_webpage"
+    tool_icon = "🌐"
+    params = FetchParams
+    mutating = False
+    description = (
+        "Read a webpage's full content as clean markdown via the Exa MCP endpoint. "
+        "Use after web_search when highlights are insufficient or to read any URL. "
+        "Batch multiple URLs in one call. "
+        "Not suitable for JavaScript-rendered pages — use web_search for those. "
+        "Returns up to 3000 characters per page by default."
+    )
+    prompt_guidelines = (
+        "Use fetch_webpage to read a specific URL you already know.",
+        "Use web_search first if you need to discover URLs.",
+    )
+
+    _MCP_URL = "https://mcp.exa.ai/mcp"
+
+    def format_call(self, params: FetchParams) -> str:
+        if len(params.urls) == 1:
+            return params.urls[0]
+        return f"{params.urls[0]} (+{len(params.urls) - 1} more)"
+
+    async def execute(
+        self, params: FetchParams, cancel_event: asyncio.Event | None = None
+    ) -> ToolResult:
+        payload = {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "tools/call",
+            "params": {
+                "name": "web_fetch_exa",
+                "arguments": {"urls": params.urls, "maxCharacters": params.max_characters},
+            },
+        }
+        headers = {
+            "Accept": "application/json, text/event-stream",
+            "Content-Type": "application/json",
+        }
+
+        try:
+            async with httpx.AsyncClient(timeout=_FETCH_TIMEOUT) as client:
+                resp = await client.post(self._MCP_URL, headers=headers, json=payload)
+                resp.raise_for_status()
+
+            for line in resp.text.splitlines():
+                if not line.startswith("data: "):
+                    continue
+                try:
+                    data = json.loads(line[6:])
+                except json.JSONDecodeError:
+                    continue
+                text = self._extract_text(data)
+                if text:
+                    return ToolResult(success=True, result=text, ui_summary="[dim]exa[/dim]")
+
+            try:
+                text = self._extract_text(resp.json())
+                if text:
+                    return ToolResult(success=True, result=text, ui_summary="[dim]exa[/dim]")
+            except Exception:
+                pass
+
+            return ToolResult(
+                success=False,
+                result="No results returned from Exa API",
+                ui_summary="[red]No Exa results[/red]",
+            )
+
+        except httpx.TimeoutException:
+            msg = f"Exa timed out after {_FETCH_TIMEOUT}s"
+            return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+        except httpx.HTTPStatusError as e:
+            msg = f"Exa API error {e.response.status_code}"
+            return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+        except Exception as e:
+            msg = f"Exa fetch failed: {e}"
+            return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+
+    @staticmethod
+    def _extract_text(data: dict) -> str | None:
+        content = data.get("result", {}).get("content", [])
+        if content and isinstance(content, list):
+            return content[0].get("text")
+        return None
+
+
+# ===========================================================================
+# WebSearchTool  (Exa neural search — no API key needed)
+# ===========================================================================
+
+
+class SearchParams(BaseModel):
+    query: str = Field(description="The search query")
+    num_results: int = Field(default=8, ge=1, le=20, description="Number of results")
+    search_type: str = Field(
+        default="auto", description="Search type: 'auto', 'neural', or 'keyword'"
+    )
+    livecrawl: str = Field(
+        default="fallback", description="Livecrawl mode: 'fallback', 'always', or 'never'"
+    )
+
+
+class WebSearchTool(BaseTool):
+    """Web search via Exa MCP endpoint (no API key required)."""
+
+    name = "web_search"
+    tool_icon = "🔍"
+    params = SearchParams
+    mutating = False
+    description = (
+        "Search the web using the Exa neural search API (via free MCP endpoint). "
+        "Returns titles, URLs, and rich content snippets. "
+        "Better for semantic/research queries than keyword search. "
+        "Requires internet access."
+    )
+    prompt_guidelines = (
+        "Use web_search for research, semantic queries, and finding current information.",
+    )
+
+    _MCP_URL = "https://mcp.exa.ai/mcp"
+    _TIMEOUT = 25.0
+
+    def format_call(self, params: SearchParams) -> str:
+        return f'"{params.query}"'
+
+    async def execute(
+        self, params: SearchParams, cancel_event: asyncio.Event | None = None
+    ) -> ToolResult:
+        payload = {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "tools/call",
+            "params": {
+                "name": "web_search_exa",
+                "arguments": {
+                    "query": params.query,
+                    "type": params.search_type,
+                    "numResults": params.num_results,
+                    "livecrawl": params.livecrawl,
+                },
+            },
+        }
+        headers = {
+            "Accept": "application/json, text/event-stream",
+            "Content-Type": "application/json",
+        }
+
+        try:
+            async with httpx.AsyncClient(timeout=self._TIMEOUT) as client:
+                resp = await client.post(self._MCP_URL, headers=headers, json=payload)
+                resp.raise_for_status()
+
+            # Try SSE lines first
+            for line in resp.text.splitlines():
+                if not line.startswith("data: "):
+                    continue
+                try:
+                    data = json.loads(line[6:])
+                except json.JSONDecodeError:
+                    continue
+                text = self._extract_text(data)
+                if text:
+                    return ToolResult(
+                        success=True, result=text, ui_summary=f"[dim]exa: {params.query!r}[/dim]"
+                    )
+
+            # Fallback: parse whole body as JSON
+            try:
+                text = self._extract_text(resp.json())
+                if text:
+                    return ToolResult(
+                        success=True, result=text, ui_summary=f"[dim]exa: {params.query!r}[/dim]"
+                    )
+            except Exception:
+                pass
+
+            return ToolResult(
+                success=False,
+                result="No results returned from Exa API",
+                ui_summary="[red]No Exa results[/red]",
+            )
+
+        except httpx.TimeoutException:
+            msg = f"Exa timed out after {self._TIMEOUT}s"
+            return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+        except httpx.HTTPStatusError as e:
+            msg = f"Exa API error {e.response.status_code}"
+            return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+        except Exception as e:
+            msg = f"Exa search failed: {e}"
+            return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+
+    @staticmethod
+    def _extract_text(data: dict) -> str | None:
+        content = data.get("result", {}).get("content", [])
+        if content and isinstance(content, list):
+            return content[0].get("text")
+        return None

vtx/tools/write.py

@@ -0,0 +1,88 @@
+import asyncio
+from pathlib import Path
+
+import aiofiles
+from pydantic import BaseModel, Field
+
+from vtx import config
+
+from ..core.types import FileChanges
+from ._tool_utils import shorten_path
+from .base import BaseTool, ToolResult
+
+
+class WriteParams(BaseModel):
+    path: str = Field(description="Absolute path of the file to write to")
+    content: str = Field(description="Content to be written to the file")
+
+
+class WriteTool(BaseTool):
+    name = "write"
+    tool_icon = "+"
+    params = WriteParams
+    prompt_guidelines = (
+        "Use write only for new files or complete rewrites (NOT echo >/cat <<EOF)",
+    )
+    description = (
+        "Write content to a file. Creates the file if it doesn't exist, overwrites if it does. "
+        "Automatically creates parent directories."
+    )
+
+    def format_call(self, params: WriteParams) -> str:
+        return shorten_path(params.path)
+
+    def format_preview(self, params: WriteParams) -> str | None:
+        from vtx.diff_display import DIFF_BG_PAD_MARKER, blend_hex
+
+        colors = config.ui.colors
+        bg_added = blend_hex(colors.diff_added, colors.bg)
+
+        lines = params.content.splitlines()
+        colored = []
+        for line in lines[:20]:
+            escaped = line.replace("[", "\\[")
+            content = f"+ {escaped}"
+            colored.append(f"[{colors.diff_added} on {bg_added}]{content}{DIFF_BG_PAD_MARKER}[/]")
+        if len(lines) > 20:
+            colored.append(f"[dim]  \u22ef {len(lines) - 20} more lines \u22ef[/dim]")
+        return "\n".join(colored)
+
+    async def execute(
+        self, params: WriteParams, cancel_event: asyncio.Event | None = None
+    ) -> ToolResult:
+        file_path = Path(params.path)
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_existed = file_path.exists()
+
+        old_line_count = 0
+        if file_existed:
+            try:
+                async with aiofiles.open(file_path, encoding="utf-8") as f:
+                    old_content = await f.read()
+                old_line_count = old_content.count("\n") + 1
+            except (OSError, UnicodeDecodeError):
+                pass
+
+        try:
+            async with aiofiles.open(file_path, "w", encoding="utf-8") as f:
+                await f.write(params.content)
+        except OSError as e:
+            msg = f"Failed to write: {e}"
+            return ToolResult(success=False, result=msg, ui_summary=f"[red]{msg}[/red]")
+
+        n_lines = params.content.count("\n") + 1
+        diff_added = config.ui.colors.diff_added
+
+        if file_existed:
+            result = f"Overwrote {file_path} +{n_lines}"
+            display = f"[{diff_added}]+{n_lines}[/{diff_added}]"
+        else:
+            result = f"Created {file_path} +{n_lines}"
+            display = f"[{diff_added}]+{n_lines}[/{diff_added}]"
+
+        return ToolResult(
+            success=True,
+            result=result,
+            ui_summary=display,
+            file_changes=FileChanges(path=str(file_path), added=n_lines, removed=old_line_count),
+        )