crabcode 0.1.6__py3-none-win_amd64.whl

crabcode_core/snapshot/tracker.py

@@ -0,0 +1,359 @@
+"""Lightweight snapshot tracker — bridges tools and SnapshotManager.
+
+Provides module-level convenience functions so that tools (apply_patch, Edit, Write, Bash)
+can record file changes without managing a SnapshotManager instance themselves.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from crabcode_core.logging_utils import get_logger
+from crabcode_core.snapshot.snapshot import SnapshotManager
+
+logger = get_logger(__name__)
+
+_CRABCODE_DIR = ".crabcode"
+_SNAPSHOTS_DIR = "snapshots"
+
+# A Bash call can be issued from a workspace container such as the user's
+# home directory.  Taking a file snapshot there would recursively copy the
+# whole machine-owned workspace and can exhaust disk space before the command
+# even starts.  These roots are navigation/workspace containers, not projects.
+def _is_broad_workspace(cwd: str) -> bool:
+    """Return whether *cwd* is too broad for an automatic file snapshot."""
+    try:
+        path = Path(cwd).expanduser().resolve()
+        home = Path.home().resolve()
+        if path == home or path == Path(path.anchor):
+            return True
+        return False
+    except (OSError, RuntimeError, ValueError):
+        # Snapshotting is best effort.  An unresolvable path should not block
+        # the command that requested it.
+        return True
+
+
+def _workspace_exceeds_limit(cwd: str, max_size_mb: int) -> bool:
+    """Return whether a workspace exceeds the snapshot size ceiling.
+
+    The walk is bounded: it stops at the first byte over the limit and skips
+    generated/dependency trees that SnapshotManager would not copy anyway.
+    Permission and stat failures fail closed so a damaged workspace cannot
+    trigger an unbounded snapshot.
+    """
+    if max_size_mb <= 0:
+        return True
+    limit = max_size_mb * 1024 * 1024
+    try:
+        root = Path(cwd).expanduser().resolve()
+    except (OSError, RuntimeError, ValueError):
+        return True
+    if not root.is_dir():
+        return True
+    skipped = {".git", ".crabcode", "__pycache__", "node_modules", ".venv", "venv"}
+    total = 0
+    walk_failed = False
+
+    def _on_walk_error(_error: OSError) -> None:
+        nonlocal walk_failed
+        walk_failed = True
+
+    try:
+        for current, dirs, files in os.walk(
+            root,
+            topdown=True,
+            onerror=_on_walk_error,
+            followlinks=False,
+        ):
+            if walk_failed:
+                return True
+            dirs[:] = [name for name in dirs if name not in skipped]
+            for name in files:
+                path = Path(current) / name
+                try:
+                    if path.is_symlink():
+                        continue
+                    file_stat = path.stat()
+                except OSError:
+                    return True
+                if not stat.S_ISREG(file_stat.st_mode):
+                    continue
+                total += file_stat.st_size
+                if total > limit:
+                    return True
+        if walk_failed:
+            return True
+    except OSError:
+        return True
+    return False
+
+
+def _snapshot_is_allowed(cwd: str, enabled: bool, max_size_mb: int) -> bool:
+    if not enabled or _is_broad_workspace(cwd):
+        return False
+    return not _workspace_exceeds_limit(cwd, max_size_mb)
+
+
+@dataclass
+class SnapshotInfo:
+    """A recorded snapshot entry for a session."""
+    snapshot_id: str
+    session_id: str
+    timestamp: float
+    tool_name: str
+    files: list[str] = field(default_factory=list)
+    action: str = ""  # "modify" | "create" | "delete" | "patch" | "bash"
+
+
+def _session_log_path(cwd: str, session_id: str) -> Path:
+    return Path(cwd) / _CRABCODE_DIR / _SNAPSHOTS_DIR / f"{session_id}.jsonl"
+
+
+def _ensure_dir(cwd: str) -> Path:
+    d = Path(cwd) / _CRABCODE_DIR / _SNAPSHOTS_DIR
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _append_log(cwd: str, session_id: str, entry: dict[str, Any]) -> None:
+    """Append a snapshot entry to the session's JSONL log."""
+    _ensure_dir(cwd)
+    log_path = _session_log_path(cwd, session_id)
+    line = json.dumps(entry, ensure_ascii=False) + "\n"
+    try:
+        with open(log_path, "a", encoding="utf-8") as f:
+            f.write(line)
+    except Exception:
+        logger.debug("Failed to append snapshot log: %s", log_path, exc_info=True)
+
+
+# ---------------------------------------------------------------------------
+# Public API — called from tools
+# ---------------------------------------------------------------------------
+
+def track_snapshot_for_file(
+    cwd: str,
+    session_id: str,
+    file_path: str,
+    old_content: str | None = None,
+    action: str = "modify",
+) -> None:
+    """Record that a file is about to be changed.
+
+    If *old_content* is provided, it is saved to the snapshot store so
+    the file can be restored later even without git.
+    """
+    # Create a quick snapshot ID from the file path + timestamp
+    snap_id = _make_file_snapshot_id(file_path, action)
+
+    # If old_content is given, persist it for non-git restore
+    if old_content is not None:
+        _save_file_backup(cwd, session_id, snap_id, file_path, old_content)
+
+    _append_log(cwd, session_id, {
+        "snapshot_id": snap_id,
+        "session_id": session_id,
+        "timestamp": time.time(),
+        "tool_name": "file_edit",
+        "files": [file_path],
+        "action": action,
+    })
+
+
+def pre_bash_snapshot(
+    cwd: str,
+    session_id: str,
+    *,
+    enabled: bool = True,
+    max_size_mb: int = 1024,
+    tool_name: str = "Bash",
+    action: str = "bash",
+) -> str | None:
+    """Create a full working-directory snapshot before a bash command.
+
+    Returns the snapshot ID, or ``None`` on failure.
+    """
+    if not _snapshot_is_allowed(cwd, enabled, max_size_mb):
+        logger.info("Skipping Bash snapshot for workspace or size policy: %s", cwd)
+        return None
+
+    try:
+        mgr = SnapshotManager(cwd)
+        mgr.init()
+        snap_id = mgr.track()
+        if snap_id:
+            _append_log(cwd, session_id, {
+                "snapshot_id": snap_id,
+                "session_id": session_id,
+                "timestamp": time.time(),
+                "tool_name": tool_name,
+                "files": [],
+                "action": action,
+            })
+        return snap_id
+    except Exception:
+        logger.debug("pre_bash_snapshot failed", exc_info=True)
+        return None
+
+
+def get_session_snapshots(cwd: str, session_id: str) -> list[SnapshotInfo]:
+    """Return all snapshot entries recorded for a session."""
+    log_path = _session_log_path(cwd, session_id)
+    if not log_path.exists():
+        return []
+    entries: list[SnapshotInfo] = []
+    try:
+        with open(log_path, encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    d = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                entries.append(SnapshotInfo(
+                    snapshot_id=d.get("snapshot_id", ""),
+                    session_id=d.get("session_id", ""),
+                    timestamp=d.get("timestamp", 0),
+                    tool_name=d.get("tool_name", ""),
+                    files=d.get("files", []),
+                    action=d.get("action", ""),
+                ))
+    except Exception:
+        logger.debug("Failed to read session snapshots: %s", log_path, exc_info=True)
+    return entries
+
+
+def restore_snapshot(cwd: str, snapshot_id: str) -> list[str]:
+    """Restore the working directory to a given snapshot.
+
+    Returns the list of files restored.
+    """
+    # First try git-based restore
+    try:
+        mgr = SnapshotManager(cwd)
+        mgr.init()
+        files = mgr.restore(snapshot_id)
+        if files:
+            return files
+    except Exception:
+        logger.debug("Git restore failed for %s, trying file backup", snapshot_id, exc_info=True)
+
+    # Fallback: restore from file backups stored by track_snapshot_for_file
+    return _restore_file_backups(cwd, snapshot_id)
+
+
+def create_full_snapshot(
+    cwd: str,
+    session_id: str,
+    label: str = "",
+    *,
+    enabled: bool = True,
+    max_size_mb: int = 1024,
+) -> str | None:
+    """Create a full working-directory snapshot and return its ID.
+
+    This is used by /checkpoint to create a file-system-level snapshot
+    alongside the conversation checkpoint.
+    """
+    if not _snapshot_is_allowed(cwd, enabled, max_size_mb):
+        logger.info("Skipping full snapshot for workspace or size policy: %s", cwd)
+        return None
+
+    try:
+        mgr = SnapshotManager(cwd)
+        mgr.init()
+        snap_id = mgr.track()
+        if snap_id:
+            _append_log(cwd, session_id, {
+                "snapshot_id": snap_id,
+                "session_id": session_id,
+                "timestamp": time.time(),
+                "tool_name": "checkpoint",
+                "files": [],
+                "action": "checkpoint",
+                "label": label,
+            })
+        return snap_id
+    except Exception:
+        logger.warning("Failed to create full snapshot for checkpoint", exc_info=True)
+        return None
+
+
+# ---------------------------------------------------------------------------
+# File-backup helpers (for non-git or per-file granularity)
+# ---------------------------------------------------------------------------
+
+def _file_backup_dir(cwd: str, session_id: str) -> Path:
+    return Path(cwd) / _CRABCODE_DIR / _SNAPSHOTS_DIR / "files" / session_id
+
+
+def _make_file_snapshot_id(file_path: str, action: str) -> str:
+    import hashlib
+    h = hashlib.sha256(f"{file_path}:{action}:{time.time()}".encode()).hexdigest()
+    return h[:16]
+
+
+def _save_file_backup(
+    cwd: str,
+    session_id: str,
+    snap_id: str,
+    file_path: str,
+    content: str,
+) -> None:
+    d = _file_backup_dir(cwd, session_id) / snap_id
+    d.mkdir(parents=True, exist_ok=True)
+    # Store with the file's basename; original path is in the log
+    backup_file = d / "content"
+    try:
+        original = Path(file_path)
+        if not original.is_absolute():
+            original = Path(cwd) / original
+        # The UTF-8 tool view has already stripped the BOM. Back up the actual
+        # bytes so rollback preserves encoding and every newline exactly.
+        raw = original.read_bytes() if original.is_file() else content.encode("utf-8")
+        backup_file.write_bytes(raw)
+        (d / "path").write_text(file_path, encoding="utf-8")
+    except Exception:
+        logger.debug("Failed to save file backup: %s/%s", snap_id, file_path, exc_info=True)
+
+
+def _restore_file_backups(cwd: str, snapshot_id: str) -> list[str]:
+    """Restore files from file backups for a given snapshot ID.
+
+    This is a best-effort fallback — it scans all sessions' backup dirs
+    for the snapshot_id.
+    """
+    files_root = Path(cwd) / _CRABCODE_DIR / _SNAPSHOTS_DIR / "files"
+    if not files_root.exists():
+        return []
+    restored: list[str] = []
+    for session_dir in files_root.iterdir():
+        if not session_dir.is_dir():
+            continue
+        snap_dir = session_dir / snapshot_id
+        if not snap_dir.exists():
+            continue
+        content_file = snap_dir / "content"
+        path_file = snap_dir / "path"
+        if content_file.exists() and path_file.exists():
+            try:
+                file_path = path_file.read_text(encoding="utf-8").strip()
+                content = content_file.read_bytes()
+                target = Path(file_path)
+                if not target.is_absolute():
+                    target = Path(cwd) / file_path
+                target.parent.mkdir(parents=True, exist_ok=True)
+                target.write_bytes(content)
+                restored.append(str(target))
+            except Exception:
+                logger.debug("Failed to restore backup %s", snap_dir, exc_info=True)
+    return restored

crabcode_core/subprocess_utils.py

@@ -0,0 +1,260 @@
+"""Cross-platform subprocess helpers."""
+
+from __future__ import annotations
+
+import asyncio
+import codecs
+import locale
+import os
+from pathlib import Path
+import re
+import shutil
+import signal
+import subprocess
+import sys
+from typing import Any
+
+
+_POWERSHELL_UTF8_SETUP = (
+    "$utf8 = [System.Text.UTF8Encoding]::new($false); "
+    "[Console]::InputEncoding = $utf8; "
+    "[Console]::OutputEncoding = $utf8; "
+    "$OutputEncoding = $utf8; "
+)
+
+
+def resolve_executable_command(
+    command: list[str], *, env: dict[str, str] | None = None, cwd: str | None = None,
+) -> list[str]:
+    """Resolve using the launch environment, without interpreting batch arguments."""
+    if not command:
+        raise ValueError("command must not be empty")
+    if os.name != "nt":
+        return list(command)
+    environment = {key.upper(): value for key, value in (env if env is not None else os.environ).items()}
+    search_path = environment.get("PATH", "")
+    base = Path(cwd or os.getcwd()).resolve()
+    search_path = os.pathsep.join(str(base / part.strip('"')) for part in search_path.split(os.pathsep))
+    token = command[0]
+    if os.path.dirname(token):
+        token = str(base / token)
+    resolved = shutil.which(token, path=search_path)
+    # which() takes PATHEXT from the parent process, not its path argument.
+    if env is not None:
+        roots = [Path()] if os.path.dirname(token) else [Path(p) for p in search_path.split(os.pathsep)]
+        extensions = environment.get("PATHEXT", ".COM;.EXE;.BAT;.CMD").split(";")
+        names = [token] if Path(token).suffix.upper() in {e.upper() for e in extensions} else [token + ext for ext in extensions]
+        resolved = next((str(root / name) for root in roots for name in names if (root / name).is_file()), None)
+    if not resolved:
+        raise FileNotFoundError(f"Executable not found in the launch environment: {command[0]}")
+    result = [resolved, *command[1:]]
+    if Path(result[0]).suffix.lower() in {".cmd", ".bat"}:
+        # npm's cmd-shim template has a fixed Node invocation. Bypass cmd.exe
+        # for this template so filenames such as a&b.js remain literal argv.
+        shim = Path(result[0])
+        try:
+            body = shim.read_text(encoding="utf-8")
+        except (OSError, UnicodeError):
+            body = ""
+        match = re.fullmatch(
+            r'@ECHO off\s+GOTO start\s+:find_dp0\s+SET dp0=%~dp0\s+EXIT /b\s+'
+            r':start\s+SETLOCAL\s+CALL :find_dp0\s+'
+            r'IF EXIST "%dp0%\\node.exe" \(\s+SET "_prog=%dp0%\\node.exe"\s+'
+            r'\) ELSE \(\s+SET "_prog=node"\s+SET PATHEXT=%PATHEXT:;.JS;=;%\s+\)\s+'
+            r'endLocal & goto #_undefined_# 2>NUL \|\| title %COMSPEC% & "%_prog%"\s+'
+            r'"%dp0%[\\/]([^"\r\n]+)" %\*\s*', body,
+        )
+        if match:
+            script = shim.parent / match.group(1).replace("\\", "/")
+            node = shim.parent / "node.exe"
+            executable = str(node) if node.is_file() else shutil.which("node", path=search_path)
+            if executable and script.is_file():
+                return [executable, str(script), *command[1:]]
+        if any(re.search(r'[&|<>^%!"()\r\n]', value) for value in result):
+            raise ValueError(
+                "Cannot safely pass shell metacharacters to a Windows batch launcher. "
+                "Configure the native executable (for Node tools: node.exe and its JS entry point)."
+            )
+    return result
+
+
+def shell_command(command: str) -> list[str]:
+    """Return an explicit platform shell invocation with UTF-8 output."""
+    if os.name == "nt":
+        powershell = shutil.which("pwsh") or shutil.which("powershell")
+        if powershell:
+            return powershell_command(powershell, command)
+        comspec = os.environ.get("COMSPEC") or "cmd.exe"
+        return [comspec, "/d", "/s", "/c", f"chcp 65001>nul & {command}"]
+
+    bash = shutil.which("bash")
+    if bash:
+        return [bash, "-c", command]
+    return ["/bin/sh", "-c", command]
+
+
+def powershell_command(executable: str, command: str) -> list[str]:
+    """Build a non-interactive PowerShell command that emits UTF-8."""
+    return [
+        executable,
+        "-NoLogo",
+        "-NoProfile",
+        "-NonInteractive",
+        "-Command",
+        _POWERSHELL_UTF8_SETUP + command,
+    ]
+
+
+def managed_process_command(command: list[str]) -> list[str]:
+    """Wrap a Windows command in a job whose lifetime includes all descendants."""
+    if os.name != "nt":
+        return command
+    return [sys.executable, "-I", str(Path(__file__).with_name("_windows_process.py")), *command]
+
+
+def subprocess_group_options() -> dict[str, Any]:
+    """Options used for processes that may need tree-wide cancellation."""
+    if os.name != "nt":
+        return {"start_new_session": True}
+    # CrabCode subprocesses are non-interactive and communicate through pipes.
+    # Prevent console programs spawned by the GUI/Gateway from flashing a new
+    # terminal window on Windows.
+    creation_flags = getattr(subprocess, "CREATE_NO_WINDOW", 0)
+    return {"creationflags": creation_flags} if creation_flags else {}
+
+
+def decode_subprocess_output(data: bytes) -> str:
+    """Decode subprocess output without assuming every Windows tool uses UTF-8."""
+    if not data:
+        return ""
+    if data.startswith((codecs.BOM_UTF16_LE, codecs.BOM_UTF16_BE)):
+        return data.decode("utf-16", errors="replace")
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError:
+        encodings = [locale.getpreferredencoding(False) or "utf-8"]
+        if os.name == "nt":
+            encodings.append("mbcs")
+        for encoding in dict.fromkeys(encodings):
+            try:
+                return data.decode(encoding)
+            except (LookupError, UnicodeDecodeError):
+                continue
+        return data.decode(encodings[-1], errors="replace")
+
+
+def is_process_running(pid: int) -> bool:
+    """Return whether *pid* identifies a live process without signalling it."""
+    if pid <= 0:
+        return False
+    if os.name != "nt":
+        try:
+            os.kill(pid, 0)
+        except ProcessLookupError:
+            return False
+        except PermissionError:
+            return True
+        except OSError:
+            return False
+        return True
+
+    import ctypes
+    from ctypes import wintypes
+
+    process_query_limited_information = 0x1000
+    still_active = 259
+    access_denied = 5
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    kernel32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
+    kernel32.OpenProcess.restype = wintypes.HANDLE
+    kernel32.GetExitCodeProcess.argtypes = [wintypes.HANDLE, ctypes.POINTER(wintypes.DWORD)]
+    kernel32.GetExitCodeProcess.restype = wintypes.BOOL
+    kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
+    kernel32.CloseHandle.restype = wintypes.BOOL
+
+    handle = kernel32.OpenProcess(process_query_limited_information, False, pid)
+    if not handle:
+        return ctypes.get_last_error() == access_denied
+    try:
+        exit_code = wintypes.DWORD()
+        if not kernel32.GetExitCodeProcess(handle, ctypes.byref(exit_code)):
+            return False
+        return exit_code.value == still_active
+    finally:
+        kernel32.CloseHandle(handle)
+
+
+async def terminate_process_tree(process: Any, *, timeout: float = 5.0) -> None:
+    """Terminate a subprocess and all descendants created beneath it."""
+    if process is None or process.returncode is not None:
+        return
+
+    if os.name == "nt":
+        taskkill = shutil.which("taskkill")
+        tree_killed = False
+        if taskkill:
+            options: dict[str, Any] = {}
+            if hasattr(subprocess, "CREATE_NO_WINDOW"):
+                options["creationflags"] = subprocess.CREATE_NO_WINDOW
+            try:
+                killer = await asyncio.create_subprocess_exec(
+                    taskkill,
+                    "/PID",
+                    str(process.pid),
+                    "/T",
+                    "/F",
+                    stdout=asyncio.subprocess.DEVNULL,
+                    stderr=asyncio.subprocess.DEVNULL,
+                    **options,
+                )
+                await asyncio.wait_for(killer.wait(), timeout=timeout)
+                tree_killed = killer.returncode == 0
+            except asyncio.TimeoutError:
+                killer.kill()
+            except OSError:
+                pass
+        if not tree_killed and process.returncode is None:
+            try:
+                process.kill()
+            except ProcessLookupError:
+                pass
+        if process.returncode is None:
+            try:
+                await asyncio.wait_for(process.wait(), timeout=timeout)
+                return
+            except asyncio.TimeoutError:
+                try:
+                    process.kill()
+                except ProcessLookupError:
+                    pass
+        try:
+            await asyncio.wait_for(process.wait(), timeout=timeout)
+        except asyncio.TimeoutError:
+            pass  # A kernel-blocked process must not hold its caller forever.
+        return
+
+    try:
+        os.killpg(process.pid, signal.SIGTERM)
+    except ProcessLookupError:
+        return
+    except OSError:
+        try:
+            process.terminate()
+        except ProcessLookupError:
+            return
+    try:
+        await asyncio.wait_for(process.wait(), timeout=timeout)
+    except asyncio.TimeoutError:
+        try:
+            os.killpg(process.pid, signal.SIGKILL)
+        except ProcessLookupError:
+            return
+        except OSError:
+            try:
+                process.kill()
+            except ProcessLookupError:
+                return
+        try:
+            await asyncio.wait_for(process.wait(), timeout=timeout)
+        except asyncio.TimeoutError:
+            pass  # SIGKILL does not guarantee an immediate reap (e.g. D state).

crabcode_core/team/__init__.py

@@ -0,0 +1,27 @@
+"""Agent Teams — flat teams with named messaging and shared task boards."""
+
+from crabcode_core.team.models import (
+    BridgePolicy,
+    CrossTeamMessage,
+    TaskItem,
+    TaskStatus,
+    TeamConfig,
+    TeamMessage,
+    TeamState,
+    TeammateInfo,
+    TeammateRole,
+    TeammateState,
+)
+
+__all__ = [
+    "BridgePolicy",
+    "CrossTeamMessage",
+    "TaskItem",
+    "TaskStatus",
+    "TeamConfig",
+    "TeamMessage",
+    "TeamState",
+    "TeammateInfo",
+    "TeammateRole",
+    "TeammateState",
+]