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.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
"""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)