Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

Files in the panel

A file the brain shows (file.v1, pi_show_file): the request (path, title, page), the gateway's checks in order (the allowed folders [files] roots after symlinks, no dot-dot, no hidden or secret part, a regular file within [files] max_bytes) and their typed, sayable refusals, the type sniffed from the bytes, the FileSpec body (name, mime, size, sha256, page), who gets the file and who its card, the file_fetch / file_chunk / file_fetch_refused frames and who may fetch, and what the Admin row logs.

Living doc, checked against the code 2026-11-14

file.v1 — a file the gateway shows from its own disk: named on the render, fetched by its hash

  • Status: landed on protocol 5, additive. Decided in ADR 0049.
  • Scope: the visual response channel’s file tier, beside panel-card.v1 and visual.v1. The brain shows a file that already exists (a picture, a PDF, a document, a log, a video, a glTF model) instead of data it wrote.

What the brain sends

pi_show_file {path, title?, page?}:

  • path: the file’s full path on the gateway’s machine (~/ allowed).
  • title: optional plain words for the pane’s header, at most 80.
  • page: a PDF’s page to open at, from 1.

The tool sends the gateway’s show_render mutation line with kind file.v1 and that request as its body. The bytes never pass through the brain.

What the gateway does with the request

The mutation listener resolves it on a blocking thread before the line reaches the session (crates/voice_gateway/src/file_show.rs), in this order:

  1. [files] enabled is on, else file_off.
  2. The path is absolute (or ~/, the gateway user’s home), at most 4096 bytes, with no NUL and no .., else bad_path.
  3. The real path (every symlink followed) is under a real allowed folder ([files] roots), else not_allowed. A path outside every folder is refused whether it exists or not. Inside a folder, a missing file is not_found.
  4. No part of the real path below its folder, nor of the asked path below a folder it names, is hidden (a dot name: .ssh, .env, .git) or a secret’s name (id_rsa, id_dsa, id_ecdsa, id_ed25519, each also with .pub, authorized_keys, known_hosts, credentials, credentials.json, secrets.json, secrets.toml, secrets.yaml, token.json, netrc, a name or stem that says password, passwords, wallet or seed-phrase, or an extension pem, key, p12, pfx, keychain, keychain-db, kdbx, ovpn, ppk), else secret_path.
  5. It is a regular file, else not_a_file (a folder, a device, a pipe, a socket). It is at most [files] max_bytes, else too_large. It is readable, else unreadable.
  6. Its type is sniffed from its first 8 KiB (below). page applies to a PDF only, from 1 to 100000, else bad_page.

A refusal is answered at once, in the session’s render_shown shape, and the line never reaches the session:

{"status": "render_shown", "kind": "file.v1", "outcome": "refused", "reason": "secret_path", "waited_ms": 1,
 "error": "that file is hidden or holds keys or secrets, so I will not show it"}

error is plain words the brain may say: never a path, a hash or markup. not_allowed names the allowed folders by name, Desktop, Documents, Downloads, Pictures and Movies. unreadable says the gateway may need the Mac’s permission for that folder.

A file kept in iCloud. With Optimize Mac Storage, an iCloud folder holds dataless placeholders (SF_DATALESS). Their bytes download on the first read only when the reader’s materialization policy is on (man setiopolicy_np); a launchd agent’s default is off, and the read then fails with EDEADLK. The gateway turns the policy on for each shown or fetched file’s read (crates/voice_gateway/src/file_icloud.rs). A dataless file that still fails is not_downloaded (“that file is kept in iCloud and is not downloaded on this Mac, and it could not be downloaded just now; open it once on the Mac and ask again”), counted on the gateway.files row apart from unreadable.

macOS’s folder permission. macOS guards Desktop, Documents and Downloads per process (Privacy & Security > Files and Folders); Pictures and Movies are not guarded. The grant belongs to the gateway binary (foxline-voice-gateway). It is keyed to the binary’s path and anchored on its signing identifier and certificate, so an update keeps it.

The gateway reads each guarded folder’s state without asking (TCC’s preflight) and never opens one it may not, so macOS never prompts during a turn. A find walks the other folders. With no match there, or for a path inside the folder, the refusal is folder_not_granted (“I can’t read your Documents folder yet: … Allow it in the Glyph’s welcome window, on the Documents Folder row”). A grant made while the gateway runs is restart_to_apply: macOS hands a grant over only at a restart.

Vulpine.app’s welcome window on the gateway’s Mac walks the grant, through the gateway’s <state>/file-access/file-access.json. Allow… makes the gateway open the folder once, so macOS asks then. Open System Settings opens Files and Folders. Restart gateway kickstarts its launchd job. A tool refused for a folder opens the window at its row. The Admin’s gateway.file_access Health row shows each folder’s state.

A root on another volume is guarded by that volume’s grant: Removable Volumes for a local drive under /Volumes, Network Volumes for a share. The gateway reads which applies from the mount table at start, touching nothing on the volume. The root is held, asked and reported like a home folder, with the words “I can’t read your external drives yet: … on the Removable Volumes row”. A refused read there names that row instead of unreadable.

A file that passes replaces the request with its body. The gateway keeps it by its hash for a later fetch and sends it through the session’s render router.

[files] (gateway config)

key default meaning
enabled true show files at all; false refuses each with file_off
roots ["~/Desktop", "~/Documents", "~/Downloads", "~/Pictures", "~/Movies"] the allowed folders; one that does not exist is left out
max_bytes 33554432 (32 MiB) the largest file shown; held to at most 256 MiB (FILE_MAX_BYTES_CEILING)
find true find a file by description (below); false refuses each with find_off
find_min_margin 0.5 the decision model’s pick of a close find is taken at or above this margin (0..=1)

Finding a file by description

The find runs on the gateway’s machine only. The brain never lists the operator’s folders and never sees a file name, folder, size or date it did not name itself. pi_show_file takes {describe, folder?, title?} in place of {path, title?, page?}: never both, never a page. describe is the operator’s own words (1..=300 characters, one line). folder is one of desktop, documents, downloads, pictures, movies. The gateway finds the file on its own disk (crates/voice_gateway/src/file_find.rs):

  1. The name index. A bounded walk of the allowed folders (or the one folder names; a folder not allowed is not_allowed): at most 4 s, 100,000 files and 12 folders deep, kept 120 s. It never follows a symlink, never enters a hidden folder, a secret-named one or a package (an app, a Photos or Music library), and never keeps a file the show checks would refuse (a hidden or secret name, over max_bytes). The index is the gateway’s own, not Spotlight’s. Its name matching is a port of fsearch’s (v0.2.1, MIT): a whole word ranks above a word’s start, and that above a run inside a word. One typo is forgiven in a word of 5 letters or more, two in one of 8 or more, and a digit is never edited. A recent change lifts a file by a two-week half-life. A word of 5 letters or more that no typo reaches still matches, below a typo, when it sounds like the name’s word: the same consonant key (sch as sh, ph as f, ck and a hard c as k, a soft c as s, vowels after the first letter dropped, doubles once) of at least 4 letters. So a name the recognizer spelled by ear (“Shooler” for “Schuler”) still matches. The words go through a stop list. Kind words (“the PDF”, “a screenshot”) become a kind hint, time words (“latest”) weigh recency up, and folder words favor that folder. A file scoring under 40 is no candidate.
  2. The pick. One clear match (a score of 90 or more and 40 above the next) is shown. Close ones are asked of the served decision model: decision.v1, one choice question file_pick over file_1..file_8 whose descriptions are the candidates’ names, folders, kinds and ages, plus none, with the user’s words as state.utterance. The model is asked only when every entry of [decision_shadow] entries is on this machine (a loopback URL), never with a model load, and within 2.5 s. Its pick is taken when the guarded answer’s margin reaches find_min_margin. Otherwise the window gets a chooser.
  3. The chooser. The body is the best match’s FileSpec with title “Which file did you mean?” and choices (below): up to three files, each read, hashed and kept for a fetch like a shown file, and granted with the render. The conversation window draws the choices and fetches none until one is tapped. The tap fetches that choice by its hash (file_fetch). A card frontend gets the list of names and “Choose one in the conversation window.”
  4. Each file shown or offered goes through the show checks again (file_show::resolve): the same refusals, read and hash as a path.

What the brain hears is the render’s answer (outcome, reason, projected_to) plus found (shown or asked_user), by (name, model or user), file_kind (the shown file’s kind in words, “PDF”) and choices (how many), or a refusal: no_match (“I found no file like that in Documents, Pictures and Desktop”), find_off, folder_not_granted or restart_to_apply (a guarded folder the find could not walk, when nothing else matched), find_timeout (“the search took too long; name the folder it is in, or give its full path”: the find ran past the listener’s 15 s wait), or any show refusal. It is never a name, a folder, a size, a date or a hash. The tool’s result has no name in this case, and its line says only the kind (“The PDF is on the screen.”) or the chooser (“I put 3 files that may match on the screen; choose one there.”). The receipt keeps found, file_kind and choices, never the words.

Which tool asks. The operator prompt (catalog/agents/operator/SYSTEM.md, AGENTS.md) sends any file the operator asks to see, open or read to pi_show_file with describe: their words as heard, never a spelling corrected or guessed. pi_file_searcher searches the agent’s own workspace only; its out-of-workspace refusal names pi_show_file describe.

The sniffed types

bytes mime
89 50 4E 47 0D 0A 1A 0A image/png
FF D8 FF image/jpeg
GIF87a, GIF89a image/gif
RIFF … WEBP / WAVE image/webp / audio/wav
II*\0, MM\0* image/tiff
BM with a Windows or OS/2 header size image/bmp
ftyp at 4: brands heic heix hevc heim heis mif1 msf1 / avif avis / qt / M4A / others image/heic / image/avif / video/quicktime / audio/mp4 / video/mp4
%PDF- application/pdf
glTF model/gltf-binary
1A 45 DF A3, OggS, fLaC, ID3 or an MPEG frame, PK\x03\x04 video/webm, audio/ogg, audio/flac, audio/mpeg, application/zip
UTF-8 text (no NUL, at most 1 % control characters) holding <svg image/svg+xml
other UTF-8 text, by its extension text/markdown, text/csv, application/json, model/gltf+json, text/x-rust, text/x-python, text/javascript, text/x-typescript, text/x-swift, text/x-go, text/x-c, text/x-c++, text/x-java, text/x-ruby, text/x-shellscript, text/x-toml, text/x-yaml, text/html, text/css, text/x-sql, text/x-lua, text/x-shader, text/x-nix, else text/plain
anything else application/octet-stream

The extension only names a text’s language: a .png that holds words is text/plain, and a PDF named .bin is application/pdf.

FileSpec, the body of file.v1

field type bound
title string card.v1’s title rule (1..=80, plain, no hex token): the brain’s title, else the file’s name, else its kind (“A PDF”)
summary string card.v1’s summary rule: the kind and size in words, and the page (PDF, 2.1 MB, page 3)
name string 1..=255 characters, no /, no markup or control character: the file’s name, never its folder
mime string lowercase type/subtype, at most 100 characters (the table above)
size number bytes, at most 256 MiB
sha256 string 64 lowercase hex digits: the name a window fetches it by
page number, optional a PDF’s page to open at, 1..=100000
choices array, optional a find’s chooser, 1..=3 {name, folder, mime, size, sha256} (name as above; folder at most 120 characters below the allowed folder, Documents/Taxes, no ..); absent (never empty) on the wire for a plain file

Closed (deny_unknown_fields). The protocol’s validate_render checks every bound before relay.

Who gets what

frontend declares gets
the conversation window (apps/convo-gpui, an observer) file.v1 in its hello the render whole; it fetches the bytes and draws them
Vulpine on iPhone (apps/phone) file.v1 in its hello the render whole; phone-core fetches an image of at most 8 MiB by its hash (crates/phone_core/src/link/fetch.rs) and the card draws it (apps/phone/src/convo/pictures.rs); any other file shows its name
Vulpine.app and Vulpine in a browser (the Glyph and Vigil looks; they draw cards) card.v1, not file.v1 the file’s card projection (file_card: its title, its summary as the one block, the note “A file; it shows in full in the conversation window.”); the brain’s answer says projected_to: card.v1
a frontend that draws neither nothing nothing (dropped, undeclared)

The session’s observers are offered the render whole, even when the session’s own frontend got its card. An observer that did not declare file.v1 gets the card (ws::observe::observer_frame). The panel kit draws a file.v1 frame as its card and never declares the kind (KIT_UNDECLARED_FRAMES).

Fetching the bytes

frame direction fields
file_fetch client → gateway sha256
file_chunk gateway → client sha256, offset, total, data (base64 of at most 512 KiB, FILE_CHUNK_BYTES)
file_fetch_refused gateway → client sha256, reason
  • Who may fetch: a connection whose hello declared file.v1, for a hash shown to its own session or to the session it observes (granted at the show_render dispatch). Else not_declared or not_shown. A hash never shown is not_shown too. The gateway keeps the last 64 shown files for two hours.
  • Checked again: the gateway reads the file again under the policy in force (folders, secrets, kind, cap) and hashes it: file_changed when the hash differs, file_gone when it left or was removed, file_off when the switch went off.
  • In order: the chunks of one file go in order on the connection. The file is whole when offset + bytes == total (an empty file is one chunk with no data). The receiver checks the whole file’s SHA-256 against the name it asked for and refuses a mismatch (bad_hash) or a piece out of order (bad_chunk).
  • The window’s side (apps/convo-gpui/src/files.rs): it asks once per hash when it first draws the panel (LinkCommand::FetchFile). It keeps whole files by hash, at most 256 MiB, dropping the least recently drawn first. It forgets a fetch in flight when its link drops, so the next draw asks again. The link (crates/convo_feed) only carries the frames. An observer may send file_fetch, because it acts on nothing.

The answer

A file that passed goes through the session’s render router like any render (drawn, refused, dropped, or sent unconfirmed; projected_to when a frontend got the card). The tool’s answer adds the file’s name (never its folder) and the line the brain may say (floor-plan.pdf is on the screen., The card for floor-plan.pdf is on the panel; the file itself shows in the conversation window., or the refusal’s words). The receipt keeps the outcome only: never the path, the name or the title.

Logged

  • The Admin’s gateway.files Health row: the switch, the folders and the cap; today’s files shown, fetched by a window (with the bytes) and refused by reason (not_allowed 2, secret_path 1). The host’s local day.
  • The session trace: file_fetched {bytes, ms} and file_fetch_refused {reason}.
  • Never a path, a file name or a hash in either.
  • The same row adds the finds by description today (shown by name, by the decision model, asked on screen with the choices tapped by place, no match), why the decision model gave no pick (model_not_local, no_model, low_margin, abstained, none), and the name index’s size, age and unreadable folders.

Drawing it (the conversation window)

The pane (apps/convo-gpui/src/file_pane.rs; apps/convo-gpui/README.md “Files”) draws a file.v1 panel through a viewer registry keyed by media type (apps/convo-gpui/src/file_view/), asked newest registration first, the fallback last:

viewer types how
image PNG, JPEG, GIF, WebP, BMP, TIFF; HEIC and AVIF through AppKit at most 4096 px a side, EXIF orientation; Fit, 1:1 and 2x, pan by scrolling; an animated GIF plays 8 s, then holds (never under Reduce Motion)
svg image/svg+xml GPUI’s resvg renderer at the window’s scale; over 8 MiB refused
pdf application/pdf CGPDFDocument, a page at a time at points x scale, opening on page (clamped); Previous, “Page n of m”, Next, the zoom buttons; a locked PDF says so
markdown text/markdown the reply’s markdown blocks
code text/x-*, JSON, HTML, CSS, JavaScript monospace with line numbers; syntax colors (keywords, strings, comments, numbers, type names) from the theme’s tokens for every code type above, by a small tokenizer in the window (apps/convo-gpui/src/file_view/syntax.rs), with a Syntax colors toggle (on)
text plain text, CSV monospace
video video/* (MP4 and QuickTime play; WebM and other types AVFoundation cannot read say so) the clip’s first frame, then Play / Pause / Play again and an ASCII look toggle (off at first); AVAssetReader decodes the video track only (the sound is never read, “sound off”) into NV12 frames that GPUI’s surface() draws; a track whose matrix turns its picture (a phone’s portrait clip) is read through AVFoundation’s video composition instead, so it draws upright at its turned size; a frame is asked only while it plays, so it rests at 0 frames when paused, at its end and under Reduce Motion (its first frame only)
model model/gltf-binary, and model/gltf+json whose buffers and textures are data URIs (one that names files beside it is drawn by the code viewer under a line saying why) glTF’s reader first (bounds, clips, morph targets; a texture past 4096 px refused before it decodes), then kiss3d 0.47 on the window’s wgpu device in a surface3d layer clipped to its card; the first clip plays once (no clip: the morph targets sweep), Play and Reset view, a drag turns it, the wheel zooms; 0 frames after the clip and the drag, nothing plays under Reduce Motion; two live at most (an older pane: Show in 3D); the model3d feature, on
fallback anything else (audio, zip, a Word, Excel, Keynote or Pages file) Quick Look’s thumbnail when it makes one (QLThumbnailGenerator, asked off the main thread: a document’s first page, a song’s artwork), else the file type’s icon (NSWorkspace iconForFile:); both read the bytes kept owner-only under the window’s cache folder (the newest 16); its name, kind and size. A Word document (.docx, .doc) or an OpenDocument text (.odt), told by its name under application/zip or application/octet-stream (the gateway’s sniff) or its own type, is also laid out off the main thread by AppKit’s reader and TextKit into a PDF of at most 200 pages (apps/convo-gpui/src/file_view/office.rs); once it is, the pane draws its pages as the pdf viewer does (Previous, “Page n of m”, Next, opening on page); until then, and when it cannot be read, the thumbnail

The text viewers draw at most 400 lines within 128 KiB, then “N more lines”. The log’s own fenced code blocks are colored by the same tokenizer when the fence names a language (```rust; apps/convo-gpui/src/code_colors.rs), at most 16 KiB a block. A file over 2 MiB is prepared off the main thread (“Preparing the file…”). A new viewer is one Viewer type and one registry.register line in Registry::standard; the pane does not change.

Was this page helpful?