Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
feat(ai): add file upload tool (#6687)
teo89cd91b382c1
diff --git a/apps/docs/AI/mcp/tools/index.mdx b/apps/docs/AI/mcp/tools/index.mdxindex 9484838e44..73ef685c32 100644--- a/apps/docs/AI/mcp/tools/index.mdx+++ b/apps/docs/AI/mcp/tools/index.mdx@@ -82,5 +82,6 @@ These pages are generated from Macro's Rust MCP tool registry.- [UpdateCalendarEvent](/AI/mcp/tools/update-calendar-event)- [UpdateReminder](/AI/mcp/tools/update-reminder)- [UpdateThreadLabels](/AI/mcp/tools/update-thread-labels)+- [UploadFile](/AI/mcp/tools/upload-file)- [WebFetch](/AI/mcp/tools/web-fetch)- [WebSearch](/AI/mcp/tools/web-search)diff --git a/apps/docs/AI/mcp/tools/upload-file.mdx b/apps/docs/AI/mcp/tools/upload-file.mdxnew file mode 100644index 0000000000..6652abb104--- /dev/null+++ b/apps/docs/AI/mcp/tools/upload-file.mdx@@ -0,0 +1,16 @@+---+title: UploadFile+description: "Upload an existing file to Macro from base64-encoded bytes, up to 25 MiB decoded. Use for PDFs, images, Office files, and other files; use CreateDocument for generated text or native Macro spreadsheets. Encode actual file bytes programmatically; never invent or transcribe binary content. Returns a document ID after the bytes are uploaded; preview and indexing may finish asynchronously. Does not read local paths or fetch URLs."+---++# UploadFile++Upload an existing file to Macro from base64-encoded bytes, up to 25 MiB decoded. Use for PDFs, images, Office files, and other files; use CreateDocument for generated text or native Macro spreadsheets. Encode actual file bytes programmatically; never invent or transcribe binary content. Returns a document ID after the bytes are uploaded; preview and indexing may finish asynchronously. Does not read local paths or fetch URLs.++## Parameters++| Parameter | Type | Required | Description |+| --- | --- | --- | --- |+| `fileName` | string | Yes | Filename including its extension, for example report.pdf. Do not include a directory path. |+| `contentBase64` | string | Yes | Standard padded base64 of the exact file bytes (maximum 25 MiB decoded). No data URL prefix or whitespace. Prefer constructing this argument programmatically from the file. |+| `projectId` | string | No | Optional destination project (folder) ID. Requires edit access. Omit to upload to the user's top-level files. |diff --git a/apps/docs/config/tool-pages.json b/apps/docs/config/tool-pages.jsonindex 1608061350..ec52dbd3cb 100644--- a/apps/docs/config/tool-pages.json+++ b/apps/docs/config/tool-pages.json@@ -73,6 +73,7 @@"AI/mcp/tools/update-calendar-event","AI/mcp/tools/update-reminder","AI/mcp/tools/update-thread-labels",+ "AI/mcp/tools/upload-file","AI/mcp/tools/web-fetch","AI/mcp/tools/web-search"]diff --git a/apps/docs/docs.json b/apps/docs/docs.jsonindex 5137bc3292..809c658f6e 100644--- a/apps/docs/docs.json+++ b/apps/docs/docs.json@@ -144,6 +144,7 @@"AI/mcp/tools/update-calendar-event","AI/mcp/tools/update-reminder","AI/mcp/tools/update-thread-labels",+ "AI/mcp/tools/upload-file","AI/mcp/tools/web-fetch","AI/mcp/tools/web-search"]diff --git a/apps/web/src/lib/core/component/AI/component/tool/UploadFile.tsx b/apps/web/src/lib/core/component/AI/component/tool/UploadFile.tsxnew file mode 100644index 0000000000..d24e848c37--- /dev/null+++ b/apps/web/src/lib/core/component/AI/component/tool/UploadFile.tsx@@ -0,0 +1,46 @@+import { ItemPreview } from '@core/component/ItemPreview';+import FileArrowUp from '@phosphor-icons/core/regular/file-arrow-up.svg';+import { createSignal, Show, Suspense } from 'solid-js';+import { BaseTool } from './BaseTool';+import { Tool } from './Tool';+import { createToolRenderer } from './ToolRenderer';++export const uploadFileHandler = createToolRenderer({+ name: 'UploadFile',+ render: (ctx) => {+ const [isExpanded, setIsExpanded] = createSignal(false);+ return (+ <BaseTool+ icon={FileArrowUp}+ renderContext={ctx.renderContext}+ type="call"+ response={+ <Show when={isExpanded() && ctx.response?.data}>+ {(result) => (+ <div class="space-y-1">+ <Suspense fallback={<span>{result().fileName}</span>}>+ <ItemPreview id={result().documentId} type="document" />+ </Suspense>+ <div>{result().sizeBytes.toLocaleString()} bytes uploaded</div>+ <div>Preview and indexing may still be processing.</div>+ </div>+ )}+ </Show>+ }+ >+ <div class="flex items-center justify-between gap-2">+ <span class="min-w-0 break-all">+ Upload <span class="text-ink">{ctx.tool.data.fileName}</span>+ </span>+ <Show when={ctx.response}>+ <Tool.ResultToggle+ expanded={isExpanded()}+ onToggle={() => setIsExpanded((value) => !value)}+ status="Uploaded"+ />+ </Show>+ </div>+ </BaseTool>+ );+ },+});diff --git a/apps/web/src/lib/core/component/AI/component/tool/handler.tsx b/apps/web/src/lib/core/component/AI/component/tool/handler.tsxindex 5a368bf33c..75ed9db872 100644--- a/apps/web/src/lib/core/component/AI/component/tool/handler.tsx+++ b/apps/web/src/lib/core/component/AI/component/tool/handler.tsx@@ -100,6 +100,7 @@ import {type ToolRenderContext,} from './ToolRenderer';import { updateThreadLabelsHandler } from './UpdateThreadLabels';+import { uploadFileHandler } from './UploadFile';import { webFetchHandler } from './WebFetch';import { webSearchHandler } from './WebSearch';@@ -144,6 +145,7 @@ const toolHandlers: ToolHandlerMap<RenderContext> = {DisplayResults: displayResultsHandler,ContentSearch: contentSearchHandler,CreateDocument: createDocumentHandler,+ UploadFile: uploadFileHandler,CreateProject: createProjectHandler,CreateReminder: createReminderHandler,CreateTag: createTagHandler,diff --git a/apps/web/src/lib/service-clients/service-cognition/generated/tools/schemas.ts b/apps/web/src/lib/service-clients/service-cognition/generated/tools/schemas.tsindex 9289098f7f..f21ca9cc88 100644--- a/apps/web/src/lib/service-clients/service-cognition/generated/tools/schemas.ts+++ b/apps/web/src/lib/service-clients/service-cognition/generated/tools/schemas.ts@@ -5671,6 +5671,18 @@ export const UpdateThreadLabelsResponse = z.object({summary: z.string(),});+export const UploadFile = z.object({+ fileName: z.string(),+ contentBase64: z.string(),+ projectId: z.union([z.string().uuid(), z.null()]).optional(),+});++export const UploadFileResponse = z.object({+ documentId: z.string(),+ fileName: z.string(),+ sizeBytes: z.number().int().gte(0),+});+export const WebFetch = z.object({ input: z.string() });export const WebFetchResponse = z.object({diff --git a/apps/web/src/lib/service-clients/service-cognition/generated/tools/tool.ts b/apps/web/src/lib/service-clients/service-cognition/generated/tools/tool.tsindex 114c180696..eb10d2ec0a 100644--- a/apps/web/src/lib/service-clients/service-cognition/generated/tools/tool.ts+++ b/apps/web/src/lib/service-clients/service-cognition/generated/tools/tool.ts@@ -234,6 +234,7 @@ type ToolParserMap = {call: types.UpdateThreadLabels;response: types.UpdateThreadLabelsResponse;};+ UploadFile: { call: types.UploadFile; response: types.UploadFileResponse };WebFetch: { call: types.WebFetch; response: types.WebFetchResponse };WebSearch: { call: types.WebSearch; response: types.WebSearchResponse };};@@ -495,6 +496,10 @@ const toolParserMap = {call: schemas.UpdateThreadLabels,response: schemas.UpdateThreadLabelsResponse,},+ UploadFile: {+ call: schemas.UploadFile,+ response: schemas.UploadFileResponse,+ },WebFetch: { call: schemas.WebFetch, response: schemas.WebFetchResponse },WebSearch: { call: schemas.WebSearch, response: schemas.WebSearchResponse },};@@ -734,6 +739,7 @@ type ToolDataMap = {call: types.UpdateThreadLabels;response: types.UpdateThreadLabelsResponse;};+ UploadFile: { call: types.UploadFile; response: types.UploadFileResponse };WebFetch: { call: types.WebFetch; response: types.WebFetchResponse };WebSearch: { call: types.WebSearch; response: types.WebSearchResponse };};diff --git a/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.ts b/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.tsindex 5e76843479..3d84b6fa58 100644--- a/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.ts+++ b/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.ts@@ -6081,6 +6081,40 @@ export interface UpdateThreadLabelsResponse {*/summary: string;}+/**+ * Upload an existing file to Macro from base64-encoded bytes, up to 25 MiB decoded. Use for PDFs, images, Office files, and other files; use CreateDocument for generated text or native Macro spreadsheets. Encode actual file bytes programmatically; never invent or transcribe binary content. Returns a document ID after the bytes are uploaded; preview and indexing may finish asynchronously. Does not read local paths or fetch URLs.+ */+export interface UploadFile {+ /**+ * Filename including its extension, for example report.pdf. Do not include a directory path.+ */+ fileName: string;+ /**+ * Standard padded base64 of the exact file bytes (maximum 25 MiB decoded). No data URL prefix or whitespace. Prefer constructing this argument programmatically from the file.+ */+ contentBase64: string;+ /**+ * Optional destination project (folder) ID. Requires edit access. Omit to upload to the user's top-level files.+ */+ projectId?: string | null;+}+/**+ * Metadata for an uploaded file. Does not echo the file contents.+ */+export interface UploadFileResponse {+ /**+ * ID of the new Macro document.+ */+ documentId: string;+ /**+ * Uploaded filename, including its extension.+ */+ fileName: string;+ /**+ * Number of uploaded bytes.+ */+ sizeBytes: number;+}/*** Fetch the contents of a web page using Claude's built-in web fetch tool.*/diff --git a/crates/documents/Cargo.toml b/crates/documents/Cargo.tomlindex a2bd5d2dbf..3452eb215e 100644--- a/crates/documents/Cargo.toml+++ b/crates/documents/Cargo.toml@@ -182,6 +182,6 @@ macro_event_broker = { path = "../macro_event_broker" }mockall = { workspace = true }rdkafka = { workspace = true }serde_json = { workspace = true }-tokio = { workspace = true, features = ["macros", "rt-multi-thread", "signal"] }+tokio = { workspace = true, features = ["macros", "rt-multi-thread", "signal", "test-util"] }tower = { workspace = true }tracing-subscriber = { workspace = true }diff --git a/crates/documents/src/domain/create.rs b/crates/documents/src/domain/create.rsindex e5760ff4d7..424198f15f 100644--- a/crates/documents/src/domain/create.rs+++ b/crates/documents/src/domain/create.rs@@ -8,6 +8,8 @@#[cfg(test)]mod test;+pub mod upload;+use activity::Attribution;use anyhow::Context;use base64::Engine;diff --git a/crates/documents/src/domain/create/upload.rs b/crates/documents/src/domain/create/upload.rsnew file mode 100644index 0000000000..29279ec99b--- /dev/null+++ b/crates/documents/src/domain/create/upload.rs@@ -0,0 +1,186 @@+//! Creation of files supplied as bytes, using the ordinary upload lifecycle.++use std::str::FromStr;+use std::time::Duration;++use activity::Attribution;+use entity_access::domain::models::{EditAccessLevel, EntityAccessReceipt, EntityType};+use macro_user_id::user_id::MacroUserIdStr;+use model::document::{FileType, FileTypeExt};+use rootcause::compat::anyhow1::IntoAnyhow;+use tracing::Instrument;++use super::{+ CreatedDocument, DocumentCreator, NewDocumentMetadata, RepoDocumentKind, RepoDocumentSubtype,+ file_shas,+};+use crate::domain::models::DocumentError;+use crate::domain::ports::create::{+ DocumentBytesUpload, DocumentBytesUploadPort, DocumentCreationService,+};++#[cfg(test)]+mod test;++/// Maximum decoded size of a file passed inline to an AI tool (25 MiB).+pub const MAX_INLINE_UPLOAD_BYTES: usize = 25 * 1024 * 1024;++const UPLOAD_TIMEOUT: Duration = Duration::from_secs(120);++/// File contents and the verified destination for an inline upload.+pub struct NewFileUpload {+ /// Filename, including its extension, without directory components.+ pub file_name: String,+ /// Original file bytes.+ pub bytes: Vec<u8>,+ /// Edit capability for the destination project; absent for top-level files.+ pub project: Option<EntityAccessReceipt<EditAccessLevel>>,+ /// Actor responsible for the upload on behalf of the owner.+ pub attribution: Attribution,+}++impl<Svc, MarkdownInit, BytesUpload, MentionTracker>+ DocumentCreator<Svc, MarkdownInit, BytesUpload, MentionTracker>+where+ Svc: DocumentCreationService + Clone + 'static,+ BytesUpload: DocumentBytesUploadPort + Clone + 'static,+{+ /// Upload bytes and let the storage event pipeline finalize the content.+ /// In particular, DOCX conversion and Markdown initialization must finish+ /// before those documents can be marked ready.+ /// Once metadata creation starts, the upload or its failure cleanup finishes+ /// even if the caller stops waiting.+ #[tracing::instrument(skip_all, err)]+ pub async fn upload_file(+ &self,+ user_id: MacroUserIdStr<'static>,+ upload: NewFileUpload,+ ) -> Result<CreatedDocument, DocumentError> {+ let NewFileUpload {+ file_name,+ bytes,+ project,+ attribution,+ } = upload;+ if bytes.len() > MAX_INLINE_UPLOAD_BYTES {+ return Err(DocumentError::BadRequest(+ "file exceeds the 25 MiB inline upload limit".to_string(),+ ));+ }+ if file_name.trim().is_empty()+ || file_name == "."+ || file_name == ".."+ || file_name.contains(['/', '\\'])+ || file_name.chars().any(char::is_control)+ {+ return Err(DocumentError::BadRequest(+ "fileName must be a filename without directory components or control characters"+ .to_string(),+ ));+ }++ let normalized_name = file_name.to_ascii_lowercase();+ let (document_name, file_type) = match FileType::split_suffix_match(&normalized_name) {+ Some((name, extension)) => {+ (&file_name[..name.len()], FileType::from_str(extension).ok())+ }+ None => (file_name.as_str(), None),+ };+ if document_name.trim().is_empty() {+ return Err(DocumentError::BadRequest(+ "fileName must include a name before its extension".to_string(),+ ));+ }+ if file_type == Some(FileType::Spreadsheet) {+ return Err(DocumentError::BadRequest("use CreateDocument to create a native Macro spreadsheet; upload an .xlsx or .csv file to preserve an existing workbook".to_string()));+ }+ if file_type == Some(FileType::Md) && std::str::from_utf8(&bytes).is_err() {+ return Err(DocumentError::BadRequest(+ "Markdown files must contain valid UTF-8 text".to_string(),+ ));+ }++ let mut metadata = NewDocumentMetadata::builder(document_name).attribution(attribution);+ if let Some(project) = project {+ if project.entity().entity_type != EntityType::Project+ || project.acting_user_id() != Some(&user_id)+ {+ return Err(DocumentError::Unauthorized);+ }+ let project_id =+ project.entity().entity_id.parse().map_err(|_| {+ DocumentError::BadRequest("project id must be a UUID".to_string())+ })?;+ metadata = metadata.project_id(project_id);+ }++ let hashes = file_shas(&bytes);+ let args = metadata.build().into_repo_args(+ user_id.clone(),+ RepoDocumentKind {+ file_type,+ sha: hashes.hex,+ subtype: RepoDocumentSubtype::Regular,+ team_id: None,+ share_with_team: false,+ },+ );+ let document_service = self.document_service.clone();+ let bytes_uploader = self.bytes_uploader.clone();+ // Own the entire write so dropping the caller cannot interrupt metadata+ // creation before we know its ID, the upload, or failure cleanup.+ tokio::spawn(+ async move {+ let response = document_service+ .create_document(user_id, args, None)+ .await+ .inspect_err(|error| {+ tracing::error!(error=?error, "file upload metadata creation failed");+ })?;+ let created = CreatedDocument::new(response);+ let result = async {+ let presigned_url = created+ .response()+ .document_response+ .presigned_url+ .as_ref()+ .ok_or_else(|| {+ DocumentError::Internal(+ rootcause::report!(+ "document storage did not provide an upload URL"+ )+ .into_anyhow(),+ )+ })?;+ tokio::time::timeout(+ UPLOAD_TIMEOUT,+ bytes_uploader.upload_document_bytes(DocumentBytesUpload {+ presigned_url: presigned_url.clone(),+ content_type: created.response().content_type.clone(),+ base64_sha256: hashes.base64,+ bytes,+ }),+ )+ .await+ .map_err(|_| {+ DocumentError::Internal(+ rootcause::report!("file upload timed out").into_anyhow(),+ )+ })?+ }+ .await;+ if let Err(error) = result {+ tracing::error!(error=?error, document_id=%created.document_id(), "file upload failed; cleaning up document");+ document_service+ .cleanup_created_document(created.document_id())+ .await;+ return Err(error);+ }+ Ok(created)+ }+ .in_current_span(),+ )+ .await+ .map_err(|error| DocumentError::Internal(rootcause::report!(error).into_anyhow()))?+ }+}diff --git a/crates/documents/src/domain/create/upload/test.rs b/crates/documents/src/domain/create/upload/test.rsnew file mode 100644index 0000000000..72e204d8ce--- /dev/null+++ b/crates/documents/src/domain/create/upload/test.rs@@ -0,0 +1,416 @@+use super::*;+use std::sync::{Arc, Mutex};+use tokio::sync::Notify;++use activity::Actor;+use entity_access::domain::models::{BotReceiptScope, Entity, EntityPermission};+use model::document::response::DocumentResponseMetadata;+use models_permissions::share_permission::access_level::AccessLevel;++use crate::domain::{+ content::DocumentContent,+ models::{CreateDocumentRepoArgs, CreateTaskRequest},+ response::{CreateDocumentResponseData, DocumentResponse, DocumentResponseMetadataWithContent},+};++const DOCUMENT_ID: &str = "00000000-0000-0000-0000-000000000123";+const PROJECT_ID: &str = "00000000-0000-0000-0000-000000000456";++fn owner() -> MacroUserIdStr<'static> {+ MacroUserIdStr::try_from("macro|[email protected]".to_string()).unwrap()+}++#[derive(Default)]+struct Gate {+ entered: Notify,+ release: Notify,+}++impl Gate {+ async fn wait(&self) {+ self.entered.notify_one();+ self.release.notified().await;+ }+}++async fn wait_for(notification: &Notify) {+ tokio::time::timeout(Duration::from_secs(5), notification.notified())+ .await+ .expect("operation should make progress");+}++#[derive(Default)]+struct RecordingService {+ creates: Mutex<Vec<CreateDocumentRepoArgs>>,+ cleanups: Mutex<Vec<String>>,+ omit_url: bool,+ create_gate: Option<Arc<Gate>>,+ cleanup_gate: Option<Arc<Gate>>,+ cleanup_finished: Notify,+}++impl DocumentCreationService for RecordingService {+ async fn create_document(+ &self,+ user_id: MacroUserIdStr<'static>,+ args: CreateDocumentRepoArgs,+ _job_id: Option<String>,+ ) -> Result<CreateDocumentResponseData, DocumentError> {+ let file_type = args.file_type.map(|kind| kind.to_string());+ let document_name = args.document_name.clone();+ self.creates.lock().unwrap().push(args);+ if let Some(gate) = &self.create_gate {+ gate.wait().await;+ }+ Ok(CreateDocumentResponseData {+ document_response: DocumentResponse {+ document_metadata: DocumentResponseMetadataWithContent::new(+ DocumentResponseMetadata {+ document_id: DOCUMENT_ID.to_string(),+ document_version_id: 1,+ owner: model_owner::Owner::User(user_id),+ document_name,+ file_type: file_type.clone(),+ sha: None,+ branched_from_id: None,+ branched_from_version_id: None,+ document_family_id: None,+ document_bom: None,+ modification_data: None,+ created_at: None,+ updated_at: None,+ sub_type: None,+ },+ DocumentContent::pending(),+ ),+ presigned_url: (!self.omit_url)+ .then(|| "https://storage.example/upload".to_string()),+ },+ content_type: "application/octet-stream".to_string(),+ file_type,+ })+ }++ async fn handle_task_properties(+ &self,+ _: MacroUserIdStr<'static>,+ _: &str,+ _: &CreateTaskRequest,+ _: &Attribution,+ ) -> Result<(), DocumentError> {+ panic!("file uploads do not create tasks")+ }++ async fn mark_document_uploaded(&self, _: &str) -> Result<(), DocumentError> {+ panic!("the storage event pipeline finalizes uploads")+ }++ async fn set_document_content(&self, _: &str, _: DocumentContent) -> Result<(), DocumentError> {+ panic!("the storage event pipeline finalizes uploads")+ }++ async fn cleanup_created_document(&self, id: &str) {+ if let Some(gate) = &self.cleanup_gate {+ gate.wait().await;+ }+ self.cleanups.lock().unwrap().push(id.to_string());+ self.cleanup_finished.notify_one();+ }+}++#[derive(Default)]+struct RecordingUploader {+ uploads: Mutex<Vec<DocumentBytesUpload>>,+ fail: bool,+ gate: Option<Arc<Gate>>,+ finished: Notify,+}++impl DocumentBytesUploadPort for Arc<RecordingUploader> {+ async fn upload_document_bytes(+ &self,+ upload: DocumentBytesUpload,+ ) -> Result<(), DocumentError> {+ self.uploads.lock().unwrap().push(upload);+ if let Some(gate) = &self.gate {+ gate.wait().await;+ }+ self.finished.notify_one();+ if self.fail {+ return Err(DocumentError::Gone);+ }+ Ok(())+ }+}++fn upload(name: &str, bytes: Vec<u8>) -> NewFileUpload {+ NewFileUpload {+ file_name: name.to_string(),+ bytes,+ project: None,+ attribution: Attribution::delegated(Actor::new_from_bot(bot_id::MACRO_AI_BOT_ID), owner()),+ }+}++fn project_receipt(+ user: MacroUserIdStr<'static>,+ entity_type: EntityType,+) -> EntityAccessReceipt<EditAccessLevel> {+ EntityAccessReceipt::try_new_bot(+ bot_id::MACRO_AI_BOT_ID.into(),+ BotReceiptScope::User { acting_user: user },+ Entity {+ entity_id: PROJECT_ID.to_string(),+ entity_type,+ },+ EntityPermission::AccessLevel {+ access_level: AccessLevel::Edit,+ },+ )+ .unwrap()+}++#[tokio::test]+async fn uploads_exact_bytes_with_checksums_owner_project_and_attribution() {+ let service = Arc::new(RecordingService::default());+ let uploader = Arc::new(RecordingUploader::default());+ let creator = DocumentCreator::new(service.clone(), (), uploader.clone(), ());+ let bytes = vec![0, 255, 128, 13, 10];+ let mut file = upload("Report.PDF", bytes.clone());+ file.project = Some(project_receipt(owner(), EntityType::Project));+ let created = creator.upload_file(owner(), file).await.unwrap();+ assert_eq!(created.document_id(), DOCUMENT_ID);+ assert_eq!(+ created+ .response()+ .document_response+ .document_metadata+ .content,+ DocumentContent::pending()+ );+ let creates = service.creates.lock().unwrap();+ assert_eq!(creates.len(), 1);+ assert_eq!(creates[0].document_name, "Report");+ assert_eq!(creates[0].file_type, Some(FileType::Pdf));+ assert_eq!(creates[0].user_id, owner());+ assert_eq!(creates[0].project_id, Some(PROJECT_ID.parse().unwrap()));+ assert!(creates[0].attribution.is_some());+ assert_eq!(creates[0].sha, file_shas(&bytes).hex);+ let uploads = uploader.uploads.lock().unwrap();+ assert_eq!(uploads.len(), 1);+ assert_eq!(uploads[0].bytes, bytes);+ assert_eq!(uploads[0].base64_sha256, file_shas(&bytes).base64);+ assert_eq!(uploads[0].content_type, "application/octet-stream");+ assert!(service.cleanups.lock().unwrap().is_empty());+}++#[tokio::test]+async fn preserves_unknown_extensions_and_leaves_conversion_to_the_pipeline() {+ for (name, expected_name, expected_type) in [+ ("archive.custom", "archive.custom", None),+ ("README", "README", None),+ ("report.docx", "report", Some(FileType::Docx)),+ ("notes.md", "notes", Some(FileType::Md)),+ ] {+ let service = Arc::new(RecordingService::default());+ let uploader = Arc::new(RecordingUploader::default());+ let creator = DocumentCreator::new(service.clone(), (), uploader.clone(), ());+ creator+ .upload_file(owner(), upload(name, b"contents".to_vec()))+ .await+ .unwrap();+ let creates = service.creates.lock().unwrap();+ assert_eq!(creates[0].document_name, expected_name);+ assert_eq!(creates[0].file_type, expected_type);+ }+}++#[tokio::test]+async fn rejects_invalid_files_before_creating_metadata() {+ let service = Arc::new(RecordingService::default());+ let uploader = Arc::new(RecordingUploader::default());+ let creator = DocumentCreator::new(service.clone(), (), uploader.clone(), ());+ for file in [+ upload("../report.pdf", vec![]),+ upload("C:\\report.pdf", vec![]),+ upload(" ", vec![]),+ upload(".pdf", vec![]),+ upload("bad\0.pdf", vec![]),+ upload("native.spreadsheet", vec![]),+ upload("bad.md", vec![255]),+ upload("large.pdf", vec![0; MAX_INLINE_UPLOAD_BYTES + 1]),+ ] {+ assert!(matches!(+ creator.upload_file(owner(), file).await,+ Err(DocumentError::BadRequest(_))+ ));+ }+ assert!(service.creates.lock().unwrap().is_empty());+ assert!(uploader.uploads.lock().unwrap().is_empty());+}++#[tokio::test]+async fn rejects_receipts_for_another_user_or_entity_type() {+ let service = Arc::new(RecordingService::default());+ let uploader = Arc::new(RecordingUploader::default());+ let creator = DocumentCreator::new(service.clone(), (), uploader.clone(), ());+ for receipt in [+ project_receipt(+ MacroUserIdStr::try_from("macro|[email protected]".to_string()).unwrap(),+ EntityType::Project,+ ),+ project_receipt(owner(), EntityType::Document),+ ] {+ let mut file = upload("report.pdf", vec![]);+ file.project = Some(receipt);+ assert!(matches!(+ creator.upload_file(owner(), file).await,+ Err(DocumentError::Unauthorized)+ ));+ }+ assert!(service.creates.lock().unwrap().is_empty());+ assert!(uploader.uploads.lock().unwrap().is_empty());+}++#[tokio::test]+async fn cleans_up_when_storage_upload_fails_or_url_is_missing() {+ for omit_url in [false, true] {+ let service = Arc::new(RecordingService {+ omit_url,+ ..Default::default()+ });+ let uploader = Arc::new(RecordingUploader {+ fail: true,+ ..Default::default()+ });+ let creator = DocumentCreator::new(service.clone(), (), uploader.clone(), ());+ assert!(+ creator+ .upload_file(owner(), upload("report.pdf", vec![1]))+ .await+ .is_err()+ );+ assert_eq!(*service.cleanups.lock().unwrap(), [DOCUMENT_ID]);+ assert_eq!(+ uploader.uploads.lock().unwrap().len(),+ usize::from(!omit_url)+ );+ }+}++#[tokio::test]+async fn accepts_empty_files_and_the_exact_size_limit() {+ let service = Arc::new(RecordingService::default());+ let uploader = Arc::new(RecordingUploader::default());+ let creator = DocumentCreator::new(service, (), uploader.clone(), ());+ for size in [0, MAX_INLINE_UPLOAD_BYTES] {+ creator+ .upload_file(owner(), upload("file.bin", vec![0; size]))+ .await+ .unwrap();+ }+ assert_eq!(uploader.uploads.lock().unwrap().len(), 2);+}++#[tokio::test]+async fn dropping_the_caller_during_metadata_creation_finishes_the_upload() {+ let gate = Arc::new(Gate::default());+ let service = Arc::new(RecordingService {+ create_gate: Some(gate.clone()),+ ..Default::default()+ });+ let uploader = Arc::new(RecordingUploader::default());+ let creator = DocumentCreator::new(service.clone(), (), uploader.clone(), ());+ let caller = tokio::spawn(async move {+ creator+ .upload_file(owner(), upload("report.pdf", vec![1]))+ .await+ });++ wait_for(&gate.entered).await;+ caller.abort();+ assert!(caller.await.unwrap_err().is_cancelled());+ assert!(uploader.uploads.lock().unwrap().is_empty());+ gate.release.notify_one();++ wait_for(&uploader.finished).await;+ assert_eq!(uploader.uploads.lock().unwrap().len(), 1);+ assert!(service.cleanups.lock().unwrap().is_empty());+}++#[tokio::test]+async fn dropping_the_caller_during_upload_finishes_or_cleans_up() {+ for fail in [false, true] {+ let gate = Arc::new(Gate::default());+ let service = Arc::new(RecordingService::default());+ let uploader = Arc::new(RecordingUploader {+ fail,+ gate: Some(gate.clone()),+ ..Default::default()+ });+ let creator = DocumentCreator::new(service.clone(), (), uploader.clone(), ());+ let caller = tokio::spawn(async move {+ creator+ .upload_file(owner(), upload("report.pdf", vec![1]))+ .await+ });++ wait_for(&gate.entered).await;+ caller.abort();+ assert!(caller.await.unwrap_err().is_cancelled());+ gate.release.notify_one();++ if fail {+ wait_for(&service.cleanup_finished).await;+ assert_eq!(*service.cleanups.lock().unwrap(), [DOCUMENT_ID]);+ } else {+ wait_for(&uploader.finished).await;+ assert!(service.cleanups.lock().unwrap().is_empty());+ }+ }+}++#[tokio::test]+async fn dropping_the_caller_during_cleanup_does_not_interrupt_cleanup() {+ let gate = Arc::new(Gate::default());+ let service = Arc::new(RecordingService {+ cleanup_gate: Some(gate.clone()),+ ..Default::default()+ });+ let uploader = Arc::new(RecordingUploader {+ fail: true,+ ..Default::default()+ });+ let creator = DocumentCreator::new(service.clone(), (), uploader, ());+ let caller = tokio::spawn(async move {+ creator+ .upload_file(owner(), upload("report.pdf", vec![1]))+ .await+ });++ wait_for(&gate.entered).await;+ caller.abort();+ assert!(caller.await.unwrap_err().is_cancelled());+ gate.release.notify_one();++ wait_for(&service.cleanup_finished).await;+ assert_eq!(*service.cleanups.lock().unwrap(), [DOCUMENT_ID]);+}++#[tokio::test(start_paused = true)]+async fn storage_upload_timeout_cleans_up_metadata() {+ let service = Arc::new(RecordingService::default());+ let uploader = Arc::new(RecordingUploader {+ gate: Some(Arc::new(Gate::default())),+ ..Default::default()+ });+ let creator = DocumentCreator::new(service.clone(), (), uploader.clone(), ());+ let error = creator+ .upload_file(owner(), upload("report.pdf", vec![1]))+ .await+ .unwrap_err();++ assert!(error.to_string().contains("file upload timed out"));+ assert_eq!(uploader.uploads.lock().unwrap().len(), 1);+ assert_eq!(*service.cleanups.lock().unwrap(), [DOCUMENT_ID]);+}diff --git a/crates/documents/src/inbound/toolset.rs b/crates/documents/src/inbound/toolset.rsindex a854a1f91c..2e00beec1e 100644--- a/crates/documents/src/inbound/toolset.rs+++ b/crates/documents/src/inbound/toolset.rs@@ -6,6 +6,7 @@ mod read_content;mod read_metadata;mod rename_document;mod spreadsheet;+mod upload_file;#[cfg(test)]mod test;@@ -23,6 +24,7 @@ use crate::{read_metadata::ReadMetadata,rename_document::RenameDocument,spreadsheet::{CalculateSpreadsheet, EditSpreadsheet, ReadSpreadsheet},+ upload_file::UploadFile,},outbound::{document_bytes_upload::ReqwestDocumentBytesUploader,@@ -184,6 +186,7 @@ where.add_tool::<ReadMetadata, DocumentToolContext<DSvc, ESvc, EDSvc>>().add_tool::<ReadContent, DocumentToolContext<DSvc, ESvc, EDSvc>>().add_tool::<CreateDocument, DocumentToolContext<DSvc, ESvc, EDSvc>>()+ .add_tool::<UploadFile, DocumentToolContext<DSvc, ESvc, EDSvc>>().add_tool::<RenameDocument, DocumentToolContext<DSvc, ESvc, EDSvc>>().add_tool::<EditDocument, DocumentToolContext<DSvc, ESvc, EDSvc>>().add_tool::<ReadSpreadsheet, DocumentToolContext<DSvc, ESvc, EDSvc>>()diff --git a/crates/documents/src/inbound/toolset/upload_file.rs b/crates/documents/src/inbound/toolset/upload_file.rsnew file mode 100644index 0000000000..4b5cd13ad1--- /dev/null+++ b/crates/documents/src/inbound/toolset/upload_file.rs@@ -0,0 +1,153 @@+//! UploadFile accepts inline bytes without access to the caller's filesystem.++use ai_toolset::{+ AsyncTool, RequestContext, ServiceContext, ToolAnnotated, ToolAnnotations, ToolCallError,+ ToolResult,+};+use async_trait::async_trait;+use base64::{Engine, engine::general_purpose::STANDARD};+use entity_access::domain::{+ models::{BotAccessScope, EditAccessLevel, EntityType},+ ports::EntityAccessService,+};+use schemars::JsonSchema;+use serde::{Deserialize, Serialize};++use super::DocumentToolContext;+use crate::domain::{+ create::upload::{MAX_INLINE_UPLOAD_BYTES, NewFileUpload},+ models::DocumentError,+ ports::{DocumentService, create::DocumentCreationService, editing::EditingWorkerService},+};++#[cfg(test)]+mod test;++#[derive(Deserialize, JsonSchema)]+#[serde(rename_all = "camelCase")]+#[schemars(+ title = "UploadFile",+ description = "Upload an existing file to Macro from base64-encoded bytes, up to 25 MiB decoded. Use for PDFs, images, Office files, and other files; use CreateDocument for generated text or native Macro spreadsheets. Encode actual file bytes programmatically; never invent or transcribe binary content. Returns a document ID after the bytes are uploaded; preview and indexing may finish asynchronously. Does not read local paths or fetch URLs."+)]+pub struct UploadFile {+ #[schemars(+ description = "Filename including its extension, for example report.pdf. Do not include a directory path."+ )]+ pub file_name: String,+ #[schemars(+ description = "Standard padded base64 of the exact file bytes (maximum 25 MiB decoded). No data URL prefix or whitespace. Prefer constructing this argument programmatically from the file."+ )]+ pub content_base64: String,+ #[serde(default)]+ #[schemars(+ description = "Optional destination project (folder) ID. Requires edit access. Omit to upload to the user's top-level files."+ )]+ pub project_id: Option<uuid::Uuid>,+}++/// Metadata for an uploaded file. Does not echo the file contents.+#[derive(Serialize, JsonSchema)]+#[serde(rename_all = "camelCase")]+pub struct UploadFileResponse {+ /// ID of the new Macro document.+ pub document_id: String,+ /// Uploaded filename, including its extension.+ pub file_name: String,+ /// Number of uploaded bytes.+ pub size_bytes: usize,+}++impl ToolAnnotated for UploadFile {+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::additive("Upload file");+}++fn upload_error(error: DocumentError) -> ToolCallError {+ let description = match &error {+ DocumentError::BadRequest(message) => message.clone(),+ DocumentError::NameTooLong { max } => {+ format!("filename is too long (maximum {max} characters)")+ }+ DocumentError::Unauthorized => {+ "you need edit access to the destination project".to_string()+ }+ _ => "failed to upload the file to Macro".to_string(),+ };+ ToolCallError {+ description,+ internal_error: error.into(),+ }+}++fn decode_content(content: &str) -> ToolResult<Vec<u8>> {+ // Reject oversized encoded input before allocating its decoded buffer.+ const MAX_ENCODED_BYTES: usize = MAX_INLINE_UPLOAD_BYTES.div_ceil(3) * 4;+ if content.len() > MAX_ENCODED_BYTES {+ return Err(upload_error(DocumentError::BadRequest(+ "file exceeds the 25 MiB inline upload limit".to_string(),+ )));+ }+ STANDARD.decode(content).map_err(|error| ToolCallError {+ description:+ "contentBase64 must be valid padded base64 without a data URL prefix or whitespace"+ .to_string(),+ internal_error: error.into(),+ })+}++#[async_trait]+impl<DSvc, ESvc, EDSvc> AsyncTool<DocumentToolContext<DSvc, ESvc, EDSvc>> for UploadFile+where+ DSvc: DocumentService + DocumentCreationService,+ ESvc: EntityAccessService,+ EDSvc: EditingWorkerService,+{+ type Output = UploadFileResponse;++ async fn call(+ &self,+ service_context: ServiceContext<DocumentToolContext<DSvc, ESvc, EDSvc>>,+ request_context: RequestContext,+ ) -> ToolResult<Self::Output> {+ let bytes = decode_content(&self.content_base64)?;+ let size_bytes = bytes.len();+ let project = match self.project_id {+ Some(project_id) => Some(+ service_context+ .entity_access_service+ .generate_bot_entity_access_receipt::<EditAccessLevel>(+ service_context.actor,+ BotAccessScope::user(request_context.user_id.clone()),+ &project_id.to_string(),+ EntityType::Project,+ )+ .await+ .map_err(|error| ToolCallError {+ description:+ "you need edit access to the destination project, or it does not exist"+ .to_string(),+ internal_error: error.into(),+ })?,+ ),+ None => None,+ };+ let created = service_context+ .creator+ .upload_file(+ request_context.user_id.clone(),+ NewFileUpload {+ file_name: self.file_name.clone(),+ bytes,+ project,+ attribution: service_context.attribution(request_context.user_id),+ },+ )+ .await+ .map_err(upload_error)?;++ Ok(UploadFileResponse {+ document_id: created.document_id().to_string(),+ file_name: self.file_name.clone(),+ size_bytes,+ })+ }+}diff --git a/crates/documents/src/inbound/toolset/upload_file/test.rs b/crates/documents/src/inbound/toolset/upload_file/test.rsnew file mode 100644index 0000000000..abaf14fd4f--- /dev/null+++ b/crates/documents/src/inbound/toolset/upload_file/test.rs@@ -0,0 +1,29 @@+use super::*;+use ai_toolset::schema::generate_validated_input_schema;++#[test]+fn upload_schema_is_valid_and_project_is_optional() {+ let schema = generate_validated_input_schema::<UploadFile>().unwrap();+ assert_eq!(schema.name, "UploadFile");+ let tool: UploadFile = serde_json::from_value(serde_json::json!({+ "fileName": "file.bin", "contentBase64": "AP+A"+ }))+ .unwrap();+ assert!(tool.project_id.is_none());+ assert_eq!(decode_content(&tool.content_base64).unwrap(), [0, 255, 128]);+}++#[test]+fn rejects_invalid_or_oversized_base64() {+ for content in ["data:application/pdf;base64,YQ==", "Y Q==", "YQ", "!!!!"] {+ assert!(decode_content(content).is_err());+ }+ assert!(decode_content(&"A".repeat(MAX_INLINE_UPLOAD_BYTES.div_ceil(3) * 4 + 1)).is_err());+ assert_eq!(+ decode_content(&STANDARD.encode(vec![255; MAX_INLINE_UPLOAD_BYTES]))+ .unwrap()+ .len(),+ MAX_INLINE_UPLOAD_BYTES+ );+ assert!(decode_content("").unwrap().is_empty());+}diff --git a/docs/AGENT_GUIDE/ai-chat.md b/docs/AGENT_GUIDE/ai-chat.mdindex e60cb79797..4cecc3a5e7 100644--- a/docs/AGENT_GUIDE/ai-chat.md+++ b/docs/AGENT_GUIDE/ai-chat.md@@ -1,5 +1,19 @@# AI Chat (Agents)+## Uploading files with AI++`UploadFile` accepts a filename and standard padded base64 contents, up to 25 MiB+decoded. An optional project ID places the file in a folder the caller can edit.+Use `CreateDocument` for generated text and native Macro spreadsheets. Agents with+code execution should construct the base64 argument from the original bytes;+the tool cannot access an agent's local path or download a URL.++The tool row displays the filename and, on success, **Uploaded**. Expand it to+open the created document and see the uploaded byte count. Success means the+bytes reached storage; previews, DOCX conversion, Markdown initialization, and+indexing may finish asynchronously. Invalid contents, oversized files, and folder+permission failures should display a failed tool call without a successful result.+## Where chats live- If session creation fails, the session view shows **Unable to start this agent**