traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/approval.py

@@ -0,0 +1,219 @@
+"""Decide which tool calls run without asking the user."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import PurePosixPath
+from typing import Any
+
+from traceforge.tools.base import Tool, ToolKind
+from traceforge.tools.files import dangerous_command, simple_command
+
+
+class ApprovalMode(StrEnum):
+    ASK = "ask"  # ask before any write or shell command
+    AUTO = "auto"  # writes and simple commands run; dangerous commands ask
+    YOLO = "yolo"  # everything runs (still blocks the destructive patterns when no approver)
+    READ_ONLY = "read-only"  # writes and shell are rejected
+
+
+class Decision(StrEnum):
+    ALLOW = "allow"
+    ASK = "ask"
+    DENY = "deny"
+
+
+@dataclass
+class ApprovalRequest:
+    tool: str
+    kind: ToolKind
+    arguments: dict[str, Any]
+    summary: str
+    dangerous: bool = False
+
+
+@dataclass
+class ApprovalAnswer:
+    """A richer answer than yes/no from an interactive approver."""
+
+    approved: bool
+    scope: str = "once"  # once | tool (this tool, rest of the session) | auto (switch to auto)
+    reason: str = ""
+
+
+Approver = Callable[[ApprovalRequest], Awaitable["bool | ApprovalAnswer"]]
+
+AUTO_SHELL_LEVELS = ("simple", "any", "dangerous")
+
+# Files that change what traceforge or other tools execute later. Auto mode still asks
+# before writing them, so an agent cannot quietly install a hook or a CI job.
+_SENSITIVE_WRITE = re.compile(
+    r"(^|/)(\.git|\.github|\.gitlab-ci\.yml|\.circleci|\.husky|\.vscode|\.devcontainer|\.ssh)(/|$)"
+    r"|(^|/)\.traceforge/(hooks\.(ya?ml|json)|config\.ya?ml|skills/)"
+    r"|(^|/)(\.env[^/]*|\.bashrc|\.zshrc|\.profile|\.mcp\.json|setup\.py|conftest\.py|"
+    r"sitecustomize\.py|Makefile|Dockerfile|docker-compose\.ya?ml|\.pre-commit-config\.yaml)$",
+    re.IGNORECASE,
+)
+
+
+def sensitive_write(path: str) -> bool:
+    text = PurePosixPath(str(path).replace("\\", "/")).as_posix()
+    return bool(_SENSITIVE_WRITE.search(text))
+
+
+# In auto mode, writes to these still ask: they configure tools, CI, hooks or the
+# environment, so a bad write there runs code or changes more than the design.
+_SENSITIVE_DIRS = {
+    ".git",
+    ".github",
+    ".gitlab",
+    ".circleci",
+    ".husky",
+    ".vscode",
+    ".devcontainer",
+    ".claude",
+    ".cursor",
+    ".ssh",
+    "hooks",
+}
+_SENSITIVE_FILES = {
+    ".bashrc",
+    ".zshrc",
+    ".profile",
+    ".bash_profile",
+    ".gitattributes",
+    ".gitmodules",
+    ".mcp.json",
+    ".pre-commit-config.yaml",
+    "makefile",
+    "dockerfile",
+    "docker-compose.yml",
+    "docker-compose.yaml",
+    "pyproject.toml",
+    "setup.py",
+    "setup.cfg",
+    "requirements.txt",
+    "package.json",
+    "conftest.py",
+    "sitecustomize.py",
+    "claude.md",
+    "agents.md",
+    "traceforge.md",
+}
+_SCRIPT_SUFFIXES = {".sh", ".bash", ".zsh", ".fish", ".ps1", ".bat", ".cmd", ".command"}
+_FILE_TOOLS = {"write_file", "edit_file", "multi_edit", "write_binary_file", "delete_file"}
+
+
+def sensitive_path(raw: Any) -> bool:
+    """True for paths whose change needs a person even in auto mode."""
+    if not isinstance(raw, str) or not raw.strip():
+        return False
+    parts = [part.lower() for part in raw.replace("\\", "/").split("/") if part not in ("", ".")]
+    if not parts:
+        return False
+    if any(part in _SENSITIVE_DIRS for part in parts[:-1]):
+        return True
+    name = parts[-1]
+    if parts[:2] == [".traceforge", "hooks.yaml"] or name in {"hooks.yaml", "hooks.json"}:
+        return True
+    return name in _SENSITIVE_FILES or any(name.endswith(s) for s in _SCRIPT_SUFFIXES)
+
+
+def summarize_call(tool: Tool, arguments: dict[str, Any]) -> str:
+    if tool.name == "execute":
+        prefix = "(background) " if arguments.get("background") else ""
+        return f"{prefix}$ {arguments.get('command', '')}"
+    if tool.name == "delete_file":
+        recursive = " (recursive)" if arguments.get("recursive") else ""
+        return f"delete {arguments.get('path', '')}{recursive}"
+    if tool.name in _FILE_TOOLS:
+        return f"{tool.name} {arguments.get('path', '')}"
+    target = arguments.get(tool.target_arg) if tool.target_arg else None
+    return f"{tool.name}" + (f" {target}" if target else "")
+
+
+def decide(
+    mode: ApprovalMode, tool: Tool, arguments: dict[str, Any], auto_shell: str = "any"
+) -> Decision:
+    if tool.kind in {ToolKind.READ, ToolKind.INTERACTIVE}:
+        return Decision.ALLOW
+    if mode is ApprovalMode.READ_ONLY:
+        return Decision.DENY
+    dangerous = tool.kind is ToolKind.SHELL and dangerous_command(str(arguments.get("command", "")))
+    if mode is ApprovalMode.YOLO:
+        return Decision.ASK if dangerous else Decision.ALLOW
+    if mode is ApprovalMode.AUTO:
+        if tool.name == "delete_file" and arguments.get("recursive"):
+            return Decision.ASK
+        if tool.name in _FILE_TOOLS and sensitive_path(arguments.get("path")):
+            return Decision.ASK
+        if tool.kind is ToolKind.WRITE:
+            target = arguments.get(tool.target_arg or "path") if tool.target_arg else None
+            return Decision.ASK if target and sensitive_write(str(target)) else Decision.ALLOW
+        if dangerous:
+            return Decision.ALLOW if auto_shell == "dangerous" else Decision.ASK
+        if auto_shell in {"any", "dangerous"}:
+            return Decision.ALLOW
+        return Decision.ALLOW if simple_command(str(arguments.get("command", ""))) else Decision.ASK
+    return Decision.ASK
+
+
+class ApprovalPolicy:
+    def __init__(
+        self,
+        mode: ApprovalMode | str = ApprovalMode.ASK,
+        approver: Approver | None = None,
+        auto_shell: str = "any",
+    ):
+        self.mode = ApprovalMode(mode)
+        self.approver = approver
+        self.auto_shell = auto_shell if auto_shell in AUTO_SHELL_LEVELS else "any"
+        self._always: set[str] = set()
+        # Tool calls of one model step can run concurrently; questions to the user must not.
+        self._prompt_lock = asyncio.Lock()
+
+    def allow_tool_for_session(self, tool_name: str) -> None:
+        self._always.add(tool_name)
+
+    async def check(self, tool: Tool, arguments: dict[str, Any]) -> tuple[bool, str]:
+        decision = decide(self.mode, tool, arguments, self.auto_shell)
+        if decision is Decision.ALLOW:
+            return True, ""
+        if decision is Decision.DENY:
+            return False, f"{tool.name} is not allowed in {self.mode.value} mode"
+        dangerous = tool.kind is ToolKind.SHELL and dangerous_command(
+            str(arguments.get("command", ""))
+        )
+        if tool.name in self._always and not dangerous:
+            return True, ""
+        if self.approver is None:
+            return False, (
+                f"{tool.name} needs approval and no one is available to approve it. "
+                "Use a read-only approach, or ask the user to rerun with --approve auto."
+            )
+        request = ApprovalRequest(
+            tool.name, tool.kind, arguments, summarize_call(tool, arguments), dangerous
+        )
+        async with self._prompt_lock:
+            if tool.name in self._always and not dangerous:
+                return True, ""  # approved "for the session" while this call waited
+            answer = await self.approver(request)
+            if isinstance(answer, ApprovalAnswer):
+                if answer.approved and answer.scope == "tool":
+                    self.allow_tool_for_session(tool.name)
+                elif answer.approved and answer.scope == "auto" and self.mode is ApprovalMode.ASK:
+                    self.mode = ApprovalMode.AUTO
+        if isinstance(answer, ApprovalAnswer):
+            if answer.approved:
+                return True, ""
+            reason = answer.reason.strip()
+            return False, (
+                f"the user declined this action: {reason}"
+                if reason
+                else "the user declined this action"
+            )
+        return (True, "") if answer else (False, "the user declined this action")

traceforge/attachments.py

@@ -0,0 +1,346 @@
+"""Images, screenshots, file mentions and pasted KiCad snippets in a user prompt.
+
+* Images (a photo of a board, a datasheet figure, a screenshot of KiCad) are sent to
+  the model as image content blocks. They come from ``@path`` mentions, the
+  ``/attach`` command, the clipboard (``/paste``, Ctrl+V in the terminal UI) or an
+  ACP client.
+* ``@path`` mentions of other files are listed for the agent, which reads them with
+  its file tools, so large files never inflate the prompt.
+* A pasted KiCad S-expression (a footprint, a symbol, part of a board) is recognised
+  and wrapped in ``<kicad_snippet>`` so the agent knows what it is looking at.
+
+The content blocks use the Anthropic Messages shape; the OpenAI adapter converts
+them (see :func:`traceforge.providers.to_openai_input`).
+"""
+
+from __future__ import annotations
+
+import base64
+import re
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+MAX_IMAGE_BYTES = 5 * 1024 * 1024  # the per-image limit of the Messages API
+MAX_IMAGES = 20
+MAX_SNIPPET_CHARS = 1_000_000
+IMAGE_SUFFIXES = {".png", ".jpg", ".jpeg", ".gif", ".webp"}
+KICAD_HEADS = (
+    "kicad_pcb",
+    "kicad_sch",
+    "kicad_symbol_lib",
+    "footprint",
+    "module",
+    "symbol",
+    "lib_symbols",
+    "segment",
+    "via",
+    "zone",
+    "net",
+    "wire",
+    "junction",
+    "label",
+    "global_label",
+    "hierarchical_label",
+    "gr_line",
+    "gr_rect",
+    "gr_text",
+    "fp_line",
+    "fp_text",
+    "pad",
+    "property",
+    "net_class",
+)
+_MENTION = re.compile(r"(?<![\w@])@((?:\\ |[^\s@])+)")
+_HEAD = re.compile(r"\(\s*(" + "|".join(KICAD_HEADS) + r")[\s)]")
+
+
+class AttachmentError(ValueError):
+    """An attachment could not be used."""
+
+
+def sniff_image_type(data: bytes) -> str | None:
+    """Media type from the file signature (not the name)."""
+    if data.startswith(b"\x89PNG\r\n\x1a\n"):
+        return "image/png"
+    if data.startswith(b"\xff\xd8\xff"):
+        return "image/jpeg"
+    if data[:6] in (b"GIF87a", b"GIF89a"):
+        return "image/gif"
+    if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return "image/webp"
+    return None
+
+
+@dataclass
+class ImageAttachment:
+    data: bytes
+    media_type: str
+    name: str = "image"
+
+    @classmethod
+    def from_bytes(cls, data: bytes, name: str = "image") -> ImageAttachment:
+        if not data:
+            raise AttachmentError(f"{name} is empty")
+        media_type = sniff_image_type(data)
+        if media_type is None:
+            raise AttachmentError(f"{name} is not a PNG, JPEG, GIF or WebP image")
+        if len(data) > MAX_IMAGE_BYTES:
+            data, media_type = _shrink(data, name)
+        return cls(data, media_type, name)
+
+    @classmethod
+    def from_path(cls, path: Path) -> ImageAttachment:
+        try:
+            data = Path(path).read_bytes()
+        except OSError as exc:
+            raise AttachmentError(f"cannot read {path}: {exc}") from exc
+        return cls.from_bytes(data, Path(path).name)
+
+    @classmethod
+    def from_base64(cls, payload: str, name: str = "image") -> ImageAttachment:
+        try:
+            data = base64.b64decode(payload, validate=True)
+        except ValueError as exc:
+            raise AttachmentError(f"{name} is not valid base64") from exc
+        return cls.from_bytes(data, name)
+
+    def block(self) -> dict[str, Any]:
+        return {
+            "type": "image",
+            "source": {
+                "type": "base64",
+                "media_type": self.media_type,
+                "data": base64.b64encode(self.data).decode("ascii"),
+            },
+        }
+
+    def describe(self) -> str:
+        return f"{self.name} ({self.media_type}, {len(self.data) // 1024} KB)"
+
+
+def _shrink(data: bytes, name: str) -> tuple[bytes, str]:
+    """Downscale an oversized image when Pillow is available."""
+    try:
+        import io
+
+        from PIL import Image
+    except ImportError:
+        raise AttachmentError(
+            f"{name} is {len(data) // (1024 * 1024)} MB; images must be under 5 MB "
+            "(install Pillow to have large images scaled down automatically)"
+        ) from None
+    with Image.open(io.BytesIO(data)) as image:
+        image = image.convert("RGB")
+        scale = 1.0
+        while True:
+            scale *= 0.75
+            size = (max(1, int(image.width * scale)), max(1, int(image.height * scale)))
+            out = io.BytesIO()
+            image.resize(size).save(out, format="JPEG", quality=85)
+            if out.tell() <= MAX_IMAGE_BYTES or scale < 0.05:
+                return out.getvalue(), "image/jpeg"
+
+
+# ------------------------------------------------------------------ clipboard
+
+
+def clipboard_image() -> ImageAttachment | None:
+    """An image from the system clipboard, or None when there is none."""
+    commands: list[list[str]] = []
+    if sys.platform == "darwin":
+        commands.append(["pngpaste", "-"])
+    elif sys.platform.startswith("linux"):
+        commands.append(["wl-paste", "--no-newline", "--type", "image/png"])
+        commands.append(["xclip", "-selection", "clipboard", "-t", "image/png", "-o"])
+    elif sys.platform == "win32":  # pragma: no cover
+        commands.append(
+            [
+                "powershell",
+                "-NoProfile",
+                "-Command",
+                "Add-Type -AssemblyName System.Windows.Forms;"
+                "$i=[Windows.Forms.Clipboard]::GetImage();if($i){$m=New-Object IO.MemoryStream;"
+                "$i.Save($m,[Drawing.Imaging.ImageFormat]::Png);"
+                "[Console]::OpenStandardOutput().Write($m.ToArray(),0,$m.Length)}",
+            ]
+        )
+    for command in commands:
+        if shutil.which(command[0]) is None:
+            continue
+        try:
+            result = subprocess.run(command, capture_output=True, timeout=3, check=False)
+        except (OSError, subprocess.TimeoutExpired):
+            continue
+        if result.returncode == 0 and sniff_image_type(result.stdout):
+            try:
+                return ImageAttachment.from_bytes(result.stdout, "clipboard.png")
+            except AttachmentError:
+                return None
+    if sys.platform == "darwin":
+        return _macos_clipboard_image()
+    return None
+
+
+def _macos_clipboard_image() -> ImageAttachment | None:  # pragma: no cover - macOS only
+    import tempfile
+
+    if shutil.which("osascript") is None:
+        return None
+    with tempfile.TemporaryDirectory() as tmp:
+        target = Path(tmp) / "clip.png"
+        script = (
+            "set png to the clipboard as «class PNGf»\n"
+            f'set f to open for access POSIX file "{target}" with write permission\n'
+            "write png to f\nclose access f"
+        )
+        try:
+            subprocess.run(["osascript", "-e", script], capture_output=True, timeout=3, check=False)
+            if target.exists():
+                return ImageAttachment.from_path(target)
+        except (OSError, subprocess.TimeoutExpired, AttachmentError):
+            return None
+    return None
+
+
+# --------------------------------------------------------------- KiCad snippets
+
+
+def find_kicad_snippet(text: str) -> tuple[int, int] | None:
+    """Span of the first balanced KiCad S-expression in ``text``, if any."""
+    if len(text) > MAX_SNIPPET_CHARS:
+        return None
+    for match in _HEAD.finditer(text):
+        start = match.start()
+        end = _balanced_end(text, start)
+        if end is not None:
+            return start, end
+    return None
+
+
+def _balanced_end(text: str, start: int) -> int | None:
+    depth = 0
+    quoted = escaped = False
+    for index in range(start, len(text)):
+        char = text[index]
+        if escaped:
+            escaped = False
+        elif quoted and char == "\\":
+            escaped = True
+        elif char == '"':
+            quoted = not quoted
+        elif not quoted and char == "(":
+            depth += 1
+        elif not quoted and char == ")":
+            depth -= 1
+            if depth == 0:
+                return index + 1
+    return None
+
+
+def looks_like_kicad_snippet(text: str) -> bool:
+    """True when the whole text is one KiCad S-expression."""
+    stripped = text.strip()
+    span = find_kicad_snippet(stripped)
+    return span is not None and span == (0, len(stripped))
+
+
+def split_kicad_snippet(text: str) -> tuple[str, str | None]:
+    """(the user's own words, the snippet) for a prompt that contains a pasted snippet.
+
+    Only multi-line expressions count, so a short inline mention like ``(net GND)`` in a
+    sentence stays part of the sentence.
+    """
+    span = find_kicad_snippet(text)
+    if span is None:
+        return text, None
+    snippet = text[span[0] : span[1]]
+    if "\n" not in snippet and len(snippet) < 200:
+        return text, None
+    prose = (text[: span[0]] + text[span[1] :]).strip()
+    return prose, snippet
+
+
+# --------------------------------------------------------------------- prompts
+
+
+@dataclass
+class PreparedPrompt:
+    """A user prompt turned into content blocks."""
+
+    text: str
+    images: list[ImageAttachment] = field(default_factory=list)
+    mentioned: list[str] = field(default_factory=list)
+    snippet: str | None = None
+    problems: list[str] = field(default_factory=list)
+
+    def blocks(self) -> list[dict[str, Any]]:
+        parts: list[str] = []
+        text = self.text.strip()
+        if self.snippet is not None:
+            parts.append(
+                "The user pasted this KiCad S-expression snippet:\n<kicad_snippet>\n"
+                f"{self.snippet.strip()}\n</kicad_snippet>"
+            )
+            text = text or "Explain this KiCad snippet and point out anything wrong with it."
+        if self.mentioned:
+            listing = "\n".join(f"- {path}" for path in self.mentioned)
+            parts.append(f"Files the user mentioned (read them as needed):\n{listing}")
+        if self.images and not text:
+            text = "Look at the attached image(s)."
+        blocks: list[dict[str, Any]] = [image.block() for image in self.images[:MAX_IMAGES]]
+        body = "\n\n".join([*parts, text]) if parts else text
+        if body:
+            blocks.append({"type": "text", "text": body})
+        return blocks
+
+    def summary(self) -> str:
+        bits = []
+        if self.images:
+            bits.append(f"{len(self.images)} image(s)")
+        if self.mentioned:
+            bits.append(f"{len(self.mentioned)} file mention(s)")
+        if self.snippet is not None:
+            bits.append("a KiCad snippet")
+        return ", ".join(bits)
+
+
+def prepare_prompt(
+    text: str, workspace: Path, images: list[ImageAttachment] | None = None
+) -> PreparedPrompt:
+    """Resolve ``@path`` mentions and pasted snippets; ``images`` are already attached."""
+    prepared = PreparedPrompt(text, list(images or []))
+    root = Path(workspace).resolve()
+    prose, snippet = split_kicad_snippet(text)
+    if snippet is not None:
+        prepared.snippet = snippet
+        text = prose
+    for match in _MENTION.finditer(text):
+        raw = match.group(1).replace("\\ ", " ").rstrip(".,;:)!?")
+        candidate = (root / raw).resolve() if not Path(raw).is_absolute() else Path(raw).resolve()
+        if not candidate.exists():
+            continue
+        if candidate.suffix.lower() in IMAGE_SUFFIXES and candidate.is_file():
+            try:
+                prepared.images.append(ImageAttachment.from_path(candidate))
+            except AttachmentError as exc:
+                prepared.problems.append(str(exc))
+            continue
+        try:
+            shown = candidate.relative_to(root).as_posix()
+        except ValueError:
+            prepared.problems.append(f"{raw} is outside the workspace; the agent cannot read it")
+            continue
+        if shown not in prepared.mentioned:
+            prepared.mentioned.append(shown + ("/" if candidate.is_dir() else ""))
+    prepared.text = text
+    return prepared
+
+
+def image_blocks_count(content: Any) -> int:
+    if not isinstance(content, list):
+        return 0
+    return sum(1 for block in content if isinstance(block, dict) and block.get("type") == "image")