yycode 0.3.2__py3-none-any.whl

tools/subagent.py

@@ -0,0 +1,57 @@
+"""Subagent delegation tool - tool definition only."""
+
+subagent_tool = {
+    "name": "subagent",
+    "description": (
+        "Delegate a focused task to an isolated subagent and wait for its summary result. "
+        "Use explorer for research, architect for design, worker for implementation, "
+        "tester for verification, and security for security review."
+    ),
+    "execution": {
+        "side_effects": "delegation",
+        "concurrency": "role_based",
+        "timeout_seconds": 300,
+    },
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "role": {
+                "type": "string",
+                "enum": ["explorer", "architect", "worker", "tester", "security"],
+                "description": "Subagent role to run.",
+            },
+            "task": {
+                "type": "string",
+                "description": "The concrete task the subagent should complete.",
+            },
+            "context": {
+                "type": "string",
+                "description": "Optional extra context, constraints, or relevant findings.",
+            },
+            "max_turns": {
+                "type": "integer",
+                "description": "Optional recursion limit for the subagent run. Defaults to 30.",
+            },
+            "skills": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": (
+                    "Optional local skill names to load into the subagent context before it starts. "
+                    "Use this for explicit delegation such as @architect /plan task."
+                ),
+            },
+        },
+        "required": ["role", "task"],
+    },
+}
+
+
+def subagent(
+    role: str,
+    task: str,
+    context: str = "",
+    max_turns: int = 30,
+    skills: list[str] | None = None,
+) -> str:
+    """Dummy subagent handler - should be bound by the graph at runtime."""
+    raise RuntimeError("Subagent tool handler should be created by SubagentRunner")

tools/todo.py

@@ -0,0 +1,89 @@
+"""Task state tracking tool - tool definition only."""
+
+
+TASK_MEMORY_PROPERTIES = {
+    "user_goal": {
+        "type": "string",
+        "description": "The current user goal in one concise sentence.",
+    },
+    "constraints": {
+        "type": "array",
+        "items": {"type": "string"},
+        "description": "Important constraints, preferences, or non-goals.",
+    },
+    "files_inspected": {
+        "type": "array",
+        "items": {"type": "string"},
+        "description": "Files or paths already inspected.",
+    },
+    "files_modified": {
+        "type": "array",
+        "items": {"type": "string"},
+        "description": "Files or paths modified during this task.",
+    },
+    "decisions": {
+        "type": "array",
+        "items": {"type": "string"},
+        "description": "Design or implementation decisions already made.",
+    },
+    "test_results": {
+        "type": "array",
+        "items": {"type": "string"},
+        "description": "Verification commands run and their results.",
+    },
+    "open_risks": {
+        "type": "array",
+        "items": {"type": "string"},
+        "description": "Known risks, uncertainties, or follow-up concerns.",
+    },
+    "next_steps": {
+        "type": "array",
+        "items": {"type": "string"},
+        "description": "Immediate next steps if the task continues.",
+    },
+}
+
+todo_tool = {
+    "name": "todo",
+    "description": (
+        "Update Task State for multi-step work. Track todo items plus compact task "
+        "memory such as goal, constraints, inspected/modified files, decisions, "
+        "test results, risks, and next steps."
+    ),
+    "execution": {
+        "side_effects": "session_state",
+        "concurrency": "serial",
+        "timeout_seconds": 30,
+    },
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "items": {
+                "type": "array",
+                "description": "Current ordered task checklist.",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "id": {"type": "string"},
+                        "text": {"type": "string"},
+                        "status": {"type": "string", "enum": ["pending", "in_progress", "completed"]},
+                    },
+                    "required": ["id", "text", "status"],
+                },
+            },
+            "memory": {
+                "type": "object",
+                "description": "Optional compact task memory to preserve progress across long tool loops.",
+                "properties": TASK_MEMORY_PROPERTIES,
+                "additionalProperties": False,
+            },
+        },
+        "required": ["items"],
+    },
+}
+
+
+# Dummy handler - the real one is created by TodoManager
+def todo(items, memory=None):
+    """Dummy todo handler - should not be called directly."""
+    raise RuntimeError("Todo tool handler should be created by TodoManager")

tools/verify.py

@@ -0,0 +1,107 @@
+"""Verification tool for common code-agent checks."""
+
+import shlex
+import subprocess
+import time
+from pathlib import Path
+
+from .read_file import safe_path, workspace_for
+
+MAX_OUTPUT_CHARS = 50_000
+VERIFY_TIMEOUT_SECONDS = 300
+
+
+def _target_args(target: str, workdir: Path | str | None = None) -> list[str]:
+    if not target:
+        return []
+    path_part = target.split("::", 1)[0]
+    if path_part:
+        safe_path(path_part, workdir)
+    return [target]
+
+
+def _has_file(workdir: Path | str | None, *names: str) -> bool:
+    workspace = workspace_for(workdir)
+    return any((workspace.root / name).exists() for name in names)
+
+
+def _pyproject_contains(marker: str, workdir: Path | str | None = None) -> bool:
+    pyproject = workspace_for(workdir).root / "pyproject.toml"
+    return pyproject.exists() and marker in pyproject.read_text()
+
+
+def _command_for(kind: str, target: str, workdir: Path | str | None = None) -> list[str] | None:
+    extra = _target_args(target, workdir)
+    if kind in {"all", "tests"}:
+        return ["pytest", *extra]
+    if kind == "lint":
+        if _has_file(workdir, "ruff.toml", ".ruff.toml") or _pyproject_contains("[tool.ruff", workdir):
+            return ["ruff", "check", *(extra or ["."])]
+        return None
+    if kind == "typecheck":
+        if _has_file(workdir, "mypy.ini", ".mypy.ini") or _pyproject_contains("[tool.mypy", workdir):
+            return ["mypy", *(extra or ["."])]
+        if _has_file(workdir, "pyrightconfig.json"):
+            return ["pyright", *(extra or ["."])]
+        return None
+    raise ValueError(f"unsupported verify kind: {kind}")
+
+
+def verify(kind: str = "all", target: str = "", workdir: Path | str | None = None) -> str:
+    """Run a verification check and return command output."""
+    try:
+        workspace = workspace_for(workdir)
+        kind = (kind or "all").strip().lower()
+        command = _command_for(kind, target or "", workspace.root)
+        if command is None:
+            return f"No {kind} configuration found."
+
+        started = time.monotonic()
+        result = subprocess.run(
+            command,
+            cwd=workspace.root,
+            capture_output=True,
+            text=True,
+            errors="backslashreplace",
+            timeout=VERIFY_TIMEOUT_SECONDS,
+        )
+        elapsed = time.monotonic() - started
+        output = (result.stdout + result.stderr).strip()
+        rendered_command = " ".join(shlex.quote(part) for part in command)
+        status = "passed" if result.returncode == 0 else "failed"
+        return (
+            f"verify {status}: {rendered_command}\n"
+            f"exit_code: {result.returncode}\n"
+            f"duration: {elapsed:.1f}s\n"
+            f"output:\n{output or '(no output)'}"
+        )[:MAX_OUTPUT_CHARS]
+    except subprocess.TimeoutExpired:
+        return f"Error: Timeout ({VERIFY_TIMEOUT_SECONDS}s)"
+    except Exception as exc:
+        return f"Error: {exc}"
+
+
+verify_tool = {
+    "name": "verify",
+    "description": "Run common verification checks such as tests, lint, or typecheck.",
+    "execution": {
+        "side_effects": "process",
+        "concurrency": "serial",
+        "timeout_seconds": VERIFY_TIMEOUT_SECONDS,
+    },
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "kind": {
+                "type": "string",
+                "enum": ["all", "tests", "lint", "typecheck"],
+                "description": "Verification type to run. Defaults to all.",
+            },
+            "target": {
+                "type": "string",
+                "description": "Optional workspace-relative target, such as a test file.",
+            },
+        },
+        "required": [],
+    },
+}

tools/web_search.py

@@ -0,0 +1,250 @@
+"""No-key web search tool.
+
+The default provider uses DuckDuckGo's HTML endpoint as a best-effort,
+keyless search backend. This tool intentionally returns search results only;
+full page fetching/extraction should be implemented as a separate tool.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from html import unescape
+from html.parser import HTMLParser
+
+MAX_RESULTS = 10
+MAX_OUTPUT_CHARS = 20_000
+DEFAULT_TIMEOUT_SECONDS = 15
+DUCKDUCKGO_HTML_URL = "https://html.duckduckgo.com/html/"
+DUCKDUCKGO_LITE_URL = "https://lite.duckduckgo.com/lite/"
+USER_AGENT = "yoyoagent-web-search/0.1 (+https://github.com/yoyofx/yoyoagent)"
+
+
+@dataclass
+class SearchResult:
+    title: str
+    url: str
+    snippet: str = ""
+
+
+class DuckDuckGoHTMLParser(HTMLParser):
+    """Small parser for DuckDuckGo HTML search results."""
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.results: list[SearchResult] = []
+        self._current: dict[str, str] | None = None
+        self._capture: str | None = None
+        self._parts: list[str] = []
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        attr = {key: value or "" for key, value in attrs}
+        classes = set(attr.get("class", "").split())
+
+        if tag == "a" and ("result__a" in classes or "result-link" in classes):
+            self._finish_result()
+            self._current = {"title": "", "url": _clean_duckduckgo_url(attr.get("href", "")), "snippet": ""}
+            self._capture = "title"
+            self._parts = []
+            return
+
+        if self._current is not None and (
+            "result__snippet" in classes or "result-snippet" in classes
+        ):
+            self._capture = "snippet"
+            self._parts = []
+
+    def handle_data(self, data: str) -> None:
+        if self._capture:
+            self._parts.append(data)
+
+    def handle_endtag(self, tag: str) -> None:
+        if self._current is None or self._capture is None:
+            return
+        if self._capture == "title" and tag == "a":
+            self._current["title"] = _normalize_space(" ".join(self._parts))
+            self._capture = None
+            self._parts = []
+        elif self._capture == "snippet":
+            self._current["snippet"] = _normalize_space(" ".join(self._parts))
+            self._capture = None
+            self._parts = []
+
+    def close(self) -> None:
+        super().close()
+        self._finish_result()
+
+    def _finish_result(self) -> None:
+        if not self._current:
+            return
+        title = self._current.get("title", "").strip()
+        url = self._current.get("url", "").strip()
+        if title and url:
+            self.results.append(
+                SearchResult(
+                    title=title,
+                    url=url,
+                    snippet=self._current.get("snippet", "").strip(),
+                )
+            )
+        self._current = None
+        self._capture = None
+        self._parts = []
+
+
+def _normalize_space(text: str) -> str:
+    return re.sub(r"\s+", " ", unescape(text)).strip()
+
+
+def _clean_duckduckgo_url(url: str) -> str:
+    url = unescape(url).strip()
+    parsed = urllib.parse.urlparse(url)
+    query = urllib.parse.parse_qs(parsed.query)
+    if "uddg" in query and query["uddg"]:
+        return query["uddg"][0]
+    return url
+
+
+def _fetch_url(url: str, *, timeout: int = DEFAULT_TIMEOUT_SECONDS) -> str:
+    request = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+    with urllib.request.urlopen(request, timeout=timeout) as response:
+        charset = response.headers.get_content_charset() or "utf-8"
+        return response.read().decode(charset, errors="replace")
+
+
+def _parse_duckduckgo_html(html: str, max_results: int) -> list[SearchResult]:
+    parser = DuckDuckGoHTMLParser()
+    parser.feed(html)
+    parser.close()
+    return parser.results[:max_results]
+
+
+def _search_duckduckgo(query: str, max_results: int, timeout: int) -> list[SearchResult]:
+    params = urllib.parse.urlencode({"q": query})
+    html = _fetch_url(f"{DUCKDUCKGO_HTML_URL}?{params}", timeout=timeout)
+    results = _parse_duckduckgo_html(html, max_results)
+    if results:
+        return results
+    lite_html = _fetch_url(f"{DUCKDUCKGO_LITE_URL}?{params}", timeout=timeout)
+    return _parse_duckduckgo_html(lite_html, max_results)
+
+
+def _search_searxng(
+    query: str,
+    max_results: int,
+    timeout: int,
+    searxng_base_url: str | None,
+) -> list[SearchResult]:
+    if not searxng_base_url:
+        raise ValueError("searxng_base_url is required when provider='searxng'")
+    base_url = searxng_base_url.rstrip("/")
+    params = urllib.parse.urlencode({"q": query, "format": "json"})
+    payload = _fetch_url(f"{base_url}/search?{params}", timeout=timeout)
+    data = json.loads(payload)
+    results = []
+    for item in data.get("results", [])[:max_results]:
+        title = _normalize_space(str(item.get("title", "")))
+        url = str(item.get("url", "")).strip()
+        snippet = _normalize_space(str(item.get("content", item.get("snippet", ""))))
+        if title and url:
+            results.append(SearchResult(title=title, url=url, snippet=snippet))
+    return results
+
+
+def _format_results(provider: str, query: str, results: list[SearchResult]) -> str:
+    if not results:
+        return f"No results found for {query!r} via {provider}."
+
+    lines = [f"web_search provider={provider} query={query!r} results={len(results)}"]
+    for index, result in enumerate(results, start=1):
+        lines.append(f"\n{index}. {result.title}")
+        lines.append(f"   URL: {result.url}")
+        if result.snippet:
+            lines.append(f"   Snippet: {result.snippet}")
+    return "\n".join(lines)[:MAX_OUTPUT_CHARS]
+
+
+def web_search(
+    query: str,
+    max_results: int = 5,
+    provider: str = "auto",
+    searxng_base_url: str | None = None,
+    timeout_seconds: int = DEFAULT_TIMEOUT_SECONDS,
+) -> str:
+    """Search the web using a no-key provider when possible."""
+    try:
+        query = query.strip()
+        if not query:
+            return "Error: query is required"
+
+        max_results = max(1, min(int(max_results), MAX_RESULTS))
+        timeout = max(1, min(int(timeout_seconds), DEFAULT_TIMEOUT_SECONDS))
+        provider = (provider or "auto").strip().lower()
+
+        if provider == "auto":
+            provider = "searxng" if searxng_base_url else "duckduckgo"
+
+        if provider in {"duckduckgo", "ddg"}:
+            provider_name = "duckduckgo"
+            results = _search_duckduckgo(query, max_results, timeout)
+        elif provider == "searxng":
+            provider_name = "searxng"
+            results = _search_searxng(query, max_results, timeout, searxng_base_url)
+        else:
+            return "Error: provider must be one of auto, duckduckgo, ddg, searxng"
+
+        return _format_results(provider_name, query, results)
+    except urllib.error.URLError as exc:
+        return f"Error: network request failed: {exc}"
+    except TimeoutError:
+        return "Error: network request timed out"
+    except json.JSONDecodeError as exc:
+        return f"Error: invalid provider response JSON: {exc}"
+    except ValueError as exc:
+        return f"Error: {exc}"
+    except Exception as exc:
+        return f"Error: {exc}"
+
+
+web_search_tool = {
+    "name": "web_search",
+    "description": (
+        "Search online resources using keyless providers when possible. "
+        "Default is DuckDuckGo HTML/Lite best-effort search; optional SearXNG requires a base URL."
+    ),
+    "execution": {
+        "side_effects": "read_only",
+        "concurrency": "safe",
+        "timeout_seconds": 20,
+    },
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "Search query.",
+            },
+            "max_results": {
+                "type": "integer",
+                "description": f"Maximum number of results, capped at {MAX_RESULTS}. Defaults to 5.",
+            },
+            "provider": {
+                "type": "string",
+                "description": "Search provider: auto, duckduckgo, ddg, or searxng. Defaults to auto.",
+            },
+            "searxng_base_url": {
+                "type": "string",
+                "description": "Optional SearXNG instance base URL used when provider is searxng or auto.",
+            },
+            "timeout_seconds": {
+                "type": "integer",
+                "description": f"Network timeout in seconds, capped at {DEFAULT_TIMEOUT_SECONDS}.",
+            },
+        },
+        "required": ["query"],
+    },
+}

tools/workspace.py

@@ -0,0 +1,36 @@
+"""Workspace path helpers shared by tools and runtime."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Workspace:
+    """Resolved workspace root with safe path helpers."""
+
+    root: Path
+
+    def __post_init__(self) -> None:
+        resolved = self.root.expanduser().resolve()
+        if not resolved.exists():
+            raise ValueError(f"workspace does not exist: {resolved}")
+        if not resolved.is_dir():
+            raise ValueError(f"workspace is not a directory: {resolved}")
+        object.__setattr__(self, "root", resolved)
+
+    def safe_path(self, path: str | Path) -> Path:
+        """Return an absolute path constrained within the workspace."""
+        raw_path = Path(path).expanduser()
+        resolved = raw_path.resolve() if raw_path.is_absolute() else (self.root / raw_path).resolve()
+        if not resolved.is_relative_to(self.root):
+            raise ValueError(f"Path escapes workspace: {path}")
+        return resolved
+
+    def relative_path(self, path: str | Path) -> str:
+        """Return a workspace-relative path after safety checks."""
+        return str(self.safe_path(path).relative_to(self.root))
+
+
+def resolve_workspace(path: str | Path | None = None) -> Workspace:
+    """Resolve a user-provided workspace or default to the current directory."""
+    return Workspace(Path(path).expanduser() if path is not None else Path.cwd())

tools/workspace_state.py

@@ -0,0 +1,60 @@
+"""Workspace state inspection tool."""
+
+import subprocess
+from pathlib import Path
+
+from .read_file import workspace_for
+
+MAX_OUTPUT_CHARS = 20_000
+
+
+def _run_git(args: list[str], workdir: Path | str | None = None) -> tuple[int, str]:
+    workspace = workspace_for(workdir)
+    result = subprocess.run(
+        ["git", *args],
+        cwd=workspace.root,
+        capture_output=True,
+        text=True,
+        errors="backslashreplace",
+        timeout=30,
+    )
+    return result.returncode, (result.stdout + result.stderr).strip()
+
+
+def workspace_state(workdir: Path | str | None = None) -> str:
+    """Return branch and working tree status."""
+    try:
+        code, branch = _run_git(["branch", "--show-current"], workdir)
+        if code != 0:
+            return f"Error: {branch or 'not a git repository'}"
+
+        _, status = _run_git(["status", "--short"], workdir)
+        lines = [line for line in status.splitlines() if line.strip()]
+        changed = len(lines)
+        status_text = "\n".join(lines) if lines else "clean"
+
+        return (
+            f"branch: {branch or '(detached)'}\n"
+            f"changed_files: {changed}\n"
+            f"status:\n{status_text}"
+        )[:MAX_OUTPUT_CHARS]
+    except subprocess.TimeoutExpired:
+        return "Error: Timeout (30s)"
+    except Exception as exc:
+        return f"Error: {exc}"
+
+
+workspace_state_tool = {
+    "name": "workspace_state",
+    "description": "Inspect the current git branch and working tree status.",
+    "execution": {
+        "side_effects": "read_only",
+        "concurrency": "safe",
+        "timeout_seconds": 30,
+    },
+    "input_schema": {
+        "type": "object",
+        "properties": {},
+        "required": [],
+    },
+}

tools/write_file.py

@@ -0,0 +1,88 @@
+"""Write file tool."""
+
+from difflib import unified_diff
+from pathlib import Path
+
+from .diff_utils import format_diff_result
+from .read_file import safe_path
+from .safety import approval_required
+
+
+def _apply_patch_required_message(path: str) -> str:
+    return (
+        f"Code workflow guard blocked write_file for existing file: {path}\n\n"
+        "Use apply_patch with path + old_text + new_text, or a unified diff, "
+        "for existing file edits. write_file is only allowed for brand-new files."
+    )
+
+
+def write_file(
+    path: str,
+    content: str,
+    approved: bool = False,
+    workdir: Path | str | None = None,
+) -> str:
+    """Write content to file."""
+    try:
+        fp = safe_path(path, workdir)
+        if fp.exists():
+            return _apply_patch_required_message(path)
+        if not approved:
+            return approval_required(
+                action="create_file",
+                path=path,
+                reason="write_file creates a new file and requires user approval before writing.",
+                risk="Creating files changes the workspace and may add unwanted artifacts.",
+            )
+        fp.parent.mkdir(parents=True, exist_ok=True)
+        fp.write_text(content)
+        return format_diff_result(f"Wrote {len(content)} bytes to {path}", [path], workdir=workdir)
+    except Exception as e:
+        return f"Error: {e}"
+
+
+def preview_write_file_diff(path: str, content: str, workdir: Path | str | None = None) -> str:
+    """Return the diff that write_file would create without writing."""
+    try:
+        fp = safe_path(path, workdir)
+        if fp.exists():
+            return ""
+        lines = "\n".join(
+            unified_diff(
+                [],
+                content.splitlines(),
+                fromfile="/dev/null",
+                tofile=f"b/{path}",
+                lineterm="",
+            )
+        )
+        return lines
+    except Exception:
+        return ""
+
+
+write_file_tool = {
+    "name": "write_file",
+    "description": (
+        "Create a brand-new file or generated artifact. Do not use this for existing "
+        "file edits; use apply_patch for existing files so the diff is reviewable. "
+        "Requires approved=true after explicit user approval."
+    ),
+    "execution": {
+        "side_effects": "workspace_write",
+        "concurrency": "serial",
+        "timeout_seconds": 60,
+    },
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string"},
+            "content": {"type": "string"},
+            "approved": {
+                "type": "boolean",
+                "description": "Set true only after the user explicitly approves this file creation.",
+            },
+        },
+        "required": ["path", "content"],
+    },
+}