llmcode-cli 1.0.0__py3-none-any.whl

llm_code/tools/task_close.py

@@ -0,0 +1,79 @@
+"""TaskCloseTool: finalize a task, write summary, transition to DONE."""
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from llm_code.task.manager import TaskLifecycleManager
+from llm_code.task.types import TaskStatus
+from llm_code.tools.base import PermissionLevel, Tool, ToolResult
+
+
+class TaskCloseInput(BaseModel):
+    task_id: str
+    summary: str = ""
+
+
+class TaskCloseTool(Tool):
+    """Close a task: transition to DONE and write a completion summary."""
+
+    def __init__(self, manager: TaskLifecycleManager) -> None:
+        self._manager = manager
+
+    @property
+    def name(self) -> str:
+        return "task_close"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Close a completed task. Transitions from CLOSE to DONE and writes "
+            "a completion summary. The task must be in CLOSE status."
+        )
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "task_id": {"type": "string", "description": "The task ID to close"},
+                "summary": {"type": "string", "description": "Completion summary"},
+            },
+            "required": ["task_id"],
+        }
+
+    @property
+    def required_permission(self) -> PermissionLevel:
+        return PermissionLevel.WORKSPACE_WRITE
+
+    @property
+    def input_model(self) -> type[TaskCloseInput]:
+        return TaskCloseInput
+
+    def execute(self, args: dict) -> ToolResult:
+        task_id = args["task_id"]
+        summary = args.get("summary", "")
+
+        task = self._manager.get_task(task_id)
+        if task is None:
+            return ToolResult(output=f"Task not found: {task_id}", is_error=True)
+
+        try:
+            self._manager.transition(task_id, TaskStatus.DONE)
+        except ValueError as exc:
+            return ToolResult(output=str(exc), is_error=True)
+
+        # Write summary to task
+        if summary:
+            self._manager.update_task(task_id, plan=f"{task.plan}\n\n## Summary\n{summary}")
+
+        closed = self._manager.get_task(task_id)
+        files = ", ".join(closed.files_modified) if closed and closed.files_modified else "(none)"
+
+        return ToolResult(
+            output=(
+                f"Task {task_id} closed successfully.\n"
+                f"Title: {task.title}\n"
+                f"Files modified: {files}\n"
+                f"Summary: {summary or '(no summary)'}"
+            )
+        )

llm_code/tools/task_plan.py

@@ -0,0 +1,79 @@
+"""TaskPlanTool: create a task with title, plan, and goals."""
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from llm_code.task.manager import TaskLifecycleManager
+from llm_code.tools.base import PermissionLevel, Tool, ToolResult
+
+
+class TaskPlanInput(BaseModel):
+    title: str
+    plan: str = ""
+    goals: list[str] = []
+
+
+class TaskPlanTool(Tool):
+    """Create a new structured task with a plan and goals."""
+
+    def __init__(self, manager: TaskLifecycleManager, session_id: str = "") -> None:
+        self._manager = manager
+        self._session_id = session_id
+
+    @property
+    def name(self) -> str:
+        return "task_plan"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Create a new structured task. Provide a title, an implementation plan, "
+            "and measurable goals. The task starts in PLAN status."
+        )
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "title": {"type": "string", "description": "Short task title"},
+                "plan": {"type": "string", "description": "Step-by-step implementation plan"},
+                "goals": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Measurable completion goals",
+                },
+            },
+            "required": ["title"],
+        }
+
+    @property
+    def required_permission(self) -> PermissionLevel:
+        return PermissionLevel.WORKSPACE_WRITE
+
+    @property
+    def input_model(self) -> type[TaskPlanInput]:
+        return TaskPlanInput
+
+    def execute(self, args: dict) -> ToolResult:
+        title = args.get("title", "").strip()
+        if not title:
+            return ToolResult(output="Error: title is required", is_error=True)
+
+        plan = args.get("plan", "")
+        goals = tuple(args.get("goals", []))
+
+        task = self._manager.create_task(
+            title=title,
+            plan=plan,
+            goals=goals,
+            session_id=self._session_id,
+        )
+        return ToolResult(
+            output=(
+                f"Created task {task.id}: {task.title}\n"
+                f"Status: {task.status.value}\n"
+                f"Goals: {', '.join(task.goals) if task.goals else '(none)'}\n"
+                f"Plan:\n{task.plan or '(no plan set)'}"
+            )
+        )

llm_code/tools/task_verify.py

@@ -0,0 +1,90 @@
+"""TaskVerifyTool: run verification checks on a task."""
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from llm_code.task.diagnostics import DiagnosticsEngine
+from llm_code.task.manager import TaskLifecycleManager
+from llm_code.task.verifier import Verifier
+from llm_code.tools.base import PermissionLevel, Tool, ToolResult
+
+
+class TaskVerifyInput(BaseModel):
+    task_id: str
+
+
+class TaskVerifyTool(Tool):
+    """Run automated verification checks (pytest, ruff, file_exists) on a task."""
+
+    def __init__(
+        self,
+        manager: TaskLifecycleManager,
+        verifier: Verifier,
+        diagnostics: DiagnosticsEngine,
+    ) -> None:
+        self._manager = manager
+        self._verifier = verifier
+        self._diagnostics = diagnostics
+
+    @property
+    def name(self) -> str:
+        return "task_verify"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Run automated verification checks on a task: pytest, ruff, and file_exists. "
+            "Returns check results and a recommended action (continue/replan/escalate)."
+        )
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "task_id": {"type": "string", "description": "The task ID to verify"},
+            },
+            "required": ["task_id"],
+        }
+
+    @property
+    def required_permission(self) -> PermissionLevel:
+        return PermissionLevel.READ_ONLY
+
+    @property
+    def input_model(self) -> type[TaskVerifyInput]:
+        return TaskVerifyInput
+
+    def is_read_only(self, args: dict) -> bool:
+        return True
+
+    def execute(self, args: dict) -> ToolResult:
+        task_id = args["task_id"]
+        task = self._manager.get_task(task_id)
+        if task is None:
+            return ToolResult(output=f"Task not found: {task_id}", is_error=True)
+
+        # Run automated checks
+        verify_result = self._verifier.verify(task)
+
+        # Append result to task history
+        self._manager.append_verify_result(task_id, verify_result)
+
+        # Run diagnostics
+        report = self._diagnostics.analyze(task, verify_result)
+
+        # Format output
+        lines = [f"Verification for task {task_id}: {task.title}"]
+        lines.append(f"Overall: {'PASSED' if verify_result.all_passed else 'FAILED'}")
+        lines.append("")
+        for check in verify_result.checks:
+            icon = "PASS" if check.passed else "FAIL"
+            lines.append(f"  [{icon}] {check.check_name}: {check.output[:200]}")
+        lines.append("")
+        lines.append(f"Recommendation: {report.recommendation}")
+        if report.summary:
+            lines.append(f"Diagnostic: {report.summary}")
+        if report.report_path:
+            lines.append(f"Full report: {report.report_path}")
+
+        return ToolResult(output="\n".join(lines))

llm_code/tools/tool_search.py

@@ -0,0 +1,65 @@
+"""ToolSearchTool — lets the LLM discover and unlock deferred tools."""
+from __future__ import annotations
+
+from llm_code.tools.base import PermissionLevel, Tool, ToolResult
+
+if True:
+    # Avoid circular imports; DeferredToolManager is a pure data class
+    from llm_code.tools.deferred import DeferredToolManager
+
+
+class ToolSearchTool(Tool):
+    """Search deferred tools by name/description and unlock matching ones."""
+
+    def __init__(self, manager: "DeferredToolManager") -> None:
+        self._manager = manager
+
+    @property
+    def name(self) -> str:
+        return "tool_search"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Search for additional tools that are not currently visible. "
+            "Provide a query string to find tools by name or description. "
+            "Matching tools will be unlocked and available in subsequent turns."
+        )
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Search query to match against tool names and descriptions.",
+                }
+            },
+            "required": ["query"],
+        }
+
+    @property
+    def required_permission(self) -> PermissionLevel:
+        return PermissionLevel.READ_ONLY
+
+    def execute(self, args: dict) -> ToolResult:
+        query = args.get("query", "")
+        deferred = self._manager._deferred
+        matches = self._manager.search_tools(query, deferred)
+
+        if not matches:
+            return ToolResult(
+                output=f"No tools found matching '{query}'. "
+                "Try a different search term or use a broader query.",
+            )
+
+        # Unlock all matching tools
+        for d in matches:
+            self._manager.unlock_tool(d.name)
+
+        lines = [f"Found {len(matches)} tool(s) matching '{query}' (now unlocked):"]
+        for d in matches:
+            lines.append(f"  - {d.name}: {d.description}")
+
+        return ToolResult(output="\n".join(lines))

llm_code/tools/web_common.py

@@ -0,0 +1,258 @@
+"""Shared utilities for web tools (URL safety, caching, extraction)."""
+from __future__ import annotations
+
+import dataclasses
+import ipaddress
+import json
+import re
+import time
+from collections import OrderedDict
+from urllib.parse import urlparse
+
+
+@dataclasses.dataclass(frozen=True)
+class UrlSafetyResult:
+    """Result of URL safety classification."""
+
+    classification: str
+    reasons: tuple[str, ...] = ()
+
+    @property
+    def is_safe(self) -> bool:
+        """Return True if URL is safe to fetch."""
+        return self.classification == "safe"
+
+    @property
+    def is_blocked(self) -> bool:
+        """Return True if URL should be blocked."""
+        return self.classification == "blocked"
+
+    @property
+    def needs_confirm(self) -> bool:
+        """Return True if URL needs user confirmation."""
+        return self.classification == "needs_confirm"
+
+
+def classify_url(url: str) -> UrlSafetyResult:
+    """Classify URL as safe, needs_confirm, or blocked.
+
+    Rules:
+    - blocked: file://, private IPs, cloud metadata, invalid URLs, unsupported schemes
+    - needs_confirm: localhost, 127.0.0.1, IP-only URLs, non-standard ports
+    - safe: standard HTTP/HTTPS URLs to regular hosts
+    """
+    reasons: list[str] = []
+
+    try:
+        parsed = urlparse(url)
+    except Exception:
+        return UrlSafetyResult(classification="blocked", reasons=("invalid URL",))
+
+    # Check scheme
+    if not parsed.scheme:
+        return UrlSafetyResult(classification="blocked", reasons=("missing scheme",))
+
+    if parsed.scheme == "file":
+        return UrlSafetyResult(
+            classification="blocked", reasons=("file scheme",)
+        )
+
+    if parsed.scheme not in ("http", "https"):
+        return UrlSafetyResult(
+            classification="blocked", reasons=("unsupported scheme",)
+        )
+
+    # Check host
+    if not parsed.hostname:
+        return UrlSafetyResult(classification="blocked", reasons=("missing host",))
+
+    host = parsed.hostname
+
+    # Check for cloud metadata hosts (must be before IP check)
+    if host in ("169.254.169.254", "metadata.google.internal", "metadata.azure.com"):
+        return UrlSafetyResult(
+            classification="blocked", reasons=("metadata",)
+        )
+
+    # Try to parse as IP address
+    is_ip = False
+    try:
+        ip = ipaddress.ip_address(host)
+        is_ip = True
+
+        # Check for loopback IPv6 (blocked)
+        if ip.version == 6 and ip.is_loopback:
+            return UrlSafetyResult(
+                classification="blocked", reasons=("loopback",)
+            )
+
+        # Check for loopback IPv4 first (needs confirm)
+        if ip.is_loopback:
+            return UrlSafetyResult(
+                classification="needs_confirm", reasons=("127.0.0.1",)
+            )
+
+        # Check for private IPs (blocked)
+        if ip.is_private:
+            return UrlSafetyResult(
+                classification="blocked", reasons=("private IP",)
+            )
+    except ValueError:
+        # Not an IP address, check for localhost string
+        pass
+
+    # Check for localhost name (needs confirm)
+    if host == "localhost":
+        return UrlSafetyResult(
+            classification="needs_confirm", reasons=("localhost",)
+        )
+
+    # Check port
+    port = parsed.port
+    if is_ip and port is None:
+        # IP-only URL without port (needs confirm)
+        return UrlSafetyResult(
+            classification="needs_confirm", reasons=("IP-only",)
+        )
+
+    if port is not None and port not in (80, 443):
+        # Non-standard port (needs confirm)
+        return UrlSafetyResult(
+            classification="needs_confirm", reasons=("non-standard port",)
+        )
+
+    # All checks passed
+    return UrlSafetyResult(classification="safe", reasons=())
+
+
+@dataclasses.dataclass(frozen=True)
+class CacheEntry:
+    """Cache entry with TTL support."""
+
+    content: str
+    fetched_at: float
+    ttl: float = 900.0
+
+    @property
+    def is_expired(self) -> bool:
+        """Return True if entry has expired based on TTL."""
+        return time.time() - self.fetched_at > self.ttl
+
+
+class UrlCache:
+    """LRU cache for URL content with TTL support."""
+
+    def __init__(self, max_entries: int = 50, ttl: float = 900.0) -> None:
+        """Initialize cache.
+
+        Args:
+            max_entries: Maximum number of entries before evicting oldest.
+            ttl: Time-to-live for entries in seconds.
+        """
+        self.max_entries = max_entries
+        self.ttl = ttl
+        self._cache: OrderedDict[str, CacheEntry] = OrderedDict()
+
+    def get(self, url: str) -> str | None:
+        """Get cached content for URL, return None if not found or expired."""
+        if url not in self._cache:
+            return None
+
+        entry = self._cache[url]
+        if entry.is_expired:
+            del self._cache[url]
+            return None
+
+        # Move to end (LRU)
+        self._cache.move_to_end(url)
+        return entry.content
+
+    def put(self, url: str, content: str) -> None:
+        """Store content in cache. Evicts oldest entry if cache is full."""
+        # If updating existing, remove it first
+        if url in self._cache:
+            del self._cache[url]
+
+        # Add new entry
+        entry = CacheEntry(content=content, fetched_at=time.time(), ttl=self.ttl)
+        self._cache[url] = entry
+
+        # Evict oldest if over capacity
+        if len(self._cache) > self.max_entries:
+            self._cache.popitem(last=False)
+
+    def clear(self) -> None:
+        """Clear all cached entries."""
+        self._cache.clear()
+
+
+def _html_to_markdown(html: str, use_readability: bool = True) -> str:
+    """Convert HTML to markdown using readability and html2text.
+
+    Falls back gracefully if dependencies are missing.
+    """
+    content = html
+
+    # Try readability first if requested
+    if use_readability:
+        try:
+            from readability import Document
+            doc = Document(content)
+            content = doc.summary()
+        except ImportError:
+            pass
+
+    # Try html2text
+    try:
+        import html2text
+        converter = html2text.HTML2Text()
+        converter.ignore_links = False
+        return converter.handle(content)
+    except ImportError:
+        # Fallback: simple regex tag stripping
+        content = re.sub(r"<[^>]+>", "", content)
+        content = re.sub(r"\s+", " ", content).strip()
+        return content
+
+
+def extract_content(
+    body: str,
+    content_type: str,
+    raw: bool = False,
+    max_length: int = 50000,
+) -> str:
+    """Extract and format content based on content type.
+
+    Args:
+        body: Raw content body.
+        content_type: MIME type of content.
+        raw: If True, skip readability for HTML (just strip tags).
+        max_length: Maximum length before truncation.
+
+    Returns:
+        Formatted content, possibly truncated with "[truncated]" marker.
+    """
+    if not body:
+        return ""
+
+    result = ""
+
+    if content_type.startswith("application/json"):
+        try:
+            data = json.loads(body)
+            result = json.dumps(data, indent=2)
+        except json.JSONDecodeError:
+            result = body
+    elif "html" in content_type:
+        result = _html_to_markdown(body, use_readability=not raw)
+    else:
+        # Passthrough
+        result = body
+
+    # Truncate if needed
+    if len(result) > max_length:
+        truncated_marker = "\n\n[truncated]"
+        available = max_length - len(truncated_marker)
+        result = result[:available] + truncated_marker
+
+    return result