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.

18.8 KB
Raw Blame
"""The ``read`` tool (C-7 section 2).

Ported from Pi ``packages/coding-agent/src/core/tools/read.ts`` and
``src/utils/mime.ts`` (MIT, Copyright (c) 2025 Mario Zechner); the description
and every model-facing string are Pi's unless marked as Avibe's.

Unlike Pi, the file is streamed: only the lines that can reach the model are
kept in memory, so reading a multi-gigabyte log cannot exhaust the process the
loop shares with the rest of Avibe. The result is the same as Pi's.
"""

from __future__ import annotations

import asyncio
import codecs
import inspect
import os
import struct
from dataclasses import dataclass
from typing import Any, Awaitable, BinaryIO, Callable, Mapping, Optional, Union

from core.agent_core.messages import IMAGE_MIME_TYPES, ImageBlock, TextBlock
from core.agent_core.tools.args import (
    ToolInputError,
    error_result,
    optional_line_arg,
    str_arg,
    text_result,
)
from core.agent_core.tools.base import MAX_BYTES, MAX_LINES, ToolContext, ToolResult, ToolSpec
from core.agent_core.tools.paths import (
    KIND_REASON,
    NotRegularFile,
    open_regular,
    os_reason,
    resolve_read_path,
    target_kind,
)
from core.agent_core.tools.shell import read_line_advice
from core.agent_core.tools.text import decode_file, shown
from core.agent_core.tools.truncate import format_size, truncate_head, utf8_len

#: Stores an image for the transcript and returns its media token: ``(data, mime_type, name)``.
ImageSink = Callable[[bytes, str, str], Union[str, Awaitable[str]]]

# Pi keeps images under 4.5MB of base64 payload, below Anthropic's 5MB limit. Avibe's ``read`` does not
# resize, so the cap applies to the file as it is; requests fit its dimensions (``ai/image_limits.py``).
MAX_INLINE_IMAGE_BYTES = int(4.5 * 1024 * 1024) * 3 // 4
_IMAGE_SNIFF_BYTES = 4100
_PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
_BOM = b"\xef\xbb\xbf"
_READ_CHUNK_BYTES = 1024 * 1024

READ_DESCRIPTION = (
    "Read the contents of a file. Supports text files and images (jpg, png, gif, webp). Images are sent as "
    f"attachments. For text files, output is truncated to {MAX_LINES} lines or {MAX_BYTES // 1024}KB (whichever is "
    "hit first). Use offset/limit for large files. When you need the full file, continue with offset until complete."
)

READ_SCHEMA: Mapping[str, Any] = {
    "type": "object",
    "required": ["path"],
    "properties": {
        "path": {"type": "string", "description": "Path to the file to read (relative or absolute)"},
        "offset": {"type": "integer", "minimum": 1, "description": "Line number to start reading from (1-indexed)"},
        "limit": {"type": "integer", "minimum": 1, "description": "Maximum number of lines to read"},
    },
}


class ReadTool:
    concurrent = True

    def __init__(self, *, image_sink: Optional[ImageSink] = None) -> None:
        self._image_sink = image_sink
        self._spec = ToolSpec(name="read", description=READ_DESCRIPTION, input_schema=READ_SCHEMA)

    @property
    def spec(self) -> ToolSpec:
        return self._spec

    async def execute(self, arguments: Mapping[str, Any], ctx: ToolContext) -> ToolResult:
        if ctx.cancel.cancelled:
            return error_result("Operation aborted")
        try:
            path = str_arg(arguments, "path")
            offset = optional_line_arg(arguments, "offset")
            limit = optional_line_arg(arguments, "limit")
        except ToolInputError as exc:
            return error_result(str(exc))

        try:
            absolute = resolve_read_path(path, ctx.cwd)
            refusal = await asyncio.to_thread(_refusal, absolute)
            if refusal:
                return error_result(f"Cannot read {path}: {refusal}.")
            # Off the event loop, which every Session and surface shares; the scan stops on cancel.
            loaded = await asyncio.to_thread(_load, absolute, path, offset, limit, lambda: ctx.cancel.cancelled)
            if isinstance(loaded, _Image):
                return await self._attach(absolute, loaded)
            return loaded
        except _Aborted:
            return error_result("Operation aborted")
        except NotRegularFile as exc:
            return error_result(f"Cannot read {path}: {KIND_REASON[exc.kind]}.")
        except OSError as exc:
            return error_result(f"Cannot read {path}: {os_reason(exc)}.")
        except ToolInputError as exc:
            return error_result(str(exc))

    async def _attach(self, absolute: str, image: "_Image") -> ToolResult:
        header = f"Read image file [{image.mime_type}]"
        details = {"path": absolute, "mime_type": image.mime_type, "bytes": image.size}
        if self._image_sink is None:
            return text_result(f"{header}\n[Image omitted: image attachments are not available.]", details=details)
        name = os.path.basename(absolute)
        token = self._image_sink(image.data, image.mime_type, name)
        if inspect.isawaitable(token):
            token = await token
        return ToolResult(
            content=(TextBlock(text=header), ImageBlock(mime_type=image.mime_type, media_token=token, name=name)),
            details=details,
        )


@dataclass(frozen=True)
class _Image:
    mime_type: str
    data: bytes
    size: int


class _Aborted(Exception):
    pass


def _refusal(absolute: str) -> Optional[str]:
    """Why ``read`` will not open ``absolute``, checked without opening it (a FIFO would block)."""
    try:
        kind = target_kind(absolute)
    except OSError as exc:
        return os_reason(exc)
    if kind != "regular":
        return KIND_REASON[kind]
    if not os.access(absolute, os.R_OK):
        return "permission denied"
    return None


def _load(
    absolute: str, path: str, offset: Optional[int], limit: Optional[int], cancelled: Callable[[], bool]
) -> Union[ToolResult, _Image]:
    """Everything read takes from the file, through one descriptor: the kind, the image type, the size,
    and the bytes. A file swapped or grown after an earlier check by path cannot get past its limits,
    and image work never looks past the bytes the cap allows."""
    with os.fdopen(open_regular(absolute), "rb") as handle:
        head = handle.read(_IMAGE_SNIFF_BYTES)
        mime_type = _sniff_image(head)
        if mime_type is None:
            return _read_text(handle, absolute, path, offset, limit, cancelled)
        image = _load_image(handle, head, mime_type)
    if isinstance(image, _Image):
        return image
    details = {"path": absolute, "mime_type": image.mime_type}
    if image.size is not None:
        details["bytes"] = image.size
    return text_result(f"Read image file [{image.mime_type}]\n[Image omitted: {image.reason}]", details=details)


@dataclass(frozen=True)
class _Omitted:
    mime_type: str
    reason: str
    size: Optional[int] = None


def _load_image(handle: BinaryIO, head: bytes, mime_type: str) -> Union[_Image, _Omitted]:
    """The image ``handle`` holds, ``head`` already read from it, or why ``read`` cannot attach it."""
    if mime_type in IMAGE_MIME_TYPES:
        data = head + handle.read(max(0, MAX_INLINE_IMAGE_BYTES + 1 - len(head)))
        size = max(os.fstat(handle.fileno()).st_size, len(data))
        if size > MAX_INLINE_IMAGE_BYTES:
            # Avibe: ``read`` does not resize to fit the byte cap.
            reason = (
                f"the file is {format_size(size)}, over the {format_size(MAX_INLINE_IMAGE_BYTES)} inline image limit. "
                "Images are not resized."
            )
            return _Omitted(mime_type, reason, size)
        if mime_type == "image/png" and _png_is_animated(data):
            # acTL may sit past the sniffed prefix, behind large ancillary chunks.
            mime_type = "image/apng"
        else:
            return _Image(mime_type, data, len(data))
    # Pi converts other formats to PNG; without an image library Avibe cannot.
    return _Omitted(mime_type, "could not be converted to a supported inline image format.")


class ImageUnreadable(Exception):
    """Why ``read_image`` cannot give the image at a path: ``kind`` says which check refused it, so a caller can word
    it; ``reason`` is the text ``read`` would show, the system's own words for a file it could not open."""

    def __init__(
        self,
        reason: str,
        *,
        kind: str = "unreadable",
        mime_type: Optional[str] = None,
        size: Optional[int] = None,
    ) -> None:
        super().__init__(reason)
        self.reason, self.kind, self.mime_type, self.size = reason, kind, mime_type, size


def read_image(path: str, cwd: str) -> tuple[str, bytes]:
    """The image at ``path`` as ``read`` attaches it, its type and bytes: the path resolved against ``cwd`` and checked
    as ``read`` does (a regular, readable file; a supported image type within the inline limit). Raises
    ``ImageUnreadable`` with the reason otherwise. Blocking: call it off the event loop."""
    try:
        absolute = resolve_read_path(path, cwd)
        refusal = _refusal(absolute)
        if refusal:
            raise ImageUnreadable(refusal)
        with os.fdopen(open_regular(absolute), "rb") as handle:
            head = handle.read(_IMAGE_SNIFF_BYTES)
            mime_type = _sniff_image(head)
            image = _load_image(handle, head, mime_type) if mime_type is not None else None
    except NotRegularFile as exc:
        raise ImageUnreadable(KIND_REASON[exc.kind]) from None
    except OSError as exc:
        raise ImageUnreadable(os_reason(exc)) from None
    except ToolInputError as exc:
        raise ImageUnreadable(str(exc)) from None
    if image is None:
        raise ImageUnreadable("it is not an image (jpg, png, gif, webp)", kind="not_image")
    if isinstance(image, _Omitted):
        kind = "too_large" if image.size is not None else "unsupported"
        raise ImageUnreadable(image.reason.rstrip("."), kind=kind, mime_type=image.mime_type, size=image.size)
    return image.mime_type, image.data


def _sniff_image(head: bytes) -> Optional[str]:
    """The image type ``head`` shows, or ``None`` for text. A PNG or JPEG Pi cannot send (animated PNG,
    JPEG-LS) keeps its family, so it is omitted rather than decoded as text."""
    supported = detect_supported_image_mime_type(head)
    if supported is not None:
        return supported
    if head.startswith(_PNG_SIGNATURE):
        return "image/apng" if _is_png(head) else None
    if head.startswith(b"\xff\xd8\xff"):
        return "image/jls"
    return None


def _png_is_animated(data: bytes) -> bool:
    """Walk the chunk headers of ``data`` (at most the image cap, already read) until IDAT or acTL."""
    offset = len(_PNG_SIGNATURE)
    while offset + 8 <= len(data):
        length, kind = struct.unpack(">I", data[offset : offset + 4])[0], data[offset + 4 : offset + 8]
        if kind == b"acTL":
            return True
        if kind == b"IDAT":
            return False
        offset += 12 + length
    return False


def _read_text(
    handle: BinaryIO,
    absolute: str,
    path: str,
    offset: Optional[int],
    limit: Optional[int],
    cancelled: Callable[[], bool],
) -> ToolResult:
    start_line = offset - 1 if offset is not None else 0
    stop_line = start_line + limit if limit is not None else None
    collected, total_lines, first_line_bytes = _scan_lines(handle, start_line, stop_line, cancelled)
    if start_line >= total_lines:
        raise ToolInputError(f"Offset {offset} is beyond end of file ({total_lines} lines total)")

    truncation = truncate_head("\n".join(collected))
    start_display = start_line + 1
    details: dict[str, Any] = {"path": absolute}
    if truncation.first_line_exceeds_limit:
        text = (
            f"[Line {start_display} is {format_size(first_line_bytes)}, exceeds {format_size(MAX_BYTES)} limit. "
            f"{read_line_advice(absolute, start_display, MAX_BYTES)}]"
        )
        details["truncation"] = truncation.to_details()
    elif truncation.truncated:
        end_display = start_display + truncation.output_lines - 1
        next_offset = end_display + 1
        if truncation.truncated_by == "lines":
            notice = (
                f"[Showing lines {start_display}-{end_display} of {total_lines}. Use offset={next_offset} to continue.]"
            )
        else:
            notice = (
                f"[Showing lines {start_display}-{end_display} of {total_lines} ({format_size(MAX_BYTES)} limit). "
                f"Use offset={next_offset} to continue.]"
            )
        text = f"{truncation.content}\n\n{notice}"
        details["truncation"] = truncation.to_details()
    elif stop_line is not None and stop_line < total_lines:
        text = f"{truncation.content}\n\n[{total_lines - stop_line} more lines in file. Use offset={stop_line + 1} to continue.]"
    else:
        text = truncation.content
    return text_result(text, details=details)


def _scan_lines(
    handle: BinaryIO, start: int, stop: Optional[int], cancelled: Callable[[], bool] = lambda: False
) -> tuple[list[str], int, int]:
    """Lines ``[start, stop)`` as Pi's ``text.split("\\n")`` gives them, without the ``\\r`` of a CRLF break,
    the file's line count, and the size of line ``start`` as it is shown.

    Avibe drops the ``\\r`` (as tau does; Pi shows it) so read's text is edit's matching view: a copied line
    can no longer end in a bare ``\\r`` that edit would read as a line break. A line ending in more than
    one ``\\r`` keeps them all: edit reads ``\\r\\r\\n`` as two breaks, and so does the copied text.

    Collection stops once the kept lines pass either cap, so the kept prefix exceeds a cap exactly when
    the whole selection does: decoding with replacement never makes text shorter than its bytes, and
    ``\\n`` never occurs inside a UTF-8 sequence, so lines decode independently.
    """
    lines: list[bytearray] = []
    kept = 0  # raw bytes of "\\n".join(lines)
    opened = -1  # file line index of lines[-1]
    index = 0  # file line index of the bytes being read
    first_line_bytes = 0  # UTF-8 bytes of line ``start`` as shown
    first_decoder = codecs.getincrementaldecoder("utf-8")("surrogateescape")
    first_line_tail = b""  # its last two bytes, for the dropped "\r"
    collecting = stop is None or start < stop

    def measure(segment: bytes, ends_line: bool) -> None:
        """Add a piece of line ``start`` to its shown size; ``ends_line`` once its ``\\n`` is reached."""
        nonlocal first_line_bytes, first_line_tail
        first_line_bytes += utf8_len(shown(first_decoder.decode(segment, final=ends_line)))
        first_line_tail = (first_line_tail + segment)[-2:]
        if ends_line and first_line_tail.endswith(b"\r") and not first_line_tail.endswith(b"\r\r"):
            first_line_bytes -= 1

    def collect(segment: bytes, ends_line: bool) -> None:
        nonlocal kept, opened, collecting
        if opened != index:
            if lines:
                kept += 1
            lines.append(bytearray())
            opened = index
        # One more byte at a line end, for a "\r" that is dropped below.
        room = MAX_BYTES + 1 - kept + (1 if ends_line else 0)
        if room > 0:
            lines[-1] += segment[:room]
            kept += min(len(segment), room)
            if ends_line and len(segment) <= room and lines[-1].endswith(b"\r") and not lines[-1].endswith(b"\r\r"):
                del lines[-1][-1]
                kept -= 1
        # One line beyond the cap: a final empty piece does not count as a line.
        if kept > MAX_BYTES or len(lines) > MAX_LINES + 1:
            collecting = False

    def count_rest(chunk: bytes, pos: int) -> None:
        nonlocal index
        if index == start:
            newline = chunk.find(b"\n", pos)
            measure(chunk[pos : len(chunk) if newline == -1 else newline], newline != -1)
        index += chunk.count(b"\n", pos)

    handle.seek(0)
    # A UTF-8 BOM is not shown, as edit does not match it, so text read shows can be edited.
    if handle.read(len(_BOM)) != _BOM:
        handle.seek(0)
    while chunk := handle.read(_READ_CHUNK_BYTES):
        if cancelled():
            raise _Aborted
        pos = 0
        while collecting:
            newline = chunk.find(b"\n", pos)
            end = len(chunk) if newline == -1 else newline
            if stop is not None and index >= stop:
                collecting = False
                continue
            if index == start:
                measure(chunk[pos:end], newline != -1)
            if index >= start:
                collect(chunk[pos:end], newline != -1)
            if newline == -1:
                pos = len(chunk)
                break
            index += 1
            pos = newline + 1
        else:
            count_rest(chunk, pos)
    if index == start:
        # Line ``start`` is the last line and has no "\n": what the decoder still holds is shown too.
        first_line_bytes += utf8_len(shown(first_decoder.decode(b"", final=True)))
    if collecting and opened != index and index >= start:
        # An empty file: its one line is empty.
        lines.append(bytearray())
    return [shown(decode_file(bytes(line))) for line in lines], index + 1, first_line_bytes


def detect_supported_image_mime_type(data: bytes) -> Optional[str]:
    """Pi's content sniffing: JPEG, static PNG, GIF, WebP, and BMP."""
    if data.startswith(b"\xff\xd8\xff"):
        return None if len(data) > 3 and data[3] == 0xF7 else "image/jpeg"
    if data.startswith(_PNG_SIGNATURE):
        return "image/png" if _is_png(data) and not _is_animated_png(data) else None
    if data.startswith((b"GIF87a", b"GIF89a")):
        return "image/gif"
    if data.startswith(b"RIFF") and data[8:12] == b"WEBP":
        return "image/webp"
    if data.startswith(b"BM") and _is_bmp(data):
        return "image/bmp"
    return None


def _is_png(data: bytes) -> bool:
    return len(data) >= 16 and struct.unpack(">I", data[8:12])[0] == 13 and data[12:16] == b"IHDR"


def _is_animated_png(data: bytes) -> bool:
    offset = 8
    while offset + 8 <= len(data):
        length = struct.unpack(">I", data[offset : offset + 4])[0]
        kind = data[offset + 4 : offset + 8]
        if kind == b"acTL":
            return True
        if kind == b"IDAT":
            return False
        following = offset + 8 + length + 4
        if following <= offset or following > len(data):
            return False
        offset = following
    return False


def _is_bmp(data: bytes) -> bool:
    if len(data) < 26:
        return False
    (declared_size,) = struct.unpack("<I", data[2:6])
    (pixel_offset,) = struct.unpack("<I", data[10:14])
    (dib_size,) = struct.unpack("<I", data[14:18])
    if declared_size != 0 and declared_size < 26:
        return False
    if pixel_offset < 14 + dib_size:
        return False
    if declared_size != 0 and pixel_offset >= declared_size:
        return False
    if dib_size == 12:
        planes, bits = struct.unpack("<HH", data[22:26])
    elif 40 <= dib_size <= 124:
        if len(data) < 30:
            return False
        planes, bits = struct.unpack("<HH", data[26:30])
    else:
        return False
    return planes == 1 and bits in (1, 4, 8, 16, 24, 32)