docs(runtime): describe trusted launcher API contract

Signed-off-by: Alex Rosenzweig <arosenzweig@squareup.com>

crates/buzz-agent/src/sandbox_runtime.rs

@@ -16,13 +16,19 @@ use serde::{Deserialize, Serialize};
 use std::path::Path;
 use std::{sync::Arc, time::Duration};
 
+/// Launcher-supplied JSON capability for a fixed loopback credential broker.
 pub const BROKER_ENV: &str = "BUZZ_SANDBOX_AUTH_BROKER";
+/// Path to the immutable certificate snapshot supplied by the launcher.
 pub const ROOTS_ENV: &str = "BUZZ_SANDBOX_TLS_ROOTS";
 
+/// Connection capability passed only to the protected agent, never its tools.
 #[derive(Clone, Serialize, Deserialize)]
 pub struct BrokerConfig {
+    /// Loopback TCP port selected by the trusted launcher.
     pub port: u16,
+    /// Random bearer capability authenticating requests to the launcher.
     pub secret: String,
+    /// Exact configured model service URL; prevents cross-provider reuse.
     pub host: String,
 }
 #[derive(Serialize, Deserialize)]

crates/buzz-runtime-support/src/tls.rs

@@ -1,6 +1,8 @@
 //! Local certificate verification for protected agents and their CLI helpers.
 use std::path::Path;
+/// Optional launcher-owned certificate snapshot path.
 pub const ROOTS_ENV: &str = "BUZZ_SANDBOX_TLS_ROOTS";
+/// Use ordinary platform trust unless an explicit launcher snapshot is configured.
 pub fn http_builder() -> Result<reqwest::ClientBuilder, anyhow::Error> {
     let builder = reqwest::Client::builder();
     match std::env::var_os(ROOTS_ENV) {
@@ -8,6 +10,7 @@ pub fn http_builder() -> Result<reqwest::ClientBuilder, anyhow::Error> {
         Some(path) => builder_with_roots(builder, Path::new(&path)),
     }
 }
+/// Restrict verification to a nonempty DER certificate snapshot; invalid input fails closed.
 pub fn builder_with_roots(
     builder: reqwest::ClientBuilder,
     path: &Path,