kiwimatecoder 0.1.0__py3-none-any.whl

kiwimatecoder/templates.py

@@ -0,0 +1,108 @@
+"""Custom prompt templates runnable as REPL slash commands.
+
+Users drop Markdown files named after the command into
+``~/.kiwimatecoder/commands/`` or ``<workspace>/.kiwimatecoder/commands/``.
+The file body is the prompt; ``$ARGUMENTS`` is replaced with whatever the user
+typed after the command name. A workspace template wins over a user-level
+template with the same name.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from kiwimatecoder import config
+
+WORKSPACE_COMMANDS_DIR = Path(".kiwimatecoder") / "commands"
+USER_COMMANDS_DIR_NAME = "commands"
+MAX_TEMPLATE_BYTES = 16 * 1024
+MAX_NAME_LENGTH = 40
+ARGUMENTS_TOKEN = "$ARGUMENTS"
+
+_NAME_PATTERN = re.compile(r"[a-z0-9][a-z0-9_-]*\Z")
+
+
+@dataclass(frozen=True)
+class TemplateInfo:
+    """One discovered prompt template."""
+
+    name: str
+    path: Path
+    description: str
+    body: str
+
+
+def _valid_name(name: str) -> bool:
+    return bool(name) and len(name) <= MAX_NAME_LENGTH and bool(_NAME_PATTERN.match(name))
+
+
+def _first_line(text: str, fallback: str) -> str:
+    for raw_line in text.splitlines():
+        line = raw_line.strip().lstrip("#").strip()
+        if line:
+            return line
+    return fallback
+
+
+def _load_template(path: Path) -> TemplateInfo | None:
+    name = path.stem.strip().lower()
+    if not _valid_name(name):
+        return None
+    try:
+        raw = path.read_bytes()
+    except OSError:
+        return None
+    if b"\x00" in raw[:1024]:
+        return None
+    body = raw[:MAX_TEMPLATE_BYTES].decode("utf-8", "replace")
+    return TemplateInfo(
+        name=name,
+        path=path,
+        description=_first_line(body, name),
+        body=body,
+    )
+
+
+def _template_dirs(workspace_root: Path) -> list[Path]:
+    """Workspace first so it wins name collisions with user templates."""
+    dirs = [workspace_root / WORKSPACE_COMMANDS_DIR]
+    try:
+        dirs.append(config.ensure_config_dir() / USER_COMMANDS_DIR_NAME)
+    except OSError:
+        # An unwritable home directory just means no user-level templates.
+        pass
+    return dirs
+
+
+def discover_templates(workspace_root: Path) -> dict[str, TemplateInfo]:
+    """Return every valid template keyed by command name, sorted by name."""
+    found: dict[str, TemplateInfo] = {}
+    for directory in _template_dirs(workspace_root):
+        if not directory.is_dir():
+            continue
+        for path in sorted(directory.glob("*.md")):
+            template = _load_template(path)
+            if template is None:
+                continue
+            found.setdefault(template.name, template)
+    return dict(sorted(found.items()))
+
+
+def find_template(name: str, workspace_root: Path) -> TemplateInfo | None:
+    """Look up a template by command name; None when unknown or invalid."""
+    key = str(name).strip().lower()
+    if not key:
+        return None
+    return discover_templates(workspace_root).get(key)
+
+
+def render_template(body: str, arguments: str) -> str:
+    """Substitute ``$ARGUMENTS``; append the arguments when the body lacks it."""
+    text = arguments.strip()
+    if ARGUMENTS_TOKEN in body:
+        return body.replace(ARGUMENTS_TOKEN, text)
+    if text:
+        return f"{body}\n\nArguments: {text}"
+    return body

kiwimatecoder/tools/__init__.py

@@ -0,0 +1,190 @@
+"""Tool registry: schema export, dispatch, and approval previews.
+
+A tool is "advertised" to the model via its JSON schema. In PLAN mode only
+read-only tools are advertised (and the permission gate blocks the rest as a
+second line of defense).
+
+The mapping lives in :class:`~kiwimatecoder.tools.registry.ToolRegistry`, which
+also records each tool's source (``"builtin"`` or a plugin label). The module
+level ``TOOLS`` name is that registry and remains dict-compatible.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable
+
+from kiwimatecoder.tools.ask import ask_user_tool
+from kiwimatecoder.tools.base import FunctionTool, ToolResult
+from kiwimatecoder.tools.browser import browser_tool
+from kiwimatecoder.tools.browser import preview as _browser_preview
+from kiwimatecoder.tools.edit_file import edit_file_tool
+from kiwimatecoder.tools.edit_file import preview as _edit_preview
+from kiwimatecoder.tools.forge import forge_tool, forge_write_tool
+from kiwimatecoder.tools.forge import preview as _forge_write_preview
+from kiwimatecoder.tools.git import git_tool, git_write_tool
+from kiwimatecoder.tools.git import preview as _git_write_preview
+from kiwimatecoder.tools.image import (
+    generate_image_tool,
+    generate_video_tool,
+    view_image_tool,
+)
+from kiwimatecoder.tools.image import generate_image_preview as _media_preview
+from kiwimatecoder.tools.image import generate_video_preview as _video_preview
+from kiwimatecoder.tools.io import (
+    http_get_tool,
+    http_request_tool,
+    read_clipboard_tool,
+    write_clipboard_tool,
+)
+from kiwimatecoder.tools.io import http_request_preview as _http_request_preview
+from kiwimatecoder.tools.io import write_clipboard_preview as _clipboard_write_preview
+from kiwimatecoder.tools.list_dir import list_dir_tool
+from kiwimatecoder.tools.lsp import (
+    lsp_definition_tool,
+    lsp_diagnostics_tool,
+    lsp_references_tool,
+)
+from kiwimatecoder.tools.memory import preview as _remember_preview
+from kiwimatecoder.tools.memory import recall_tool, remember_tool
+from kiwimatecoder.tools.read_file import read_file_tool
+from kiwimatecoder.tools.registry import (
+    BUILTIN_SOURCE,
+    PLUGIN_SOURCE,
+    ToolRegistry,
+)
+from kiwimatecoder.tools.run_bash import preview as _bash_preview
+from kiwimatecoder.tools.run_bash import run_bash_tool
+from kiwimatecoder.tools.search import search_tool
+from kiwimatecoder.tools.selection import select_hunks as select_hunks
+from kiwimatecoder.tools.shell import jobs_preview as _shell_jobs_preview
+from kiwimatecoder.tools.shell import preview as _shell_preview
+from kiwimatecoder.tools.shell import shell_jobs_tool, shell_tool
+from kiwimatecoder.tools.skill import load_skill_tool
+from kiwimatecoder.tools.task import task_tool
+from kiwimatecoder.tools.todo import update_todos_tool
+from kiwimatecoder.tools.web import web_fetch_tool, web_search_tool
+from kiwimatecoder.tools.write_file import preview as _write_preview
+from kiwimatecoder.tools.write_file import write_file_tool
+
+if TYPE_CHECKING:
+    from kiwimatecoder.session import Session
+
+_ALL_TOOLS: list[FunctionTool] = [
+    read_file_tool,
+    view_image_tool,
+    generate_image_tool,
+    generate_video_tool,
+    list_dir_tool,
+    search_tool,
+    load_skill_tool,
+    write_file_tool,
+    edit_file_tool,
+    run_bash_tool,
+    shell_tool,
+    shell_jobs_tool,
+    update_todos_tool,
+    task_tool,
+    ask_user_tool,
+    web_fetch_tool,
+    web_search_tool,
+    git_tool,
+    git_write_tool,
+    forge_tool,
+    forge_write_tool,
+    remember_tool,
+    recall_tool,
+    read_clipboard_tool,
+    write_clipboard_tool,
+    http_get_tool,
+    http_request_tool,
+    lsp_diagnostics_tool,
+    lsp_definition_tool,
+    lsp_references_tool,
+    browser_tool,
+]
+
+TOOLS = ToolRegistry()
+for _tool in _ALL_TOOLS:
+    TOOLS.register(_tool, source=BUILTIN_SOURCE)
+
+# Preview functions used by the permission gate to render what an action will do.
+_PREVIEWS: dict[str, Callable[[dict[str, Any], Any], str]] = {
+    "write_file": _write_preview,
+    "edit_file": _edit_preview,
+    "run_bash": _bash_preview,
+    "shell": _shell_preview,
+    "shell_jobs": _shell_jobs_preview,
+    "git_write": _git_write_preview,
+    "forge_write": _forge_write_preview,
+    "remember": _remember_preview,
+    "write_clipboard": _clipboard_write_preview,
+    "http_request": _http_request_preview,
+    "browser": _browser_preview,
+    "generate_image": _media_preview,
+    "generate_video": _video_preview,
+}
+
+
+def register_tool(tool: FunctionTool, source: str = PLUGIN_SOURCE) -> FunctionTool:
+    """Register a tool dynamically and return it.
+
+    Raises ``ValueError`` when the name is already registered; pass through
+    ``TOOLS.register(tool, replace=True)`` to deliberately replace one.
+    """
+    return TOOLS.register(tool, source=source)
+
+
+def unregister_tool(name: str, force: bool = False) -> bool:
+    """Remove a dynamically registered tool; built-ins need ``force=True``."""
+    return TOOLS.unregister(name, force=force)
+
+
+def tool_sources() -> dict[str, list[str]]:
+    """Map each tool source to its sorted tool names."""
+    return TOOLS.sources()
+
+
+def read_only_tools() -> list[FunctionTool]:
+    return TOOLS.read_only()
+
+
+def tool_schemas(read_only: bool = False) -> list[dict[str, Any]]:
+    """Return OpenAI tool schemas, optionally restricted to read-only tools."""
+    return TOOLS.schemas(read_only=read_only)
+
+
+def get_tool(name: str) -> FunctionTool | None:
+    return TOOLS.get(name)
+
+
+def preview(name: str, args: dict[str, Any], session: Session) -> str | None:
+    """Return a human-readable preview of a tool action, or None if not previewable."""
+    fn = _PREVIEWS.get(name)
+    return fn(args, session) if fn else None
+
+
+def dispatch(name: str, args: dict[str, Any], session: Session) -> ToolResult:
+    """Execute a tool by name."""
+    tool = TOOLS.get(name)
+    if tool is None:
+        return ToolResult.error(f"Unknown tool: {name}")
+    return tool.execute(args, session)
+
+
+__all__ = [
+    "BUILTIN_SOURCE",
+    "PLUGIN_SOURCE",
+    "TOOLS",
+    "FunctionTool",
+    "ToolRegistry",
+    "ToolResult",
+    "dispatch",
+    "get_tool",
+    "preview",
+    "read_only_tools",
+    "register_tool",
+    "select_hunks",
+    "tool_schemas",
+    "tool_sources",
+    "unregister_tool",
+]

kiwimatecoder/tools/ask.py

@@ -0,0 +1,62 @@
+"""ask_user tool: ask the user a clarifying question mid-turn."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kiwimatecoder.session import Session
+from kiwimatecoder.tools.base import FunctionTool, ToolResult
+
+
+def _ask_user(args: dict[str, Any], session: Session) -> ToolResult:
+    question = str(args.get("question") or "").strip()
+    if not question:
+        return ToolResult.error("'question' is required")
+
+    raw_options = args.get("options")
+    options = (
+        [str(option).strip() for option in raw_options if str(option).strip()]
+        if isinstance(raw_options, list)
+        else []
+    )
+
+    callback = getattr(session, "ask_user", None)
+    if callback is None:
+        return ToolResult.error(
+            "No interactive user is available to answer; make a reasonable "
+            "assumption and state it."
+        )
+    try:
+        answer = callback(question, options)
+    except (EOFError, KeyboardInterrupt):
+        return ToolResult.error("The user did not answer.")
+    answer = str(answer or "").strip()
+    if not answer:
+        return ToolResult.error("The user gave an empty answer.")
+    return ToolResult(content=f"User answer: {answer}")
+
+
+ask_user_tool = FunctionTool(
+    name="ask_user",
+    description=(
+        "Ask the user a clarifying question when a decision cannot be inferred "
+        "from the workspace. Provide 2-4 concrete options when possible. Use "
+        "sparingly: prefer reading the relevant files first."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "question": {
+                "type": "string",
+                "description": "The question to ask.",
+            },
+            "options": {
+                "type": "array",
+                "description": "Optional suggested answers.",
+                "items": {"type": "string"},
+            },
+        },
+        "required": ["question"],
+    },
+    func=_ask_user,
+)

kiwimatecoder/tools/base.py

@@ -0,0 +1,69 @@
+"""Core types shared by all tools."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Protocol
+
+
+class SessionProtocol(Protocol):
+    """Protocol representing the session interface required by tools."""
+
+    workspace_root: Path
+
+    def record_touched(self, path: str) -> None: ...
+
+
+@dataclass
+class ToolResult:
+    """The outcome of running a tool."""
+
+    content: str
+    ok: bool = True
+
+    @classmethod
+    def error(cls, message: str) -> "ToolResult":
+        return cls(content=f"Error: {message}", ok=False)
+
+
+class Tool(Protocol):
+    """Protocol every tool implements."""
+
+    name: str
+    description: str
+    parameters: dict[str, Any]  # JSON Schema for the function arguments
+    writes: bool  # mutates the filesystem
+    runs: bool  # executes commands
+
+    def execute(self, args: dict[str, Any], session: Any) -> ToolResult: ...
+
+
+@dataclass
+class FunctionTool:
+    """Concrete tool backed by a plain callable."""
+
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    func: Callable[[dict[str, Any], Any], ToolResult]
+    writes: bool = False
+    runs: bool = False
+
+    def execute(self, args: dict[str, Any], session: Any) -> ToolResult:
+        return self.func(args, session)
+
+    def schema(self) -> dict[str, Any]:
+        """Return the OpenAI tool/function schema for this tool."""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+    @property
+    def needs_approval(self) -> bool:
+        return self.writes or self.runs

kiwimatecoder/tools/browser.py

@@ -0,0 +1,261 @@
+"""browser tool: drive an optional headless Chromium page via Playwright.
+
+The tool is approval-gated (``runs=True``) and only advertised while browser
+automation is enabled in config. It never imports Playwright itself; the
+optional driver lives in :mod:`kiwimatecoder.browser`.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from kiwimatecoder import browser, config, images, redaction
+from kiwimatecoder import web as web_module
+from kiwimatecoder.session import Session
+from kiwimatecoder.tools.base import FunctionTool, ToolResult
+from kiwimatecoder.tools.paths import display_path
+
+ACTIONS = ("open", "text", "screenshot", "click", "type", "evaluate", "close")
+
+TEXT_MAX_CHARS = 30_000
+EVALUATE_MAX_CHARS = 10_000
+MIN_TIMEOUT_MS = 1_000
+MAX_TIMEOUT_MS = 120_000
+
+DISABLED_MESSAGE = (
+    "Browser automation is disabled. Enable it with `/config browser enable on` "
+    "(and install the optional extra: pip install 'kiwimatecoder[browser]' && "
+    "playwright install chromium)."
+)
+NO_PAGE_MESSAGE = "No page is open. Use action='open' with a URL first."
+
+
+def _timeout_override(args: dict[str, Any]) -> tuple[int | None, str | None]:
+    raw = args.get("timeout_ms")
+    if raw is None:
+        return None, None
+    try:
+        value = int(raw)
+    except (TypeError, ValueError):
+        return None, "'timeout_ms' must be an integer number of milliseconds"
+    if not MIN_TIMEOUT_MS <= value <= MAX_TIMEOUT_MS:
+        return None, (
+            f"'timeout_ms' must be between {MIN_TIMEOUT_MS} and {MAX_TIMEOUT_MS}"
+        )
+    return value, None
+
+
+def _validate_url(url: str) -> str:
+    try:
+        cleaned = web_module.clean_url(url)
+    except web_module.WebError as exc:
+        raise browser.BrowserError(str(exc)) from exc
+    if web_module.is_local_address(cleaned) and not config.get_web()["allow_local"]:
+        raise browser.BrowserError(
+            "Refusing to open a local or private address. Enable it with "
+            "/config web allow-local on (or config web allow-local on)."
+        )
+    return cleaned
+
+
+def _required(args: dict[str, Any], key: str) -> tuple[str, str | None]:
+    value = str(args.get(key) or "").strip()
+    if not value:
+        return "", f"'{key}' is required"
+    return value, None
+
+
+def _apply_timeout(driver: browser.Driver, timeout_ms: int) -> None:
+    setter = getattr(driver, "set_timeout", None)
+    if callable(setter):
+        setter(timeout_ms)
+
+
+def _format_result(value: Any) -> str:
+    if isinstance(value, str):
+        rendered = value
+    else:
+        try:
+            rendered = json.dumps(value, indent=2, default=str)
+        except (TypeError, ValueError):
+            rendered = repr(value)
+    if len(rendered) > EVALUATE_MAX_CHARS:
+        rendered = rendered[:EVALUATE_MAX_CHARS] + (
+            f"\n\n[truncated at {EVALUATE_MAX_CHARS} characters]"
+        )
+    return rendered or "(no result)"
+
+
+def _screenshot(driver: browser.Driver, session: Session) -> ToolResult:
+    path = browser.screenshot_path(session.workspace_root)
+    driver.screenshot(path)
+    label = display_path(path, session.workspace_root)
+
+    vision = config.get_vision()
+    limit = int(vision["max_images_per_turn"])
+    if len(session.pending_images) >= limit:
+        return ToolResult(
+            content=(
+                f"Saved screenshot to {label}; the per-turn image limit "
+                f"({limit}) is reached, so it was not attached."
+            )
+        )
+    try:
+        entry = images.encode_image(path, int(vision["max_image_bytes"]))
+    except (ValueError, OSError) as exc:
+        return ToolResult(
+            content=f"Saved screenshot to {label} but could not attach it: {exc}"
+        )
+    session.pending_images.append(entry)
+    return ToolResult(content=f"Saved screenshot to {label} and attached it.")
+
+
+def _browser(args: dict[str, Any], session: Session) -> ToolResult:
+    action = str(args.get("action") or "").strip().lower()
+    if action not in ACTIONS:
+        return ToolResult.error(
+            f"Unknown browser action '{action or '?'}'. "
+            f"Choose: {', '.join(ACTIONS)}."
+        )
+    settings = config.get_browser()
+    if not settings["enabled"]:
+        return ToolResult.error(DISABLED_MESSAGE)
+
+    timeout_ms, error = _timeout_override(args)
+    if error:
+        return ToolResult.error(error)
+
+    if action == "close":
+        browser.reset_driver()
+        return ToolResult(content="Browser closed.")
+
+    if action == "open":
+        url = str(args.get("url") or "").strip()
+        if not url:
+            return ToolResult.error("'url' is required for action 'open'")
+        try:
+            cleaned = _validate_url(url)
+            driver = browser.get_driver(settings)
+            if timeout_ms is not None:
+                _apply_timeout(driver, timeout_ms)
+            final_url, title = driver.open(cleaned)
+        except browser.BrowserError as exc:
+            return ToolResult.error(str(exc))
+        return ToolResult(
+            content=f"Opened {final_url}\nTitle: {title or '(no title)'}"
+        )
+
+    page = browser.current_driver()
+    if page is None:
+        return ToolResult.error(NO_PAGE_MESSAGE)
+
+    try:
+        if timeout_ms is not None:
+            _apply_timeout(page, timeout_ms)
+
+        if action == "text":
+            page_text = page.text()
+            if len(page_text) > TEXT_MAX_CHARS:
+                page_text = page_text[:TEXT_MAX_CHARS] + (
+                    f"\n\n[truncated at {TEXT_MAX_CHARS} characters]"
+                )
+            return ToolResult(content=page_text or "(no visible text)")
+
+        if action == "screenshot":
+            return _screenshot(page, session)
+
+        if action == "click":
+            selector, error = _required(args, "selector")
+            if error:
+                return ToolResult.error(error)
+            page.click(selector)
+            return ToolResult(content=f"Clicked {selector}.")
+
+        if action == "type":
+            selector, error = _required(args, "selector")
+            if error:
+                return ToolResult.error(error)
+            text = str(args.get("text") or "")
+            if not text:
+                return ToolResult.error("'text' is required for action 'type'")
+            page.type(selector, text)
+            return ToolResult(content=f"Typed into {selector}.")
+
+        if action == "evaluate":
+            script, error = _required(args, "script")
+            if error:
+                return ToolResult.error(error)
+            return ToolResult(content=_format_result(page.evaluate(script)))
+    except browser.BrowserError as exc:
+        return ToolResult.error(str(exc))
+
+    return ToolResult.error(f"Unsupported browser action '{action}'.")
+
+
+def preview(args: dict[str, Any], session: Session) -> str:
+    """Render the approval preview: ``browser <action> <target>``."""
+    del session
+    action = str(args.get("action") or "?")
+    target = (
+        args.get("url")
+        or args.get("selector")
+        or args.get("script")
+        or args.get("text")
+        or ""
+    )
+    cleaned = redaction.redact(str(target))
+    if len(cleaned) > 80:
+        cleaned = cleaned[:77] + "..."
+    return f"browser {action} {cleaned}".rstrip()
+
+
+browser_tool = FunctionTool(
+    name="browser",
+    description=(
+        "Drive a headless Chromium page when browser automation is enabled. "
+        "Start with action='open' and a URL, then read the page with 'text', "
+        "capture it with 'screenshot' (the image is sent to you), interact "
+        "with 'click'/'type', run JavaScript with 'evaluate', or finish with "
+        "'close'. Local and private addresses are blocked unless enabled in "
+        "/config web. Requires the optional Playwright extra."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "action": {
+                "type": "string",
+                "enum": list(ACTIONS),
+                "description": "Browser action to perform.",
+            },
+            "url": {
+                "type": "string",
+                "description": "Absolute http(s) URL for action 'open'.",
+            },
+            "selector": {
+                "type": "string",
+                "description": "CSS selector for 'click' or 'type'.",
+            },
+            "text": {
+                "type": "string",
+                "description": "Text to enter for action 'type'.",
+            },
+            "script": {
+                "type": "string",
+                "description": "JavaScript expression for action 'evaluate'.",
+            },
+            "timeout_ms": {
+                "type": "integer",
+                "description": (
+                    "Optional per-action timeout in milliseconds "
+                    f"({MIN_TIMEOUT_MS}-{MAX_TIMEOUT_MS}); defaults to the "
+                    "configured browser timeout."
+                ),
+            },
+        },
+        "required": ["action"],
+    },
+    func=_browser,
+    writes=False,
+    runs=True,
+)