pascal-agent 0.3.0__py3-none-any.whl

pascal/tools.py

@@ -0,0 +1,672 @@
+"""Built-in tools for Pascal -- file, desktop, MCP.
+
+Tool hierarchy:
+  1. MCP tools  -- API-level access to business tools (Slack, Gmail, GitHub...)
+  2. File tools -- local filesystem (always available)
+  3. Shell      -- terminal commands via sandbox (in loop.py, not here)
+  4. Desktop    -- screenshot + coordinate click (pyautogui, last resort)
+
+Visual tools return ContentBlock attachments → loop.py passes to LLM → LLM sees the screen.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import logging
+from pathlib import Path
+from typing import Any
+
+from pascal.types import ContentBlock
+
+logger = logging.getLogger(__name__)
+
+# ── Workspace boundary ──────────────────────────────────────────
+
+_workspace: str = ""
+
+
+def set_workspace(path: str) -> None:
+    """Set the workspace root. File tools are restricted to this directory."""
+    global _workspace
+    _workspace = str(Path(path).resolve())
+
+
+def _check_path(path: str) -> str | None:
+    """Return error message if path is outside workspace. None if OK."""
+    if not _workspace:
+        return None  # no restriction if workspace not set
+    try:
+        resolved = Path(path).resolve()
+        workspace = Path(_workspace).resolve()
+        if resolved == workspace or resolved.is_relative_to(workspace):
+            return None
+        return f"Path '{path}' is outside workspace '{_workspace}'"
+    except Exception as e:
+        return f"Invalid path: {e}"
+
+
+# ── Visual helpers ──────────────────────────────────────────────
+
+def _capture_screenshot(region: dict | None = None) -> ContentBlock | None:
+    """Capture screen as base64 PNG at native resolution.
+
+    Full resolution (1920x1080) preserves detail for accurate element identification.
+    Optional region param for zoom: {"x": 100, "y": 100, "w": 400, "h": 300}
+    """
+    try:
+        import pyautogui
+        if region:
+            img = pyautogui.screenshot(region=(region["x"], region["y"], region["w"], region["h"]))
+        else:
+            img = pyautogui.screenshot()
+        buf = io.BytesIO()
+        img.save(buf, format="PNG")
+        return ContentBlock(
+            type="image",
+            data=base64.b64encode(buf.getvalue()).decode(),
+            mime_type="image/png",
+        )
+    except Exception:
+        return None
+
+
+def _image_hash(block: ContentBlock | None) -> str:
+    """Fast hash of image data for noop detection. No LLM call."""
+    if block is None or not block.data:
+        return ""
+    import hashlib
+    return hashlib.md5(block.data.encode()[:8192]).hexdigest()
+
+
+def _check_noop(before_hash: str, after: ContentBlock | None) -> str:
+    """Return warning string if screen unchanged after GUI action, else ''."""
+    if not before_hash or after is None:
+        return ""
+    if before_hash == _image_hash(after):
+        return " [NOOP: screen unchanged — action may have had no effect]"
+    return ""
+
+
+def _paste(text: str) -> None:
+    try:
+        import pyperclip
+        import pyautogui
+        pyperclip.copy(text)
+        pyautogui.hotkey("ctrl", "v")
+    except ImportError:
+        pass
+
+
+# ── File tools (always available) ───────────────────────────────
+
+async def read_file(params: dict[str, Any]) -> dict[str, Any]:
+    path = params.get("path", "")
+    if not path:
+        return {"ok": False, "output": "", "error": "path is required"}
+    boundary_err = _check_path(path)
+    if boundary_err:
+        return {"ok": False, "output": "", "error": boundary_err}
+    try:
+        content = Path(path).read_text(encoding="utf-8")
+        return {"ok": True, "output": content[:10000], "error": ""}
+    except Exception as e:
+        return {"ok": False, "output": "", "error": str(e)}
+
+
+async def write_file(params: dict[str, Any]) -> dict[str, Any]:
+    path = params.get("path", "")
+    content = params.get("content", "")
+    if not path:
+        return {"ok": False, "output": "", "error": "path is required"}
+    boundary_err = _check_path(path)
+    if boundary_err:
+        return {"ok": False, "output": "", "error": boundary_err}
+    try:
+        p = Path(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(content, encoding="utf-8")
+        return {"ok": True, "output": f"Wrote {len(content)} chars to {path}", "error": ""}
+    except Exception as e:
+        return {"ok": False, "output": "", "error": str(e)}
+
+
+async def list_dir(params: dict[str, Any]) -> dict[str, Any]:
+    path = params.get("path", ".")
+    boundary_err = _check_path(path)
+    if boundary_err:
+        return {"ok": False, "output": "", "error": boundary_err}
+    try:
+        entries = sorted(Path(path).iterdir())
+        lines = []
+        for e in entries[:100]:
+            prefix = "d " if e.is_dir() else "f "
+            lines.append(f"{prefix}{e.name}")
+        return {"ok": True, "output": "\n".join(lines), "error": ""}
+    except Exception as e:
+        return {"ok": False, "output": "", "error": str(e)}
+
+
+# ── Desktop tools (optional -- pyautogui) ────────────────────────
+
+async def screenshot(params: dict[str, Any]) -> dict[str, Any]:
+    """Take screenshot. Optional region param for zoom: {"x":100,"y":100,"w":400,"h":300}."""
+    region = params.get("region")
+    attachment = _capture_screenshot(region=region)
+    if attachment is None:
+        return {"ok": False, "output": "", "error": "pyautogui not installed or screenshot failed"}
+    zoom_info = f" (zoomed: {region})" if region else " (full screen, native resolution)"
+    return {"ok": True, "output": f"Screenshot captured{zoom_info}", "error": "", "attachment": attachment}
+
+
+async def click(params: dict[str, Any]) -> dict[str, Any]:
+    """Click at screen pixel coordinates."""
+    try:
+        import pyautogui
+        before_hash = _image_hash(_capture_screenshot())
+        x = int(params.get("x", 0))
+        y = int(params.get("y", 0))
+        button = str(params.get("button", "left"))
+        if button == "double":
+            pyautogui.click(x, y, button="left", clicks=2)
+        else:
+            pyautogui.click(x, y, button=button)
+        after = _capture_screenshot()
+        noop = _check_noop(before_hash, after)
+        return {"ok": True, "output": f"Clicked ({x}, {y}) {button}{noop}", "error": "",
+                "attachment": after}
+    except ImportError:
+        return {"ok": False, "output": "", "error": "pyautogui not installed"}
+    except Exception as e:
+        return {"ok": False, "output": "", "error": str(e)}
+
+
+async def type_text(params: dict[str, Any]) -> dict[str, Any]:
+    try:
+        import pyautogui
+        before_hash = _image_hash(_capture_screenshot())
+        text = params.get("text", "")
+        if text.isascii():
+            pyautogui.typewrite(text, interval=0.02)
+        else:
+            _paste(text)
+        after = _capture_screenshot()
+        noop = _check_noop(before_hash, after)
+        return {"ok": True, "output": f"Typed {len(text)} chars{noop}", "error": "",
+                "attachment": after}
+    except ImportError:
+        return {"ok": False, "output": "", "error": "pyautogui not installed"}
+    except Exception as e:
+        return {"ok": False, "output": "", "error": str(e)}
+
+
+async def hotkey(params: dict[str, Any]) -> dict[str, Any]:
+    try:
+        import pyautogui
+        before_hash = _image_hash(_capture_screenshot())
+        keys = params.get("keys", [])
+        if isinstance(keys, str):
+            keys = keys.split("+")
+        pyautogui.hotkey(*keys)
+        after = _capture_screenshot()
+        noop = _check_noop(before_hash, after)
+        return {"ok": True, "output": f"Pressed {'+'.join(keys)}{noop}", "error": "",
+                "attachment": after}
+    except ImportError:
+        return {"ok": False, "output": "", "error": "pyautogui not installed"}
+    except Exception as e:
+        return {"ok": False, "output": "", "error": str(e)}
+
+
+async def scroll(params: dict[str, Any]) -> dict[str, Any]:
+    """Scroll at screen pixel coordinates."""
+    try:
+        import pyautogui
+        before_hash = _image_hash(_capture_screenshot())
+        clicks = int(params.get("clicks", -3))
+        x = params.get("x")
+        y = params.get("y")
+        if x is not None and y is not None:
+            pyautogui.scroll(clicks, int(x), int(y))
+        else:
+            pyautogui.scroll(clicks)
+        after = _capture_screenshot()
+        noop = _check_noop(before_hash, after)
+        return {"ok": True, "output": f"Scrolled {clicks}{noop}", "error": "",
+                "attachment": after}
+    except ImportError:
+        return {"ok": False, "output": "", "error": "pyautogui not installed"}
+    except Exception as e:
+        return {"ok": False, "output": "", "error": str(e)}
+
+
+# ── Skill tool ─────────────────────────────────────────────────
+
+async def skill(params: dict[str, Any]) -> dict[str, Any]:
+    """Load and return a skill's instructions from ~/.pascal/skills/<name>.md."""
+    name = params.get("name", "").strip()
+    if not name:
+        return {"ok": False, "output": "", "error": "skill name is required"}
+    skill_path = Path.home() / ".pascal" / "skills" / f"{name}.md"
+    if not skill_path.exists():
+        # Try matching by frontmatter name
+        skills_dir = Path.home() / ".pascal" / "skills"
+        if skills_dir.is_dir():
+            for p in skills_dir.glob("*.md"):
+                try:
+                    text = p.read_text(encoding="utf-8")
+                    if text.startswith("---"):
+                        end = text.index("---", 3)
+                        if f"name: {name}" in text[3:end] or f'name: "{name}"' in text[3:end]:
+                            skill_path = p
+                            break
+                except Exception:
+                    continue
+    if not skill_path.exists():
+        return {"ok": False, "output": "", "error": f"Skill '{name}' not found in ~/.pascal/skills/"}
+    try:
+        content = skill_path.read_text(encoding="utf-8")
+        # Strip YAML frontmatter, return the body as instructions
+        if content.startswith("---"):
+            try:
+                end = content.index("---", 3)
+                body = content[end + 3:].strip()
+            except ValueError:
+                body = content
+        else:
+            body = content
+        return {"ok": True, "output": body[:5000], "error": ""}
+    except Exception as e:
+        return {"ok": False, "output": "", "error": str(e)}
+
+
+# ── Channel tools (daemon mode only) ──────────────────────────────
+
+_channel_bot = None
+_owner_chat_id: int | None = None
+_approval_callback = None
+_channel_store = None
+_reply_timestamps: list[float] = []  # Rate limiting for channel_reply
+_REPLY_RATE_LIMIT = 10  # max messages per window
+_REPLY_RATE_WINDOW = 60.0  # seconds
+
+
+def set_channel_bot(bot, owner_chat_id: int, store=None) -> None:
+    """Inject Telegram bot instance + store. Called by daemon.py at startup."""
+    global _channel_bot, _owner_chat_id, _channel_store
+    _channel_bot = bot
+    _owner_chat_id = owner_chat_id
+    _channel_store = store
+
+
+def set_approval_callback(fn) -> None:
+    """Inject approval request function. Called by daemon.py at startup."""
+    global _approval_callback
+    _approval_callback = fn
+
+
+def get_channel_bot():
+    """Public accessor for channel bot instance."""
+    return _channel_bot
+
+
+def get_owner_chat_id() -> int | None:
+    """Public accessor for owner chat ID."""
+    return _owner_chat_id
+
+
+def get_approval_callback():
+    """Public accessor for approval callback."""
+    return _approval_callback
+
+
+async def channel_reply(params: dict[str, Any]) -> dict[str, Any]:
+    """Send a message via the connected channel (Telegram)."""
+    if _channel_bot is None:
+        return {"ok": False, "output": "", "error": "No channel configured (not in daemon mode)"}
+
+    # Rate limiting: prevent LLM from spamming the channel
+    import time
+    now = time.time()
+    cutoff = now - _REPLY_RATE_WINDOW
+    _reply_timestamps[:] = [t for t in _reply_timestamps if t > cutoff]
+    if len(_reply_timestamps) >= _REPLY_RATE_LIMIT:
+        return {"ok": False, "output": "", "error": f"Rate limited: max {_REPLY_RATE_LIMIT} messages per {_REPLY_RATE_WINDOW:.0f}s"}
+    _reply_timestamps.append(now)
+
+    text = params.get("text", "")
+    chat_id = _owner_chat_id or 0
+    # Ignore LLM-provided chat_id to prevent sending to arbitrary users
+    if not text:
+        return {"ok": False, "output": "", "error": "text is required"}
+    if not chat_id:
+        return {"ok": False, "output": "", "error": "no chat_id and no owner configured"}
+    try:
+        await _channel_bot.send_message(chat_id=chat_id, text=text)
+        # Record in conversation history via injected store (if available)
+        if _channel_store is not None:
+            try:
+                _channel_store.push_conversation_turn("telegram", "assistant", text)
+            except Exception:
+                pass
+        return {"ok": True, "output": f"Sent to {chat_id}", "error": ""}
+    except Exception as e:
+        return {"ok": False, "output": "", "error": str(e)}
+
+
+# ── UIA tools (Windows native app control) ─────────────────────
+
+_uia_adapter = None
+
+
+def _get_uia():
+    global _uia_adapter
+    if _uia_adapter is None:
+        from pascal.uia import UIAutomationAdapter
+        _uia_adapter = UIAutomationAdapter()
+    return _uia_adapter
+
+
+def _uia_not_available(tool_name: str) -> dict[str, Any]:
+    return {"ok": False, "output": "", "error": f"{tool_name} requires Windows with pywinauto. Use screenshot tool instead."}
+
+
+async def uia_snapshot(params: dict[str, Any]) -> dict[str, Any]:
+    """Accessibility tree snapshot of a window."""
+    try:
+        from pascal.uia import render_snapshot
+        uia = _get_uia()
+    except ImportError:
+        return _uia_not_available("uia_snapshot")
+    window_title = params.get("window_title")
+    max_depth = int(params.get("max_depth", 3))
+    interactive_only = bool(params.get("interactive_only", False))
+    try:
+        elements = uia.snapshot(
+            window_title=window_title,
+            max_depth=max_depth,
+            interactive_only=interactive_only,
+        )
+        if not elements:
+            return {"ok": False, "output": "", "error": f"No window found or empty tree (title={window_title})"}
+        text = render_snapshot(elements, window_title=window_title or "")
+        return {"ok": True, "output": text, "error": ""}
+    except Exception as e:
+        return {"ok": False, "output": "", "error": str(e)}
+
+
+async def uia_click(params: dict[str, Any]) -> dict[str, Any]:
+    """Click a control by ref ID."""
+    try:
+        uia = _get_uia()
+    except ImportError:
+        return _uia_not_available("uia_click")
+    ref = str(params.get("ref", "")).strip()
+    if not ref:
+        return {"ok": False, "output": "", "error": "ref is required"}
+    try:
+        result = uia.click(ref)
+        return {"ok": result.get("ok", False),
+                "output": f"Clicked {ref}" if result.get("ok") else "",
+                "error": result.get("error", "")}
+    except KeyError as e:
+        return {"ok": False, "output": "", "error": str(e)}
+
+
+async def uia_type(params: dict[str, Any]) -> dict[str, Any]:
+    """Type text into an Edit control by ref ID."""
+    try:
+        uia = _get_uia()
+    except ImportError:
+        return _uia_not_available("uia_type")
+    ref = str(params.get("ref", "")).strip()
+    text = str(params.get("text", ""))
+    if not ref:
+        return {"ok": False, "output": "", "error": "ref is required"}
+    if not text:
+        return {"ok": False, "output": "", "error": "text is required"}
+    clear_first = bool(params.get("clear_first", False))
+    try:
+        result = uia.type_text(ref, text, clear_first=clear_first)
+        return {"ok": result.get("ok", False),
+                "output": f"Typed {len(text)} chars into {ref}" if result.get("ok") else "",
+                "error": result.get("error", "")}
+    except KeyError as e:
+        return {"ok": False, "output": "", "error": str(e)}
+
+
+async def uia_get_text(params: dict[str, Any]) -> dict[str, Any]:
+    """Read text from a control by ref ID."""
+    try:
+        uia = _get_uia()
+    except ImportError:
+        return _uia_not_available("uia_get_text")
+    ref = str(params.get("ref", "")).strip()
+    if not ref:
+        return {"ok": False, "output": "", "error": "ref is required"}
+    try:
+        text = uia.get_text(ref)
+        return {"ok": True, "output": text, "error": ""}
+    except KeyError as e:
+        return {"ok": False, "output": "", "error": str(e)}
+
+
+async def uia_find(params: dict[str, Any]) -> dict[str, Any]:
+    """Search for controls by name or type."""
+    try:
+        uia = _get_uia()
+    except ImportError:
+        return _uia_not_available("uia_find")
+    name = params.get("name")
+    control_type = params.get("control_type")
+    window_title = params.get("window_title")
+    try:
+        elements = uia.find(
+            name=name, control_type=control_type,
+            window_title=window_title,
+        )
+        if not elements:
+            return {"ok": True, "output": "No matching controls found.", "error": ""}
+        lines = [e.to_text() for e in elements]
+        return {"ok": True, "output": "\n".join(lines), "error": ""}
+    except Exception as e:
+        return {"ok": False, "output": "", "error": str(e)}
+
+
+async def uia_wait(params: dict[str, Any]) -> dict[str, Any]:
+    """Wait for a control to appear."""
+    try:
+        uia = _get_uia()
+    except ImportError:
+        return _uia_not_available("uia_wait")
+    name = params.get("name")
+    control_type = params.get("control_type")
+    window_title = params.get("window_title")
+    timeout = float(params.get("timeout", 10.0))
+    timeout = min(timeout, 30.0)  # cap at 30s
+    try:
+        element = uia.wait_for(
+            name=name, control_type=control_type,
+            window_title=window_title, timeout=timeout,
+        )
+        if element is None:
+            return {"ok": False, "output": "", "error": f"Timeout ({timeout}s): control not found"}
+        return {"ok": True, "output": element.to_text(), "error": ""}
+    except Exception as e:
+        return {"ok": False, "output": "", "error": str(e)}
+
+
+async def window_focus(params: dict[str, Any]) -> dict[str, Any]:
+    """Bring a window to the foreground."""
+    try:
+        uia = _get_uia()
+    except ImportError:
+        return _uia_not_available("window_focus")
+    title = params.get("title")
+    try:
+        result = uia.focus_window(window_title=title)
+        return {"ok": result.get("ok", False),
+                "output": f"Focused: {result.get('title', '')}" if result.get("ok") else "",
+                "error": result.get("error", "")}
+    except Exception as e:
+        return {"ok": False, "output": "", "error": str(e)}
+
+
+async def clipboard_get(params: dict[str, Any]) -> dict[str, Any]:
+    """Read text from the system clipboard."""
+    try:
+        from pascal import clipboard as clipboard_utils
+        text = clipboard_utils.get_text()
+        return {"ok": True, "output": text[:10000], "error": ""}
+    except ImportError:
+        return {"ok": False, "output": "", "error": "clipboard_get requires pywin32 or pyperclip"}
+    except Exception as e:
+        return {"ok": False, "output": "", "error": str(e)}
+
+
+async def clipboard_set(params: dict[str, Any]) -> dict[str, Any]:
+    """Write text to the system clipboard."""
+    if "text" not in params:
+        return {"ok": False, "output": "", "error": "text is required"}
+    text = str(params.get("text", ""))
+    try:
+        from pascal import clipboard as clipboard_utils
+        clipboard_utils.set_text(text)
+        return {"ok": True, "output": f"Copied {len(text)} chars to clipboard", "error": ""}
+    except ImportError:
+        return {"ok": False, "output": "", "error": "clipboard_set requires pywin32 or pyperclip"}
+    except Exception as e:
+        return {"ok": False, "output": "", "error": str(e)}
+
+
+# ── App lifecycle tools ──────────────────────────────────────────
+
+async def app_launch(params: dict[str, Any]) -> dict[str, Any]:
+    """Launch an application by name or path."""
+    import subprocess
+    target = params.get("name") or params.get("path") or ""
+    if not target:
+        return {"ok": False, "output": "", "error": "name or path is required"}
+    args = params.get("args", [])
+    if isinstance(args, str):
+        args = args.split()
+    try:
+        cmd = [target] + args
+        subprocess.Popen(cmd, shell=False)
+        return {"ok": True, "output": f"Launched: {target}", "error": ""}
+    except FileNotFoundError:
+        # Try via shell start (Windows)
+        try:
+            import os
+            os.startfile(target)
+            return {"ok": True, "output": f"Opened: {target}", "error": ""}
+        except Exception as e:
+            return {"ok": False, "output": "", "error": f"Cannot launch '{target}': {e}"}
+    except Exception as e:
+        return {"ok": False, "output": "", "error": str(e)}
+
+
+async def app_list(params: dict[str, Any]) -> dict[str, Any]:
+    """List visible windows / running GUI apps."""
+    try:
+        from pascal.uia import UIAutomationAdapter
+        desktop = UIAutomationAdapter()._get_desktop()
+        lines = []
+        for win in desktop.windows():
+            try:
+                title = win.window_text() or ""
+                if title and win.is_visible():
+                    lines.append(title)
+            except Exception:
+                continue
+        return {"ok": True, "output": "\n".join(lines[:50]) or "(no visible windows)", "error": ""}
+    except ImportError:
+        # Fallback: tasklist on Windows
+        import subprocess
+        try:
+            result = subprocess.run(
+                ["tasklist", "/FI", "STATUS eq RUNNING", "/FO", "CSV", "/NH"],
+                capture_output=True, text=True, timeout=5,
+            )
+            return {"ok": True, "output": result.stdout[:4000], "error": ""}
+        except Exception as e:
+            return {"ok": False, "output": "", "error": str(e)}
+
+
+async def app_close(params: dict[str, Any]) -> dict[str, Any]:
+    """Close a window by title."""
+    title = params.get("title") or ""
+    if not title:
+        return {"ok": False, "output": "", "error": "title is required"}
+    try:
+        from pascal.uia import UIAutomationAdapter
+        uia = UIAutomationAdapter()
+        win = uia._find_window(window_title=title)
+        if win is None:
+            return {"ok": False, "output": "", "error": f"Window not found: {title}"}
+        win.close()
+        return {"ok": True, "output": f"Closed: {title}", "error": ""}
+    except Exception as e:
+        return {"ok": False, "output": "", "error": str(e)}
+
+
+# ── Registry ────────────────────────────────────────────────────
+
+TOOL_REGISTRY: dict[str, Any] = {
+    "read_file": read_file,
+    "write_file": write_file,
+    "list_dir": list_dir,
+    "screenshot": screenshot,
+    "click": click,
+    "type_text": type_text,
+    "hotkey": hotkey,
+    "scroll": scroll,
+    "skill": skill,
+    "channel_reply": channel_reply,
+    # UIA tools (Windows native app control)
+    "uia_snapshot": uia_snapshot,
+    "uia_click": uia_click,
+    "uia_type": uia_type,
+    "uia_get_text": uia_get_text,
+    "uia_find": uia_find,
+    "uia_wait": uia_wait,
+    "window_focus": window_focus,
+    "clipboard_get": clipboard_get,
+    "clipboard_set": clipboard_set,
+    # App lifecycle
+    "app_launch": app_launch,
+    "app_list": app_list,
+    "app_close": app_close,
+}
+
+# Effect levels for safety gate in loop.py
+TOOL_EFFECTS: dict[str, str] = {
+    "read_file": "E0", "list_dir": "E0", "screenshot": "E0",
+    "click": "E1", "type_text": "E1", "hotkey": "E1", "scroll": "E1",
+    "write_file": "E2",
+    "skill": "E0",
+    "channel_reply": "E3",
+    # UIA tools
+    "uia_snapshot": "E0", "uia_get_text": "E0", "uia_find": "E0",
+    "uia_wait": "E0",
+    "uia_click": "E1", "window_focus": "E1",
+    "uia_type": "E2",
+    "clipboard_get": "E0",
+    "clipboard_set": "E1",
+    # App lifecycle
+    "app_launch": "E1", "app_list": "E0", "app_close": "E2",
+}
+
+
+async def execute_tool(name: str, params: dict[str, Any]) -> dict[str, Any]:
+    """Execute a registered built-in tool by name."""
+    tool_fn = TOOL_REGISTRY.get(name)
+    if tool_fn is None:
+        return {"ok": False, "output": "", "error": f"Unknown tool: {name}. Available: {', '.join(TOOL_REGISTRY)}"}
+    return await tool_fn(params)
+
+
+async def cleanup_tools():
+    """Clean up persistent tool state."""
+    global _uia_adapter
+    _uia_adapter = None