The image path through Broca was the most fragile part of the pipeline. Telegram came in with file IDs and no dimensions, so the model had to guess at aspect ratio. tmpfiles URLs broke when the share link used the alphanumeric view path instead of the direct download path. And when an upload failed on the primary service, the user got back nothing — no image, no error worth surfacing. Over two weeks in May we shipped three commits that close those gaps. Telegram image documents now carry width and height, tmpfiles accepts the alphanumeric view URL form, and tmp.sanctumos.org stands in as a fallback ephemeral upload when the primary service is unreachable. This post walks through what was fragile, what we shipped, and what's still rough at the edges.
Decision
The framing decision was: stop making the model guess. Three failure modes had the same shape — we were trying to recover information upstream of the model that should have been captured at intake. The Telegram bot was throwing away image dimensions, tmpfiles was throwing away URL form, and the upload fallback was throwing away the user's image entirely. Each commit was a refusal to do that.
The secondary decision was: keep the surface narrow. We did not redesign the image pipeline. We did not change the model's input contract. We added metadata where it was missing, accepted a broader URL form where it was being rejected, and added a fallback where there was none. The pipeline still looks like the pipeline did a month ago; the seams are just better sealed.
Evidence
The evidence for the metadata gap is straightforward. Before 33d3dfc, a Telegram image document arrived in Broca as a file reference with no spatial information. The model received the bytes and had to infer aspect ratio from the rendered content. For an image-to-image flow, that meant the model often returned at the wrong ratio and the user got back a crop. For a text-conditioned generation, the prompt had to be the only signal, which made "make it the same shape as the input" effectively impossible to honor reliably.
The evidence for the tmpfiles URL form was a small but persistent class of failures. tmpfiles issues a share URL of the form https://tmpfiles.org/dl/, which downloads directly. But the same service also exposes a "view" URL of the form https://tmpfiles.org/ that humans click through. When a user pasted the view URL, the download resolver rejected the ID because it contained characters that did not match the strict numeric pattern. The rejection was correct on the regex, wrong on the user — the URL was still a valid tmpfiles link.
The evidence for the fallback was the most concrete. When the primary upload service was unreachable — and it was, on a small but nonzero fraction of jobs — the user got back a message that the image was lost. The image was not lost; the model had the bytes. The fallback was missing.
Implementation
33d3dfc (2026-05-12) added width and height to the Telegram image document and propagated it through the metadata that Broca hands to the model. The dimensions are extracted from the Telegram message at intake and stored alongside the file reference, so the model knows the aspect ratio before it touches the bytes. The same commit also added a tmpfiles failure marker that Letta reads — a small contract change that lets the orchestrator tell the difference between a successful upload and a failed one, instead of having to infer it from the absence of a URL.
b2a6f96 (2026-05-12) is the smaller commit and the most surgical. The tmpfiles download resolver now accepts the alphanumeric view URL form. The ID is parsed from both the direct download path and the view path, and the same download endpoint is used either way. The regex went from strict numeric to alphanumeric with a length constraint, which is the actual range tmpfiles issues. No more silent rejection of a URL the user believed was a URL.
1b368f9 (2026-05-19) added the fallback. When the primary upload fails, Broca now writes the image to tmp.sanctumos.org, which serves it back as an ephemeral URL with a short lifetime. The user gets a usable image. The model gets a usable reference. The orchestrator gets a marker that this was a fallback path, not the primary one, so the result is tagged accordingly in the metadata. The fallback is not a replacement for the primary service — it is the difference between the user's image existing in the output and the user's image not existing in the output.
What became more reliable
Three things used to be best-effort and are now contractually true:
- Telegram image dimensions are present on the metadata Broca hands downstream. The model no longer has to guess aspect ratio for image-conditioned work.
- tmpfiles URLs in either form resolve. The alphanumeric view URL is no longer a silent failure for users who paste what they see in the address bar.
- An image that makes it to Broca makes it to the user. The fallback path closes the gap where the primary upload was unavailable.
The honest caveat: the fallback is best-effort in its own way. tmp.sanctumos.org is our own service, and it has its own availability profile. The fallback is the difference between "usually works" and "almost always works," not the difference between "almost always works" and "always works." For an image pipeline, that is a meaningful improvement.
Next
The next round of work covers three surfaces. First, the image metadata is moving from the Telegram-specific document to a generic image document on the Broca side, so the same width/height contract holds for image inputs that come in through other channels. Second, the fallback path needs an explicit retry against the primary service, so a transient primary failure does not turn into a permanent fallback classification. Third, the model side needs a small change to actually use the dimensions it now receives — today it has the data, but the conditioning code path that reads it is the next thing on the list.
The commits covered here are 33d3dfc, b2a6f96, and 1b368f9, shipped on 2026-05-12 and 2026-05-19.