llmcode-cli 1.0.0__py3-none-any.whl

llm_code/tools/computer_use_tools.py

@@ -0,0 +1,278 @@
+"""Tool classes for computer use (GUI automation)."""
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from llm_code.tools.base import PermissionLevel, Tool, ToolResult
+
+if TYPE_CHECKING:
+    from llm_code.runtime.config import ComputerUseConfig
+
+
+class _ComputerUseTool(Tool):
+    """Base class for computer-use tools with shared config check."""
+
+    def __init__(self, config: "ComputerUseConfig") -> None:
+        from llm_code.computer_use.coordinator import ComputerUseCoordinator
+        self._config = config
+        self._coordinator = ComputerUseCoordinator(config)
+
+    def _check_enabled(self) -> ToolResult | None:
+        if not self._config.enabled:
+            return ToolResult(
+                output="Computer use is not enabled. Set computer_use.enabled=true in config.",
+                is_error=True,
+            )
+        return None
+
+
+class ScreenshotTool(_ComputerUseTool):
+    @property
+    def name(self) -> str:
+        return "screenshot"
+
+    @property
+    def description(self) -> str:
+        return "Take a screenshot of the current screen. Returns a base64-encoded PNG image."
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": False,
+        }
+
+    @property
+    def required_permission(self) -> PermissionLevel:
+        return PermissionLevel.READ_ONLY
+
+    def is_read_only(self, args: dict) -> bool:
+        return True
+
+    def execute(self, args: dict) -> ToolResult:
+        err = self._check_enabled()
+        if err:
+            return err
+        try:
+            result = self._coordinator.screenshot()
+            return ToolResult(
+                output=json.dumps(result),
+                metadata={"has_image": True},
+            )
+        except Exception as exc:
+            return ToolResult(output=f"Screenshot failed: {exc}", is_error=True)
+
+
+class MouseClickTool(_ComputerUseTool):
+    @property
+    def name(self) -> str:
+        return "mouse_click"
+
+    @property
+    def description(self) -> str:
+        return "Click the mouse at (x, y) coordinates. Returns a screenshot after clicking."
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "x": {"type": "integer", "description": "X coordinate"},
+                "y": {"type": "integer", "description": "Y coordinate"},
+                "button": {
+                    "type": "string",
+                    "enum": ["left", "right", "middle"],
+                    "default": "left",
+                    "description": "Mouse button",
+                },
+            },
+            "required": ["x", "y"],
+            "additionalProperties": False,
+        }
+
+    @property
+    def required_permission(self) -> PermissionLevel:
+        return PermissionLevel.FULL_ACCESS
+
+    def execute(self, args: dict) -> ToolResult:
+        err = self._check_enabled()
+        if err:
+            return err
+        try:
+            result = self._coordinator.click_and_observe(
+                x=args["x"],
+                y=args["y"],
+                button=args.get("button", "left"),
+            )
+            return ToolResult(output=json.dumps(result), metadata={"has_image": True})
+        except Exception as exc:
+            return ToolResult(output=f"Mouse click failed: {exc}", is_error=True)
+
+
+class KeyboardTypeTool(_ComputerUseTool):
+    @property
+    def name(self) -> str:
+        return "keyboard_type"
+
+    @property
+    def description(self) -> str:
+        return "Type text using the keyboard. Returns a screenshot after typing."
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "text": {"type": "string", "description": "Text to type"},
+            },
+            "required": ["text"],
+            "additionalProperties": False,
+        }
+
+    @property
+    def required_permission(self) -> PermissionLevel:
+        return PermissionLevel.FULL_ACCESS
+
+    def execute(self, args: dict) -> ToolResult:
+        err = self._check_enabled()
+        if err:
+            return err
+        try:
+            result = self._coordinator.type_and_observe(args["text"])
+            return ToolResult(output=json.dumps(result), metadata={"has_image": True})
+        except Exception as exc:
+            return ToolResult(output=f"Keyboard type failed: {exc}", is_error=True)
+
+
+class KeyPressTool(_ComputerUseTool):
+    @property
+    def name(self) -> str:
+        return "key_press"
+
+    @property
+    def description(self) -> str:
+        return "Press a keyboard shortcut (e.g., ctrl+c). Returns a screenshot after pressing."
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "keys": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Keys to press simultaneously (e.g., ['ctrl', 'c'])",
+                },
+            },
+            "required": ["keys"],
+            "additionalProperties": False,
+        }
+
+    @property
+    def required_permission(self) -> PermissionLevel:
+        return PermissionLevel.FULL_ACCESS
+
+    def execute(self, args: dict) -> ToolResult:
+        err = self._check_enabled()
+        if err:
+            return err
+        try:
+            result = self._coordinator.hotkey_and_observe(*args["keys"])
+            return ToolResult(output=json.dumps(result), metadata={"has_image": True})
+        except Exception as exc:
+            return ToolResult(output=f"Key press failed: {exc}", is_error=True)
+
+
+class ScrollTool(_ComputerUseTool):
+    @property
+    def name(self) -> str:
+        return "scroll"
+
+    @property
+    def description(self) -> str:
+        return "Scroll the mouse wheel. Positive clicks = up, negative = down. Returns a screenshot."
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "clicks": {
+                    "type": "integer",
+                    "description": "Scroll amount (positive=up, negative=down)",
+                },
+                "x": {"type": "integer", "description": "Optional X position"},
+                "y": {"type": "integer", "description": "Optional Y position"},
+            },
+            "required": ["clicks"],
+            "additionalProperties": False,
+        }
+
+    @property
+    def required_permission(self) -> PermissionLevel:
+        return PermissionLevel.FULL_ACCESS
+
+    def execute(self, args: dict) -> ToolResult:
+        err = self._check_enabled()
+        if err:
+            return err
+        try:
+            result = self._coordinator.scroll_and_observe(
+                clicks=args["clicks"],
+                x=args.get("x"),
+                y=args.get("y"),
+            )
+            return ToolResult(output=json.dumps(result), metadata={"has_image": True})
+        except Exception as exc:
+            return ToolResult(output=f"Scroll failed: {exc}", is_error=True)
+
+
+class MouseDragTool(_ComputerUseTool):
+    @property
+    def name(self) -> str:
+        return "mouse_drag"
+
+    @property
+    def description(self) -> str:
+        return "Drag the mouse from a start position by an offset. Returns a screenshot."
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "start_x": {"type": "integer", "description": "Start X coordinate"},
+                "start_y": {"type": "integer", "description": "Start Y coordinate"},
+                "offset_x": {"type": "integer", "description": "Horizontal drag distance"},
+                "offset_y": {"type": "integer", "description": "Vertical drag distance"},
+                "duration": {
+                    "type": "number",
+                    "default": 0.5,
+                    "description": "Drag duration in seconds",
+                },
+            },
+            "required": ["start_x", "start_y", "offset_x", "offset_y"],
+            "additionalProperties": False,
+        }
+
+    @property
+    def required_permission(self) -> PermissionLevel:
+        return PermissionLevel.FULL_ACCESS
+
+    def execute(self, args: dict) -> ToolResult:
+        err = self._check_enabled()
+        if err:
+            return err
+        try:
+            result = self._coordinator.drag_and_observe(
+                start_x=args["start_x"],
+                start_y=args["start_y"],
+                offset_x=args["offset_x"],
+                offset_y=args["offset_y"],
+                duration=args.get("duration", 0.5),
+            )
+            return ToolResult(output=json.dumps(result), metadata={"has_image": True})
+        except Exception as exc:
+            return ToolResult(output=f"Mouse drag failed: {exc}", is_error=True)

llm_code/tools/coordinator_tool.py

@@ -0,0 +1,75 @@
+"""CoordinatorTool — auto-decompose and delegate a task to swarm workers."""
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+
+from pydantic import BaseModel
+
+from llm_code.tools.base import PermissionLevel, Tool, ToolResult
+
+
+class CoordinatorInput(BaseModel):
+    task: str
+
+
+class CoordinatorTool(Tool):
+    """Tool that auto-decomposes a high-level task and dispatches to swarm workers."""
+
+    def __init__(self, coordinator: object) -> None:
+        self._coordinator = coordinator
+
+    @property
+    def name(self) -> str:
+        return "coordinate"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Auto-decompose a high-level task into subtasks and delegate each one "
+            "to a separate swarm worker agent. The coordinator monitors progress "
+            "and returns an aggregated summary when all workers finish (or timeout)."
+        )
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "task": {
+                    "type": "string",
+                    "description": "High-level task to decompose and delegate to worker agents.",
+                },
+            },
+            "required": ["task"],
+        }
+
+    @property
+    def required_permission(self) -> PermissionLevel:
+        return PermissionLevel.FULL_ACCESS
+
+    @property
+    def input_model(self) -> type[CoordinatorInput]:
+        return CoordinatorInput
+
+    def execute(self, args: dict) -> ToolResult:
+        task = args["task"]
+        try:
+            try:
+                asyncio.get_running_loop()
+                running = True
+            except RuntimeError:
+                running = False
+
+            if running:
+                with concurrent.futures.ThreadPoolExecutor() as pool:
+                    result = pool.submit(
+                        asyncio.run,
+                        self._coordinator.orchestrate(task),
+                    ).result()
+            else:
+                result = asyncio.run(self._coordinator.orchestrate(task))
+
+            return ToolResult(output=result)
+        except Exception as exc:
+            return ToolResult(output=f"Coordinator error: {exc}", is_error=True)

llm_code/tools/cron_create.py

@@ -0,0 +1,90 @@
+"""CronCreateTool — schedule a new cron task."""
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from llm_code.cron.parser import parse_cron
+from llm_code.cron.storage import CronStorage
+from llm_code.tools.base import PermissionLevel, Tool, ToolResult
+
+
+class CronCreateInput(BaseModel):
+    cron: str
+    prompt: str
+    recurring: bool = True
+    permanent: bool = False
+
+
+class CronCreateTool(Tool):
+    def __init__(self, storage: CronStorage) -> None:
+        self._storage = storage
+
+    @property
+    def name(self) -> str:
+        return "cron_create"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Schedule a prompt to run on a cron schedule. "
+            "5-field format: minute hour day-of-month month day-of-week (local time). "
+            "recurring=True keeps firing; permanent=True prevents 30-day auto-expiry."
+        )
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "cron": {"type": "string", "description": "Cron expression (5-field)"},
+                "prompt": {"type": "string", "description": "Prompt to execute when fired"},
+                "recurring": {"type": "boolean", "description": "Keep firing (default true)", "default": True},
+                "permanent": {"type": "boolean", "description": "Prevent 30-day auto-expiry (default false)", "default": False},
+            },
+            "required": ["cron", "prompt"],
+        }
+
+    @property
+    def required_permission(self) -> PermissionLevel:
+        return PermissionLevel.FULL_ACCESS
+
+    @property
+    def input_model(self) -> type[CronCreateInput]:
+        return CronCreateInput
+
+    def execute(self, args: dict) -> ToolResult:
+        cron_expr = args["cron"]
+        prompt = args["prompt"]
+        recurring = args.get("recurring", True)
+        permanent = args.get("permanent", False)
+
+        # Validate cron expression
+        try:
+            parse_cron(cron_expr)
+        except ValueError as exc:
+            return ToolResult(output=f"Invalid cron expression: {exc}", is_error=True)
+
+        try:
+            task = self._storage.add(
+                cron=cron_expr,
+                prompt=prompt,
+                recurring=recurring,
+                permanent=permanent,
+            )
+        except ValueError as exc:
+            return ToolResult(output=str(exc), is_error=True)
+
+        flags = []
+        if recurring:
+            flags.append("recurring")
+        if permanent:
+            flags.append("permanent")
+        flag_str = f" ({', '.join(flags)})" if flags else ""
+
+        return ToolResult(
+            output=(
+                f"Scheduled task {task.id}{flag_str}\n"
+                f"  Cron: {task.cron}\n"
+                f"  Prompt: {task.prompt}"
+            )
+        )

llm_code/tools/cron_delete.py

@@ -0,0 +1,49 @@
+"""CronDeleteTool — delete a scheduled cron task."""
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from llm_code.cron.storage import CronStorage
+from llm_code.tools.base import PermissionLevel, Tool, ToolResult
+
+
+class CronDeleteInput(BaseModel):
+    task_id: str
+
+
+class CronDeleteTool(Tool):
+    def __init__(self, storage: CronStorage) -> None:
+        self._storage = storage
+
+    @property
+    def name(self) -> str:
+        return "cron_delete"
+
+    @property
+    def description(self) -> str:
+        return "Delete a scheduled cron task by ID."
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "task_id": {"type": "string", "description": "ID of the task to delete"},
+            },
+            "required": ["task_id"],
+        }
+
+    @property
+    def required_permission(self) -> PermissionLevel:
+        return PermissionLevel.FULL_ACCESS
+
+    @property
+    def input_model(self) -> type[CronDeleteInput]:
+        return CronDeleteInput
+
+    def execute(self, args: dict) -> ToolResult:
+        task_id = args["task_id"]
+        removed = self._storage.remove(task_id)
+        if not removed:
+            return ToolResult(output=f"Task '{task_id}' not found", is_error=True)
+        return ToolResult(output=f"Deleted task {task_id}")

llm_code/tools/cron_list.py

@@ -0,0 +1,51 @@
+"""CronListTool — list all scheduled cron tasks."""
+from __future__ import annotations
+
+from llm_code.cron.storage import CronStorage
+from llm_code.tools.base import PermissionLevel, Tool, ToolResult
+
+
+class CronListTool(Tool):
+    def __init__(self, storage: CronStorage) -> None:
+        self._storage = storage
+
+    @property
+    def name(self) -> str:
+        return "cron_list"
+
+    @property
+    def description(self) -> str:
+        return "List all scheduled cron tasks with their status."
+
+    @property
+    def input_schema(self) -> dict:
+        return {"type": "object", "properties": {}}
+
+    @property
+    def required_permission(self) -> PermissionLevel:
+        return PermissionLevel.READ_ONLY
+
+    def is_read_only(self, args: dict) -> bool:
+        return True
+
+    def is_concurrency_safe(self, args: dict) -> bool:
+        return True
+
+    def execute(self, args: dict) -> ToolResult:
+        tasks = self._storage.list_all()
+        if not tasks:
+            return ToolResult(output="No scheduled tasks.")
+
+        lines: list[str] = [f"Scheduled tasks ({len(tasks)}):"]
+        for t in tasks:
+            flags = []
+            if t.recurring:
+                flags.append("recurring")
+            if t.permanent:
+                flags.append("permanent")
+            flag_str = f" [{', '.join(flags)}]" if flags else ""
+            fired = f", last fired: {t.last_fired_at:%Y-%m-%d %H:%M}" if t.last_fired_at else ""
+            lines.append(
+                f"  {t.id}  {t.cron}  \"{t.prompt}\"{flag_str}{fired}"
+            )
+        return ToolResult(output="\n".join(lines))

llm_code/tools/deferred.py

@@ -0,0 +1,92 @@
+"""Deferred tool loading: keeps visible tool list small by hiding rarely-used tools."""
+from __future__ import annotations
+
+from llm_code.api.types import ToolDefinition
+
+# Core tools always visible regardless of max_visible limit
+CORE_TOOLS: frozenset[str] = frozenset(
+    {
+        "read_file",
+        "write_file",
+        "edit_file",
+        "glob_search",
+        "grep_search",
+        "bash",
+        "agent",
+        "tool_search",
+    }
+)
+
+
+class DeferredToolManager:
+    """Manages splitting tool definitions into visible and deferred sets.
+
+    Core tools are always visible. Additional tools are shown up to max_visible;
+    the rest are deferred until the LLM calls tool_search to unlock them.
+    """
+
+    def __init__(self) -> None:
+        self._unlocked: set[str] = set()
+        # Track the last deferred list for search
+        self._deferred: list[ToolDefinition] = []
+
+    def select_tools(
+        self,
+        all_defs: list[ToolDefinition],
+        max_visible: int = 20,
+    ) -> tuple[list[ToolDefinition], list[ToolDefinition]]:
+        """Partition tool definitions into (visible, deferred).
+
+        Core tools and any unlocked tools are always visible. Non-core tools
+        fill remaining slots up to max_visible; the rest go to deferred.
+
+        Returns:
+            A 2-tuple of (visible_defs, deferred_defs).
+        """
+        all_names = {d.name for d in all_defs}
+
+        # Always-visible: core tools present in all_defs + previously unlocked
+        always_visible_names = (CORE_TOOLS | self._unlocked) & all_names
+
+        visible: list[ToolDefinition] = []
+        deferred: list[ToolDefinition] = []
+
+        for d in all_defs:
+            if d.name in always_visible_names:
+                visible.append(d)
+
+        # Fill remaining slots with non-core, non-unlocked tools
+        remaining_slots = max_visible - len(visible)
+        for d in all_defs:
+            if d.name not in always_visible_names:
+                if remaining_slots > 0:
+                    visible.append(d)
+                    remaining_slots -= 1
+                else:
+                    deferred.append(d)
+
+        # Store for search
+        self._deferred = deferred
+        return visible, deferred
+
+    def search_tools(
+        self, query: str, deferred: list[ToolDefinition]
+    ) -> list[ToolDefinition]:
+        """Fuzzy-match query against name and description of deferred tools.
+
+        Matching is case-insensitive substring search against both the tool
+        name and description.
+
+        Returns:
+            List of matching ToolDefinition objects.
+        """
+        q = query.lower()
+        results: list[ToolDefinition] = []
+        for d in deferred:
+            if q in d.name.lower() or q in d.description.lower():
+                results.append(d)
+        return results
+
+    def unlock_tool(self, name: str) -> None:
+        """Mark a tool as unlocked so it appears in visible set on future calls."""
+        self._unlocked.add(name)