small gleam coding and (not yet) persistent agent daemon with a detachable cli forked from okami.mom/albedo
albedo robot-docs files.md
4.2 kB · 91 lines
Markdown
at main

Files extension #

The Python files plugin provides bounded reads, exact edits, directory listings, and searches in the kernel's environment. Relative paths resolve in that environment's working directory. See workspaces.

A file attached to a chat message reaches the model as a saved path under the daemon home. The model can read that absolute path with files.read or other kernel code. Attaching adds no plugin API and no sandbox. See saved pastes and uploads.

Read #

files.read(path, start_line=1, end_line=None, limit=None, max_chars=16000) returns numbered lines. limit counts lines and max_chars bounds output. The maximum character budget is 200,000. If the budget stops the read, the result identifies where to resume. files.ls lists one directory and excludes hidden entries by default. The implementation is in Files.read and Files.ls.

Uploaded images #

await files.image(index=0, entry=None) returns the original bytes of an image uploaded in the calling session. Indices start at zero. Without entry, it uses the latest user message containing images, looking past later text-only messages. Pass a user message's transcript position to read an older upload explicitly. An unavailable image, another session's entry, or an out-of-range index raises FilesError with code image_unavailable. Invalid Python arguments raise ValueError.

Assign the bytes before using an image library, for example:

import io
from PIL import Image

original = await files.image()
picture = Image.open(io.BytesIO(original))

The call uses the session's host connection, so the kernel does not need a path on the daemon's filesystem. Images stay in the existing image store; fetching one creates no extracted file or additional image-store entry. User-upload bytes remain separate from provider-sized image fits and tool screenshots. The transcript reader in conversation.gleam owns the selection, and the files extension exposes it through its existing host routes. The default search pages row identities through an upload-candidate index, then reads one payload at a time. The candidate tag also covers legacy inline images; prose containing it is decoded and skipped. The search resumes between Python awaits, so cancellation stops the look-back between pages.

Edit #

files.edit replaces an exact string or applies an ordered list of replacement pairs. A missing or ambiguous match fails before publication. A list is evaluated in memory before the file is replaced. line_hint can select among occurrences for a single edit. files.write creates or replaces the entire file and creates parent directories.

_snapshot and _replace compare the file before replacement and refuse a detected concurrent change. The comparison and os.replace are separate operations, so another writer can still change the file between them. The temporary file is synced and retains the original mode.

files.find searches contents and files.paths searches names. Both return work that must be awaited. The plugin uses ripgrep when available and has a Python fallback. find excludes hidden and ignored files by default, accepts literal or regular-expression searches, and returns bounded results. External search commands run as supervised jobs with a 30-second timeout. See Files.find, Files.paths, and _run.

Credential boundary #

files.read and content search refuse the configured credentials file, and search filters that path from results. This is a boundary of those operations, not a filesystem sandbox. Other processes and operations have their own permissions. See _secret and _refuse_secrets and settings.