The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
"""In-process write primitives for the local POSIX backend.
``write_file`` asked the backend shell three questions per write (pre-write probe, atomic write,
sha256 verification): three ``bash`` spawns, ~100 ms on a warm host before any real work. On the
local POSIX backend the file is on this host, so ``ShellFileOperations`` answers them here instead,
under the same gate as the native read path (``_native_read_enabled``; ``HERMES_NATIVE_FILE_READ=0``
turns both off). Semantics mirror the shell scripts they replace; anything they cannot answer
(a FIFO, a device, an unexpected error) returns None and the caller takes the shell path.
"""
from __future__ import annotations
import contextlib
import hashlib
import os
import secrets
import stat
from typing import Optional
_UTF8_BOM = b"\xef\xbb\xbf"
def _open_regular(path: str) -> Optional[int]:
"""fd of ``path`` when it is a regular file; None when missing; raises ``_NotRegular`` otherwise.
One lookup with O_NONBLOCK, judged by fstat: a FIFO swapped in never blocks this thread."""
try:
fd = os.open(path, os.O_RDONLY | getattr(os, "O_NONBLOCK", 0))
except FileNotFoundError:
return None
if not stat.S_ISREG(os.fstat(fd).st_mode):
os.close(fd)
raise _NotRegular(path)
return fd
class _NotRegular(OSError):
pass
def probe(path: str, want_text: bool) -> Optional[tuple[bool, Optional[bytes]]]:
"""``(has_bom, body)`` for a write target: ``body`` is the whole file when ``want_text`` else its
first 4 KB (the line-ending sample); ``(False, None)`` when the file is missing; None = ask the shell."""
try:
fd = _open_regular(path)
if fd is None:
return False, None
with open(fd, "rb") as fh:
data = fh.read() if want_text else fh.read(4096)
except OSError:
return None
return data.startswith(_UTF8_BOM), data
def atomic_write(path: str, data: bytes) -> Optional[str]:
"""Replace ``path`` with ``data`` atomically; None on success, else an error message.
Same contract as the shell script: a symlink target is written through (the link survives),
parent directories are created, the temp file lives in the target's directory so the rename is
atomic, an existing target's mode is kept and a new one gets the umask default (``O_CREAT`` with
0o666 applies the process umask itself), and the temp is removed on every failure.
The temp holds its final mode before the first byte lands: an existing target's temp is created
0o600 and ``fchmod``-ed to the target's mode, so a private file's new contents are never readable
through a wider temp (the shell script's ``mktemp`` 0600 temp gave the same guarantee)."""
target = os.path.realpath(path) if os.path.islink(path) else path
parent = os.path.dirname(target) or "."
try:
os.makedirs(parent, exist_ok=True)
try:
mode: Optional[int] = stat.S_IMODE(os.stat(target).st_mode)
except FileNotFoundError:
mode = None
tmp = os.path.join(parent, f".hermes-tmp.{secrets.token_hex(6)}")
fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_CLOEXEC", 0),
0o666 if mode is None else 0o600)
except OSError as e:
return f"{e.strerror or e}: {e.filename or target}"
try:
if mode is not None:
try:
os.fchmod(fd, mode) # before any content: the bytes never sit in a wider file
except OSError:
pass # best effort, as in the shell script (the temp then stays 0o600)
with open(fd, "wb") as fh:
fh.write(data)
os.replace(tmp, target)
except OSError as e:
with contextlib.suppress(OSError):
os.unlink(tmp)
return f"{e.strerror or e}: {e.filename or target}"
return None
def sha256_of(path: str) -> Optional[str]:
"""Hex sha256 of the regular file at ``path``; None when it cannot be read natively."""
try:
fd = _open_regular(path)
if fd is None:
return None
digest = hashlib.sha256()
with open(fd, "rb") as fh:
for chunk in iter(lambda: fh.read(1 << 20), b""):
digest.update(chunk)
except OSError:
return None
return digest.hexdigest()
__all__ = ["atomic_write", "probe", "sha256_of"]