From 06d49e156edb11ebbe734675aa2b71f8fe0b237f Mon Sep 17 00:00:00 2001 From: renyuanz Date: Thu, 19 Nov 2026 19:00:02 +0800 Subject: [PATCH] feat(hub): save files for a run's agent on its machine, over the bridge and the API (OFF-143) offdesk.so lets the person attach pictures, recordings and any file to a message for an agent. New bridge commands upload_begin / upload_chunk / upload_end (and POST /api/agent-runs/{id}/files/begin|chunk|end for runs:message tokens) save a file of up to 100 MB in ~/.offdesk/attachments/ on the run's machine, through the node's existing file transfer, and answer with its path for the message to name. Co-Authored-By: Claude Opus 5.5 --- crates/hub/src/auth.rs | 7 + crates/hub/src/bridge.rs | 52 +- crates/hub/src/bridge/tests.rs | 162 ++++++ crates/hub/src/routes/agent_runs.rs | 16 + crates/hub/src/routes/agent_runs/files.rs | 600 ++++++++++++++++++++++ docs/agent-bridge-protocol.md | 27 +- 6 files changed, 862 insertions(+), 2 deletions(-) create mode 100644 crates/hub/src/routes/agent_runs/files.rs diff --git a/crates/hub/src/auth.rs b/crates/hub/src/auth.rs index 081bd4c8..cad402d0 100644 --- a/crates/hub/src/auth.rs +++ b/crates/hub/src/auth.rs @@ -298,6 +298,13 @@ fn scoped_route( ) => Some(CHAT), ("POST", "/api/agent-runs/{run_id}/answer") => Some(ANSWER), ("POST", "/api/agent-runs/{run_id}/message") => Some(MESSAGE), + // Files for the agent, saved on the run's machine (routes/agent_runs/files.rs) + ( + "POST", + "/api/agent-runs/{run_id}/files/begin" + | "/api/agent-runs/{run_id}/files/chunk" + | "/api/agent-runs/{run_id}/files/end", + ) => Some(MESSAGE), ("POST", "/api/agent-runs") => Some(START), ("GET", "/api/machines/{machine_id}/agents") => Some(START), // Answering, messaging and starting take the machine's control lease, as the CLI does diff --git a/crates/hub/src/bridge.rs b/crates/hub/src/bridge.rs index 6abafa51..23c4ea83 100644 --- a/crates/hub/src/bridge.rs +++ b/crates/hub/src/bridge.rs @@ -25,6 +25,7 @@ use tokio_util::sync::CancellationToken; use crate::auth::AuthUser; use crate::db::{self, integrations::{self, Integration}}; +use crate::routes::agent_runs::files; use crate::AppState; /// The protocol version this hub speaks (`hello.protocol`). @@ -429,6 +430,21 @@ enum ServerMessage { limit: Option, }, Cancel { command_id: String, run_id: String }, + /// Starts saving a file for a run's agent on its machine (runs:message). + UploadBegin { + command_id: String, + run_id: String, + name: String, + size: u64, + }, + /// The next chunk of an upload. `data` is never logged or kept. + UploadChunk { + command_id: String, + upload_id: String, + index: u32, + data: String, + }, + UploadEnd { command_id: String, upload_id: String }, Pong, #[serde(other)] Other, @@ -488,7 +504,10 @@ async fn handle(state: &AppState, bridge: &Integration, text: &str) -> Option command_id.clone(), + | ServerMessage::Cancel { command_id, .. } + | ServerMessage::UploadBegin { command_id, .. } + | ServerMessage::UploadChunk { command_id, .. } + | ServerMessage::UploadEnd { command_id, .. } => command_id.clone(), }; // A command seen before gets the same result, not a second go if let Some(previous) = state @@ -558,6 +577,8 @@ fn bridge_caller(bridge: &Integration) -> AuthUser { } } +const UPLOAD_SCOPE: &str = "This bridge can't attach files; it needs runs:message"; + /// Carries out a command as the bridge: its access decides, and it's audited. async fn command(state: &AppState, bridge: &Integration, message: ServerMessage) -> Value { let caller = bridge_caller(bridge); @@ -626,6 +647,35 @@ async fn command(state: &AppState, bridge: &Integration, message: ServerMessage) Err(refused) => refusal(refused), } } + ServerMessage::UploadBegin { run_id, name, size, .. } => { + if !caller.allows(TokenScope::RunsMessage) { + let reason = UPLOAD_SCOPE; + caller.audit(&state.db, "upload", &run_id, reason); + return json!({ "ok": false, "status": 403, "error": reason }); + } + match files::upload_begin_as(state, &caller, &run_id, &name, size).await { + Ok(begun) => json!({ "ok": true, "upload_id": begun.upload_id, "chunk_bytes": begun.chunk_bytes }), + Err(refused) => refusal(refused), + } + } + ServerMessage::UploadChunk { upload_id, index, data, .. } => { + if !caller.allows(TokenScope::RunsMessage) { + return json!({ "ok": false, "status": 403, "error": UPLOAD_SCOPE }); + } + match files::upload_chunk_as(state, &caller, None, &upload_id, index, data).await { + Ok(received) => json!({ "ok": true, "received": received }), + Err(refused) => refusal(refused), + } + } + ServerMessage::UploadEnd { upload_id, .. } => { + if !caller.allows(TokenScope::RunsMessage) { + return json!({ "ok": false, "status": 403, "error": UPLOAD_SCOPE }); + } + match files::upload_end_as(state, &caller, None, &upload_id).await { + Ok((path, size)) => json!({ "ok": true, "path": path, "size": size }), + Err(refused) => refusal(refused), + } + } ServerMessage::Cancel { run_id, .. } => { let reason = "This hub can't do that yet"; caller.audit(&state.db, "denied", &run_id, reason); diff --git a/crates/hub/src/bridge/tests.rs b/crates/hub/src/bridge/tests.rs index 885827e5..48678c4d 100644 --- a/crates/hub/src/bridge/tests.rs +++ b/crates/hub/src/bridge/tests.rs @@ -255,3 +255,165 @@ fn bridge_urls_are_wss_or_this_machine() { assert!(new_key().starts_with("obk_") && new_key() != new_key()); assert!(backoff(0) >= Duration::from_millis(750) && backoff(20) <= Duration::from_secs(75)); } + +/// A hub with one person, machine-a, an open run and an ended one. +fn upload_state() -> (AppState, std::path::PathBuf, String, String) { + let path = std::env::temp_dir().join(format!("offdesk-bridge-{}.db", uuid::Uuid::new_v4())); + let pool = db::create_pool(&path.to_string_lossy()).unwrap(); + let (open, ended) = { + let conn = pool.get().unwrap(); + db::init_db(&conn).unwrap(); + db::users::create_user(&conn, "user-a", "test", "user-a", "user-a", None, "admin").unwrap(); + db::machines::ensure_machine_for_user(&conn, "machine-a", "user-a", "studio", Some("linux"), Some("/tmp")).unwrap(); + let open = db::agent_runs::insert(&conn, "machine-a", "t1", RunAgent::Claude, "/w", AgentRunStatus::Working).unwrap(); + let ended = db::agent_runs::insert(&conn, "machine-a", "t2", RunAgent::Claude, "/w", AgentRunStatus::Working).unwrap(); + db::agent_runs::set_status(&conn, &ended.id, AgentRunStatus::Done).unwrap(); + (open.id, ended.id) + }; + let state = AppState { + manager: Arc::new(MachineManager::new(pool.clone())), + router: Arc::new(HubRouter::new()), + web_previews: Arc::new(crate::web_preview::registry::Registry::default()), + db: pool, + jwt_secret: "test-secret".to_string(), + base_url: "http://localhost:4317".to_string(), + dev_mode: false, + github_client_id: None, + github_client_secret: None, + google_client_id: None, + google_client_secret: None, + }; + (state, path, open, ended) +} + +fn upload_bridge(id: &str, scopes: Vec) -> Integration { + Integration { + id: id.into(), + user_id: "user-a".into(), + kind: "bridge".into(), + name: id.into(), + url: "ws://127.0.0.1:1/".into(), + secret: new_key(), + events: vec![], + access: TokenAccess { scopes, content: ContentLevel::Requests, ..Default::default() }, + enabled: false, + created_at: 0, + last_delivery_at: None, + last_error: None, + pairing_code: None, + } +} + +async fn send(state: &AppState, bridge: &Integration, command: Value) -> Value { + handle(state, bridge, &command.to_string()).await.expect("a result") +} + +#[tokio::test] +async fn a_bridge_saves_files_for_a_run_on_its_machine() { + use base64::Engine; + use offdesk_protocol::{FsOp, FsOpErrorCode, HubToMachine, MachineInfo, MachineToHub, OnConflict}; + let (state, path, open, ended) = upload_state(); + let reader = upload_bridge("bridge-r", vec![TokenScope::RunsRead]); + let bridge = upload_bridge("bridge-m", vec![TokenScope::RunsRead, TokenScope::RunsMessage]); + let other = upload_bridge("bridge-o", vec![TokenScope::RunsRead, TokenScope::RunsMessage]); + for b in [&reader, &bridge, &other] { + integrations::insert(&state.db.get().unwrap(), b).unwrap(); + } + let begin = |command_id: &str, run_id: &str, name: &str, size: u64| { + json!({ "type": "upload_begin", "command_id": command_id, "run_id": run_id, "name": name, "size": size }) + }; + + // Refusals: scope, unknown run, ended run, too big, machine offline + let result = send(&state, &reader, begin("c1", &open, "a.png", 3)).await; + assert_eq!((result["type"].as_str(), result["command_id"].as_str(), result["status"].as_u64()), (Some("result"), Some("c1"), Some(403))); + assert_eq!(result["error"], "This bridge can't attach files; it needs runs:message"); + assert_eq!(send(&state, &bridge, begin("c2", "nope", "a.png", 3)).await["status"], 404); + assert_eq!(send(&state, &bridge, begin("c3", &ended, "a.png", 3)).await["status"], 409); + assert_eq!(send(&state, &bridge, begin("c4", &open, "a.png", 100 * 1024 * 1024 + 1)).await["status"], 413); + let result = send(&state, &bridge, begin("c5", &open, "a.png", 3)).await; + assert_eq!((result["status"].as_u64(), result["error"].as_str()), (Some(503), Some("The machine is offline"))); + + // A node without file operations + let info = |id: &str| MachineInfo { id: id.into(), name: "studio".into(), os: "linux".into(), home_dir: "/home/me".into(), production: false }; + let (_, _old) = state.manager.register_machine_with_capabilities(info("machine-a"), Some("user-a".into()), vec![]).await; + let result = send(&state, &bridge, begin("c6", &open, "a.png", 3)).await; + assert_eq!(result["status"], 503); + assert!(result["error"].as_str().unwrap().starts_with("Update Offdesk on that machine")); + + // A node that can: folders one level at a time ("exists" is fine), then the upload + let (_, mut commands) = state + .manager + .register_machine_with_capabilities(info("machine-a"), Some("user-a".into()), vec![offdesk_protocol::FS_OPS_CAPABILITY.into()]) + .await; + let dir = format!("~/.offdesk/attachments/{open}"); + let saved = format!("/home/me/.offdesk/attachments/{open}/passwd"); + let made = Arc::new(std::sync::Mutex::new(Vec::::new())); + let machine_side = { + let (manager, dir, saved, made) = (state.manager.clone(), dir.clone(), saved.clone(), made.clone()); + tokio::spawn(async move { + let mut received = 0u64; + while let Some(command) = commands.recv().await { + let reply = match command { + HubToMachine::FsOp { request_id, op: FsOp::Mkdir { path } } => { + let first = { + let mut made = made.lock().unwrap(); + made.push(path.clone()); + made.len() == 1 + }; + if first { + MachineToHub::FsOpError { request_id, code: FsOpErrorCode::Exists, message: "exists".into(), path: Some(path) } + } else { + MachineToHub::FsOpResult { request_id, paths: vec![path] } + } + } + HubToMachine::FsUploadBegin { request_id, dest_dir, filename, size, on_conflict, chunk_bytes, .. } => { + assert_eq!((dest_dir.as_str(), filename.as_str(), size, on_conflict, chunk_bytes), (dir.as_str(), "passwd", 5, OnConflict::KeepBoth, None)); + MachineToHub::FsUploadAck { request_id, received: 0, parallel: false } + } + HubToMachine::FsUploadChunk { request_id, data, .. } => { + received += base64::engine::general_purpose::STANDARD.decode(data).unwrap().len() as u64; + MachineToHub::FsUploadAck { request_id, received, parallel: false } + } + HubToMachine::FsUploadEnd { request_id, .. } => { + MachineToHub::FsUploadDone { request_id, path: saved.clone(), size: received } + } + HubToMachine::FsUploadAbort { .. } => continue, + other => panic!("unexpected {other:?}"), + }; + manager.handle_machine_message("machine-a", reply).await; + } + }) + }; + let result = send(&state, &bridge, begin("c7", &open, "../../etc/passwd", 5)).await; + assert_eq!((result["ok"].as_bool(), result["chunk_bytes"].as_u64()), (Some(true), Some(1024 * 1024))); + let upload_id = result["upload_id"].as_str().unwrap().to_string(); + let chunk = |command_id: &str, index: u32, bytes: &[u8]| { + let data = base64::engine::general_purpose::STANDARD.encode(bytes); + json!({ "type": "upload_chunk", "command_id": command_id, "upload_id": upload_id, "index": index, "data": data }) + }; + // Only the bridge that began it goes on + assert_eq!(send(&state, &other, chunk("o1", 0, b"abc")).await["status"], 404); + let result = send(&state, &bridge, chunk("c8", 0, b"abc")).await; + assert_eq!((result["ok"].as_bool(), result["received"].as_u64()), (Some(true), Some(3))); + // A repeat gets the same result, not a second write + assert_eq!(send(&state, &bridge, chunk("c8", 0, b"abc")).await["received"], 3); + let kept = integrations::command_result(&state.db.get().unwrap(), "bridge-m", "c8").unwrap().unwrap(); + assert!(!kept.contains("YWJj"), "a chunk's data isn't kept"); + assert_eq!(send(&state, &bridge, chunk("c9", 1, b"de")).await["received"], 5); + let end = |command_id: &str| json!({ "type": "upload_end", "command_id": command_id, "upload_id": upload_id }); + assert_eq!(send(&state, &other, end("o2")).await["status"], 404); + let result = send(&state, &bridge, end("c10")).await; + assert_eq!((result["ok"].as_bool(), result["path"].as_str(), result["size"].as_u64()), (Some(true), Some(saved.as_str()), Some(5))); + // Done: the upload is gone + assert_eq!(send(&state, &bridge, end("c11")).await["status"], 404); + assert_eq!(*made.lock().unwrap(), ["~/.offdesk".to_string(), "~/.offdesk/attachments".into(), dir.clone()]); + + let audit = db::tokens::list_audit(&state.db.get().unwrap(), "user-a", Some("bridge-m"), 20).unwrap(); + let actions: Vec<(&str, &str, &str)> = audit.iter().map(|a| (a.action.as_str(), a.target.as_str(), a.result.as_str())).collect(); + assert!(actions.contains(&("upload_end", saved.as_str(), "ok, 5 bytes")), "{actions:?}"); + assert!(actions.contains(&("upload", open.as_str(), "ok")), "{actions:?}"); + drop(state); + machine_side.abort(); + let _ = machine_side.await; + let _ = std::fs::remove_file(&path); +} diff --git a/crates/hub/src/routes/agent_runs.rs b/crates/hub/src/routes/agent_runs.rs index 2c873649..4ddce9a9 100644 --- a/crates/hub/src/routes/agent_runs.rs +++ b/crates/hub/src/routes/agent_runs.rs @@ -22,6 +22,8 @@ use crate::auth::AuthUser; use crate::db::agent_runs; use crate::AppState; +pub(crate) mod files; + /// The machines a scoped token may reach; None: any of the caller's (full access). fn reachable_machines( db: &rusqlite::Connection, @@ -723,6 +725,7 @@ pub fn router() -> Router { "/api/machines/{machine_id}/sessions/{agent}/{session_id}/messages", get(machine_session_conversation), ) + .merge(files::router()) } #[cfg(test)] @@ -974,11 +977,24 @@ mod tests { ("POST", "/api/auth/api-tokens"), ("POST", &format!("/api/agent-runs/{}/answer", waiting.id)), ("POST", "/api/agent-runs"), + ("POST", &format!("/api/agent-runs/{}/files/begin", waiting.id)), ] { let body = (method == "POST").then(|| serde_json::json!({})); let (status, _) = call(&state, "odk_read", method, uri, body).await; assert_eq!(status, StatusCode::FORBIDDEN, "{method} {uri}"); } + // Files for the agent take runs:message, and 100 MB at most + token(&state, "odk_message", Some(TokenAccess { scopes: vec![TokenScope::RunsMessage], ..Default::default() })); + let files = format!("/api/agent-runs/{}/files/begin", waiting.id); + let too_big = serde_json::json!({ "name": "a.mov", "size": 100 * 1024 * 1024 + 1 }); + let (status, _) = call(&state, "odk_message", "POST", &files, Some(too_big)).await; + assert_eq!(status, StatusCode::PAYLOAD_TOO_LARGE); + let small = serde_json::json!({ "name": "a.png", "size": 3 }); + let (status, body) = call(&state, "odk_message", "POST", &files, Some(small)).await; + assert_eq!((status, body.as_str()), (StatusCode::SERVICE_UNAVAILABLE, "Update Offdesk on that machine to attach files from here")); + let chunk = serde_json::json!({ "upload_id": "nope", "index": 0, "data": "" }); + let (status, _) = call(&state, "odk_message", "POST", &format!("/api/agent-runs/{}/files/chunk", waiting.id), Some(chunk)).await; + assert_eq!(status, StatusCode::NOT_FOUND); // ...and so are the WebSockets and the beacon, which take full access only assert!(crate::auth::verify_bearer_token("odk_read", &state.db, &state.jwt_secret).is_err()); assert!(crate::auth::verify_bearer_token("odk_full", &state.db, &state.jwt_secret).is_ok()); diff --git a/crates/hub/src/routes/agent_runs/files.rs b/crates/hub/src/routes/agent_runs/files.rs new file mode 100644 index 00000000..26ca2a52 --- /dev/null +++ b/crates/hub/src/routes/agent_runs/files.rs @@ -0,0 +1,600 @@ +//! Files for a run's agent (docs/agent-bridge-protocol.md, `upload_*`): a server or an +//! API token sends a file in chunks, and the hub saves it on the run's machine under +//! `~/.offdesk/attachments//`, through the node's file upload. The agent reads +//! it from there once a message names the path. Chunks go straight to the machine; the +//! hub keeps only who started each upload and how far it got. + +use std::collections::HashMap; +use std::sync::{Mutex, OnceLock}; +use std::time::{Duration, Instant}; + +use axum::{ + extract::{DefaultBodyLimit, Path, State}, + http::StatusCode, + response::{IntoResponse, Json, Response}, + routing::post, + Router, +}; +use offdesk_protocol::{FsOp, FsOpErrorCode, HubToMachine, OnConflict, TokenScope}; +use serde::Deserialize; + +use super::{failed, over_limit, refuse, refused, visible_run, Refusal}; +use crate::auth::AuthUser; +use crate::machine_manager::{FsOpFailure, FsTransferReply}; +use crate::AppState; + +/// The largest file one upload takes. +pub(crate) const MAX_FILE_BYTES: u64 = 100 * 1024 * 1024; +/// Every chunk but the last carries this many bytes (base64 in `data`). +pub(crate) const CHUNK_BYTES: usize = 1024 * 1024; +/// An upload nobody touched for this long is forgotten (the node drops its part +/// file on its own after the same time). +const IDLE: Duration = Duration::from_secs(10 * 60); +const STEP_TIMEOUT: Duration = Duration::from_secs(60); +/// Longest file name kept, in bytes; the node adds its own suffix to a part file. +const NAME_MAX: usize = 120; + +const OUTDATED: &str = "Update Offdesk on that machine to attach files from here"; +const OFFLINE: &str = "The machine is offline"; +const NO_UPLOAD: &str = "Upload not found"; + +/// One upload in progress, as the hub knows it. +#[derive(Debug, Clone)] +struct Upload { + /// The token or bridge (or person) that started it: only it may go on. + owner: String, + user_id: String, + machine_id: String, + run_id: String, + next_index: u32, + received: u64, + size: u64, + /// A chunk is on its way to the machine. + busy: bool, + touched: Instant, +} + +static UPLOADS: OnceLock>> = OnceLock::new(); + +/// The uploads in progress, without the ones left idle. +fn uploads() -> std::sync::MutexGuard<'static, HashMap> { + let mut uploads = UPLOADS + .get_or_init(Default::default) + .lock() + .unwrap_or_else(|e| e.into_inner()); + uploads.retain(|_, upload| upload.touched.elapsed() < IDLE); + uploads +} + +fn owner(auth_user: &AuthUser) -> String { + match &auth_user.api_token_id { + Some(id) => format!("token:{id}"), + None => format!("user:{}", auth_user.user_id), + } +} + +/// A bare file name that's safe on the machine: the last part of whatever path came +/// with it, no control characters, at most `NAME_MAX` bytes (keeping a short +/// extension), and "file" when nothing usable is left. +pub(crate) fn safe_name(raw: &str) -> String { + let base = raw.rsplit(['/', '\\']).next().unwrap_or_default(); + let cleaned: String = base.chars().filter(|c| !c.is_control()).collect(); + let name = cleaned.trim(); + if name.is_empty() || name == "." || name == ".." { + return "file".to_string(); + } + if name.len() <= NAME_MAX { + return name.to_string(); + } + let (stem, ext) = match name.rfind('.') { + Some(dot) if dot > 0 && name.len() - dot <= 16 => name.split_at(dot), + _ => (name, ""), + }; + let mut end = NAME_MAX - ext.len(); + while !stem.is_char_boundary(end) { + end -= 1; + } + format!("{}{ext}", stem[..end].trim_end()) +} + +/// Where a run's files go, and the folders to make first, outermost first. +pub(crate) fn attachments_dirs(run_id: &str) -> [String; 3] { + [ + "~/.offdesk".to_string(), + "~/.offdesk/attachments".to_string(), + format!("~/.offdesk/attachments/{run_id}"), + ] +} + +/// A failed file step as a refusal, with the status the HTTP API would give. +fn fs_refusal(failure: FsOpFailure) -> Refusal { + match failure { + FsOpFailure::Machine { code, message, .. } => { + let status = match code { + FsOpErrorCode::NotFound => StatusCode::NOT_FOUND, + FsOpErrorCode::Exists => StatusCode::CONFLICT, + FsOpErrorCode::PermissionDenied => StatusCode::FORBIDDEN, + FsOpErrorCode::Invalid => StatusCode::BAD_REQUEST, + FsOpErrorCode::TooLarge => StatusCode::PAYLOAD_TOO_LARGE, + FsOpErrorCode::NoSpace => StatusCode::INSUFFICIENT_STORAGE, + FsOpErrorCode::Io => StatusCode::BAD_GATEWAY, + }; + refused(status, message) + } + FsOpFailure::Outdated => refused(StatusCode::SERVICE_UNAVAILABLE, OUTDATED), + FsOpFailure::NoMachine | FsOpFailure::Disconnected => { + refused(StatusCode::SERVICE_UNAVAILABLE, OFFLINE) + } + FsOpFailure::Timeout => refused( + StatusCode::GATEWAY_TIMEOUT, + "The machine took too long to answer", + ), + } +} + +fn unexpected() -> Refusal { + refused(StatusCode::BAD_GATEWAY, "Unexpected reply from the machine") +} + +async fn transfer( + state: &AppState, + machine_id: &str, + msg: impl FnOnce(String) -> HubToMachine, +) -> Result { + let request_id = uuid::Uuid::new_v4().to_string(); + let msg = msg(request_id.clone()); + state + .manager + .fs_transfer(machine_id, request_id, msg, STEP_TIMEOUT) + .await + .map_err(fs_refusal) +} + +pub(crate) struct Begun { + pub upload_id: String, + pub chunk_bytes: usize, +} + +/// Starts saving a file for a run's agent as `auth_user`: runs:message, a run of +/// theirs that hasn't ended on a machine they may reach, at most `MAX_FILE_BYTES`, +/// within the hourly limit of answers (each upload counts once). Audited as `upload`. +pub(crate) async fn upload_begin_as( + state: &AppState, + auth_user: &AuthUser, + run_id: &str, + name: &str, + size: u64, +) -> Result { + if !auth_user.allows(TokenScope::RunsMessage) { + return Err(refuse( + auth_user, + state, + "upload", + run_id, + "This token can't attach files; it needs runs:message", + )); + } + let run = { + let db = state.db.get().map_err(failed)?; + visible_run(&db, auth_user, run_id) + .map_err(failed)? + .ok_or_else(|| refused(StatusCode::NOT_FOUND, "Agent run not found"))? + }; + if run.ended_at.is_some() { + return Err(refused(StatusCode::CONFLICT, "This agent run has ended")); + } + if size > MAX_FILE_BYTES { + return Err(refused( + StatusCode::PAYLOAD_TOO_LARGE, + "A file can be at most 100 MB", + )); + } + let limit = auth_user + .access + .as_ref() + .and_then(|access| access.max_answers_per_hour); + if over_limit( + state, + auth_user, + &["answer", "approve", "message", "upload"], + limit, + ) { + auth_user.audit(&state.db, "upload", run_id, "hourly limit reached"); + return Err(refused( + StatusCode::TOO_MANY_REQUESTS, + "This token reached its hourly limit of answers", + )); + } + let result = begin_on_machine(state, auth_user, &run.machine_id, run_id, name, size).await; + auth_user.audit( + &state.db, + "upload", + run_id, + match &result { + Ok(_) => "ok", + Err((_, reason)) => reason, + }, + ); + result +} + +async fn begin_on_machine( + state: &AppState, + auth_user: &AuthUser, + machine_id: &str, + run_id: &str, + name: &str, + size: u64, +) -> Result { + if !state + .manager + .user_can_access_machine(&auth_user.user_id, machine_id) + .await + { + return Err(refused(StatusCode::SERVICE_UNAVAILABLE, OFFLINE)); + } + if !state + .manager + .machine_supports(machine_id, offdesk_protocol::FS_OPS_CAPABILITY) + .await + { + return Err(refused(StatusCode::SERVICE_UNAVAILABLE, OUTDATED)); + } + // The node only uploads into a folder that's there + let dirs = attachments_dirs(run_id); + for dir in &dirs { + match state + .manager + .fs_op(machine_id, FsOp::Mkdir { path: dir.clone() }) + .await + { + Ok(_) + | Err(FsOpFailure::Machine { + code: FsOpErrorCode::Exists, + .. + }) => {} + Err(failure) => return Err(fs_refusal(failure)), + } + } + let upload_id = uuid::Uuid::new_v4().to_string(); + let (id, dest_dir, filename) = (upload_id.clone(), dirs[2].clone(), safe_name(name)); + let reply = transfer(state, machine_id, move |request_id| { + HubToMachine::FsUploadBegin { + request_id, + upload_id: id, + dest_dir, + filename, + size, + on_conflict: OnConflict::KeepBoth, + chunk_bytes: None, + } + }) + .await?; + if !matches!(reply, FsTransferReply::Ack { .. }) { + return Err(unexpected()); + } + uploads().insert( + upload_id.clone(), + Upload { + owner: owner(auth_user), + user_id: auth_user.user_id.clone(), + machine_id: machine_id.to_string(), + run_id: run_id.to_string(), + next_index: 0, + received: 0, + size, + busy: false, + touched: Instant::now(), + }, + ); + Ok(Begun { + upload_id, + chunk_bytes: CHUNK_BYTES, + }) +} + +/// The upload, when `auth_user` started it (and, given a run, for that run). +fn owned(auth_user: &AuthUser, upload_id: &str, run_id: Option<&str>) -> Result { + uploads() + .get(upload_id) + .filter(|upload| upload.owner == owner(auth_user) && upload.user_id == auth_user.user_id) + .filter(|upload| run_id.is_none_or(|run_id| upload.run_id == run_id)) + .cloned() + .ok_or_else(|| refused(StatusCode::NOT_FOUND, NO_UPLOAD)) +} + +/// Forgets an upload and has the machine drop what it got. +async fn abandon(state: &AppState, upload_id: &str, machine_id: &str) { + uploads().remove(upload_id); + state + .manager + .fs_upload_abort(machine_id, upload_id.to_string()) + .await; +} + +/// Stores the next chunk (base64 of at most `CHUNK_BYTES`, in order from 0); the bytes +/// saved so far. A chunk that fails ends the upload. +pub(crate) async fn upload_chunk_as( + state: &AppState, + auth_user: &AuthUser, + run_id: Option<&str>, + upload_id: &str, + index: u32, + data: String, +) -> Result { + if !auth_user.allows(TokenScope::RunsMessage) { + return Err(refused( + StatusCode::FORBIDDEN, + "This token can't attach files; it needs runs:message", + )); + } + let upload = { + let mut uploads = uploads(); + let upload = uploads + .get_mut(upload_id) + .filter(|upload| { + upload.owner == owner(auth_user) && upload.user_id == auth_user.user_id + }) + .filter(|upload| run_id.is_none_or(|run_id| upload.run_id == run_id)) + .ok_or_else(|| refused(StatusCode::NOT_FOUND, NO_UPLOAD))?; + if upload.busy { + return Err(refused(StatusCode::CONFLICT, "Send one chunk at a time")); + } + if index != upload.next_index { + return Err(refused( + StatusCode::BAD_REQUEST, + format!( + "Send chunks in order; the next one is {}", + upload.next_index + ), + )); + } + upload.busy = true; + upload.touched = Instant::now(); + upload.clone() + }; + if data.len() > CHUNK_BYTES.div_ceil(3) * 4 { + abandon(state, upload_id, &upload.machine_id).await; + return Err(refused( + StatusCode::PAYLOAD_TOO_LARGE, + format!("A chunk carries at most {CHUNK_BYTES} bytes"), + )); + } + let id = upload_id.to_string(); + let result = transfer(state, &upload.machine_id, move |request_id| { + HubToMachine::FsUploadChunk { + request_id, + upload_id: id, + index, + data, + } + }) + .await; + match result { + Ok(FsTransferReply::Ack { received, .. }) if received <= upload.size => { + if let Some(upload) = uploads().get_mut(upload_id) { + upload.busy = false; + upload.next_index += 1; + upload.received = received; + upload.touched = Instant::now(); + } + Ok(received) + } + Ok(FsTransferReply::Ack { .. }) => { + abandon(state, upload_id, &upload.machine_id).await; + Err(refused( + StatusCode::PAYLOAD_TOO_LARGE, + "That's more than the size the upload began with", + )) + } + Ok(_) => { + abandon(state, upload_id, &upload.machine_id).await; + Err(unexpected()) + } + Err(refusal) => { + abandon(state, upload_id, &upload.machine_id).await; + Err(refusal) + } + } +} + +/// Finishes an upload: the file's path on the machine and its size. Audited as +/// `upload_end` with the path (never the content). +pub(crate) async fn upload_end_as( + state: &AppState, + auth_user: &AuthUser, + run_id: Option<&str>, + upload_id: &str, +) -> Result<(String, u64), Refusal> { + if !auth_user.allows(TokenScope::RunsMessage) { + return Err(refused( + StatusCode::FORBIDDEN, + "This token can't attach files; it needs runs:message", + )); + } + let upload = owned(auth_user, upload_id, run_id)?; + if upload.busy { + return Err(refused(StatusCode::CONFLICT, "A chunk is still on its way")); + } + uploads().remove(upload_id); + let id = upload_id.to_string(); + let result = transfer(state, &upload.machine_id, move |request_id| { + HubToMachine::FsUploadEnd { + request_id, + upload_id: id, + } + }) + .await + .and_then(|reply| match reply { + FsTransferReply::Done { path, size } => Ok((path, size)), + _ => Err(unexpected()), + }); + match &result { + Ok((path, size)) => { + auth_user.audit(&state.db, "upload_end", path, &format!("ok, {size} bytes")) + } + Err((_, reason)) => { + auth_user.audit(&state.db, "upload_end", &upload.run_id, reason); + state + .manager + .fs_upload_abort(&upload.machine_id, upload_id.to_string()) + .await; + } + } + result +} + +#[derive(Deserialize)] +struct BeginBody { + name: String, + size: u64, +} + +#[derive(Deserialize)] +struct ChunkBody { + upload_id: String, + index: u32, + data: String, +} + +#[derive(Deserialize)] +struct EndBody { + upload_id: String, +} + +async fn begin( + State(state): State, + auth_user: AuthUser, + Path(run_id): Path, + Json(body): Json, +) -> Response { + match upload_begin_as(&state, &auth_user, &run_id, &body.name, body.size).await { + Ok(begun) => Json(serde_json::json!({ + "upload_id": begun.upload_id, + "chunk_bytes": begun.chunk_bytes, + })) + .into_response(), + Err(refusal) => refusal.into_response(), + } +} + +async fn chunk( + State(state): State, + auth_user: AuthUser, + Path(run_id): Path, + Json(body): Json, +) -> Response { + match upload_chunk_as( + &state, + &auth_user, + Some(&run_id), + &body.upload_id, + body.index, + body.data, + ) + .await + { + Ok(received) => Json(serde_json::json!({ "received": received })).into_response(), + Err(refusal) => refusal.into_response(), + } +} + +async fn end( + State(state): State, + auth_user: AuthUser, + Path(run_id): Path, + Json(body): Json, +) -> Response { + match upload_end_as(&state, &auth_user, Some(&run_id), &body.upload_id).await { + Ok((path, size)) => Json(serde_json::json!({ "path": path, "size": size })).into_response(), + Err(refusal) => refusal.into_response(), + } +} + +pub(super) fn router() -> Router { + Router::new() + .route("/api/agent-runs/{run_id}/files/begin", post(begin)) + .route( + "/api/agent-runs/{run_id}/files/chunk", + // 1 MiB as base64 in JSON is past half of axum's 2 MB default + post(chunk).layer(DefaultBodyLimit::max(4 * 1024 * 1024)), + ) + .route("/api/agent-runs/{run_id}/files/end", post(end)) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn names_are_bare_and_short() { + assert_eq!(safe_name("IMG_1.png"), "IMG_1.png"); + assert_eq!(safe_name("../../etc/passwd"), "passwd"); + assert_eq!(safe_name("C:\\Users\\me\\shot.jpg"), "shot.jpg"); + assert_eq!(safe_name("a\0b\nc.txt"), "abc.txt"); + for bad in ["", " ", ".", "..", "dir/", "x/..", "\0"] { + assert_eq!(safe_name(bad), "file", "{bad:?}"); + } + let long = format!("{}.mov", "é".repeat(200)); + let short = safe_name(&long); + assert!(short.len() <= NAME_MAX && short.ends_with(".mov") && short.starts_with('é')); + let no_ext = "x".repeat(300); + assert_eq!(safe_name(&no_ext).len(), NAME_MAX); + } + + #[test] + fn files_go_under_the_runs_folder() { + assert_eq!( + attachments_dirs("run-1"), + [ + "~/.offdesk".to_string(), + "~/.offdesk/attachments".to_string(), + "~/.offdesk/attachments/run-1".to_string(), + ] + ); + } + + #[test] + fn only_who_began_an_upload_goes_on() { + let person = |token: Option<&str>, user: &str| AuthUser { + user_id: user.into(), + api_token_name: token.map(String::from), + api_token_id: token.map(String::from), + access: None, + }; + let (a, b, other_user) = ( + person(Some("a"), "u"), + person(Some("b"), "u"), + person(Some("a"), "v"), + ); + let id = uuid::Uuid::new_v4().to_string(); + uploads().insert( + id.clone(), + Upload { + owner: owner(&a), + user_id: "u".into(), + machine_id: "m".into(), + run_id: "run-1".into(), + next_index: 0, + received: 0, + size: 1, + busy: false, + touched: Instant::now(), + }, + ); + assert!(owned(&a, &id, None).is_ok()); + assert!(owned(&a, &id, Some("run-1")).is_ok()); + assert_eq!( + owned(&a, &id, Some("run-2")).unwrap_err().0, + StatusCode::NOT_FOUND + ); + assert_eq!(owned(&b, &id, None).unwrap_err().0, StatusCode::NOT_FOUND); + assert_eq!( + owned(&other_user, &id, None).unwrap_err().0, + StatusCode::NOT_FOUND + ); + // Left idle: forgotten + uploads().get_mut(&id).unwrap().touched = Instant::now() - IDLE; + assert!(owned(&a, &id, None).is_err()); + } +} diff --git a/docs/agent-bridge-protocol.md b/docs/agent-bridge-protocol.md index f5363b34..2c68b861 100644 --- a/docs/agent-bridge-protocol.md +++ b/docs/agent-bridge-protocol.md @@ -4,7 +4,7 @@ A bridge connects an Offdesk hub to a server you choose (your own service, or a one such as Offdesk at offdesk.so). The hub dials out and keeps one WebSocket open; nothing has to reach the hub. Over it the server sees the hub's coding agent runs and, within what the person allowed **on the hub**, answers them, reads their conversations, sends them -messages and starts agents. Terminal output never goes over a bridge. +messages and files, and starts agents. Terminal output never goes over a bridge. `examples/bridge-server` is a small working server. The hub side is `crates/hub/src/bridge.rs`. @@ -93,6 +93,9 @@ shows the error and keeps retrying with backoff. Messages are JSON text frames w { "type": "sessions", "command_id": "…", "days": 7, "limit": 50 } { "type": "session_messages", "command_id": "…", "machine_id": "…", "agent": "claude", "session_id": "…", "after": "…", "limit": 100 } +{ "type": "upload_begin", "command_id": "…", "run_id": "…", "name": "IMG_1.png", "size": 12345 } +{ "type": "upload_chunk", "command_id": "…", "upload_id": "…", "index": 0, "data": "" } +{ "type": "upload_end", "command_id": "…", "upload_id": "…" } { "type": "pong" } ``` @@ -132,6 +135,28 @@ shows the error and keeps retrying with backoff. Messages are JSON text frames w other first. - A node without the `local-sessions-v1` capability gets status 503 for `session_messages` and `start` with `resume`, and is left out of `sessions`. +- **upload_begin**, **upload_chunk** and **upload_end** save a file (an image, a video, + anything up to 100 MB) on the machine a run is on, so its agent can read it. They need + `runs:message`, and the run must be open on a machine the bridge may reach. The file + lands in `~/.offdesk/attachments//` under its name (the last part of `name`, + at most 120 bytes; "file" when nothing is left). A name already there gets a free one + (`IMG_1 copy.png`). Then send a **message** that names the path. + - `upload_begin` answers `{ "ok": true, "upload_id": "…", "chunk_bytes": 1048576 }`. + Status 404 for an unknown run, 409 for an ended one, 413 above 100 MB, 503 when the + machine is offline or its Offdesk is too old to take files. Each upload counts once + toward the hourly limit of answers. + - `upload_chunk` sends the file's next `chunk_bytes` (the last one may be shorter) as + base64, one at a time and in order from 0. It answers `{ "ok": true, "received": + 12345 }`, the bytes saved so far. A chunk out of order gets 400; a chunk that fails + ends the upload, so start again. + - `upload_end` answers `{ "ok": true, "path": "/Users/me/.offdesk/attachments//IMG_1.png", + "size": 12345 }`. The audit records the path and size, never the content. + - Only the bridge that began an upload can go on with it. One nobody touches for 10 + minutes is dropped, and the machine deletes what it got. + - Results are kept for repeats like any command's; a chunk's data never is. The same + goes over HTTP for an API token with `runs:message`: `POST + /api/agent-runs//files/begin` (`{name, size}`), `…/files/chunk` (`{upload_id, + index, data}`) and `…/files/end` (`{upload_id}`), with the same answers less `ok` (a refusal is its status and a line of text). - `cancel` is reserved; this hub answers it with `ok: false`, status 501. Unknown types are ignored.