semora-coding 0.2.0__py3-none-any.whl

semora_coding/builtins/_files.py

@@ -0,0 +1,257 @@
+"""Workspace-backed read, write, and edit built-ins."""
+
+from __future__ import annotations
+
+import base64
+import json
+from pathlib import PurePath
+from typing import Any
+
+from semora.workspace import ToolContext, WorkspaceViolation
+
+from ._types import BuiltinToolState, ToolResult, error_result, require_workspace, text_result
+
+MAX_LINES = 2_000
+MAX_BYTES = 8 * 1024 * 1024
+NOTEBOOK_OUTPUT_LIMIT = 10 * 1024
+IMAGE_MIME_BY_EXT = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+}
+
+
+async def read_tool(
+    _call_id: str, arguments: object, context: ToolContext, state: BuiltinToolState
+) -> ToolResult:
+    """Read a text file, image, notebook, or directory through ``WorkspaceFS``.
+
+    Ports ``createReadTool().execute`` and its ``numberLines`` expression.
+    """
+    params = arguments if isinstance(arguments, dict) else {}
+    raw_path = params.get("path")
+    path = raw_path.strip() if isinstance(raw_path, str) else ""
+    if not path:
+        return error_result("path is required")
+    workspace = require_workspace(context)
+    if workspace is None:
+        return error_result(
+            "read requires an active workspace; configure AgentRuntime(workspace_provider=...) "
+            "or pass a ToolContext to builtin_tools()"
+        )
+
+    try:
+        stat = await workspace.fs.stat(path)
+    except FileNotFoundError:
+        return await _not_found(path, context)
+    except (OSError, ValueError, WorkspaceViolation) as error:
+        return error_result(f"Cannot read: {error}")
+
+    if stat.is_directory:
+        try:
+            entries = await workspace.fs.readdir(path)
+        except (OSError, ValueError, WorkspaceViolation) as error:
+            return error_result(f"Cannot read directory: {error}")
+        lines = sorted(entry.name + ("/" if entry.is_directory else "") for entry in entries)
+        return text_result(f"Directory: {path}\n\n" + "\n".join(lines))
+    if not stat.is_file:
+        return error_result(f"Cannot read: {path} is not a regular file")
+
+    suffix = PurePath(path).suffix.lower()
+    try:
+        data = await workspace.fs.read_file(path)
+    except (OSError, ValueError, WorkspaceViolation) as error:
+        return error_result(f"Cannot read: {error}")
+
+    if suffix in IMAGE_MIME_BY_EXT:
+        return {
+            "type": "image",
+            "data": base64.b64encode(data).decode("ascii"),
+            "mime_type": IMAGE_MIME_BY_EXT[suffix],
+        }
+    if suffix == ".pdf":
+        return error_result(
+            "Cannot read PDF: page rendering is not available in this runtime; "
+            "provide a PDF-capable tool if the application needs it"
+        )
+    if len(data) > MAX_BYTES:
+        return error_result(f"Cannot read: {path} exceeds {MAX_BYTES} byte cap ({len(data)} bytes)")
+    if suffix == ".ipynb":
+        return _read_notebook(path, data)
+
+    offset = _positive_int(params.get("offset"))
+    limit = _positive_int(params.get("limit"))
+    key = f"{workspace.id}\0{path}"
+    signature = (int(stat.mtime_ms), stat.size, offset, limit)
+    if state.read_files.get(key) == signature:
+        return text_result(
+            f"<file unchanged since you last read it — its content is already in context: {path}>"
+        )
+    state.read_files[key] = signature
+    return text_result(_number_lines(data.decode("utf-8", errors="replace"), offset, limit))
+
+
+async def write_tool(
+    _call_id: str, arguments: object, context: ToolContext, state: BuiltinToolState
+) -> ToolResult:
+    """Create or replace a workspace file, matching ``createWriteTool().execute``."""
+    params = arguments if isinstance(arguments, dict) else {}
+    raw_path = params.get("path")
+    path = raw_path.strip() if isinstance(raw_path, str) else ""
+    if not path:
+        return error_result("path is required")
+    content = params.get("content")
+    if not isinstance(content, str):
+        return error_result("content is required")
+    workspace = require_workspace(context)
+    if workspace is None:
+        return error_result("write requires an active workspace")
+    try:
+        resolved = await workspace.resolve(path, access="write")
+        async with state.file_lock(f"{workspace.id}\0{resolved.relative_path}"):
+            await workspace.fs.write_file(path, content.encode(), atomic=True)
+    except (OSError, ValueError, WorkspaceViolation) as error:
+        return error_result(f"Cannot write: {error}")
+    return text_result(f"Wrote {len(content)} bytes to {path}")
+
+
+async def edit_tool(
+    _call_id: str, arguments: object, context: ToolContext, state: BuiltinToolState
+) -> ToolResult:
+    """Apply an exact string replacement, matching ``createEditTool().execute``."""
+    params = arguments if isinstance(arguments, dict) else {}
+    raw_path = params.get("path")
+    path = raw_path.strip() if isinstance(raw_path, str) else ""
+    if not path:
+        return error_result("path is required")
+    old = params.get("old_string")
+    new = params.get("new_string")
+    if not isinstance(old, str):
+        return error_result("old_string is required")
+    if not isinstance(new, str):
+        return error_result("new_string is required")
+    if old == new:
+        return error_result("old_string and new_string are identical")
+    workspace = require_workspace(context)
+    if workspace is None:
+        return error_result("edit requires an active workspace")
+
+    try:
+        resolved = await workspace.resolve(path, access="readwrite")
+        async with state.file_lock(f"{workspace.id}\0{resolved.relative_path}"):
+            stat = await workspace.fs.stat(path)
+            if stat.is_directory:
+                return error_result(f"Cannot edit: {path} is a directory")
+            content = (await workspace.fs.read_file(path)).decode("utf-8")
+            occurrences = content.count(old)
+            if occurrences == 0:
+                return error_result("old_string not found in file")
+            replace_all = params.get("replace_all") is True
+            if occurrences > 1 and not replace_all:
+                return error_result(
+                    f"old_string appears {occurrences} times; provide a more specific string "
+                    "or set replace_all=true"
+                )
+            updated = content.replace(old, new) if replace_all else content.replace(old, new, 1)
+            await workspace.fs.write_file(
+                path, updated.encode(), mode=stat.mode & 0o777, atomic=True
+            )
+    except FileNotFoundError:
+        return error_result(f"Cannot edit: {path} not found")
+    except UnicodeDecodeError:
+        return error_result(f"Cannot edit: {path} is not UTF-8 text")
+    except (OSError, ValueError, WorkspaceViolation) as error:
+        return error_result(f"Cannot edit: {error}")
+    count = occurrences if params.get("replace_all") is True else 1
+    return text_result(f"Replaced {count} occurrence{'s' if count != 1 else ''} in {path}")
+
+
+def _number_lines(content: str, offset: int | None, limit: int | None) -> str:
+    lines = content.split("\n")
+    start = offset - 1 if offset is not None else 0
+    count = min(limit, MAX_LINES) if limit is not None else MAX_LINES
+    end = min(start + count, len(lines))
+    numbered = "\n".join(
+        f"{line_number:>6}→{line}"
+        for line_number, line in enumerate(lines[start:end], start=start + 1)
+    )
+    if end < len(lines):
+        numbered += (
+            f"\n\n[Showing lines {start + 1}-{end} of {len(lines)}. "
+            f"Use offset={end + 1} to continue.]"
+        )
+    return numbered
+
+
+def _positive_int(value: Any) -> int | None:
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or value <= 0:
+        return None
+    return int(value)
+
+
+async def _not_found(path: str, context: ToolContext) -> ToolResult:
+    workspace = context.workspace
+    assert workspace is not None
+    pure = PurePath(path)
+    try:
+        entries = await workspace.fs.readdir(str(pure.parent))
+    except (OSError, ValueError, WorkspaceViolation):
+        return error_result(f"Cannot read: {path} not found")
+    match = next(
+        (
+            entry.name
+            for entry in entries
+            if entry.name != pure.name and PurePath(entry.name).stem == pure.stem
+        ),
+        None,
+    )
+    suggestion = str(pure.parent / match) if match is not None else None
+    message = f"Cannot read: {path} not found"
+    if suggestion is not None:
+        message += f". Did you mean {suggestion}?"
+    return error_result(message)
+
+
+def _read_notebook(path: str, data: bytes) -> ToolResult:
+    try:
+        notebook = json.loads(data)
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        return error_result(f"Cannot read notebook {path}: {error}")
+    cells = notebook.get("cells") if isinstance(notebook, dict) else None
+    if not isinstance(cells, list):
+        return error_result(f"Cannot read notebook {path}: cells is not a list")
+    sections: list[str] = []
+    for index, cell in enumerate(cells, start=1):
+        if not isinstance(cell, dict):
+            continue
+        kind = cell.get("cell_type", "unknown")
+        source = cell.get("source", "")
+        text = "".join(source) if isinstance(source, list) else str(source)
+        sections.append(f"## Cell {index} ({kind})\n{text}")
+        outputs = cell.get("outputs", [])
+        if isinstance(outputs, list):
+            rendered = "".join(_notebook_output(item) for item in outputs)
+            if rendered:
+                sections.append(rendered[:NOTEBOOK_OUTPUT_LIMIT])
+    return text_result("\n\n".join(sections))
+
+
+def _notebook_output(output: object) -> str:
+    if not isinstance(output, dict):
+        return ""
+    for key in ("text", "traceback"):
+        value = output.get(key)
+        if isinstance(value, list):
+            return "".join(str(item) for item in value)
+        if isinstance(value, str):
+            return value
+    data = output.get("data")
+    if isinstance(data, dict):
+        text = data.get("text/plain")
+        if isinstance(text, list):
+            return "".join(str(item) for item in text)
+        if isinstance(text, str):
+            return text
+    return ""

semora_coding/builtins/_search.py

@@ -0,0 +1,384 @@
+"""Workspace-backed glob and grep built-ins."""
+
+from __future__ import annotations
+
+import asyncio
+import math
+from collections.abc import Mapping, Sequence
+
+from semora.workspace import CommandResult, SandboxCommand, ToolContext, WorkspaceViolation
+
+from ._types import (
+    BuiltinToolState,
+    ToolResult,
+    error_result,
+    require_workspace,
+    text_result,
+    tool_environment,
+)
+
+SEARCH_TIMEOUT_SECONDS = 120.0
+DEFAULT_HEAD_LIMIT = 250
+MAX_COLUMNS = 500
+
+
+async def glob_tool(
+    _call_id: str, arguments: object, context: ToolContext, state: BuiltinToolState
+) -> ToolResult:
+    """Find paths using ripgrep, porting ``createGlobTool().execute``."""
+    params = arguments if isinstance(arguments, dict) else {}
+    raw_pattern = params.get("pattern")
+    pattern = raw_pattern.strip() if isinstance(raw_pattern, str) else ""
+    if not pattern:
+        return error_result("pattern is required")
+    if ".." in pattern:
+        return error_result('pattern must not contain ".."')
+    workspace = require_workspace(context)
+    if workspace is None:
+        return error_result("glob requires an active workspace")
+    offset = _clamp_int(params.get("offset"), 0, 0)
+    head_limit = _clamp_int(params.get("head_limit"), DEFAULT_HEAD_LIMIT, 0)
+    raw_path = params.get("path")
+    path = raw_path.strip() if isinstance(raw_path, str) and raw_path.strip() else "."
+    try:
+        resolved = await workspace.fs.real_path(path)
+    except FileNotFoundError:
+        return text_result("No files found.")
+    except (OSError, ValueError, WorkspaceViolation) as error:
+        return error_result(f"Cannot glob: {error}")
+    if await _detect_engine(context, state) != "rg":
+        return error_result("glob requires ripgrep (rg), which was not found on PATH")
+    try:
+        process = await _run_engine(
+            context,
+            "rg",
+            ["--files", "--glob", pattern, str(resolved.path)],
+            str(resolved.root),
+        )
+    except (OSError, ValueError, WorkspaceViolation) as error:
+        return error_result(f"Cannot glob: {error}")
+    classified = _classify(process, "glob")
+    if isinstance(classified, str):
+        return error_result(classified)
+    stdout, warning = classified
+    lines = [line for line in stdout.splitlines() if line]
+    if not lines:
+        return text_result("No files found." + warning)
+    return await _format_files(
+        lines, str(resolved.root), offset, head_limit, warning, context
+    )
+
+
+async def grep_tool(
+    _call_id: str, arguments: object, context: ToolContext, state: BuiltinToolState
+) -> ToolResult:
+    """Search contents, porting ``createGrepTool().execute`` and argument builders."""
+    params = arguments if isinstance(arguments, dict) else {}
+    raw_pattern = params.get("pattern")
+    pattern = raw_pattern.strip() if isinstance(raw_pattern, str) else ""
+    if not pattern:
+        return error_result("pattern is required")
+    output_mode = params.get("output_mode", "content")
+    if output_mode not in {"content", "files_with_matches", "count"}:
+        return error_result("output_mode must be content, files_with_matches, or count")
+    raw_glob = params.get("glob")
+    glob = raw_glob.strip() if isinstance(raw_glob, str) and raw_glob.strip() else None
+    if glob is not None and ".." in glob:
+        return error_result('glob must not contain ".."')
+    workspace = require_workspace(context)
+    if workspace is None:
+        return error_result("grep requires an active workspace")
+    raw_path = params.get("path")
+    path = raw_path.strip() if isinstance(raw_path, str) and raw_path.strip() else "."
+    try:
+        resolved = await workspace.fs.real_path(path)
+    except FileNotFoundError:
+        return text_result("No matches found.")
+    except (OSError, ValueError, WorkspaceViolation) as error:
+        return error_result(f"Cannot grep: {error}")
+
+    offset = _clamp_int(params.get("offset"), 0, 0)
+    head_limit = _clamp_int(params.get("head_limit"), DEFAULT_HEAD_LIMIT, 0)
+    engine = await _detect_engine(context, state)
+    target = str(resolved.path)
+    args = (
+        _rg_args(params, pattern, str(output_mode), glob, target)
+        if engine == "rg"
+        else _grep_args(params, pattern, str(output_mode), glob, target)
+    )
+    try:
+        process = await _run_engine(context, engine, args, str(resolved.root))
+    except (OSError, ValueError, WorkspaceViolation) as error:
+        return error_result(f"Cannot grep: {error}")
+    classified = _classify(process, "grep")
+    if isinstance(classified, str):
+        return error_result(classified)
+    stdout, warning = classified
+    degraded = _grep_degradation(params) if engine == "grep" else ""
+    tail = warning + (f"\n\n{degraded}" if degraded else "")
+    lines = [line for line in stdout.splitlines() if line]
+    if not lines:
+        return text_result("No matches found." + tail)
+    root = str(resolved.root)
+    if output_mode == "files_with_matches":
+        return await _format_files(lines, root, offset, head_limit, tail, context)
+    if output_mode == "count":
+        return _format_count(lines, root, offset, head_limit, tail)
+    return _format_content(lines, root, offset, head_limit, tail)
+
+
+async def _detect_engine(context: ToolContext, state: BuiltinToolState) -> str:
+    workspace = context.workspace
+    assert workspace is not None
+    cached = state.search_engines.get(workspace.id)
+    if cached is not None:
+        return cached
+    try:
+        result = await _run_engine(context, "rg", ["--version"], str(workspace.root), timeout=5)
+        engine = "rg" if result.exit_code == 0 else "grep"
+    except (OSError, ValueError, WorkspaceViolation):
+        engine = "grep"
+    state.search_engines[workspace.id] = engine
+    return engine
+
+
+async def _run_engine(
+    context: ToolContext,
+    engine: str,
+    args: Sequence[str],
+    cwd: str,
+    *,
+    timeout: float = SEARCH_TIMEOUT_SECONDS,
+) -> CommandResult:
+    workspace = context.workspace
+    assert workspace is not None
+    return await workspace.run(
+        SandboxCommand(
+            argv=[engine, *args],
+            cwd=cwd,
+            env=tool_environment(()),
+            inherit_env=False,
+            timeout_seconds=timeout,
+            require_isolation=workspace.isolated,
+            allowed_domains=() if workspace.isolated else None,
+        )
+    )
+
+
+def _classify(result: CommandResult, noun: str) -> tuple[str, str] | str:
+    has_stdout = bool(result.stdout.strip())
+    if result.aborted:
+        return (
+            (result.stdout, f"\n\n[{noun} aborted: partial results returned]")
+            if has_stdout
+            else f"{noun} aborted"
+        )
+    if result.timed_out:
+        return (
+            (result.stdout, f"\n\n[{noun} timed out: partial results returned]")
+            if has_stdout
+            else f"{noun} timed out"
+        )
+    if result.signal:
+        partial = f"\n\n[{noun} killed by signal {result.signal}: partial results returned]"
+        return (
+            (result.stdout, partial)
+            if has_stdout
+            else f"{noun} killed by signal {result.signal}"
+        )
+    if result.exit_code in {0, 1}:
+        return result.stdout, ""
+    detail = result.stderr.strip() or f"{noun} failed with exit {result.exit_code}"
+    if has_stdout:
+        warning = (
+            f"\n\n[{noun} exited {result.exit_code}: {detail}; partial results returned]"
+        )
+        return result.stdout, warning
+    return detail
+
+
+def _rg_args(
+    params: Mapping[str, object],
+    pattern: str,
+    output_mode: str,
+    glob: str | None,
+    target: str,
+) -> list[str]:
+    args = ["--max-columns", str(MAX_COLUMNS)]
+    if params.get("multiline") is True:
+        args.extend(["-U", "--multiline-dotall"])
+    if params.get("-i") is True:
+        args.append("-i")
+    if output_mode == "files_with_matches":
+        args.append("-l")
+    elif output_mode == "count":
+        args.append("-c")
+    else:
+        if params.get("-n", True) is not False:
+            args.append("-n")
+        _push_context(args, params)
+    _push_pattern(args, pattern)
+    file_type = params.get("type")
+    if isinstance(file_type, str) and file_type:
+        args.extend(["--type", file_type])
+    for item in _split_globs(glob):
+        args.extend(["--glob", item])
+    args.append(target)
+    return args
+
+
+def _grep_args(
+    params: Mapping[str, object],
+    pattern: str,
+    output_mode: str,
+    glob: str | None,
+    target: str,
+) -> list[str]:
+    args = ["-rE", "--color=never"]
+    if params.get("-i") is True:
+        args.append("-i")
+    if output_mode == "files_with_matches":
+        args.append("-l")
+    elif output_mode == "count":
+        args.append("-c")
+    else:
+        if params.get("-n", True) is not False:
+            args.append("-n")
+        _push_context(args, params)
+    for item in _split_globs(glob):
+        if "/" not in item:
+            args.append(f"--include={item}")
+    args.append("--")
+    _push_pattern(args, pattern)
+    args.append(target)
+    return args
+
+
+def _push_context(args: list[str], params: Mapping[str, object]) -> None:
+    for key in ("context", "-C"):
+        if key in params:
+            args.extend(["-C", str(_clamp_int(params[key], 0, 0))])
+            return
+    if "-B" in params:
+        args.extend(["-B", str(_clamp_int(params["-B"], 0, 0))])
+    if "-A" in params:
+        args.extend(["-A", str(_clamp_int(params["-A"], 0, 0))])
+
+
+def _push_pattern(args: list[str], pattern: str) -> None:
+    if pattern.startswith("-"):
+        args.extend(["-e", pattern])
+    else:
+        args.append(pattern)
+
+
+def _split_globs(glob: str | None) -> list[str]:
+    if glob is None:
+        return []
+    output: list[str] = []
+    for raw in glob.split():
+        output.extend([raw] if "{" in raw and "}" in raw else filter(None, raw.split(",")))
+    return output
+
+
+def _grep_degradation(params: Mapping[str, object]) -> str:
+    lost: list[str] = []
+    if params.get("type"):
+        lost.append("type")
+    if params.get("multiline"):
+        lost.append("multiline")
+    lost.append(".gitignore not respected")
+    return f"[grep fallback: ripgrep not found — {', '.join(lost)} unavailable]"
+
+
+async def _format_files(
+    lines: list[str],
+    root: str,
+    offset: int,
+    head_limit: int,
+    tail: str,
+    context: ToolContext,
+) -> ToolResult:
+    workspace = context.workspace
+    assert workspace is not None
+
+    async def mtime(path: str) -> float:
+        try:
+            return (await workspace.fs.stat(path)).mtime_ms
+        except (OSError, ValueError, WorkspaceViolation):
+            return 0
+
+    mtimes = await asyncio.gather(*(mtime(path) for path in lines))
+    sorted_lines = [
+        path
+        for path, _ in sorted(
+            zip(lines, mtimes, strict=True), key=lambda item: (-item[1], item[0])
+        )
+    ]
+    items, limited = _page(sorted_lines, head_limit, offset)
+    relative = [_strip_root(path, root) for path in items]
+    info = _limit_info(head_limit if limited else None, offset)
+    noun = "file" if len(relative) == 1 else "files"
+    header = f"Found {len(relative)} {noun}" + (f" ({info})" if info else "")
+    return text_result(f"{header}\n" + "\n".join(relative) + tail)
+
+
+def _format_count(
+    lines: list[str], root: str, offset: int, head_limit: int, tail: str
+) -> ToolResult:
+    items, limited = _page(lines, head_limit, offset)
+    total = 0
+    output: list[str] = []
+    for line in items:
+        path, separator, count = line.rpartition(":")
+        if separator and count.isdigit():
+            total += int(count)
+            output.append(f"{_strip_root(path, root)}:{count}")
+        else:
+            output.append(_strip_root(line, root))
+    info = _limit_info(head_limit if limited else None, offset)
+    noun = "occurrence" if total == 1 else "occurrences"
+    files = "file" if len(output) == 1 else "files"
+    summary = f"Found {total} total {noun} across {len(output)} {files}."
+    if info:
+        summary += f" ({info})"
+    return text_result("\n".join(output) + f"\n\n{summary}" + tail)
+
+
+def _format_content(
+    lines: list[str], root: str, offset: int, head_limit: int, tail: str
+) -> ToolResult:
+    items, limited = _page(lines, head_limit, offset)
+    output = [_strip_content_root(line, root) for line in items]
+    info = _limit_info(head_limit if limited else None, offset)
+    footer = f"\n\n[pagination: {info}]" if info else ""
+    return text_result("\n".join(output) + footer + tail)
+
+
+def _strip_root(path: str, root: str) -> str:
+    prefix = root.rstrip("/") + "/"
+    return path[len(prefix) :] if path.startswith(prefix) else path
+
+
+def _strip_content_root(line: str, root: str) -> str:
+    prefix = root.rstrip("/") + "/"
+    return line[len(prefix) :] if line.startswith(prefix) else line
+
+
+def _page(items: list[str], limit: int, offset: int) -> tuple[list[str], bool]:
+    if limit == 0:
+        return items[offset:], False
+    return items[offset : offset + limit], len(items) - offset > limit
+
+
+def _limit_info(limit: int | None, offset: int) -> str:
+    parts = ([f"limit {limit}"] if limit is not None else []) + (
+        [f"offset {offset}"] if offset else []
+    )
+    return ", ".join(parts)
+
+
+def _clamp_int(value: object, fallback: int, minimum: int) -> int:
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+        return fallback
+    return max(minimum, int(value))