Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

13.3 KB
Raw Blame
"""Path resolution and per-file mutation serialization for the file tools.

Ported from Pi ``packages/coding-agent/src/core/tools/path-utils.ts``,
``file-mutation-queue.ts``, and ``src/utils/paths.ts`` (MIT, Copyright (c) 2025
Mario Zechner).
"""

from __future__ import annotations

import asyncio
import contextlib
import errno
import functools
import ipaddress
import os
import re
import stat
import unicodedata
from contextlib import asynccontextmanager
from concurrent.futures import Executor
from typing import Any, AsyncIterator, Awaitable, Callable, Literal, Optional, TypeVar
from urllib.parse import unquote

from core.agent_core.tools import windows_files
from core.agent_core.tools.args import ToolInputError

T = TypeVar("T")

_UNICODE_SPACES = re.compile("[\u00a0\u2000-\u200a\u202f\u205f\u3000]")
_NARROW_NO_BREAK_SPACE = "\u202f"
_AM_PM = re.compile(r" (AM|PM)\.", re.IGNORECASE)
_WINDOWS = os.name == "nt"
_ENCODED_SEPARATOR = re.compile("%2f", re.IGNORECASE)
_ENCODED_SEPARATOR_WINDOWS = re.compile("%2f|%5c", re.IGNORECASE)
_MALFORMED_ESCAPE = re.compile("%(?![0-9a-fA-F]{2})")
_C0_OR_SPACE = "".join(map(chr, range(0x21)))
_TAB_OR_NEWLINE = dict.fromkeys(map(ord, "\t\n\r"))
_QUERY_OR_FRAGMENT = re.compile("[?#]")
_DRIVE = re.compile(r"[A-Za-z][:|]\Z")
_NORMALIZED_DRIVE = re.compile(r"[A-Za-z]:\Z")
_FORBIDDEN_HOST = re.compile(r"[\x00-\x20#%/:<>?@\[\\\]^|\x7f]")
_IDNA_JOINERS = re.compile("[\u1806\u200c\u200d]")
_NUMERIC_LABEL = re.compile(r"(?:[0-9]+|0[xX][0-9a-fA-F]*)\Z")
_SINGLE_DOT = {".", "%2e"}
_DOUBLE_DOT = {"..", ".%2e", "%2e.", "%2e%2e"}


def expand_path(path: str) -> str:
    """Normalize a model-supplied path: Unicode spaces, a leading ``@``, ``~``, ``file://``."""
    value = _UNICODE_SPACES.sub(" ", path)
    if value.startswith("@"):
        value = value[1:]
    if value == "~" or value.startswith("~/"):
        value = os.path.expanduser(value)
    if value.startswith("file://"):
        value = _file_url_to_path(value)
    return value


def _file_url_to_path(url: str) -> str:
    """Node's ``fileURLToPath``, which Pi uses, after the WHATWG URL parser's steps for a file URL.

    The parser removes C0 controls and spaces at either end and every tab and newline, reads a
    backslash as ``/``, drops the query and fragment, percent-decodes and lowercases the host, takes
    ``file://C:/`` as a path, writes a drive ``C|`` as ``C:``, and resolves ``.`` and ``..`` segments
    (``%2e`` too) without climbing above a drive. An empty or ``localhost`` host names this machine.
    Any other host is a UNC share on Windows and an error elsewhere, so a URL can never name a local
    file it did not mean. Encoded separators are refused, as Node refuses them.
    """
    rest = url.strip(_C0_OR_SPACE).translate(_TAB_OR_NEWLINE).replace("\\", "/")[len("file://") :]
    rest = _QUERY_OR_FRAGMENT.split(rest, maxsplit=1)[0]
    authority, slash, path = rest.partition("/")
    if _DRIVE.match(authority):
        authority, path = "", f"{authority}/{path}" if slash else authority
    host = _url_host(authority)
    pathname = _url_pathname(path)
    if _WINDOWS:
        if _ENCODED_SEPARATOR_WINDOWS.search(pathname):
            raise ToolInputError("Invalid path: a file URL must not include encoded \\ or / characters")
        local = _decode_url_path(pathname).replace("/", "\\")
        if host:
            return f"\\\\{host}{local}"
        if len(local) >= 3 and local[1].isascii() and local[1].isalpha() and local[2] == ":":
            return local[1:]
        raise ToolInputError("Invalid path: a file URL must be absolute")
    if host:
        raise ToolInputError("Invalid path: file URL host must be empty or localhost")
    if _ENCODED_SEPARATOR.search(pathname):
        raise ToolInputError("Invalid path: a file URL must not include encoded / characters")
    return _decode_url_path(pathname)


def _url_host(authority: str) -> str:
    """The WHATWG host of a file URL, lowercased, and empty for ``localhost``.

    Only hosts whose WHATWG form is the text itself are kept: ASCII names, dotted-quad IPv4, and
    IPv6 in its compressed form. A host that needs IDNA processing or address parsing to reach
    Node's form is refused rather than guessed (Python has IDNA 2003, Node UTS #46), unless it maps
    to ``localhost``, so a URL never names a share or a file Node would not.
    """
    if not authority:
        return ""
    try:
        host = unquote(authority, errors="strict")
    except UnicodeError:
        raise _invalid_host() from None
    if host.startswith("[") and host.endswith("]"):
        try:
            canonical = ipaddress.IPv6Address(host[1:-1]).compressed
        except ValueError:
            raise _invalid_host() from None
        if "." in host or canonical != host[1:-1].lower():
            raise _invalid_host()
        return f"[{canonical}]"
    if not host.isascii() or "xn--" in host.lower():
        # Node fails a zero-width joiner or non-joiner where Python's IDNA quietly drops it.
        if not _IDNA_JOINERS.search(host):
            with contextlib.suppress(UnicodeError):
                if host.encode("idna").decode("ascii").lower() == "localhost":
                    return ""
        raise _invalid_host()
    host = host.lower()
    if _FORBIDDEN_HOST.search(host):
        raise _invalid_host()
    labels = host.split(".")
    last = labels[-1] or (labels[-2] if len(labels) > 1 else "")
    if _NUMERIC_LABEL.match(last):
        # WHATWG parses it as IPv4 and prints it as a dotted quad; only that form is the text itself.
        try:
            if str(ipaddress.IPv4Address(host)) != host:
                raise ValueError(host)
        except ValueError:
            raise _invalid_host() from None
    return "" if host == "localhost" else host


def _invalid_host() -> ToolInputError:
    return ToolInputError("Invalid path: a file URL must have a valid host")


def _url_pathname(path: str) -> str:
    """The WHATWG path of a file URL (still percent-encoded), from the text after the authority's ``/``."""
    segments: list[str] = []
    parts = path.split("/")
    for index, segment in enumerate(parts):
        last = index == len(parts) - 1
        lowered = segment.lower()
        if lowered in _DOUBLE_DOT:
            if segments and not (len(segments) == 1 and _NORMALIZED_DRIVE.match(segments[0])):
                segments.pop()
            if last:
                segments.append("")
        elif lowered in _SINGLE_DOT:
            if last:
                segments.append("")
        else:
            if not segments and _DRIVE.match(segment):
                segment = segment[0] + ":"
            segments.append(segment)
    return "/" + "/".join(segments)


def _decode_url_path(path: str) -> str:
    """``decodeURIComponent``: a malformed escape or bytes that are not UTF-8 are an error, never a guess."""
    if _MALFORMED_ESCAPE.search(path):
        raise ToolInputError("Invalid path: a file URL must use valid percent-encoded UTF-8")
    try:
        return unquote(path, errors="strict")
    except UnicodeDecodeError:
        raise ToolInputError("Invalid path: a file URL must use valid percent-encoded UTF-8") from None


def resolve_to_cwd(path: str, cwd: str) -> str:
    """The absolute path; raises ``ToolInputError`` for a path no file can have (a NUL byte, possibly from ``%00``)."""
    expanded = expand_path(path)
    if "\x00" in expanded:
        raise ToolInputError(f"Invalid path: {path!r} contains a NUL byte")
    if os.path.isabs(expanded):
        return os.path.normpath(expanded)
    return os.path.normpath(os.path.join(cwd, expanded))


def resolve_read_path(path: str, cwd: str) -> str:
    """Like ``resolve_to_cwd``, also trying the spellings macOS uses in screenshot names."""
    resolved = resolve_to_cwd(path, cwd)
    if os.path.exists(resolved):
        return resolved
    am_pm = _AM_PM.sub(lambda m: f"{_NARROW_NO_BREAK_SPACE}{m.group(1)}.", resolved)
    nfd = unicodedata.normalize("NFD", resolved)
    curly = resolved.replace("'", "\u2019")
    nfd_curly = nfd.replace("'", "\u2019")
    for candidate in (am_pm, nfd, curly, nfd_curly):
        if candidate != resolved and os.path.exists(candidate):
            return candidate
    return resolved


FileKind = Literal["regular", "directory", "other"]

#: Why a tool refuses a file that exists but is not a regular file.
KIND_REASON = {"directory": "it is a directory", "other": "it is not a regular file"}


def target_kind(path: str) -> FileKind:
    """What ``path`` names, following symlinks. ``stat`` never opens the file, so a FIFO cannot block it.

    Raises ``OSError`` as ``stat`` does: missing or dangling (ENOENT), a loop (ELOOP), a file used as a
    directory (ENOTDIR), no search permission (EACCES).
    """
    mode = os.stat(path).st_mode
    if stat.S_ISREG(mode):
        return "regular"
    return "directory" if stat.S_ISDIR(mode) else "other"


class NotRegularFile(OSError):
    """The descriptor names a directory or a special file; ``kind`` says which."""

    def __init__(self, kind: FileKind) -> None:
        super().__init__(KIND_REASON[kind])
        self.kind = kind


def open_regular(path: str, flags: int = os.O_RDONLY) -> int:
    """Open a model-named file once and return the descriptor, which is a regular file.

    ``O_NONBLOCK`` keeps a FIFO swapped in after an earlier check from blocking the open, and the
    kind is taken from the descriptor (``fstat``), so sizes and contents come from the same file.
    Windows has no FIFO to block on, and needs ``O_BINARY``: a text-mode descriptor would drop CRs
    and stop reading at the first 0x1A byte. Raises ``NotRegularFile`` or the ``OSError`` of the open.

    On Windows a file is opened for reading shared for delete, as POSIX always shares it, so a job's
    wrapper can still replace the ``tail.log`` the model is told to read (``windows_files``).
    """
    if os.name == "nt" and flags == os.O_RDONLY:
        fd = windows_files.open_for_reading(path)
    else:
        fd = os.open(path, flags | getattr(os, "O_NONBLOCK", 0) | getattr(os, "O_BINARY", 0) | getattr(os, "O_CLOEXEC", 0))
    try:
        mode = os.fstat(fd).st_mode
        if not stat.S_ISREG(mode):
            raise NotRegularFile("directory" if stat.S_ISDIR(mode) else "other")
    except BaseException:
        os.close(fd)
        raise
    return fd


def read_at_most(fd: int, limit: int) -> bytes:
    """Up to ``limit + 1`` bytes from ``fd``, so a caller can tell the file is over ``limit``."""
    chunks, remaining = [], limit + 1
    while remaining > 0:
        chunk = os.read(fd, min(remaining, 1024 * 1024))
        if not chunk:
            break
        chunks.append(chunk)
        remaining -= len(chunk)
    return b"".join(chunks)


def os_reason(error: OSError) -> str:
    """``No such file or directory`` → ``no such file or directory``, for ``Cannot … {path}: {reason}.``"""
    text = error.strerror or str(error) or type(error).__name__
    return text[:1].lower() + text[1:]


def errno_name(error: OSError) -> str:
    return errno.errorcode.get(error.errno or 0, "EIO")


class _PathLock:
    __slots__ = ("lock", "users")

    def __init__(self) -> None:
        self.lock = asyncio.Lock()
        self.users = 0


_locks: dict[str, _PathLock] = {}


@asynccontextmanager
async def file_mutation_lock(path: str) -> AsyncIterator[None]:
    """Serialize ``write`` and ``edit`` on one file, keyed by its canonical path.

    Different files proceed in parallel. The key follows symlinks, so two names
    for one file share a lock, and so do two spellings of one name on Windows, where names are
    case-insensitive and a file that does not exist yet keeps the spelling it was named with.
    """
    key = os.path.normcase(os.path.realpath(path))
    entry = _locks.get(key)
    if entry is None:
        entry = _locks[key] = _PathLock()
    entry.users += 1
    try:
        async with entry.lock:
            yield
    finally:
        entry.users -= 1
        if entry.users == 0:
            del _locks[key]


async def to_thread_joined(func: Callable[..., T], /, *args: Any) -> T:
    """``asyncio.to_thread`` for work inside ``file_mutation_lock``: a cancel waits for the thread.

    Cancelling an await does not stop its worker thread, so without the wait a write could land after
    the lock was released and overwrite the next writer's result. The cancel is re-raised once the
    thread is done, however often the caller is cancelled and even when the thread raised.
    """
    return await run_joined(None, func, *args)


async def run_joined(executor: Optional[Executor], func: Callable[..., T], /, *args: Any) -> T:
    """``func(*args)`` on ``executor`` (``None``: asyncio's default); a cancel waits for it (see above)."""
    return await run_to_end(asyncio.get_running_loop().run_in_executor(executor, functools.partial(func, *args)))


async def run_to_end(awaitable: Awaitable[T]) -> T:
    """Await ``awaitable`` to its end even if the caller is cancelled meanwhile, then re-raise the cancel.

    For state transitions that must not stop half-way once begun (a worker thread, a decision, a kill).
    """
    worker = asyncio.ensure_future(awaitable)
    try:
        return await asyncio.shield(worker)
    except asyncio.CancelledError:
        while not worker.done():
            try:
                await asyncio.wait({worker})
            except asyncio.CancelledError:
                pass
        if not worker.cancelled():
            worker.exception()  # retrieved; the caller's cancel is what propagates
        raise