kiwimatecoder 0.1.0__py3-none-any.whl

kiwimatecoder/routing.py

@@ -0,0 +1,65 @@
+"""Per-turn model routing.
+
+A deliberately small, pure heuristic: short, plain user messages can be sent
+to a cheaper "simple" model, while anything that looks like real engineering
+work stays on the session's model. Nothing here touches the network or global
+state, so the decision is trivial to unit-test.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+#: A fenced code block means the user is showing/handling code.
+_CODE_FENCE = "```"
+
+#: A token like ``main.py`` or ``tests/test_x.py`` looks like a file path.
+_FILE_PATH_RE = re.compile(r"\S+\.\w{1,6}")
+
+#: A slash command such as ``/help`` or ``/config set``.
+_SLASH_COMMAND_RE = re.compile(r"(?:^|\s)/[A-Za-z]")
+
+
+def _contains_exclude_keyword(text: str, keywords: Any) -> bool:
+    if not isinstance(keywords, list):
+        return False
+    lowered = text.lower()
+    for keyword in keywords:
+        word = str(keyword).strip().lower()
+        if word and re.search(rf"\b{re.escape(word)}\b", lowered):
+            return True
+    return False
+
+
+def choose_turn_model(
+    user_input: str, session: Any, routing: dict[str, Any]
+) -> str | None:
+    """Return the simple model to use for this turn, or None to stay put.
+
+    The override applies only when routing is enabled, a simple model is
+    configured, the message is short, and it shows no sign of real work: no
+    code fence, no file path, no slash command, and no exclude keyword
+    (whole-word, case-insensitive).
+    """
+    if not routing.get("enabled"):
+        return None
+    simple_model = str(routing.get("simple_model") or "").strip()
+    if not simple_model:
+        return None
+    text = user_input or ""
+    try:
+        max_chars = int(routing.get("simple_max_chars") or 0)
+    except (TypeError, ValueError):
+        return None
+    if max_chars <= 0 or len(text) > max_chars:
+        return None
+    if _CODE_FENCE in text:
+        return None
+    if _FILE_PATH_RE.search(text):
+        return None
+    if _SLASH_COMMAND_RE.search(text):
+        return None
+    if _contains_exclude_keyword(text, routing.get("exclude_keywords")):
+        return None
+    return simple_model

kiwimatecoder/sandbox.py

@@ -0,0 +1,169 @@
+"""Optional OS-level command sandboxing for ``run_bash`` and the shell tools.
+
+This module is pure command construction: it decides *what* to execute (macOS
+seatbelt via ``sandbox-exec`` or Linux bubblewrap via ``bwrap``) but never runs
+anything itself. That keeps it trivially testable and lets callers fall back to
+an unsandboxed execution when a backend is missing.
+
+The sandbox is **off by default** and is a damage-limiter, not a security
+boundary against a hostile model: the profile still allows broad reads and,
+unless network is disabled, full network access. Only enable it in workspaces
+you trust. Windows has no supported backend here.
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+from kiwimatecoder.config import get_sandbox
+
+FALLBACK_WARNING = (
+    "Sandboxing is enabled but no supported backend is available on this "
+    "platform; running the command without a sandbox."
+)
+
+
+def sandbox_available(platform: str | None = None) -> tuple[str, str] | None:
+    """Detect the sandbox backend for ``platform`` (defaults to ``sys.platform``).
+
+    Returns ``(backend, path)`` where ``backend`` is ``"seatbelt"`` on macOS or
+    ``"bwrap"`` on Linux, or ``None`` when the platform is unsupported or the
+    backend executable is not installed.
+    """
+    system = platform if platform is not None else sys.platform
+    if system == "darwin":
+        path = shutil.which("sandbox-exec")
+        return ("seatbelt", path) if path else None
+    if system.startswith("linux"):
+        path = shutil.which("bwrap")
+        return ("bwrap", path) if path else None
+    return None
+
+
+def _sbpl_string(value: object) -> str:
+    """Quote a path for an SBPL profile string."""
+    text = str(value).replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{text}"'
+
+
+def seatbelt_profile(
+    *,
+    workspace: str | Path,
+    extra_writable: Sequence[str] = (),
+    network: bool = True,
+) -> str:
+    """Build the seatbelt (SBPL) profile used by :func:`seatbelt_command`.
+
+    Reads are allowed broadly; writes are limited to the workspace, ``/tmp``
+    (and its macOS alias ``/private/tmp``), and any ``extra_writable`` paths.
+    Network access is allowed only when ``network`` is true.
+    """
+    writable = [str(Path(workspace).expanduser()), "/tmp", "/private/tmp"]
+    writable.extend(str(Path(path).expanduser()) for path in extra_writable)
+    write_rule = " ".join(f"(subpath {_sbpl_string(path)})" for path in writable)
+    network_rule = "(allow network*)" if network else "(deny network*)"
+    return "\n".join(
+        [
+            "(version 1)",
+            "(deny default)",
+            "(allow process*)",
+            "(allow file-read*)",
+            f"(allow file-write* {write_rule})",
+            "(allow sysctl-read)",
+            network_rule,
+        ]
+    )
+
+
+def seatbelt_command(
+    command: str,
+    *,
+    workspace: str | Path,
+    extra_writable: Sequence[str] = (),
+    network: bool = True,
+) -> list[str]:
+    """Build ``sandbox-exec -p <profile> /bin/sh -c <command>``."""
+    profile = seatbelt_profile(
+        workspace=workspace, extra_writable=extra_writable, network=network
+    )
+    return ["sandbox-exec", "-p", profile, "/bin/sh", "-c", command]
+
+
+def bwrap_command(
+    command: str,
+    *,
+    workspace: str | Path,
+    extra_writable: Sequence[str] = (),
+    network: bool = True,
+) -> list[str]:
+    """Build a bubblewrap invocation with a read-only root and writable workspace.
+
+    ``/`` is bind-mounted read-only, the workspace read-write, ``/tmp`` is a
+    private tmpfs, and ``--unshare-net`` is added when ``network`` is false.
+    """
+    ws = str(Path(workspace).expanduser())
+    argv = [
+        "bwrap",
+        "--ro-bind",
+        "/",
+        "/",
+        "--bind",
+        ws,
+        ws,
+        "--dev",
+        "/dev",
+        "--proc",
+        "/proc",
+        "--tmpfs",
+        "/tmp",
+    ]
+    for path in extra_writable:
+        resolved = str(Path(path).expanduser())
+        argv.extend(["--bind", resolved, resolved])
+    if not network:
+        argv.append("--unshare-net")
+    argv.extend(["/bin/sh", "-c", command])
+    return argv
+
+
+def wrap_command(
+    command: str,
+    *,
+    workspace: str | Path,
+    cfg: dict[str, Any] | None = None,
+) -> tuple[list[str], str | None]:
+    """Return the argv to execute plus an optional warning for the caller.
+
+    Disabled settings return the plain ``["/bin/sh", "-c", command]`` and no
+    warning. Enabled settings with no usable backend also return the plain
+    argv, with a warning the caller should surface before running.
+    """
+    settings = get_sandbox(cfg)
+    fallback = ["/bin/sh", "-c", command]
+    if not settings["enabled"]:
+        return fallback, None
+    available = sandbox_available()
+    if available is None:
+        return fallback, FALLBACK_WARNING
+    backend, path = available
+    if backend == "seatbelt":
+        argv = seatbelt_command(
+            command,
+            workspace=workspace,
+            extra_writable=settings["extra_writable"],
+            network=settings["network"],
+        )
+    else:
+        argv = bwrap_command(
+            command,
+            workspace=workspace,
+            extra_writable=settings["extra_writable"],
+            network=settings["network"],
+        )
+    if path:
+        argv[0] = path
+    return argv, None

kiwimatecoder/sdk.py

@@ -0,0 +1,146 @@
+"""Embedded SDK for programmatic, headless agent runs.
+
+The SDK wraps the same implementation the CLI's ``-p/--print`` mode uses, so a
+host application gets identical session setup, tool behavior, permissions, and
+cost accounting without spawning a subprocess.
+
+Example::
+
+    from kiwimatecoder.sdk import run_agent_sync
+
+    result = run_agent_sync("Summarize README.md", workspace=".", mode="plan")
+    if result.success:
+        print(result.text)
+
+``run_agent`` is the async entry point for hosts that already own an event
+loop. Both entry points return a :class:`RunResult`. Approvals default to
+deny; pass ``confirm`` to grant them (for example
+``confirm=lambda summary, preview: True``) or run with
+``mode="auto-accept"``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable
+
+from rich.console import Console
+
+from kiwimatecoder.headless import run_agent_once
+from kiwimatecoder.permissions import ConfirmFn, PermissionMode
+from kiwimatecoder.session import Session
+
+EventCallback = Callable[[str, dict[str, Any]], None]
+
+
+@dataclass
+class RunResult:
+    """The outcome of one programmatic agent run.
+
+    ``usage`` totals the billed prompt/completion tokens across every model
+    call in the turn. ``cost_usd`` is ``None`` when the model has no price
+    entry (see :mod:`kiwimatecoder.pricing`). ``error`` is set only when
+    ``success`` is False.
+    """
+
+    text: str
+    usage: dict[str, int]
+    cost_usd: float | None
+    provider: str
+    model: str
+    mode: str
+    tools_used: list[str]
+    messages: int
+    success: bool
+    error: str | None = None
+
+
+async def run_agent(
+    prompt: str,
+    *,
+    workspace: str | Path | None = None,
+    provider: str | None = None,
+    model: str | None = None,
+    mode: PermissionMode | str = PermissionMode.ASK,
+    on_event: EventCallback | None = None,
+    max_turns: int = 30,
+    console: Console | None = None,
+    session: Session | None = None,
+    confirm: ConfirmFn | None = None,
+) -> RunResult:
+    """Run one agentic turn and return its :class:`RunResult`.
+
+    ``workspace`` defaults to the current directory. ``provider``, ``model``,
+    and ``mode`` override the configured defaults for this run only. Text is
+    written to ``console`` when one is supplied, otherwise the run is silent.
+    ``on_event`` receives ``(name, payload)`` for every render event. Without
+    ``confirm`` (and outside auto-accept/plan modes) approvals are denied.
+    """
+    outcome = await run_agent_once(
+        prompt,
+        workspace=workspace,
+        provider=provider,
+        model=model,
+        mode=mode,
+        confirm=confirm,
+        on_event=on_event,
+        max_turns=max_turns,
+        console=console,
+        session=session,
+        render_text=True,
+    )
+    return RunResult(
+        text=outcome.text,
+        usage=outcome.usage,
+        cost_usd=outcome.cost_usd,
+        provider=outcome.provider,
+        model=outcome.model,
+        mode=outcome.mode,
+        tools_used=outcome.tools_used,
+        messages=outcome.messages,
+        success=outcome.success,
+        error=outcome.error,
+    )
+
+
+def run_agent_sync(
+    prompt: str,
+    *,
+    workspace: str | Path | None = None,
+    provider: str | None = None,
+    model: str | None = None,
+    mode: PermissionMode | str = PermissionMode.ASK,
+    on_event: EventCallback | None = None,
+    max_turns: int = 30,
+    console: Console | None = None,
+    session: Session | None = None,
+    confirm: ConfirmFn | None = None,
+) -> RunResult:
+    """Blocking wrapper around :func:`run_agent`.
+
+    Raises :class:`RuntimeError` when called from inside a running event loop;
+    ``await run_agent(...)`` instead.
+    """
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(
+            run_agent(
+                prompt,
+                workspace=workspace,
+                provider=provider,
+                model=model,
+                mode=mode,
+                on_event=on_event,
+                max_turns=max_turns,
+                console=console,
+                session=session,
+                confirm=confirm,
+            )
+        )
+    raise RuntimeError(
+        "run_agent_sync() cannot run inside a running event loop; "
+        "await run_agent(...) instead."
+    )