crabcode 0.1.6__py3-none-win_amd64.whl

crabcode_core/file_lock.py

@@ -0,0 +1,81 @@
+"""Cross-platform advisory file locking for cooperating CrabCode processes."""
+
+from __future__ import annotations
+
+import errno
+import os
+import threading
+import time
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Iterator
+
+try:  # POSIX whole-file locking.
+    import fcntl  # type: ignore
+except ImportError:  # pragma: no cover - exercised only on Windows
+    fcntl = None  # type: ignore[assignment]
+
+try:  # Windows byte-range locking.
+    import msvcrt  # type: ignore
+except ImportError:  # pragma: no cover - exercised only on POSIX
+    msvcrt = None  # type: ignore[assignment]
+
+
+_LOCK_GUARD = threading.Lock()
+_PROCESS_LOCKS: dict[str, threading.Lock] = {}
+_WINDOWS_LOCK_RETRY_SECONDS = 0.05
+
+
+def _process_lock(path: Path) -> threading.Lock:
+    key = os.path.normcase(str(path.resolve()))
+    with _LOCK_GUARD:
+        return _PROCESS_LOCKS.setdefault(key, threading.Lock())
+
+
+def _lock_windows_byte(lock_file: object, *, exclusive: bool) -> None:
+    """Acquire byte zero until it is available instead of timing out after 10s."""
+    if msvcrt is None:  # pragma: no cover - guarded by the caller
+        return
+    handle = lock_file  # Keep the file-like protocol local for type checkers.
+    handle.seek(0, os.SEEK_END)  # type: ignore[attr-defined]
+    if handle.tell() == 0:  # type: ignore[attr-defined]
+        handle.write(b"\0")  # type: ignore[attr-defined]
+        handle.flush()  # type: ignore[attr-defined]
+    mode = msvcrt.LK_NBLCK if exclusive else msvcrt.LK_NBRLCK
+    while True:
+        handle.seek(0)  # type: ignore[attr-defined]
+        try:
+            msvcrt.locking(handle.fileno(), mode, 1)  # type: ignore[attr-defined]
+            return
+        except OSError as exc:
+            if exc.errno not in {errno.EACCES, errno.EAGAIN, errno.EDEADLK}:
+                raise
+            time.sleep(_WINDOWS_LOCK_RETRY_SECONDS)
+
+
+@contextmanager
+def file_lock(path: Path, *, exclusive: bool = True) -> Iterator[None]:
+    """Lock *path* across threads and processes until the context exits.
+
+    All callers must use the same sidecar path. POSIX uses ``flock`` while
+    Windows locks byte zero with ``msvcrt``. The in-process lock also prevents
+    same-process threads from racing on platforms whose OS lock semantics are
+    process- or handle-oriented.
+    """
+    thread_lock = _process_lock(path)
+    with thread_lock:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "a+b") as lock_file:
+            if fcntl is not None:
+                mode = fcntl.LOCK_EX if exclusive else fcntl.LOCK_SH
+                fcntl.flock(lock_file.fileno(), mode)
+            elif msvcrt is not None:
+                _lock_windows_byte(lock_file, exclusive=exclusive)
+            try:
+                yield
+            finally:
+                if fcntl is not None:
+                    fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)
+                elif msvcrt is not None:
+                    lock_file.seek(0)
+                    msvcrt.locking(lock_file.fileno(), msvcrt.LK_UNLCK, 1)

crabcode_core/filesystem.py

@@ -0,0 +1,22 @@
+"""Small filesystem operations shared by atomic writers."""
+
+import os
+from pathlib import Path
+import time
+
+
+def read_text_file(path: str) -> str:
+    """Worker entry point for LSP text synchronization."""
+    return Path(path).read_text(encoding="utf-8")
+
+
+def replace_with_retry(source: Path, target: Path) -> None:
+    """Keep atomic replacement, tolerating brief Windows sharing violations."""
+    for attempt in range(5):
+        try:
+            os.replace(source, target)
+            return
+        except OSError as exc:
+            if os.name != "nt" or getattr(exc, "winerror", None) not in {5, 32, 33} or attempt == 4:
+                raise
+            time.sleep(0.05 * 2**attempt)

crabcode_core/goal.py

@@ -0,0 +1,149 @@
+"""Durable session goals for long-running tasks."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Literal
+from xml.sax.saxutils import escape
+
+
+GoalStatus = Literal["active", "paused", "complete", "blocked"]
+GOAL_STATUSES = frozenset({"active", "paused", "complete", "blocked"})
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+@dataclass
+class Goal:
+    """One session-scoped objective and its lifecycle state."""
+
+    objective: str
+    status: GoalStatus = "active"
+    token_budget: int | None = None
+    tokens_used: int = 0
+    created_at: str = ""
+    updated_at: str = ""
+    completed_at: str | None = None
+
+    def __post_init__(self) -> None:
+        self.objective = self.objective.strip()
+        if not self.objective:
+            raise ValueError("Goal objective cannot be empty")
+        if self.status not in GOAL_STATUSES:
+            raise ValueError(f"Invalid goal status: {self.status}")
+
+        if self.token_budget is not None:
+            self.token_budget = int(self.token_budget)
+            if self.token_budget <= 0:
+                raise ValueError("Goal token budget must be positive")
+        self.tokens_used = int(self.tokens_used)
+        if self.tokens_used < 0:
+            raise ValueError("Goal token usage cannot be negative")
+
+        timestamp = _now_iso()
+        if not self.created_at:
+            self.created_at = timestamp
+        if not self.updated_at:
+            self.updated_at = self.created_at
+        if self.status == "complete" and not self.completed_at:
+            self.completed_at = self.updated_at
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.status in {"complete", "blocked"}
+
+    @property
+    def remaining_tokens(self) -> int | None:
+        if self.token_budget is None:
+            return None
+        return max(0, self.token_budget - self.tokens_used)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "objective": self.objective,
+            "status": self.status,
+            "token_budget": self.token_budget,
+            "tokens_used": self.tokens_used,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "completed_at": self.completed_at,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Goal:
+        """Restore a goal from session metadata."""
+        objective = data.get("objective")
+        if not isinstance(objective, str):
+            raise ValueError("Persisted goal has no objective")
+        status = data.get("status", "active")
+        if status not in GOAL_STATUSES:
+            raise ValueError(f"Invalid persisted goal status: {status}")
+        return cls(
+            objective=objective,
+            status=status,
+            token_budget=data.get("token_budget"),
+            tokens_used=data.get("tokens_used", 0),
+            created_at=str(data.get("created_at") or ""),
+            updated_at=str(data.get("updated_at") or ""),
+            completed_at=(
+                str(data["completed_at"]) if data.get("completed_at") else None
+            ),
+        )
+
+    def with_status(self, status: GoalStatus) -> Goal:
+        """Return a copy with an updated lifecycle status."""
+        if status not in GOAL_STATUSES:
+            raise ValueError(f"Invalid goal status: {status}")
+        timestamp = _now_iso()
+        return Goal(
+            objective=self.objective,
+            status=status,
+            token_budget=self.token_budget,
+            tokens_used=self.tokens_used,
+            created_at=self.created_at,
+            updated_at=timestamp,
+            completed_at=timestamp if status == "complete" else None,
+        )
+
+    def with_added_usage(self, tokens: int) -> Goal:
+        """Return a copy with additional model token usage."""
+        tokens = int(tokens)
+        if tokens <= 0:
+            return self
+        return Goal(
+            objective=self.objective,
+            status=self.status,
+            token_budget=self.token_budget,
+            tokens_used=self.tokens_used + tokens,
+            created_at=self.created_at,
+            updated_at=_now_iso(),
+            completed_at=self.completed_at,
+        )
+
+    def prompt_context(self) -> str:
+        """Format the active goal as stable model context."""
+        lines = [
+            "<active-goal>",
+            "The user has set a persistent goal for this session.",
+            f"Objective: {escape(self.objective)}",
+        ]
+        if self.token_budget is not None:
+            lines.extend(
+                [
+                    f"Token budget: {self.token_budget}",
+                    f"Tokens used: {self.tokens_used}",
+                    f"Tokens remaining: {self.remaining_tokens}",
+                ]
+            )
+        lines.extend(
+            [
+                "Keep this objective as the primary success criterion.",
+                "Do not claim completion until the requested outcome is verified.",
+                "Use update_goal only when the goal is genuinely complete or blocked.",
+                "</active-goal>",
+            ]
+        )
+        return "\n".join(lines)

crabcode_core/hooks/__init__.py

@@ -0,0 +1,5 @@
+"""Hook runtime for settings-defined shell hooks."""
+
+from crabcode_core.hooks.manager import HookManager, HookRunResult
+
+__all__ = ["HookManager", "HookRunResult"]

crabcode_core/hooks/manager.py

@@ -0,0 +1,290 @@
+"""Hooks manager for running settings-defined shell hooks."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from dataclasses import dataclass
+from fnmatch import fnmatch
+from typing import Any
+
+from crabcode_core.subprocess_utils import (
+    decode_subprocess_output,
+    managed_process_command,
+    shell_command,
+    subprocess_group_options,
+    terminate_process_tree,
+)
+
+
+@dataclass
+class HookRunResult:
+    blocked: bool = False
+    feedback: list[str] | None = None
+    details: list[str] | None = None
+
+
+class HookManager:
+    """Execute hooks from settings for supported lifecycle events."""
+
+    _ALIASES: dict[str, tuple[str, ...]] = {
+        "user_prompt_submit": (
+            "user_prompt_submit",
+            "userPromptSubmit",
+            "UserPromptSubmit",
+            "user-prompt-submit",
+            "user-prompt-submit-hook",
+        ),
+        "pre_tool_call": (
+            "pre_tool_call",
+            "preToolCall",
+            "PreToolCall",
+            "pre-tool-call",
+            "pre_tool_use",
+            "preToolUse",
+            "PreToolUse",
+            "pre-tool-use",
+        ),
+        "post_tool_call": (
+            "post_tool_call",
+            "postToolCall",
+            "PostToolCall",
+            "post-tool-call",
+            "post_tool_use",
+            "postToolUse",
+            "PostToolUse",
+            "post-tool-use",
+        ),
+        "pre_compact": (
+            "pre_compact",
+            "preCompact",
+            "PreCompact",
+            "pre-compact",
+        ),
+        "post_compact": (
+            "post_compact",
+            "postCompact",
+            "PostCompact",
+            "post-compact",
+        ),
+    }
+
+    def __init__(self, hooks: dict[str, list[dict[str, Any]]] | None = None):
+        self._hooks = hooks or {}
+
+    def set_hooks(self, hooks: dict[str, list[dict[str, Any]]] | None) -> None:
+        self._hooks = hooks or {}
+
+    async def run(
+        self,
+        event: str,
+        payload: dict[str, Any],
+        *,
+        cwd: str,
+        env: dict[str, str] | None = None,
+    ) -> HookRunResult:
+        canonical = self._canonical_event_name(event)
+        raw_entries = self._gather_hooks(canonical)
+        hooks = self._expand_entries(raw_entries)
+        if not hooks:
+            return HookRunResult(blocked=False, feedback=[], details=[])
+
+        merged_env = {**os.environ, **(env or {})}
+        blocked = False
+        feedback: list[str] = []
+        details: list[str] = []
+
+        for cfg in hooks:
+            command = self._extract_command(cfg)
+            if not command:
+                continue
+            if not self._matches(cfg, payload):
+                continue
+            timeout = self._extract_timeout(cfg)
+            continue_on_error = self._extract_continue_on_error(cfg)
+            result = await self._run_command(
+                command,
+                payload=payload,
+                event=canonical,
+                cwd=cwd,
+                env=merged_env,
+                timeout=timeout,
+            )
+            details.append(result["detail"])
+            if result["feedback"]:
+                feedback.append(result["feedback"])
+            if result["blocked"] and not continue_on_error:
+                blocked = True
+                # Mirror Claude behavior: stop execution on first blocking hook.
+                break
+
+        return HookRunResult(
+            blocked=blocked,
+            feedback=feedback,
+            details=details,
+        )
+
+    def _canonical_event_name(self, event: str) -> str:
+        for canonical, aliases in self._ALIASES.items():
+            if event == canonical or event in aliases:
+                return canonical
+        return event
+
+    def _gather_hooks(self, canonical_event: str) -> list[dict[str, Any]]:
+        keys = set(self._ALIASES.get(canonical_event, (canonical_event,)))
+        hooks: list[dict[str, Any]] = []
+        for key in keys:
+            entries = self._hooks.get(key, [])
+            if isinstance(entries, list):
+                hooks.extend(item for item in entries if isinstance(item, dict))
+        return hooks
+
+    def _extract_command(self, cfg: dict[str, Any]) -> str:
+        cmd = cfg.get("command") or cfg.get("cmd") or cfg.get("run")
+        return cmd if isinstance(cmd, str) else ""
+
+    def _extract_timeout(self, cfg: dict[str, Any]) -> int:
+        raw = cfg.get("timeout")
+        if isinstance(raw, int) and raw > 0:
+            return raw
+        return 60
+
+    def _extract_continue_on_error(self, cfg: dict[str, Any]) -> bool:
+        value = cfg.get("continue_on_error")
+        if value is None:
+            value = cfg.get("continueOnError")
+        return bool(value)
+
+    def _expand_entries(self, entries: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        expanded: list[dict[str, Any]] = []
+        for entry in entries:
+            nested = entry.get("hooks")
+            if isinstance(nested, list):
+                for item in nested:
+                    if not isinstance(item, dict):
+                        continue
+                    merged = dict(item)
+                    if "matcher" not in merged and "matcher" in entry:
+                        merged["matcher"] = entry["matcher"]
+                    if "timeout" not in merged and "timeout" in entry:
+                        merged["timeout"] = entry["timeout"]
+                    if (
+                        "continue_on_error" not in merged
+                        and "continue_on_error" in entry
+                    ):
+                        merged["continue_on_error"] = entry["continue_on_error"]
+                    if (
+                        "continueOnError" not in merged
+                        and "continueOnError" in entry
+                    ):
+                        merged["continueOnError"] = entry["continueOnError"]
+                    hook_type = str(merged.get("type", "command")).strip().lower()
+                    if hook_type in {"", "command"}:
+                        expanded.append(merged)
+            else:
+                expanded.append(entry)
+        return expanded
+
+    def _matches(self, cfg: dict[str, Any], payload: dict[str, Any]) -> bool:
+        matcher = cfg.get("matcher")
+        if not matcher:
+            return True
+
+        tool_name = str(payload.get("tool_name") or payload.get("trigger") or "")
+        if isinstance(matcher, str):
+            if not tool_name:
+                return False
+            return tool_name == matcher or fnmatch(tool_name, matcher)
+        if isinstance(matcher, list):
+            if not tool_name:
+                return False
+            return any(
+                isinstance(item, str) and (tool_name == item or fnmatch(tool_name, item))
+                for item in matcher
+            )
+        if isinstance(matcher, dict):
+            for key in ("tool_name", "tool", "name", "trigger"):
+                pattern = matcher.get(key)
+                if pattern is None:
+                    continue
+                if isinstance(pattern, str):
+                    if tool_name != pattern and not fnmatch(tool_name, pattern):
+                        return False
+                elif isinstance(pattern, list):
+                    found = False
+                    for item in pattern:
+                        if not isinstance(item, str):
+                            continue
+                        if tool_name == item or fnmatch(tool_name, item):
+                            found = True
+                            break
+                    if not found:
+                        return False
+            return True
+        return True
+
+    async def _run_command(
+        self,
+        command: str,
+        *,
+        payload: dict[str, Any],
+        event: str,
+        cwd: str,
+        env: dict[str, str],
+        timeout: int,
+    ) -> dict[str, Any]:
+        encoded = json.dumps(payload, ensure_ascii=False)
+        proc_env = {
+            **env,
+            "CRABCODE_HOOK_EVENT": event,
+            "CRABCODE_HOOK_PAYLOAD": encoded,
+            "CRABCODE_HOOK_TOOL_NAME": str(payload.get("tool_name", "")),
+            "CRABCODE_HOOK_TOOL_USE_ID": str(payload.get("tool_use_id", "")),
+            "CRABCODE_HOOK_AGENT_ID": str(payload.get("agent_id", "")),
+        }
+
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *managed_process_command(shell_command(command)),
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                cwd=cwd,
+                env=proc_env,
+                **subprocess_group_options(),
+            )
+            try:
+                stdout_b, stderr_b = await asyncio.wait_for(proc.communicate(), timeout=timeout)
+                timed_out = False
+            except asyncio.TimeoutError:
+                await terminate_process_tree(proc)
+                stdout_b = b""
+                stderr_b = f"Hook timed out after {timeout}s".encode()
+                timed_out = True
+            except asyncio.CancelledError:
+                await terminate_process_tree(proc)
+                raise
+        except Exception as exc:
+            return {
+                "blocked": True,
+                "feedback": f"Hook failed to start: {exc}",
+                "detail": f"hook-start-error: {exc}",
+            }
+
+        stdout = decode_subprocess_output(stdout_b).strip()
+        stderr = decode_subprocess_output(stderr_b).strip()
+        exit_code = proc.returncode if proc.returncode is not None else 1
+
+        if timed_out:
+            return {
+                "blocked": True,
+                "feedback": stderr or "Hook timed out.",
+                "detail": f"hook timeout; command={command}",
+            }
+
+        feedback = stdout or stderr
+        blocked = exit_code != 0
+        detail = f"hook exit={exit_code}; command={command}"
+        if stderr and stderr != feedback:
+            detail += f"; stderr={stderr}"
+        return {"blocked": blocked, "feedback": feedback, "detail": detail}

crabcode_core/image_io.py

@@ -0,0 +1,111 @@
+"""Decode local raster images into image formats accepted by vision models.
+
+Call from a filesystem worker: image decoding can be slow or block on storage.
+PSD reads use the saved merged image, not an individual layer.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from io import BytesIO
+from pathlib import Path
+
+from PIL import Image, ImageOps
+
+from crabcode_core.types import tool as tool_types
+
+
+_IMAGE_EXTENSIONS = {
+    ".png", ".jpg", ".jpeg", ".jpe", ".webp", ".gif", ".bmp", ".dib",
+    ".tif", ".tiff", ".ico", ".psd", ".psb", ".ppm", ".pgm", ".pbm",
+    ".tga", ".jp2", ".j2k", ".avif", ".heic", ".heif",
+}
+# Restrict decoding to raster plugins; do not invoke external renderers (EPS/PDF).
+_FORMATS = ("PNG", "JPEG", "WEBP", "GIF", "BMP", "TIFF", "ICO", "PSD",
+            "PPM", "TGA", "JPEG2000", "AVIF")
+_NATIVE_MIME = {"PNG": "image/png", "JPEG": "image/jpeg", "WEBP": "image/webp"}
+MAX_PREVIEW_DIMENSION = 4096
+MAX_DECODE_PIXELS = 40_000_000
+
+
+def is_image_file(path: Path) -> bool:
+    """Recognize common raster files, including files without an image suffix.
+
+SVG and other text-based graphics remain readable as source with Read.
+"""
+    if path.suffix.lower() in _IMAGE_EXTENSIONS:
+        return True
+    with path.open("rb") as stream:
+        header = stream.read(16)
+    return (
+        header.startswith((b"\x89PNG\r\n\x1a\n", b"\xff\xd8\xff", b"GIF87a", b"GIF89a",
+                           b"II*\0", b"MM\0*", b"II+\0", b"MM\0+", b"8BPS",
+                           b"\0\0\1\0"))
+        or (header.startswith(b"RIFF") and header[8:12] == b"WEBP")
+        or (header.startswith(b"BM") and header[6:10] == b"\0\0\0\0")
+        or (header[4:8] == b"ftyp" and header[8:12] in {b"avif", b"avis", b"heic", b"mif1"})
+    )
+
+
+@dataclass
+class ImagePreview:
+    data: bytes
+    media_type: str
+    width: int
+    height: int
+    source_format: str
+    original_size: tuple[int, int]
+    first_frame: bool
+
+    def summary(self) -> str:
+        details = f"{self.width}x{self.height}, {self.media_type}, {len(self.data)} bytes"
+        if self.source_format == "PSD":
+            details += "; saved PSD composite preview (layers are not included)"
+        elif self.first_frame:
+            details += "; first frame/page only"
+        if self.original_size != (self.width, self.height):
+            details += f"; original {self.original_size[0]}x{self.original_size[1]}"
+        return details
+
+
+def load_image_preview(path: Path) -> ImagePreview:
+    """Validate pixels and normalize non-native, animated, or oversized images."""
+    try:
+        with Image.open(path, formats=_FORMATS) as source:
+            source_format = source.format or "unknown"
+            original_size = source.size
+            if source.width * source.height > MAX_DECODE_PIXELS:
+                raise ValueError(f"image exceeds the {MAX_DECODE_PIXELS:,}-pixel decode limit")
+            # PSD exposes layers as frames; frame 0 is its saved merged image.
+            first_frame = source_format != "PSD" and getattr(source, "is_animated", False)
+            orientation = source.getexif().get(274, 1)
+            source.load()
+            native_mime = _NATIVE_MIME.get(source_format)
+            if (native_mime and not first_frame and orientation == 1
+                    and source.mode in {"RGB", "RGBA", "L", "LA", "P"}
+                    and max(source.size) <= MAX_PREVIEW_DIMENSION
+                    and path.stat().st_size <= tool_types.MAX_INLINE_IMAGE_BYTES):
+                return ImagePreview(path.read_bytes(), native_mime, *source.size,
+                                    source_format, original_size, False)
+
+            preview = ImageOps.exif_transpose(source)
+            preview = preview.convert("RGBA" if "A" in preview.getbands()
+                                      or "transparency" in preview.info else "RGB")
+            preview.thumbnail((MAX_PREVIEW_DIMENSION, MAX_PREVIEW_DIMENSION), Image.Resampling.LANCZOS)
+            # Do not copy arbitrary source metadata into a model attachment.
+            preview.info.clear()
+            while True:
+                output = BytesIO()
+                preview.save(output, format="PNG")
+                data = output.getvalue()
+                if len(data) <= tool_types.MAX_INLINE_IMAGE_BYTES:
+                    return ImagePreview(data, "image/png", *preview.size, source_format,
+                                        original_size, bool(first_frame))
+                if max(preview.size) <= 1:
+                    raise ValueError("image preview exceeds the attachment byte limit")
+                preview = preview.resize((max(1, preview.width * 3 // 4),
+                                          max(1, preview.height * 3 // 4)), Image.Resampling.LANCZOS)
+    except (OSError, ValueError, SyntaxError, Image.DecompressionBombError) as exc:
+        raise ValueError(
+            f"Cannot decode image {path}: {exc}. Export a flattened PNG or JPEG and read that file."
+        ) from exc