users/<id>/photos/<uuid>.jpg, a link, or a [Media: image/png <url>] marker in a tool result. With media capture, your Worker hands each file to Moda once, under its name. Moda then links every name it finds in your traces to the file, including files that arrive after the trace. Replays use the real bytes:
- a replayed read of
env.R2_BUCKET.get(key)returns the original object; - a replayed fetch of a captured URL returns the original response body;
- any other name behaves as it did before.
put. R2 event notifications feed a queue, and one branch in the queue() handler you already have consumes it.
Ask Moda to enable media linking for your workspace before you start. Until it’s enabled, files still upload, but traces and replays don’t link to them.
1. Create the queue and the notification rules
Create one rule for each prefix that holds media your agent reads or writes:2. Consume the queue in your Worker
Add the consumer to your Wrangler config:queue() handler:
The handler acknowledges each message when it’s done. It asks for redelivery only when Moda or R2 is briefly unavailable (HTTP 408, 429, 5xx, or a network error). Under at-least-once delivery, a file is stored once:
- uploads are keyed by the file’s SHA-256;
- redelivered notifications are skipped;
- copies of one notification in the same batch share one upload.
crypto.DigestStream), so memory stays flat.
3. Capture media fetched from outside URLs
Media that never lands in R2, such as a CDN image your image tool fetches, goes throughcaptureFetchedMedia right after the fetch: