super-code-assistant 3.3.6__py3-none-any.whl

tools/file_edit.py

@@ -0,0 +1,269 @@
+"""Edit tool — scoped string replacement with snippet_id safety (Phase 2)."""
+from __future__ import annotations
+
+from pathlib import Path
+from core.tool import Tool, ToolResult
+from core.file_state import (
+    get_snippet,
+    get_file_state,
+    is_snippet_stale,
+    record_file_state,
+    create_snippet,
+)
+
+
+class FileEditTool(Tool):
+    name = "Edit"
+    description = (
+        "Replaces exact string matches in files.\n\n"
+        "Usage:\n"
+        "- You must use Read at least once before editing. "
+        "This tool will fail if you attempt an edit without having read the file.\n"
+        "- The edit will FAIL if old_string is not unique in the file. "
+        "Either provide a larger string with more surrounding context or use replace_all.\n"
+        "- Use replace_all to replace and rename strings across the entire file."
+    )
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "snippet_id": {
+                "type": "string",
+                "description": (
+                    "Required: snippet_id from a previous Read call. "
+                    "The edit is scoped to the lines covered by that snippet."
+                ),
+            },
+            "file_path": {
+                "type": "string",
+                "description": "Optional absolute path guard; must match snippet_id's file.",
+            },
+            "old_string": {"type": "string", "description": "Exact string to replace"},
+            "new_string": {"type": "string", "description": "Replacement string (must differ from old_string)"},
+            "replace_all": {"type": "boolean", "description": "Replace all occurrences (default false)", "default": False},
+        },
+        "required": ["snippet_id", "old_string", "new_string"],
+    }
+
+    # Shared set of files that have been read — populated by FileReadTool
+    _read_files: set[str] = set()
+
+    @classmethod
+    def mark_file_read(cls, file_path: str) -> None:
+        cls._read_files.add(file_path)
+
+    def __init__(self, sandbox_manager=None, session_id: str = ""):
+        self._sandbox = sandbox_manager
+        self._session_id = session_id
+
+    def set_session_id(self, session_id: str) -> None:
+        """Phase 3: engine 注入当前会话 ID。"""
+        self._session_id = session_id
+
+    def get_activity_description(self, **kwargs) -> str | None:
+        fp = kwargs.get("file_path", "") or kwargs.get("snippet_id", "")
+        return f"Editing {fp}" if fp else None
+
+    def execute(self, snippet_id: str, old_string: str, new_string: str,
+                file_path: str = "", replace_all: bool = False, **kwargs) -> ToolResult:
+        # ── 1. snippet 校验 ──────────────────────────────────────────────
+        if not snippet_id.strip():
+            return ToolResult(
+                content="Error: snippet_id is required. Use Read first to get a snippet_id.",
+                is_error=True,
+            )
+
+        snippet = get_snippet(self._session_id, snippet_id) if self._session_id else None
+        if snippet is None:
+            return ToolResult(
+                content=f"Error: Unknown snippet_id: {snippet_id}. The snippet may have expired "
+                        f"or you may need to Read the file again to get a fresh snippet_id.",
+                is_error=True,
+            )
+
+        if is_snippet_stale(self._session_id, snippet):
+            return ToolResult(
+                content=f"Error: The file {snippet.file_path} has been modified since snippet "
+                        f"'{snippet_id}' was created. Read the file again to get a fresh snippet_id.",
+                is_error=True,
+            )
+
+        # ── 2. file_path 校验 既允许用户不传路径（使用凭证中的路径），又防止用户用凭证去编辑其他文件（路径必须匹配）
+        fp = file_path.strip() if file_path else snippet.file_path
+        if not fp:
+            return ToolResult(content="Error: file_path is required.", is_error=True)
+        if file_path.strip() and Path(file_path.strip()).resolve() != Path(snippet.file_path):
+            return ToolResult(
+                content=f"Error: snippet_id '{snippet_id}' belongs to {snippet.file_path}, "
+                        f"not {file_path}.",
+                is_error=True,
+            )
+
+        # ── 3. 沙箱 & 文件存在性 ──────────────────────────────────────────
+        if self._sandbox is not None:
+            allowed, reason = self._sandbox.check_path(fp, "write")
+            if not allowed:
+                return ToolResult(content=f"Error: {reason}", is_error=True)
+
+        path = Path(fp)
+        if not path.exists():
+            return ToolResult(content=f"Error: File not found: {fp}", is_error=True)
+        if path.is_dir():
+            return ToolResult(content=f"Error: {fp} is a directory.", is_error=True)
+
+        # ── 4. 基本参数校验 ──────────────────────────────────────────────
+        if not old_string:
+            return ToolResult(
+                content="Error: old_string cannot be empty.",
+                is_error=True,
+            )
+        if old_string == new_string:
+            return ToolResult(
+                content="Error: new_string must differ from old_string.",
+                is_error=True,
+            )
+
+        # ── 5. 读取文件 & 范围搜索 ───────────────────────────────────────
+        try:
+            content = path.read_text(encoding="utf-8")
+        except OSError as e:
+            return ToolResult(content=f"Error reading file: {e}", is_error=True)
+
+        lines = content.splitlines(keepends=True)
+        total_lines = len(lines) if lines else 1
+
+        # 搜索范围：snippet 行范围
+        scope_start = snippet.start_line
+        scope_end = min(snippet.end_line, total_lines)
+        scope_text = "".join(lines[scope_start - 1:scope_end])
+
+        # 在 scope 内搜索匹配
+        match_positions = _find_all(scope_text, old_string)
+
+        # ── 6. 匹配结果处理 ──────────────────────────────────────────────
+        # 先检查文件是否被外部程序修改过（mtime 变化），给出具体原因提示；无论哪种情况，都要求 AI 重新读取文件获取新 snippet。
+        if len(match_positions) == 0:
+            # 试试：文件外部被修改了？
+            try:
+                stat = path.stat()
+                state = get_file_state(self._session_id, fp)
+                if state and stat.st_mtime != state.mtime:
+                    return ToolResult(
+                        content=f"Error: old_string not found in {fp}. The file has been modified "
+                                f"externally since it was read. Read it again to get a fresh snippet_id.\n"
+                                f"  snippet scope: lines {scope_start}-{scope_end}",
+                        is_error=True,
+                        metadata={"scope": {"file_path": fp, "start_line": scope_start,
+                                              "end_line": scope_end, "snippet_id": snippet_id}},
+                    )
+            except Exception:
+                pass
+
+            return ToolResult(
+                content=f"Error: old_string not found in {fp} within the snippet scope "
+                        f"(lines {scope_start}-{scope_end}). "
+                        f"Read the file again if the content has changed.",
+                is_error=True,
+                metadata={"scope": {"file_path": fp, "start_line": scope_start,
+                                      "end_line": scope_end, "snippet_id": snippet_id}},
+            )
+        # 在 snippet 范围内找到多个匹配且未启用 replace_all 时，拒绝执行，防止模糊替换改错地方。
+        if not replace_all and len(match_positions) > 1:
+            # 非唯一匹配 → 返回候选片段
+            candidates = []
+            for idx, pos in enumerate(match_positions[:5]):  # 最多 5 个
+                match_line = _offset_to_line(lines, scope_start, pos)
+                preview_start = max(1, match_line - 1)
+                preview_end = min(total_lines, match_line + 2)
+                preview = "".join(
+                    f"{ln}\t{lines[ln - 1]}" for ln in range(preview_start, preview_end + 1)
+                )
+                candidates.append({
+                    "index": idx + 1,
+                    "line": match_line,
+                    "preview": preview,
+                })
+
+            return ToolResult(
+                content=f"Error: old_string is not unique within snippet scope "
+                        f"(lines {scope_start}-{scope_end}); found {len(match_positions)} matches. "
+                        f"Use replace_all=true or provide more surrounding context.",
+                is_error=True,
+                metadata={
+                    "match_count": len(match_positions),
+                    "scope": {"file_path": fp, "start_line": scope_start,
+                               "end_line": scope_end, "snippet_id": snippet_id},
+                    "candidates": candidates,
+                },
+            )
+
+        # ── 7. 执行替换 ──────────────────────────────────────────────────
+        # 通过累计行长度计算出替换位置在文件中的全局字节偏移（scope_bytes_before 是范围前的字节数，global_pos 是具体匹配位置的全局偏移
+        scope_bytes_before = sum(len(line) for line in lines[:scope_start - 1])
+        if replace_all:
+            new_scope = scope_text.replace(old_string, new_string)
+            scope_bytes = sum(len(line) for line in lines[scope_start - 1:scope_end])
+            new_content = content[:scope_bytes_before] + new_scope + content[scope_bytes_before + scope_bytes:]
+            replaced = len(match_positions)
+        else:
+            pos = match_positions[0]
+            # 计算全局偏移
+            scope_bytes_before = sum(len(line) for line in lines[:scope_start - 1])
+            global_pos = scope_bytes_before + pos
+            new_content = content[:global_pos] + new_string + content[global_pos + len(old_string):]
+            replaced = 1
+
+        try:
+            path.write_text(new_content, encoding="utf-8")
+        except OSError as e:
+            return ToolResult(content=f"Error writing file: {e}", is_error=True)
+
+        # ── 8. 刷新文件状态 ──────────────────────────────────────────────
+        # 编辑后更新文件状态并自增版本号（bump_version=True），使所有旧 snippet 自动失效。基于修改后的完整文件内容重新生成一个 full 类型的 snippet，让 AI 可以继续编辑（同时返回 new_snippet_id）。
+        if self._session_id:
+            stat = path.stat()
+            record_file_state(self._session_id, fp, new_content, stat.st_mtime, bump_version=True)
+            # 用替换后的内容计算行数，避免多行替换导致新 snippet 的 end_line 偏小
+            new_total_lines = len(new_content.splitlines(keepends=True)) or 1
+            new_snippet = create_snippet(self._session_id, fp, 1, new_total_lines, scope_type="full")
+            meta = {
+                "file_path": fp,
+                "replaced_count": replaced,
+                "scope": {"file_path": fp, "start_line": scope_start,
+                           "end_line": scope_end, "snippet_id": snippet_id},
+                "new_snippet_id": new_snippet.id,
+            }
+        else:
+            meta = None
+
+        return ToolResult(
+            content=f"Successfully replaced {replaced} occurrence(s) in {fp}.",
+            metadata=meta,
+        )
+
+
+# ---------------------------------------------------------------------------
+# 工具函数
+# ---------------------------------------------------------------------------
+
+
+def _find_all(text: str, needle: str) -> list[int]:
+    """返回 needle 在 text 中所有出现位置的偏移量列表。"""
+    positions = []
+    start = 0
+    while True:
+        pos = text.find(needle, start)
+        if pos == -1:
+            break
+        positions.append(pos)
+        start = pos + len(needle)
+    return positions
+
+
+def _offset_to_line(lines: list[str], scope_start_line: int, scope_offset: int) -> int:
+    """将 scope 内的偏移量转换为文件行号（1-based）。"""
+    remaining = scope_offset
+    for i in range(scope_start_line - 1, len(lines)):
+        remaining -= len(lines[i])
+        if remaining < 0:
+            return i + 1
+    return len(lines)

tools/file_read.py

@@ -0,0 +1,206 @@
+"""Simple file read tool implementation."""
+import time
+from pathlib import Path
+from core.tool import Tool, ToolResult
+from core.file_state import (
+    record_file_state,
+    create_snippet,
+    clear_session_state as _clear_snippets,
+)
+
+
+class FileReadTool(Tool):
+    """A simple tool to read file contents."""
+
+    # Phase C：最近读过的文件 → 最后一次 Read 时间戳。压缩流程取 top-N 重新 Read
+    # 注入到压缩后对话，让模型不丢失文件内容上下文。
+    # 类级别全局变量：worker engine 与主 engine 共享（已知限制，实际工作目录场景下
+    # 通常不构成问题；如未来要严格隔离，再改为实例字段）。time.time() 为系统墙钟，
+    # 不随调试或 monkey-patch 改变。
+    _recent_reads: dict[str, float] = {}
+
+    @classmethod
+    def mark_recent_read(cls, file_path: str) -> None:
+        """记录一次成功的 Read 调用（用绝对路径作 key，避免相对路径引发的重复）。"""
+        if file_path:
+            cls._recent_reads[file_path] = time.time()
+
+    @classmethod
+    def get_recent_reads(cls) -> list[tuple[str, float]]:
+        """返回 (path, ts) 列表，按 ts 倒序（最近的在前）。压缩重注入用。"""
+        return sorted(cls._recent_reads.items(), key=lambda kv: kv[1], reverse=True)
+
+    @classmethod
+    def clear_recent_reads(cls) -> None:
+        """清空记录（测试或 /clear 命令使用）。"""
+        cls._recent_reads.clear()
+    
+    @property
+    def name(self) -> str:
+        return "Read"
+    
+    def __init__(self, sandbox_manager=None, session_id: str = ""):
+        self._sandbox = sandbox_manager
+        self._session_id = session_id
+
+    def set_session_id(self, session_id: str) -> None:
+        """Phase 1/3: engine 注入当前会话 ID，用于创建 snippet。"""
+        self._session_id = session_id
+    
+    @property
+    def description(self) -> str:
+        return (
+            "Reads a file from the local filesystem. "
+            "Usage: Provide an absolute file path to read its contents."
+        )
+    
+    @property
+    def input_schema(self) -> dict:
+        """
+            操作大文件的时候看，第一次可以全读，后续如果要修改文件，那么可以使用offset、limit规定只读取某个片段
+        :return:
+        """
+        return {
+            "type": "object",
+            "properties": {
+                "file_path": {
+                    "type": "string",
+                    "description": "Absolute path to the file to read"
+                },
+                "offset": {
+                    "type": "integer",
+                    "description": "Line number to start reading from (1-based). Default: 1."
+                },
+                "limit": {
+                    "type": "integer",
+                    "description": "Number of lines to read. Default: read all lines."
+                },
+            },
+            "required": ["file_path"]
+        }
+    
+    def is_read_only(self) -> bool:
+        return True
+    
+    def get_activity_description(self, **kwargs) -> str | None:
+        file_path = kwargs.get("file_path", "")
+        return f"Reading {file_path}" if file_path else None
+    
+    def execute(self, file_path: str, **kwargs) -> ToolResult:
+        """Execute the file read operation."""
+        # 沙箱路径保护：禁止读取受保护目录
+        if self._sandbox is not None:
+            allowed, reason = self._sandbox.check_path(file_path, "read")
+            if not allowed:
+                return ToolResult(content=f"Error: {reason}", is_error=True)
+
+        try:
+            path = Path(file_path)
+            
+            if not path.exists():
+                return ToolResult(
+                    content=f"Error: File not found: {file_path}",
+                    is_error=True
+                )
+            
+            if not path.is_file():
+                return ToolResult(
+                    content=f"Error: Not a file: {file_path}",
+                    is_error=True
+                )
+            
+            # Read file content
+            content = path.read_text(encoding="utf-8", errors="replace")
+            
+            # ---- offset / limit 解析 ----
+            offset = _parse_positive_int(kwargs.get("offset"), "offset")
+            limit = _parse_positive_int(kwargs.get("limit"), "limit")
+            if isinstance(offset, str):
+                return ToolResult(content=f"Error: {offset}", is_error=True)
+            if isinstance(limit, str):
+                return ToolResult(content=f"Error: {limit}", is_error=True)
+
+            # Format with line numbers
+            all_lines = content.splitlines(keepends=True)
+            total_lines = len(all_lines) if all_lines else 1
+
+            # 计算实际行范围
+            actual_start = offset if offset else 1
+            if limit:
+                actual_end = min(actual_start + limit - 1, total_lines)
+            else:
+                actual_end = total_lines
+
+            # 截取对应行
+            selected = all_lines[actual_start - 1:actual_end]
+            numbered = "".join(f"{actual_start + i}\t{line}" for i, line in enumerate(selected))
+
+            from tools.file_edit import FileEditTool
+            FileEditTool.mark_file_read(file_path)
+            FileEditTool.mark_file_read(str(path.resolve()))
+            # Phase C：用 resolve 后的绝对路径作 key，避免同一文件因相对/绝对路径
+            # 不同被记成两条。失败路径不调用，避免压缩去 Read 一个本来就读不出来的文件。
+            try:
+                FileReadTool.mark_recent_read(str(path.resolve()))
+            except Exception:
+                try:
+                    FileReadTool.mark_recent_read(file_path)
+                except Exception:
+                    pass
+
+            # Phase 1: Snippet 系统 — 记录文件状态 + 创建编辑凭证
+            snippet_meta = None
+            if self._session_id:
+                resolved = str(path.resolve())
+                stat = path.stat()
+                record_file_state(self._session_id, resolved, content, stat.st_mtime)
+                # 根据 offset/limit 决定 snippet 的行范围和 scope_type
+                is_partial = bool(offset or limit)
+                snippet = create_snippet(
+                    self._session_id, resolved,
+                    start_line=actual_start,
+                    end_line=actual_end,
+                    scope_type="snippet" if is_partial else "full",
+                )
+                snippet_meta = {
+                    "snippet_id": snippet.id,
+                    "file_path": snippet.file_path,
+                    "start_line": snippet.start_line,
+                    "end_line": snippet.end_line,
+                    "scope_type": snippet.scope_type,
+                }
+                # 将 snippet_id 注入 content 头部，让 LLM 能看到并用于后续 Edit 调用
+                header = (
+                    f"[snippet_id: {snippet_meta['snippet_id']} | "
+                    f"lines: {snippet_meta['start_line']}-{snippet_meta['end_line']} | "
+                    f"scope: {snippet_meta['scope_type']}]\n"
+                )
+                numbered = header + numbered
+
+            return ToolResult(
+                content=numbered,
+                metadata=snippet_meta,
+            )
+
+        except Exception as e:
+            return ToolResult(
+                content=f"Error reading file: {e}",
+                is_error=True
+            )
+
+
+def _parse_positive_int(value, label: str) -> int | None | str:
+    """解析正整数参数。返回 None=未传入, int=有效值, str=错误信息。"""
+    if value is None:
+        return None
+    if isinstance(value, str):
+        value = value.strip()
+        if not value:
+            return None
+    try:
+        num = int(value)
+    except (ValueError, TypeError):
+        return f"{label} must be an integer, got: {value}"
+    if num < 1:
+        return f"{label} must be >= 1, got: {num}"
+    return num

tools/file_write.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from pathlib import Path
+from core.tool import Tool, ToolResult
+from core.file_state import (
+    record_file_state,
+    create_snippet,
+)
+
+
+class FileWriteTool(Tool):
+    name = "Write"
+    description = (
+        "Writes a file to the local filesystem.\n\n"
+        "Usage:\n"
+        "- This tool will overwrite the existing file if one exists at the path.\n"
+        "- Prefer the Edit tool for modifying existing files — it only sends the diff. "
+        "Only use this tool to create new files or for complete rewrites.\n"
+        "- NEVER create documentation files (*.md) or README files unless explicitly requested."
+    )
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "file_path": {"type": "string", "description": "Absolute path to the file to write"},
+            "content": {"type": "string", "description": "The full content to write to the file"},
+        },
+        "required": ["file_path", "content"],
+    }
+
+    def __init__(self, sandbox_manager=None, session_id: str = ""):
+        self._sandbox = sandbox_manager
+        self._session_id = session_id
+
+    def set_session_id(self, session_id: str) -> None:
+        """Phase 3: engine 注入当前会话 ID。"""
+        self._session_id = session_id
+
+    def get_activity_description(self, **kwargs) -> str | None:
+        fp = kwargs.get("file_path", "")
+        return f"Writing {fp}" if fp else None
+
+    def execute(self, file_path: str, content: str) -> ToolResult:
+        # 沙箱路径保护：禁止写入受保护目录
+        if self._sandbox is not None:
+            allowed, reason = self._sandbox.check_path(file_path, "write")
+            if not allowed:
+                return ToolResult(content=f"Error: {reason}", is_error=True)
+
+        path = Path(file_path)
+
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(content, encoding="utf-8")
+        except OSError as e:
+            return ToolResult(content=f"Error writing file: {e}", is_error=True)
+
+        lines = content.count("\n") + (1 if content and not content.endswith("\n") else 0)
+        lines = max(lines, 1)  # 空文件 → 1 行，避免 snippet end_line=0
+
+        # Phase 3: 刷新文件状态 + 创建新 snippet
+        meta = None
+        if self._session_id:
+            resolved = str(path.resolve())
+            stat = path.stat()
+            record_file_state(self._session_id, resolved, content, stat.st_mtime, bump_version=True)
+            snippet = create_snippet(self._session_id, resolved, 1, lines, scope_type="full")
+            meta = {
+                "file_path": resolved,
+                "snippet_id": snippet.id,
+                "start_line": 1,
+                "end_line": lines,
+                "scope_type": "full",
+            }
+
+        return ToolResult(
+            content=f"Successfully wrote {lines} lines to {file_path}",
+            metadata=meta,
+        )

tools/glob_tool.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import glob as glob_module
+import subprocess
+from pathlib import Path
+
+from core.tool import Tool, ToolResult
+
+_MAX_RESULTS = 100
+
+
+class GlobTool(Tool):
+    name = "Glob"
+    description = (
+        "- Fast file pattern matching tool\n"
+        "- Supports glob patterns like \"**/*.js\" or \"src/**/*.ts\"\n"
+        "- Returns matching file paths sorted by modification date\n"
+        "- Use when you need to find files by name patterns"
+    )
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "pattern": {"type": "string", "description": "Glob pattern for file matching"},
+            "path": {"type": "string", "description": "Directory to search in (default: cwd)"},
+        },
+        "required": ["pattern"],
+    }
+
+    def is_read_only(self) -> bool:
+        return True
+
+    def get_activity_description(self, **kwargs) -> str | None:
+        pattern = kwargs.get("pattern", "")
+        return f"Finding {pattern}" if pattern else None
+
+    def execute(self, pattern: str, path: str = ".") -> ToolResult:
+        base = Path(path).resolve()
+        if not base.exists():
+            return ToolResult(content=f"Error: Directory not found: {path}", is_error=True)
+        if not base.is_dir():
+            return ToolResult(content=f"Error: Path is not a directory: {path}", is_error=True)
+
+        try:
+            matches = self._rg_glob(pattern, str(base))
+        except FileNotFoundError:
+            matches = self._python_glob(pattern, base)
+
+        if not matches:
+            return ToolResult(content="No files found matching the pattern.")
+
+        truncated = len(matches) > _MAX_RESULTS
+        matches = matches[:_MAX_RESULTS]
+
+        rel_matches = []
+        for m in matches:
+            try:
+                rel_matches.append(str(Path(m).relative_to(base)))
+            except ValueError:
+                rel_matches.append(m)
+
+        result = "\n".join(rel_matches)
+        if truncated:
+            result += "\n(Results are truncated. Consider using a more specific path or pattern.)"
+        return ToolResult(content=result)
+
+    def _rg_glob(self, pattern: str, search_dir: str) -> list[str]:
+        cmd = ["rg", "--files", "--glob", pattern, "--sort=modified",
+               "--no-ignore", "--hidden", search_dir]
+        result = subprocess.run(
+            cmd, capture_output=True, text=True,
+            encoding="utf-8", errors="replace", timeout=30,
+        )
+        if result.returncode not in (0, 1):
+            raise FileNotFoundError("rg failed")
+        output = result.stdout.strip()
+        return output.split("\n") if output else []
+
+    def _python_glob(self, pattern: str, base: Path) -> list[str]:
+        matches = glob_module.glob(pattern, root_dir=str(base), recursive=True)
+        matches = sorted(matches, key=lambda p: (base / p).stat().st_mtime, reverse=True)
+        return [str(base / m) for m in matches]