kiwimatecoder 0.1.0__py3-none-any.whl

kiwimatecoder/tools/selection.py

@@ -0,0 +1,108 @@
+"""Apply a hunk-level approval selection to file-changing tool arguments."""
+
+from __future__ import annotations
+
+import difflib
+from collections.abc import Sequence
+from typing import Any
+
+from kiwimatecoder import hunks
+from kiwimatecoder.session import Session
+from kiwimatecoder.tools.edit_file import compute_new_content
+from kiwimatecoder.tools.paths import PathError, display_path, resolve_in_workspace
+
+
+def _unified_diff(old_text: str, new_text: str, rel: str) -> str:
+    return "".join(
+        difflib.unified_diff(
+            old_text.splitlines(keepends=True),
+            new_text.splitlines(keepends=True),
+            fromfile=rel,
+            tofile=rel,
+            n=3,
+        )
+    )
+
+
+def _selection_in_range(selected: Sequence[int], count: int) -> bool:
+    return all(1 <= index <= count for index in selected)
+
+
+def _select_write(
+    args: dict[str, Any], session: Session, selected: Sequence[int]
+) -> dict[str, Any] | None:
+    path = str(args.get("path") or "")
+    if not path:
+        return None
+    content = str(args.get("content", "") or "")
+    try:
+        resolved = resolve_in_workspace(path, session.workspace_root)
+    except PathError:
+        return None
+    if resolved.exists():
+        old_text = resolved.read_text(encoding="utf-8", errors="replace")
+    else:
+        old_text = ""
+    rel = display_path(resolved, session.workspace_root)
+    diff = _unified_diff(old_text, content, rel)
+    if not diff:
+        return {**args}
+    parsed = hunks.split_hunks(diff)
+    if not parsed or not _selection_in_range(selected, len(parsed)):
+        return None
+    new_content = hunks.apply_selected_hunks(old_text, diff, selected)
+    if new_content == old_text:
+        return None
+    return {**args, "content": new_content}
+
+
+def _select_edit(
+    args: dict[str, Any], session: Session, selected: Sequence[int]
+) -> dict[str, Any] | None:
+    path = str(args.get("path") or "")
+    if not path:
+        return None
+    try:
+        resolved = resolve_in_workspace(path, session.workspace_root)
+    except PathError:
+        return None
+    if not resolved.exists():
+        return None
+    old_text = resolved.read_text(encoding="utf-8", errors="replace")
+    new_text = compute_new_content(old_text, args)
+    if new_text is None:
+        return None
+    rel = display_path(resolved, session.workspace_root)
+    diff = _unified_diff(old_text, new_text, rel)
+    if not diff:
+        return {**args}
+    parsed = hunks.split_hunks(diff)
+    if not parsed or not _selection_in_range(selected, len(parsed)):
+        return None
+    new_content = hunks.apply_selected_hunks(old_text, diff, selected)
+    if new_content == old_text:
+        return None
+    return {
+        **args,
+        "old_string": old_text,
+        "new_string": new_content,
+        "replace_all": False,
+    }
+
+
+def select_hunks(
+    name: str,
+    args: dict[str, Any],
+    session: Session,
+    selected_hunks: Sequence[int],
+) -> dict[str, Any] | None:
+    """Return ``args`` rewritten to apply only ``selected_hunks``.
+
+    Returns ``None`` when the selection cannot be applied; callers should treat
+    that as a denial. Tools without hunk support also return ``None``.
+    """
+    if name == "write_file":
+        return _select_write(args, session, selected_hunks)
+    if name == "edit_file":
+        return _select_edit(args, session, selected_hunks)
+    return None

kiwimatecoder/tools/shell.py

@@ -0,0 +1,158 @@
+"""Persistent-shell tools: stateful commands and background process control.
+
+``shell`` runs a command in the session's long-lived shell, so ``cd`` and
+exported environment variables persist between calls. ``shell_jobs`` starts,
+lists, reads, and kills detached background commands. Both are approval-gated.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kiwimatecoder.remote import remote_preview
+from kiwimatecoder.shell import (
+    ShellDisabledError,
+    ShellError,
+    ShellJobLimitError,
+    get_shell,
+)
+from kiwimatecoder.tools.base import FunctionTool, ToolResult
+
+
+def preview(args: dict[str, Any], session: Any) -> str:
+    """Return the command text (and remote wrapper) for the approval prompt."""
+    command = str(args.get("command", ""))
+    return remote_preview(command, workspace=session.workspace_root)
+
+
+def jobs_preview(args: dict[str, Any], session: Any) -> str:
+    """Return a short description of a background-job action for approval."""
+    action = str(args.get("action") or "").strip().lower()
+    if action == "start":
+        command = str(args.get("command", ""))
+        return f"start: {remote_preview(command, workspace=session.workspace_root)}"
+    if action in ("output", "kill"):
+        return f"{action}: {args.get('id', '')}"
+    return action or "list"
+
+
+def _run_shell(args: dict[str, Any], session: Any) -> ToolResult:
+    command = str(args.get("command") or "")
+    if not command.strip():
+        return ToolResult.error("'command' is required")
+    try:
+        exit_code, output = get_shell(session).run(command)
+    except ShellDisabledError as exc:
+        return ToolResult.error(str(exc))
+    except ShellError as exc:
+        return ToolResult.error(str(exc))
+
+    parts = [output] if output else []
+    parts.append(f"[exit code: {exit_code}]")
+    return ToolResult(content="\n".join(parts), ok=exit_code == 0)
+
+
+def _shell_jobs(args: dict[str, Any], session: Any) -> ToolResult:
+    action = str(args.get("action") or "").strip().lower()
+    if not action:
+        return ToolResult.error("'action' is required (start, list, output, kill)")
+    manager = get_shell(session)
+
+    if action == "start":
+        command = str(args.get("command") or "")
+        if not command.strip():
+            return ToolResult.error("'command' is required for action 'start'")
+        try:
+            job_id = manager.start_background(command)
+        except ShellJobLimitError as exc:
+            return ToolResult.error(str(exc))
+        except ShellError as exc:
+            return ToolResult.error(str(exc))
+        job = manager.get_background(job_id)
+        output_path = str(job.output_path) if job is not None else ""
+        return ToolResult(
+            content=(
+                f"Started background job {job_id} (output at {output_path}). "
+                "Use shell_jobs with action 'output' to read it."
+            )
+        )
+
+    if action == "list":
+        jobs = manager.list_background()
+        if not jobs:
+            return ToolResult(content="No background jobs.")
+        lines = []
+        for job in jobs:
+            state = "running" if job.alive else f"exited ({job.exit_code})"
+            lines.append(f"{job.id}  [{state}]  {job.command}")
+        return ToolResult(content="\n".join(lines))
+
+    job_id = str(args.get("id") or "").strip()
+    if not job_id:
+        return ToolResult.error(f"'id' is required for action '{action}'")
+
+    if action == "output":
+        text = manager.output_background(job_id)
+        if text is None:
+            return ToolResult.error(f"Unknown background job '{job_id}'")
+        return ToolResult(content=text or "(no output yet)")
+
+    if action == "kill":
+        if not manager.kill_background(job_id):
+            return ToolResult.error(f"Unknown background job '{job_id}'")
+        return ToolResult(content=f"Killed background job {job_id}.")
+
+    return ToolResult.error("Unknown action; choose start, list, output, or kill")
+
+
+shell_tool = FunctionTool(
+    name="shell",
+    description=(
+        "Run a command in a persistent shell that keeps its working directory "
+        "and exported environment between calls. Prefer this over run_bash when "
+        "state must persist across commands (e.g. `cd`, `export`, virtualenv "
+        "activation). Returns the exit code and combined output."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "command": {
+                "type": "string",
+                "description": "The shell command to execute.",
+            },
+        },
+        "required": ["command"],
+    },
+    func=_run_shell,
+    runs=True,
+)
+
+shell_jobs_tool = FunctionTool(
+    name="shell_jobs",
+    description=(
+        "Manage background shell processes. Actions: start (run a command "
+        "detached; 'command' required), list, output ('id' required), kill "
+        "('id' required). Background output is captured to a file."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "action": {
+                "type": "string",
+                "enum": ["start", "list", "output", "kill"],
+                "description": "The background-job action to perform.",
+            },
+            "command": {
+                "type": "string",
+                "description": "Command to start in the background (action 'start').",
+            },
+            "id": {
+                "type": "string",
+                "description": "Background job id (actions 'output' and 'kill').",
+            },
+        },
+        "required": ["action"],
+    },
+    func=_shell_jobs,
+    runs=True,
+)

kiwimatecoder/tools/skill.py

@@ -0,0 +1,46 @@
+"""load_skill tool: fetch an Agent Skill's full instructions on demand."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kiwimatecoder.session import Session
+from kiwimatecoder.skills import discover_skills, load_skill as _load_skill
+from kiwimatecoder.tools.base import FunctionTool, ToolResult
+
+
+def _load_skill_tool(args: dict[str, Any], session: Session) -> ToolResult:
+    name = str(args.get("name") or "").strip()
+    if not name:
+        return ToolResult.error("'name' is required")
+    content = _load_skill(name, session.workspace_root)
+    if content is None:
+        available = [skill.name for skill in discover_skills(session.workspace_root)]
+        hint = ", ".join(available) if available else "none"
+        return ToolResult.error(
+            f"Unknown skill '{name}'. Available skills: {hint}."
+        )
+    return ToolResult(content=content)
+
+
+load_skill_tool = FunctionTool(
+    name="load_skill",
+    description=(
+        "Load the full instructions for an available Agent Skill by name. "
+        "Use this when the current task matches a skill listed in the system "
+        "prompt; the return value is the skill's complete markdown guide."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "name": {
+                "type": "string",
+                "description": "Name of the skill to load, exactly as listed.",
+            }
+        },
+        "required": ["name"],
+    },
+    func=_load_skill_tool,
+    writes=False,
+    runs=False,
+)

kiwimatecoder/tools/task.py

@@ -0,0 +1,61 @@
+"""task tool: delegate a focused investigation to a subagent.
+
+The tool is declared with ``runs=True`` so spawning a subagent is
+approval-gated in ASK mode: the subagent can write files and run commands, and
+its own actions still go through the normal permission gate.
+
+Execution itself is special-cased in :class:`kiwimatecoder.agent.Agent` (the
+subagent runs an async loop), so the sync callable below only exists for
+dispatch paths without an agent driving them.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kiwimatecoder.session import Session
+from kiwimatecoder.tools.base import FunctionTool, ToolResult
+
+
+def _run_task(args: dict[str, Any], session: Session) -> ToolResult:
+    return ToolResult.error(
+        "The task tool must run inside the agent loop; use it from a normal "
+        "conversation turn."
+    )
+
+
+task_tool = FunctionTool(
+    name="task",
+    description=(
+        "Delegate a focused, self-contained investigation to a subagent that "
+        "runs in its own context with the same workspace and tools. It cannot "
+        "ask the user questions and it cannot delegate further, so put every "
+        "needed decision in the prompt. It returns a final report and its "
+        "intermediate tool output stays out of this conversation. Its file "
+        "writes and commands still require the same approvals as yours."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "description": {
+                "type": "string",
+                "description": "Short (3-5 word) description of the task.",
+            },
+            "prompt": {
+                "type": "string",
+                "description": (
+                    "Complete, self-contained instructions for the subagent, "
+                    "including what to report back."
+                ),
+            },
+            "model": {
+                "type": "string",
+                "description": "Optional model override for this subagent.",
+            },
+        },
+        "required": ["description", "prompt"],
+    },
+    func=_run_task,
+    writes=False,
+    runs=True,
+)

kiwimatecoder/tools/todo.py

@@ -0,0 +1,77 @@
+"""update_todos tool: keep an explicit task list for multi-step work."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kiwimatecoder.session import Session
+from kiwimatecoder.tools.base import FunctionTool, ToolResult
+
+VALID_STATUSES = ("pending", "in_progress", "completed")
+_MARKERS = {"pending": "[ ]", "in_progress": "[~]", "completed": "[x]"}
+
+
+def _update_todos(args: dict[str, Any], session: Session) -> ToolResult:
+    raw = args.get("todos")
+    if not isinstance(raw, list):
+        return ToolResult.error("'todos' must be a list of {content, status} objects")
+
+    cleaned: list[dict[str, str]] = []
+    for item in raw:
+        if not isinstance(item, dict):
+            return ToolResult.error(
+                "each todo must be an object with 'content' and 'status'"
+            )
+        content = str(item.get("content") or "").strip()
+        status = str(item.get("status") or "pending").strip().lower()
+        if not content:
+            return ToolResult.error("todo 'content' is required")
+        if status not in VALID_STATUSES:
+            return ToolResult.error(
+                f"Unknown todo status '{status}'. "
+                f"Choose: {', '.join(VALID_STATUSES)}."
+            )
+        cleaned.append({"content": content, "status": status})
+
+    session.todos = cleaned
+    if not cleaned:
+        return ToolResult(content="Task list cleared.")
+
+    lines = [f"{_MARKERS[t['status']]} {t['content']}" for t in cleaned]
+    done = sum(1 for todo in cleaned if todo["status"] == "completed")
+    return ToolResult(content="\n".join(lines) + f"\n\n{done}/{len(cleaned)} complete.")
+
+
+update_todos_tool = FunctionTool(
+    name="update_todos",
+    description=(
+        "Replace the task list with the given items. Use it for multi-step work: "
+        "keep exactly one task 'in_progress' at a time and mark tasks "
+        "'completed' as soon as they are done. Passing an empty list clears it."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "todos": {
+                "type": "array",
+                "description": "The full task list, in order.",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "content": {
+                            "type": "string",
+                            "description": "Short imperative description of the task.",
+                        },
+                        "status": {
+                            "type": "string",
+                            "enum": list(VALID_STATUSES),
+                        },
+                    },
+                    "required": ["content", "status"],
+                },
+            }
+        },
+        "required": ["todos"],
+    },
+    func=_update_todos,
+)

kiwimatecoder/tools/web.py

@@ -0,0 +1,146 @@
+"""web_fetch and web_search tools: read the web with citation-friendly output."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kiwimatecoder import config
+from kiwimatecoder import web as web_module
+from kiwimatecoder.session import Session
+from kiwimatecoder.tools.base import FunctionTool, ToolResult
+
+DEFAULT_FETCH_MAX_CHARS = 50_000
+DEFAULT_SEARCH_COUNT = 5
+MAX_SEARCH_COUNT = 10
+
+
+def _fetch_max_chars(args: dict[str, Any], default: int) -> tuple[int, str | None]:
+    raw = args.get("max_chars")
+    if raw is None:
+        return default, None
+    try:
+        value = int(raw)
+    except (TypeError, ValueError):
+        return default, "'max_chars' must be an integer"
+    return max(config.WEB_MAX_CHARS_MIN, min(value, config.WEB_MAX_CHARS_MAX)), None
+
+
+def _web_fetch(args: dict[str, Any], session: Session) -> ToolResult:
+    del session  # fetching does not depend on the workspace
+    url = str(args.get("url") or "").strip()
+    if not url:
+        return ToolResult.error("'url' is required")
+    settings = config.get_web()
+    max_chars, error = _fetch_max_chars(args, settings["max_chars"])
+    if error:
+        return ToolResult.error(error)
+    try:
+        final_url, text = web_module.fetch_url(
+            url,
+            timeout=settings["timeout"],
+            max_chars=max_chars,
+            allow_local=settings["allow_local"],
+        )
+    except web_module.WebError as exc:
+        return ToolResult.error(str(exc))
+
+    if not text.strip():
+        return ToolResult(
+            content=f"Fetched {final_url} but found no readable text content."
+        )
+    truncated = len(text) > max_chars
+    if truncated:
+        text = text[:max_chars] + f"\n\n[truncated at {max_chars} characters]"
+    header = f"URL: {final_url}\n\n" if final_url != url else ""
+    return ToolResult(content=header + text)
+
+
+def _web_search(args: dict[str, Any], session: Session) -> ToolResult:
+    del session
+    query = str(args.get("query") or "").strip()
+    if not query:
+        return ToolResult.error("'query' is required")
+    raw_count = args.get("count")
+    try:
+        count = int(raw_count) if raw_count is not None else DEFAULT_SEARCH_COUNT
+    except (TypeError, ValueError):
+        return ToolResult.error("'count' must be an integer")
+    count = max(1, min(count, MAX_SEARCH_COUNT))
+
+    settings = config.get_web()
+    try:
+        results = web_module.search_web(
+            query,
+            count=count,
+            timeout=settings["timeout"],
+            provider=settings["search_provider"],
+            api_key=settings["search_api_key"] or None,
+        )
+    except web_module.WebError as exc:
+        return ToolResult.error(str(exc))
+
+    if not results:
+        return ToolResult(content=f"No results found for {query!r}.")
+    lines = [f"Results for {query!r} ({len(results)}):", ""]
+    for index, result in enumerate(results, 1):
+        lines.append(f"{index}. {result.title}")
+        lines.append(f"   {result.url}")
+        if result.snippet:
+            lines.append(f"   {result.snippet}")
+        lines.append("")
+    lines.append("Cite the URLs you use; prefer official documentation over mirrors.")
+    return ToolResult(content="\n".join(lines).rstrip())
+
+
+web_fetch_tool = FunctionTool(
+    name="web_fetch",
+    description=(
+        "Fetch a web page and return its readable text. Use it to consult "
+        "official documentation and cite the URL in your answer. Prefer "
+        "official docs and primary sources over aggregator pages. HTML is "
+        "converted to text; binary files are summarized. Local and private "
+        "addresses are blocked unless enabled in /config web."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "url": {
+                "type": "string",
+                "description": "Absolute http(s) URL to fetch.",
+            },
+            "max_chars": {
+                "type": "integer",
+                "description": (
+                    "Maximum characters to return (defaults to the configured "
+                    "limit)."
+                ),
+            },
+        },
+        "required": ["url"],
+    },
+    func=_web_fetch,
+)
+
+web_search_tool = FunctionTool(
+    name="web_search",
+    description=(
+        "Search the web and return result titles, URLs, and snippets. Use it "
+        "to find current information, then fetch the most promising URLs. "
+        "Always cite the URLs you rely on and prefer official documentation."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "Search query.",
+            },
+            "count": {
+                "type": "integer",
+                "description": f"Number of results (1-{MAX_SEARCH_COUNT}, default 5).",
+            },
+        },
+        "required": ["query"],
+    },
+    func=_web_search,
+)

kiwimatecoder/tools/write_file.py

@@ -0,0 +1,83 @@
+"""write_file tool: create or overwrite a file in the workspace."""
+
+from __future__ import annotations
+
+import difflib
+from typing import Any
+
+from kiwimatecoder.session import Session
+from kiwimatecoder.tools.base import FunctionTool, ToolResult
+from kiwimatecoder.tools.paths import (
+    PathError,
+    atomic_write_text,
+    display_path,
+    resolve_in_workspace,
+    workspace_ref,
+)
+
+
+def preview(args: dict[str, Any], session: Session) -> str:
+    """Return a human-readable preview (diff) for the approval prompt."""
+    path = str(args.get("path", "") or "")
+    content = str(args.get("content", "") or "")
+    try:
+        resolved = resolve_in_workspace(path, session.workspace_root)
+    except PathError as exc:
+        return str(exc)
+    rel = display_path(resolved, session.workspace_root)
+    if resolved.exists():
+        old = resolved.read_text(encoding="utf-8", errors="replace").splitlines(keepends=True)
+        new = content.splitlines(keepends=True)
+        diff = "".join(
+            difflib.unified_diff(old, new, fromfile=rel, tofile=rel, n=3)
+        )
+        return diff or f"(no changes to {rel})"
+    return f"+++ create {rel}\n" + "\n".join(
+        f"+{line}" for line in content.splitlines()
+    )
+
+
+def _write_file(args: dict[str, Any], session: Session) -> ToolResult:
+    path = str(args.get("path") or "")
+    if not path:
+        return ToolResult.error("'path' is required")
+    content = str(args.get("content", "") or "")
+    try:
+        resolved = resolve_in_workspace(path, session.workspace_root)
+    except PathError as exc:
+        return ToolResult.error(str(exc))
+
+    existed = resolved.exists()
+    resolved.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        atomic_write_text(resolved, content)
+    except OSError as exc:
+        return ToolResult.error(f"Could not write file: {exc}")
+    session.record_touched(workspace_ref(resolved, session.workspace_root))
+    verb = "Updated" if existed else "Created"
+    return ToolResult(content=f"{verb} {path} ({len(content)} bytes).")
+
+
+write_file_tool = FunctionTool(
+    name="write_file",
+    description=(
+        "Create a new file or overwrite an existing one with the given content. "
+        "Parent directories are created automatically."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": "Path relative to the workspace root.",
+            },
+            "content": {
+                "type": "string",
+                "description": "Full content to write to the file.",
+            },
+        },
+        "required": ["path", "content"],
+    },
+    func=_write_file,
+    writes=True,
+)