Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

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.mdx
index 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.mdx
new file mode 100644
index 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.json
index 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.json
index 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.tsx
new file mode 100644
index 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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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.toml
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.md
index 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**