feat(mcp): hand images to an artifact sink as well as to the model

A screenshot returned from browser_take_screenshot reaches exactly one place:
the model's context. That is enough for the model to look at the page and no
use at all to the person who asked to see it — they get a description of an
image that was never sent anywhere. The agent cannot fix that on its own
either, because the bytes never touch a filesystem it can reach.

So when RUSTWRIGHT_ARTIFACT_SINK names an endpoint, every image this server
produces is POSTed there as well. The operator decides what that means. It is
best effort throughout: the tool call's real job is answering the model, and a
sink that is missing, slow or broken must not turn a working screenshot into a
failed tool.

Placed before the inline size branch deliberately — an image too large to inline
is the one a person most wants sent somewhere they can open it, and telling the
model "saved to /tmp/..." helps nobody outside the machine.

Written by hand over a unix socket rather than pulling in an HTTP client for a
request with a fixed shape sent to the same host.

Author: jaredLunde

mcp/src/artifacts.rs

@@ -0,0 +1,158 @@
+//! Handing media the browser produced to whoever is hosting this server.
+//!
+//! # Why this exists
+//!
+//! A screenshot returned from `browser_take_screenshot` reaches exactly one
+//! place: the model's context. That is enough for the model to *look* at the
+//! page and no use at all to the person who asked to see it — they get a
+//! description of an image that was never sent anywhere. The agent has no way
+//! to fix that on its own either, because the bytes never touch a filesystem it
+//! can reach.
+//!
+//! So when an operator points [`ENV_SINK`] at an endpoint, every image this
+//! server produces is also POSTed there. The operator decides what that means:
+//! attach it to a chat message, drop it in a bucket, ignore it.
+//!
+//! # Best effort, always
+//!
+//! Every failure here is swallowed. The tool call's real job is answering the
+//! model, and a sink that is missing, slow, or broken must not turn a working
+//! screenshot into a failed tool. Nothing in this module returns an error to a
+//! caller; it logs to stderr and moves on.
+
+use std::io::{Read, Write};
+use std::os::unix::net::UnixStream;
+use std::time::Duration;
+
+/// Where to POST media this server produces.
+///
+/// A URL rather than a bare path, and read from the environment rather than
+/// configured in a tool call: whether artifacts are collected is a property of
+/// the deployment, not something a model should be deciding per screenshot.
+///
+/// Only `unix://` is understood today. An operator running this somewhere else
+/// gets a warning on the first attempt and no artifacts, which is the same
+/// outcome as not setting it.
+pub const ENV_SINK: &str = "RUSTWRIGHT_ARTIFACT_SINK";
+
+/// How long one POST may take.
+///
+/// The tool call is holding while this runs, so it is short. A sink that cannot
+/// take a screenshot in this long is one whose artifacts are not worth the
+/// latency they are costing the person waiting for an answer.
+const TIMEOUT: Duration = Duration::from_secs(20);
+
+/// Refuse to hold more than this in one request.
+///
+/// Well above any screenshot and below the point where a stuck encoder could
+/// have us buffering a video into memory forever.
+const MAX_BYTES: usize = 96 * 1024 * 1024;
+
+/// Post one artifact, if a sink is configured.
+///
+/// `name` is a suggestion. A sink is free to rename or ignore it — it reaches a
+/// header, so it is sanitized here rather than trusted.
+pub fn offer(bytes: &[u8], mime: &str, name: &str) {
+    let Ok(url) = std::env::var(ENV_SINK) else {
+        return;
+    };
+    let url = url.trim();
+    if url.is_empty() {
+        return;
+    }
+    let Some(path) = url.strip_prefix("unix://") else {
+        eprintln!("[rustwright] {ENV_SINK} is not a unix:// URL; ignoring it");
+        return;
+    };
+    if bytes.is_empty() || bytes.len() > MAX_BYTES {
+        return;
+    }
+
+    if let Err(error) = post(path, bytes, mime, name) {
+        // Worth saying out loud: from the model's side the tool succeeded, so a
+        // silent failure here is a screenshot that vanishes with no trace.
+        eprintln!("[rustwright] could not hand an artifact to the sink: {error}");
+    }
+}
+
+/// Write one HTTP/1.1 POST by hand and read back the status line.
+///
+/// By hand because the alternative is an HTTP client dependency for a request
+/// with a fixed shape, sent to a socket on the same machine. Content-Length,
+/// not chunked: the length is known and a sink that streams straight into
+/// object storage wants it up front.
+fn post(path: &str, bytes: &[u8], mime: &str, name: &str) -> std::io::Result<()> {
+    let mut stream = UnixStream::connect(path)?;
+    stream.set_write_timeout(Some(TIMEOUT))?;
+    stream.set_read_timeout(Some(TIMEOUT))?;
+
+    let head = format!(
+        "POST / HTTP/1.1\r\n\
+         Host: localhost\r\n\
+         Content-Type: {}\r\n\
+         X-Artifact-Name: {}\r\n\
+         Content-Length: {}\r\n\
+         Connection: close\r\n\r\n",
+        header_safe(mime),
+        header_safe(name),
+        bytes.len(),
+    );
+    stream.write_all(head.as_bytes())?;
+    stream.write_all(bytes)?;
+    stream.flush()?;
+
+    // Enough for the status line. The body is not interesting and the
+    // connection closes either way.
+    let mut response = [0u8; 64];
+    let read = stream.read(&mut response).unwrap_or(0);
+    let status = String::from_utf8_lossy(&response[..read]);
+    let ok = status
+        .split_whitespace()
+        .nth(1)
+        .and_then(|code| code.parse::<u16>().ok())
+        .is_some_and(|code| (200..300).contains(&code));
+    if !ok {
+        return Err(std::io::Error::other(format!(
+            "sink refused it: {}",
+            status.lines().next().unwrap_or("no response").trim()
+        )));
+    }
+    Ok(())
+}
+
+/// Strip anything that would end a header line or smuggle another one in.
+///
+/// These values are ours rather than a user's, but `name` is derived from a
+/// page title in some callers and a CR in a header is a request-splitting bug
+/// wherever it comes from.
+fn header_safe(value: &str) -> String {
+    value
+        .chars()
+        .filter(|c| !c.is_control())
+        .take(200)
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn header_safe_drops_control_characters() {
+        assert_eq!(header_safe("a\r\nX-Evil: 1"), "aX-Evil: 1");
+        assert_eq!(header_safe("shot.png"), "shot.png");
+    }
+
+    #[test]
+    fn header_safe_bounds_length() {
+        assert_eq!(header_safe(&"x".repeat(500)).len(), 200);
+    }
+
+    // No sink configured is the common case and must be free of side effects.
+    #[test]
+    fn offer_without_a_sink_does_nothing() {
+        // SAFETY: single-threaded test, and the variable is read once per call.
+        unsafe { std::env::remove_var(ENV_SINK) };
+        offer(b"not a real png", "image/png", "shot.png");
+    }
+}

mcp/src/main.rs

@@ -1,4 +1,5 @@
 mod actor;
+mod artifacts;
 mod config;
 mod server;
 mod shaping;

mcp/src/server.rs

@@ -163,6 +163,14 @@ fn output_content(
             mime,
             extension,
         } => {
+            // Hand it to the host as well as to the model.
+            //
+            // Before the size branch below, deliberately: an image too large to
+            // inline is exactly the one a person most wants sent somewhere they
+            // can open it, and telling the model "saved to /tmp/..." helps
+            // nobody outside this VM.
+            crate::artifacts::offer(&bytes, &mime, &format!("screenshot.{extension}"));
+
             let payload_bytes = encoded_len(bytes.len(), true).unwrap_or(usize::MAX);
             if payload_bytes <= screenshot_max_bytes {
                 return Ok((ContentBlock::image(STANDARD.encode(bytes), mime), None));