From ca7976fb46911355f6c4b5c637bb093cf764d6e2 Mon Sep 17 00:00:00 2001 From: Bill Raj-Derouin Date: Wed, 14 Oct 2026 17:39:50 -0700 Subject: [PATCH 1/4] rust(feat): add file attachment tools to the MCP server --- rust/crates/sift_cli/CHANGELOG.md | 5 + .../sift_cli/assets/skills/sift/SKILL.md | 9 +- rust/crates/sift_mcp/src/server/mod.rs | 10 +- .../sift_mcp/src/service/artifacts/mod.rs | 43 +-- .../sift_mcp/src/service/artifacts/test.rs | 10 +- .../sift_mcp/src/service/remote_files/mod.rs | 183 ++++++++++++ .../sift_mcp/src/service/remote_files/test.rs | 256 ++++++++++++++++- .../sift_mcp/src/tool/file_attachments/mod.rs | 221 +++++++++++++++ .../src/tool/file_attachments/test.rs | 262 ++++++++++++++++++ rust/crates/sift_mcp/src/tool/mod.rs | 1 + rust/crates/sift_mcp/src/tool_events.json | 2 + 11 files changed, 965 insertions(+), 37 deletions(-) create mode 100644 rust/crates/sift_mcp/src/tool/file_attachments/mod.rs create mode 100644 rust/crates/sift_mcp/src/tool/file_attachments/test.rs diff --git a/rust/crates/sift_cli/CHANGELOG.md b/rust/crates/sift_cli/CHANGELOG.md index d19ef6979b..70b88bd2be 100644 --- a/rust/crates/sift_cli/CHANGELOG.md +++ b/rust/crates/sift_cli/CHANGELOG.md @@ -7,6 +7,11 @@ This project adheres to [Semantic Versioning](http://semver.org/). ### What's New +- New `list_file_attachments` and `download_file_attachment` tools let agents + find the files attached to runs, assets, annotations and their comments, test + reports, and test steps, and fetch each one through a short-lived download + URL. Agents used to send users to the run page to download these by hand. + ## [v0.9.1] - November 17, 2026 ### What's New diff --git a/rust/crates/sift_cli/assets/skills/sift/SKILL.md b/rust/crates/sift_cli/assets/skills/sift/SKILL.md index 736186ca80..166141fb01 100644 --- a/rust/crates/sift_cli/assets/skills/sift/SKILL.md +++ b/rust/crates/sift_cli/assets/skills/sift/SKILL.md @@ -88,13 +88,20 @@ tool. connectivity check; when it fails, expect every other Sift tool to fail too. - **Discovery:** `list_assets`, `list_runs`, `list_channels`, `list_reports`, `list_report_templates`, `list_rules`, `list_rule_versions`, `list_annotations`, - `list_artifacts`, `list_artifact_versions`, `list_webhooks`. + `list_artifacts`, `list_artifact_versions`, `list_webhooks`, + `list_file_attachments`. - **Artifacts:** `download_artifact` (latest version, or pin `artifact_version_id`), `list_artifact_versions` for one artifact's history, newest first. The artifact tools, including `list_artifacts` and the artifact writes below, are enabled per account by the agents feature flag resolved when the MCP server starts, so they may be absent from the tool list. Enabling them requires an account setting and an MCP restart. +- **File attachments:** `list_file_attachments` lists the files attached to + runs, assets, annotations and their comments, test reports, and test steps; + scope it with `entity_ids`. `download_file_attachment` returns a short-lived signed URL + for one file that you can fetch without Sift credentials. Use these when a + user asks for a file attached to a run or asset, instead of sending them to + the run page to download it. - **Derived channels:** `list_calculated_channels`, `list_calculated_channel_versions`, `list_user_defined_functions`, `list_user_defined_function_versions`. diff --git a/rust/crates/sift_mcp/src/server/mod.rs b/rust/crates/sift_mcp/src/server/mod.rs index cf8cbacb32..95cb3f589a 100644 --- a/rust/crates/sift_mcp/src/server/mod.rs +++ b/rust/crates/sift_mcp/src/server/mod.rs @@ -49,9 +49,9 @@ use crate::service::{ annotations::AnnotationService, artifacts::ArtifactService, assets::AssetService, calculated_channels::CalculatedChannelService, channels::ChannelService, data::DataService, declarative::DeclarativeService, docs::DocsService, ingest::IngestService, ping::PingService, - report_templates::ReportTemplateService, reports::ReportService, - rule_evaluation::RuleEvaluationService, rules::RuleService, runs::RunService, - test_reports::TestReportService, url::UrlService, + remote_files::RemoteFileService, report_templates::ReportTemplateService, + reports::ReportService, rule_evaluation::RuleEvaluationService, rules::RuleService, + runs::RunService, test_reports::TestReportService, url::UrlService, user_defined_functions::UserDefinedFunctionService, users::UserService, webhooks::WebhookService, }; @@ -71,6 +71,7 @@ pub struct SiftMcpServer { pub url_service: UrlService, pub ingest_service: IngestService, pub ping_service: PingService, + pub remote_file_service: RemoteFileService, pub run_service: RunService, pub report_service: ReportService, pub report_template_service: ReportTemplateService, @@ -235,6 +236,7 @@ impl SiftMcpServer { tool_router.merge(Self::rule_evaluation_router()); tool_router.merge(Self::annotations_router()); tool_router.merge(Self::artifacts_router()); + tool_router.merge(Self::file_attachments_router()); tool_router.merge(Self::test_reports_router()); tool_router.merge(Self::docs_router()); tool_router.merge(Self::user_defined_functions_router()); @@ -296,6 +298,7 @@ impl SiftMcpServer { let url_service = UrlService::new(app_uri); let ingest_service = IngestService::new(channel.clone()); let ping_service = PingService::new(channel.clone(), retry_policy.clone()); + let remote_file_service = RemoteFileService::new(channel.clone(), retry_policy.clone()); let run_service = RunService::new(channel.clone(), retry_policy.clone()); let report_service = ReportService::new(channel.clone(), retry_policy.clone()); let report_template_service = @@ -321,6 +324,7 @@ impl SiftMcpServer { url_service, ingest_service, ping_service, + remote_file_service, run_service, report_service, report_template_service, diff --git a/rust/crates/sift_mcp/src/service/artifacts/mod.rs b/rust/crates/sift_mcp/src/service/artifacts/mod.rs index a68ac4a4e2..f660833411 100644 --- a/rust/crates/sift_mcp/src/service/artifacts/mod.rs +++ b/rust/crates/sift_mcp/src/service/artifacts/mod.rs @@ -1,4 +1,4 @@ -use anyhow::{Context, Result, anyhow, bail}; +use anyhow::{Context, Result, anyhow}; use sift_rs::{ SiftChannel, artifacts::v1::{ @@ -9,16 +9,13 @@ use sift_rs::{ artifact_service_client::ArtifactServiceClient, }, metadata::v1::MetadataValue, - remote_files::v1::{ - GetRemoteFileDownloadUrlRequest, remote_file_service_client::RemoteFileServiceClient, - }, }; use std::path::Path; use crate::policy::{RetryPolicy, once, with_retry}; use crate::service::common; -use crate::service::remote_files::RemoteFileUploader; +use crate::service::remote_files::{RemoteFileService, RemoteFileUploader}; #[cfg(test)] mod test; @@ -92,6 +89,7 @@ impl UpdatePath { pub struct ArtifactService { channel: SiftChannel, policy: RetryPolicy, + remote_files: RemoteFileService, // Absent only when the server runs without a REST endpoint (some tests); // creating an artifact with a file requires it. uploader: Option, @@ -100,6 +98,7 @@ pub struct ArtifactService { impl ArtifactService { pub fn new(channel: SiftChannel, policy: RetryPolicy) -> Self { Self { + remote_files: RemoteFileService::new(channel.clone(), policy.clone()), channel, policy, uploader: None, @@ -250,7 +249,12 @@ impl ArtifactService { .as_ref() .and_then(|version| version.remote_file_id.clone()); let download_url = match remote_file_id { - Some(remote_file_id) => Some(self.download_url(remote_file_id).await?), + Some(remote_file_id) => Some( + self.remote_files + .download_url(remote_file_id) + .await + .context("failed to get artifact download url")?, + ), None => None, }; Ok(ArtifactView { @@ -407,7 +411,7 @@ impl ArtifactService { .as_ref() .and_then(|version| version.remote_file_id.clone()); let download_url = match remote_file_id { - Some(remote_file_id) => self.download_url(remote_file_id).await.ok(), + Some(remote_file_id) => self.remote_files.download_url(remote_file_id).await.ok(), None => None, }; return Ok(ArtifactView { @@ -451,7 +455,7 @@ impl ArtifactService { .as_ref() .and_then(|version| version.remote_file_id.clone()); let download_url = match remote_file_id { - Some(remote_file_id) => self.download_url(remote_file_id).await.ok(), + Some(remote_file_id) => self.remote_files.download_url(remote_file_id).await.ok(), None => None, }; Ok(ArtifactView { @@ -486,27 +490,4 @@ impl ArtifactService { .artifact .ok_or_else(|| anyhow!("get artifact response missing artifact")) } - - async fn download_url(&self, remote_file_id: String) -> Result { - let channel = self.channel.clone(); - let resp = with_retry(&self.policy, move || { - let channel = channel.clone(); - let remote_file_id = remote_file_id.clone(); - async move { - let mut client = RemoteFileServiceClient::new(channel); - client - .get_remote_file_download_url(GetRemoteFileDownloadUrlRequest { - remote_file_id, - }) - .await - .map(|resp| resp.into_inner()) - } - }) - .await - .context("failed to get artifact download url")?; - if resp.download_url.is_empty() { - bail!("download url response was empty"); - } - Ok(resp.download_url) - } } diff --git a/rust/crates/sift_mcp/src/service/artifacts/test.rs b/rust/crates/sift_mcp/src/service/artifacts/test.rs index 00a256b96d..ca0b2d7556 100644 --- a/rust/crates/sift_mcp/src/service/artifacts/test.rs +++ b/rust/crates/sift_mcp/src/service/artifacts/test.rs @@ -290,7 +290,15 @@ async fn download_artifact_rejects_empty_download_url() { .download_artifact("art-1".into(), None) .await .expect_err("empty url is an error"); - assert!(err.to_string().contains("download url response was empty")); + let message = format!("{err:#}"); + assert!( + message.contains("failed to get artifact download url"), + "{message}" + ); + assert!( + message.contains("download url response was empty"), + "{message}" + ); } #[tokio::test] diff --git a/rust/crates/sift_mcp/src/service/remote_files/mod.rs b/rust/crates/sift_mcp/src/service/remote_files/mod.rs index 5560176876..071cd9407f 100644 --- a/rust/crates/sift_mcp/src/service/remote_files/mod.rs +++ b/rust/crates/sift_mcp/src/service/remote_files/mod.rs @@ -3,8 +3,17 @@ use std::time::Duration; use anyhow::{Context, Result, bail}; use reqwest::header::USER_AGENT; +use sift_rs::{ + SiftChannel, + remote_files::v1::{ + GetRemoteFileDownloadUrlRequest, ListRemoteFilesRequest, ListRemoteFilesResponse, + RemoteFile, remote_file_service_client::RemoteFileServiceClient, + }, +}; use crate::ClientName; +use crate::policy::{RetryPolicy, with_retry}; +use crate::service::common; const UPLOAD_PATH: &str = "/api/v0/remote-files/upload"; /// Client-side cap on one uploaded file. The server allows more, but an @@ -21,6 +30,180 @@ const FALLBACK_MIME: &str = "application/octet-stream"; /// looser than the interactive-call default. const UPLOAD_TIMEOUT: Duration = Duration::from_secs(10 * 60); +/// The entity types users attach files to. Remote files on other entities +/// (artifact versions, chat uploads, canvas code) are not attachments and stay +/// out of every listing. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum AttachmentEntityType { + Run, + Asset, + Annotation, + /// A comment on an annotation. + AnnotationLog, + TestReport, + TestStep, +} + +impl AttachmentEntityType { + pub const ALL: [Self; 6] = [ + Self::Run, + Self::Asset, + Self::Annotation, + Self::AnnotationLog, + Self::TestReport, + Self::TestStep, + ]; + + /// The singular name callers use. + pub fn name(self) -> &'static str { + match self { + Self::Run => "run", + Self::Asset => "asset", + Self::Annotation => "annotation", + Self::AnnotationLog => "annotation_log", + Self::TestReport => "test_report", + Self::TestStep => "test_step", + } + } + + /// The value the `ListRemoteFiles` filter compares `entity_type` against: + /// the backend's table name, not the `ENTITY_TYPE_*` name listed rows carry. + pub fn filter_value(self) -> &'static str { + match self { + Self::Run => "runs", + Self::Asset => "assets", + Self::Annotation => "annotations", + Self::AnnotationLog => "annotation_logs", + Self::TestReport => "test_reports", + Self::TestStep => "test_steps", + } + } +} + +/// ANDs the scope onto the caller's CEL `filter`. With no `entity_type`, the +/// listing is held to every [`AttachmentEntityType`]. +fn attachment_filter( + entity_ids: &[String], + entity_type: Option, + filter: &str, +) -> String { + let mut clauses = Vec::new(); + if !entity_ids.is_empty() { + let ids = entity_ids + .iter() + .map(|id| format!("\"{}\"", common::cel_escape(id.trim()))) + .collect::>() + .join(", "); + clauses.push(format!("entity_id in [{ids}]")); + } + match entity_type { + Some(entity_type) => { + clauses.push(format!("entity_type == \"{}\"", entity_type.filter_value())) + } + // The backend fails `entity_type in [...]` with an internal error, so + // the type set is spelled as `==` alternatives. + None => clauses.push(format!( + "({})", + AttachmentEntityType::ALL + .iter() + .map(|entity_type| format!("entity_type == \"{}\"", entity_type.filter_value())) + .collect::>() + .join(" || ") + )), + } + let filter = filter.trim(); + if !filter.is_empty() { + clauses.push(format!("({filter})")); + } + clauses.join(" && ") +} + +/// Reads remote files over gRPC: the files attached to runs, assets, and other +/// entities, and the bytes behind artifact versions. +#[derive(Clone)] +pub struct RemoteFileService { + channel: SiftChannel, + policy: RetryPolicy, +} + +impl RemoteFileService { + pub fn new(channel: SiftChannel, policy: RetryPolicy) -> Self { + Self { channel, policy } + } + + /// Lists the attachments matching the scope and the caller's CEL `filter`, + /// held to [`AttachmentEntityType`] even when no type is given. + /// + /// Makes one request only. The backend's page tokens do not advance past + /// the first page, so following one returns the same rows again. A page can + /// also come back short, or empty, with a token when the caller can't view + /// some of its files, so `has_more` comes from the token, not the row count. + pub async fn list_attachments( + &self, + entity_ids: Vec, + entity_type: Option, + filter: String, + limit: Option, + ) -> Result> { + let (page_size, record_limit) = common::paging(limit); + let filter = attachment_filter(&entity_ids, entity_type, &filter); + + let channel = self.channel.clone(); + let resp = with_retry(&self.policy, move || { + let channel = channel.clone(); + let filter = filter.clone(); + async move { + let mut client = RemoteFileServiceClient::new(channel); + client + .list_remote_files(ListRemoteFilesRequest { + page_size, + filter, + ..Default::default() + }) + .await + .map(|resp| resp.into_inner()) + } + }) + .await + .context("failed to query file attachments")?; + + let ListRemoteFilesResponse { + mut remote_files, + next_page_token, + } = resp; + let has_more = remote_files.len() > record_limit || !next_page_token.is_empty(); + remote_files.truncate(record_limit); + Ok(common::Page { + items: remote_files, + has_more, + }) + } + + /// Mints a short-lived signed URL for one remote file's bytes. + pub async fn download_url(&self, remote_file_id: String) -> Result { + let channel = self.channel.clone(); + let resp = with_retry(&self.policy, move || { + let channel = channel.clone(); + let remote_file_id = remote_file_id.clone(); + async move { + let mut client = RemoteFileServiceClient::new(channel); + client + .get_remote_file_download_url(GetRemoteFileDownloadUrlRequest { + remote_file_id, + }) + .await + .map(|resp| resp.into_inner()) + } + }) + .await + .context("failed to get remote file download url")?; + if resp.download_url.is_empty() { + bail!("download url response was empty"); + } + Ok(resp.download_url) + } +} + /// REST endpoint and credential for calls the gRPC surface does not offer. /// Today that is one thing: the multipart remote-file upload that gives an /// artifact version its bytes. diff --git a/rust/crates/sift_mcp/src/service/remote_files/test.rs b/rust/crates/sift_mcp/src/service/remote_files/test.rs index 043bad1cc0..eb7ef28f2a 100644 --- a/rust/crates/sift_mcp/src/service/remote_files/test.rs +++ b/rust/crates/sift_mcp/src/service/remote_files/test.rs @@ -1,9 +1,263 @@ use std::io::Write; +use sift_rs::remote_files::v1::{ + GetRemoteFileDownloadUrlResponse, ListRemoteFilesResponse, RemoteFile, + remote_file_service_server::RemoteFileServiceServer, +}; +use sift_test_util::{ + grpc::memory_sift_channel, mock::remote_files::v1::MockRemoteFileServiceImpl, +}; use tempdir::TempDir; +use tokio::task::JoinHandle; +use tonic::{Code, Response, Status, transport::Server}; -use super::{RemoteFileUploader, RestConfig, mime_type_for}; +use super::{ + AttachmentEntityType, RemoteFileService, RemoteFileUploader, RestConfig, attachment_filter, + mime_type_for, +}; use crate::client_event::start_http_server; +use crate::policy::RetryPolicy; + +async fn service_with_mock(mock: MockRemoteFileServiceImpl) -> (RemoteFileService, JoinHandle<()>) { + let (client, server) = tokio::io::duplex(1024); + let channel = memory_sift_channel(client).await; + + let handle = tokio::spawn(async move { + Server::builder() + .add_service(RemoteFileServiceServer::new(mock)) + .serve_with_incoming(tokio_stream::once(Ok::<_, std::io::Error>(server))) + .await + .unwrap(); + }); + + ( + RemoteFileService::new(channel, RetryPolicy::default()), + handle, + ) +} + +fn remote_file(remote_file_id: &str) -> RemoteFile { + RemoteFile { + remote_file_id: remote_file_id.into(), + entity_id: "run-1".into(), + file_name: format!("{remote_file_id}.csv"), + ..Default::default() + } +} + +fn ids(page: &crate::service::common::Page) -> Vec<&str> { + page.items + .iter() + .map(|file| file.remote_file_id.as_str()) + .collect() +} + +const ATTACHMENT_TYPES: &str = "(entity_type == \"runs\" || entity_type == \"assets\" || \ + entity_type == \"annotations\" || entity_type == \"annotation_logs\" || \ + entity_type == \"test_reports\" || entity_type == \"test_steps\")"; + +#[test] +fn unscoped_filter_holds_the_listing_to_attachment_types() { + assert_eq!(attachment_filter(&[], None, ""), ATTACHMENT_TYPES); + assert_eq!(attachment_filter(&[], None, " "), ATTACHMENT_TYPES); +} + +#[test] +fn filter_ands_ids_type_and_the_callers_expression() { + let ids = vec!["run-1".to_string(), " run-2 ".to_string()]; + assert_eq!( + attachment_filter( + &ids, + Some(AttachmentEntityType::Run), + "file_name.matches(\"(?i)log\") || file_name == \"a.csv\"" + ), + "entity_id in [\"run-1\", \"run-2\"] && entity_type == \"runs\" && \ + (file_name.matches(\"(?i)log\") || file_name == \"a.csv\")" + ); +} + +#[test] +fn filter_escapes_quotes_in_ids() { + let ids = vec!["a\"b".to_string()]; + assert_eq!( + attachment_filter(&ids, Some(AttachmentEntityType::AnnotationLog), ""), + "entity_id in [\"a\\\"b\"] && entity_type == \"annotation_logs\"" + ); +} + +#[test] +fn every_attachment_type_has_a_distinct_name_and_filter_value() { + let names: std::collections::HashSet<_> = AttachmentEntityType::ALL + .map(AttachmentEntityType::name) + .into(); + let values: std::collections::HashSet<_> = AttachmentEntityType::ALL + .map(AttachmentEntityType::filter_value) + .into(); + assert_eq!(names.len(), AttachmentEntityType::ALL.len()); + assert_eq!(values.len(), AttachmentEntityType::ALL.len()); +} + +#[tokio::test] +async fn list_attachments_sends_the_scoped_filter_and_limit() { + let mut mock = MockRemoteFileServiceImpl::new(); + mock.expect_list_remote_files() + .withf(|req| { + let req = req.get_ref(); + req.filter == "entity_id in [\"run-1\"] && entity_type == \"runs\"" + && req.page_size == 50 + && req.page_token.is_empty() + }) + .times(1) + .returning(|_| { + Ok(Response::new(ListRemoteFilesResponse { + remote_files: vec![remote_file("rf-1")], + next_page_token: String::new(), + })) + }); + + let (service, _h) = service_with_mock(mock).await; + let page = service + .list_attachments( + vec!["run-1".into()], + Some(AttachmentEntityType::Run), + String::new(), + None, + ) + .await + .expect("list"); + assert_eq!(ids(&page), ["rf-1"]); + assert!(!page.has_more); +} + +#[tokio::test] +async fn list_attachments_reads_has_more_from_the_token_without_following_it() { + let mut mock = MockRemoteFileServiceImpl::new(); + mock.expect_list_remote_files() + .withf(|req| req.get_ref().page_size == 5) + .times(1) + .returning(|_| { + Ok(Response::new(ListRemoteFilesResponse { + remote_files: vec![remote_file("rf-1"), remote_file("rf-2")], + next_page_token: "next".into(), + })) + }); + + let (service, _h) = service_with_mock(mock).await; + let page = service + .list_attachments(Vec::new(), None, String::new(), Some(5)) + .await + .expect("list"); + assert_eq!(ids(&page), ["rf-1", "rf-2"]); + assert!(page.has_more); +} + +#[tokio::test] +async fn list_attachments_reports_more_behind_an_empty_page() { + // The backend drops files the caller can't view after paging, so a page + // can be empty and still carry a token. + let mut mock = MockRemoteFileServiceImpl::new(); + mock.expect_list_remote_files().times(1).returning(|_| { + Ok(Response::new(ListRemoteFilesResponse { + remote_files: Vec::new(), + next_page_token: "next".into(), + })) + }); + + let (service, _h) = service_with_mock(mock).await; + let page = service + .list_attachments(Vec::new(), None, String::new(), None) + .await + .expect("list"); + assert!(page.items.is_empty()); + assert!(page.has_more); +} + +#[tokio::test] +async fn list_attachments_truncates_to_limit() { + let mut mock = MockRemoteFileServiceImpl::new(); + mock.expect_list_remote_files().returning(|_| { + Ok(Response::new(ListRemoteFilesResponse { + remote_files: vec![ + remote_file("rf-1"), + remote_file("rf-2"), + remote_file("rf-3"), + ], + next_page_token: String::new(), + })) + }); + + let (service, _h) = service_with_mock(mock).await; + let page = service + .list_attachments(Vec::new(), None, String::new(), Some(2)) + .await + .expect("list"); + assert_eq!(ids(&page), ["rf-1", "rf-2"]); + assert!(page.has_more); +} + +#[tokio::test] +async fn list_attachments_propagates_invalid_argument() { + let mut mock = MockRemoteFileServiceImpl::new(); + mock.expect_list_remote_files() + .returning(|_| Err(Status::invalid_argument("bad filter"))); + + let (service, _h) = service_with_mock(mock).await; + let err = service + .list_attachments(Vec::new(), None, "file_name ==".into(), None) + .await + .expect_err("expected error"); + let status = err.downcast_ref::().expect("status"); + assert_eq!(status.code(), Code::InvalidArgument); +} + +#[tokio::test] +async fn download_url_returns_the_signed_url() { + let mut mock = MockRemoteFileServiceImpl::new(); + mock.expect_get_remote_file_download_url() + .withf(|req| req.get_ref().remote_file_id == "rf-1") + .times(1) + .returning(|_| { + Ok(Response::new(GetRemoteFileDownloadUrlResponse { + download_url: "https://files.test.local/rf-1?sig=abc".into(), + })) + }); + + let (service, _h) = service_with_mock(mock).await; + let url = service.download_url("rf-1".into()).await.expect("url"); + assert_eq!(url, "https://files.test.local/rf-1?sig=abc"); +} + +#[tokio::test] +async fn download_url_rejects_an_empty_url() { + let mut mock = MockRemoteFileServiceImpl::new(); + mock.expect_get_remote_file_download_url().returning(|_| { + Ok(Response::new(GetRemoteFileDownloadUrlResponse { + download_url: String::new(), + })) + }); + + let (service, _h) = service_with_mock(mock).await; + let err = service + .download_url("rf-1".into()) + .await + .expect_err("empty url is an error"); + assert!(err.to_string().contains("download url response was empty")); +} + +#[tokio::test] +async fn download_url_propagates_not_found() { + let mut mock = MockRemoteFileServiceImpl::new(); + mock.expect_get_remote_file_download_url() + .returning(|_| Err(Status::not_found("remote file not found"))); + + let (service, _h) = service_with_mock(mock).await; + let err = service + .download_url("missing".into()) + .await + .expect_err("expected error"); + let status = err.downcast_ref::().expect("status"); + assert_eq!(status.code(), Code::NotFound); +} fn write_file(dir: &TempDir, name: &str, contents: &[u8]) -> std::path::PathBuf { let path = dir.path().join(name); diff --git a/rust/crates/sift_mcp/src/tool/file_attachments/mod.rs b/rust/crates/sift_mcp/src/tool/file_attachments/mod.rs new file mode 100644 index 0000000000..42db65237f --- /dev/null +++ b/rust/crates/sift_mcp/src/tool/file_attachments/mod.rs @@ -0,0 +1,221 @@ +use rmcp::{ + ErrorData, + handler::server::wrapper::Parameters, + model::CallToolResult, + schemars::{self, JsonSchema}, + tool, tool_router, +}; +use serde::Deserialize; + +use crate::{ + error::{self, from_anyhow}, + server::SiftMcpServer, + service::remote_files::AttachmentEntityType, + tool::common::{list_body, to_values}, +}; + +#[cfg(test)] +mod test; + +#[derive(Debug, Deserialize, JsonSchema)] +pub struct ListFileAttachmentsParams { + entity_ids: Option>, + entity_type: Option, + filter: String, + limit: Option, + fields: Option>, +} + +#[derive(Debug, Deserialize, JsonSchema)] +pub struct DownloadFileAttachmentParams { + remote_file_id: String, +} + +/// Accepts the singular name, the plural the backend filters on, or the proto +/// name rows carry (`ENTITY_TYPE_RUN`), in any case. +fn parse_entity_type(value: Option) -> Result, ErrorData> { + let Some(value) = value else { + return Ok(None); + }; + let lowered = value.trim().to_ascii_lowercase(); + if lowered.is_empty() { + return Ok(None); + } + let name = lowered.strip_prefix("entity_type_").unwrap_or(&lowered); + AttachmentEntityType::ALL + .into_iter() + .find(|entity_type| name == entity_type.name() || name == entity_type.filter_value()) + .map(Some) + .ok_or_else(|| { + let expected = AttachmentEntityType::ALL + .map(|entity_type| format!("`{}`", entity_type.name())) + .join(", "); + ErrorData::invalid_params( + format!("unknown `entity_type` `{value}`; expected one of {expected}"), + None, + ) + }) +} + +/// An empty array is an error, not "no scope": it usually means an earlier +/// lookup found nothing, and listing every attachment in the organization +/// would answer a different question. +fn parse_entity_ids(entity_ids: Option>) -> Result, ErrorData> { + let Some(entity_ids) = entity_ids else { + return Ok(Vec::new()); + }; + if entity_ids.is_empty() { + return Err(ErrorData::invalid_params( + "`entity_ids` is empty. Resolve at least one run or asset id first, or omit \ + `entity_ids` only when the user wants files across every entity.", + None, + )); + } + if entity_ids.iter().any(|id| id.trim().is_empty()) { + return Err(ErrorData::invalid_params( + "`entity_ids` must not contain an empty id", + None, + )); + } + Ok(entity_ids) +} + +#[tool_router(router = file_attachments_router, vis = "pub(crate)")] +impl SiftMcpServer { + #[tool( + name = "list_file_attachments", + description = " + List the files attached to runs, assets, annotations and their comments, test reports, and test + steps. + + Each row is one file's metadata. Bytes are not returned; call `download_file_attachment` with a + row's `remote_file_id` for a download URL. Artifact files are not attachments and never appear + here; use the artifact tools for those. + + Output: + - `{ \"file_attachments\": [RemoteFile, ...] }`. Each item includes `remote_file_id`, + `entity_id`, `entity_type`, `file_name`, `file_mime_type`, `file_size` (bytes, as a + string), `description`, `metadata_values`, `remote_file_type`, `created_by_user_id`, and + `created_date`. `remote_file_type` is `REMOTE_FILE_TYPE_TELEMETRY` for the source file a + data import read. Rows come back sorted by file name. + - `count`: how many items THIS response carries — read it instead of + counting the array yourself. It is the size of the page you got back, not + how many files match. + - `has_more`: `true` when the service hit `limit` with matches left over, so + this page is not the whole set. Never report `count` as a total while + `has_more` is `true` — raise `limit` or narrow the scope and ask again. `count` can be + below `limit` while `has_more` is `true`, because the page drops files the caller can't view. + + Parameters: + - `entity_ids`: optional ids of the runs, assets, or other entities whose files to list. + Resolve a run or asset by name with `list_runs` or `list_assets` first. Must not be an + empty array; omit it to list across every entity. + - `entity_type`: optional; `run`, `asset`, `annotation`, `annotation_log` (a comment on an + annotation), `test_report`, or `test_step`. Scope by type here, never in `filter`: the + filter takes a different spelling from the `entity_type` rows carry and rejects theirs. + - `filter`: CEL expression ANDed with the scope above. Pass an empty string for none. + Filterable fields are `remote_file_id`, `entity_id`, `file_name`, and `metadata[\"\"]`. + When filtering or searching, use `file_name.matches(\"(?i)flight\")`, not `==`. Use `==` only + for an exact value from a prior result. `contains`/`startsWith`/`endsWith` are case-SENSITIVE: + `contains(\"Flight\")` silently misses `flight_log.csv`. `.` is a regex wildcard, so use + `contains` to match a full literal file name. + - `limit`: max items to return. Start at 50 and only raise it if the result is capped + and you still need more. Values are clamped to `1..=200`; omitting it defaults to 50. + - `fields`: optional array of field names to keep on each item, e.g. + `[\"file_name\"]`. Omit it for the full object. Names match case-insensitively + and ignore underscores and hyphens, so `remote_file_id`, `remoteFileId` and + `remote-file-id` all work. Any name that matched nothing on any returned item + is listed in `unmatched_fields`; an empty page reports none. + + Errors: + - `INVALID_PARAMS` for an unknown `entity_type`, an empty `entity_ids` array or id, or an + invalid `filter`, including an `entity_type` value copied from a row into it. + - `INTERNAL_ERROR` for upstream failures. + ", + annotations( + title = "file_attachments/list_file_attachments", + read_only_hint = true + ) + )] + pub async fn list_file_attachments( + &self, + params: Parameters, + ) -> error::McpResult { + let Parameters(ListFileAttachmentsParams { + entity_ids, + entity_type, + filter, + limit, + fields, + }) = params; + + let entity_ids = parse_entity_ids(entity_ids)?; + let entity_type = parse_entity_type(entity_type)?; + + let page = self + .remote_file_service + .list_attachments(entity_ids, entity_type, filter, limit) + .await + .map_err(from_anyhow)?; + + let file_attachments = to_values(&page.items)?; + Ok( + list_body("file_attachments", file_attachments, fields, page.has_more) + .into_result(None), + ) + } + + #[tool( + name = "download_file_attachment", + description = " + Get a signed download URL for one file from `list_file_attachments`. + + Output: + - `{ \"remote_file_id\": string, \"download_url\": string }`. `download_url` is a short-lived + signed URL that needs no Sift credentials, so any HTTP client can fetch the file from it. + + Parameters: + - `remote_file_id`: required, from a `list_file_attachments` row. + + Errors: + - `INVALID_PARAMS` if `remote_file_id` is empty. + - `RESOURCE_NOT_FOUND` if the file does not exist. + - `INTERNAL_ERROR` for upstream failures, including a stop signal when the caller cannot view + the file. + + Guidance: + - Fetch `download_url` yourself when you need the file's contents. + - When the user wants the file, give them `download_url` and tell them it expires soon. Call + this tool again for a fresh URL rather than reusing an old one. + - For an artifact's file, call `download_artifact` instead. + ", + annotations( + title = "file_attachments/download_file_attachment", + read_only_hint = true + ) + )] + pub async fn download_file_attachment( + &self, + params: Parameters, + ) -> error::McpResult { + let Parameters(DownloadFileAttachmentParams { remote_file_id }) = params; + let remote_file_id = remote_file_id.trim().to_owned(); + if remote_file_id.is_empty() { + return Err(ErrorData::invalid_params( + "`remote_file_id` must not be empty", + None, + )); + } + + let download_url = self + .remote_file_service + .download_url(remote_file_id.clone()) + .await + .map_err(from_anyhow)?; + + Ok(CallToolResult::structured(serde_json::json!({ + "remote_file_id": remote_file_id, + "download_url": download_url, + }))) + } +} diff --git a/rust/crates/sift_mcp/src/tool/file_attachments/test.rs b/rust/crates/sift_mcp/src/tool/file_attachments/test.rs new file mode 100644 index 0000000000..6a2962a54b --- /dev/null +++ b/rust/crates/sift_mcp/src/tool/file_attachments/test.rs @@ -0,0 +1,262 @@ +use rmcp::{handler::server::wrapper::Parameters, model::ErrorCode}; +use serde_json::json; +use sift_rs::remote_files::v1::{ + EntityType, GetRemoteFileDownloadUrlResponse, ListRemoteFilesResponse, RemoteFile, + remote_file_service_server::RemoteFileServiceServer, +}; +use sift_test_util::{ + grpc::memory_sift_channel, mock::remote_files::v1::MockRemoteFileServiceImpl, +}; +use tokio::task::JoinHandle; +use tonic::{Response, Status, transport::Server}; + +use super::{DownloadFileAttachmentParams, ListFileAttachmentsParams, parse_entity_type}; +use crate::{ + server::SiftMcpServer, service::remote_files::AttachmentEntityType, + tool::common::test_support::structured, +}; + +const ATTACHMENT_TYPES: &str = "(entity_type == \"runs\" || entity_type == \"assets\" || \ + entity_type == \"annotations\" || entity_type == \"annotation_logs\" || \ + entity_type == \"test_reports\" || entity_type == \"test_steps\")"; + +async fn server_with_mock(mock: MockRemoteFileServiceImpl) -> (SiftMcpServer, JoinHandle<()>) { + let (client, server) = tokio::io::duplex(1024); + let channel = memory_sift_channel(client).await; + + let handle = tokio::spawn(async move { + Server::builder() + .add_service(RemoteFileServiceServer::new(mock)) + .serve_with_incoming(tokio_stream::once(Ok::<_, std::io::Error>(server))) + .await + .unwrap(); + }); + + ( + SiftMcpServer::new( + channel, + String::from("https://app.test.local"), + false, + false, + ), + handle, + ) +} + +fn list_params( + entity_ids: Option<&[&str]>, + entity_type: Option<&str>, + filter: &str, +) -> Parameters { + Parameters(ListFileAttachmentsParams { + entity_ids: entity_ids.map(|ids| ids.iter().map(|id| (*id).to_string()).collect()), + entity_type: entity_type.map(str::to_string), + filter: filter.into(), + limit: None, + fields: None, + }) +} + +#[test] +fn entity_type_accepts_singular_plural_and_proto_names() { + for value in ["run", "runs", "RUN", " Run ", "ENTITY_TYPE_RUN"] { + assert_eq!( + parse_entity_type(Some(value.into())).unwrap(), + Some(AttachmentEntityType::Run) + ); + } + for value in [ + "annotation_log", + "annotation_logs", + "ENTITY_TYPE_ANNOTATION_LOG", + ] { + assert_eq!( + parse_entity_type(Some(value.into())).unwrap(), + Some(AttachmentEntityType::AnnotationLog) + ); + } + for entity_type in AttachmentEntityType::ALL { + assert_eq!( + parse_entity_type(Some(entity_type.name().into())).unwrap(), + Some(entity_type) + ); + } + for value in [None, Some(String::new()), Some(" ".into())] { + assert_eq!(parse_entity_type(value).unwrap(), None); + } +} + +#[test] +fn entity_type_rejects_non_attachment_types() { + for value in ["artifact_versions", "chat_conversations", "canvas_version"] { + let err = parse_entity_type(Some(value.into())).unwrap_err(); + assert_eq!(err.code, ErrorCode::INVALID_PARAMS); + } +} + +#[tokio::test] +async fn list_file_attachments_sends_the_scoped_filter() { + let mut mock = MockRemoteFileServiceImpl::new(); + mock.expect_list_remote_files() + .withf(|req| { + req.get_ref().filter + == "entity_id in [\"run-1\"] && entity_type == \"runs\" && (file_name.matches(\"(?i)log\"))" + }) + .times(1) + .returning(|_| { + Ok(Response::new(ListRemoteFilesResponse { + remote_files: vec![RemoteFile { + remote_file_id: "rf-1".into(), + entity_id: "run-1".into(), + entity_type: EntityType::Run as i32, + file_name: "flight_log.csv".into(), + file_size: 42, + ..Default::default() + }], + next_page_token: String::new(), + })) + }); + + let (server, _h) = server_with_mock(mock).await; + let result = server + .list_file_attachments(list_params( + Some(&["run-1"]), + Some("run"), + "file_name.matches(\"(?i)log\")", + )) + .await + .expect("list"); + + let body = structured(result); + assert_eq!(body["count"], json!(1)); + assert_eq!(body["has_more"], json!(false)); + let file = &body["file_attachments"][0]; + assert_eq!(file["remoteFileId"], json!("rf-1")); + assert_eq!(file["entityType"], json!("ENTITY_TYPE_RUN")); + assert_eq!(file["fileName"], json!("flight_log.csv")); +} + +#[tokio::test] +async fn list_file_attachments_projects_fields() { + let mut mock = MockRemoteFileServiceImpl::new(); + mock.expect_list_remote_files() + .withf(|req| req.get_ref().filter == ATTACHMENT_TYPES) + .returning(|_| { + Ok(Response::new(ListRemoteFilesResponse { + remote_files: vec![RemoteFile { + remote_file_id: "rf-1".into(), + file_name: "notes.pdf".into(), + ..Default::default() + }], + next_page_token: String::new(), + })) + }); + + let (server, _h) = server_with_mock(mock).await; + let mut params = list_params(None, None, ""); + params.0.fields = Some(vec!["file_name".into()]); + let body = structured(server.list_file_attachments(params).await.expect("list")); + assert_eq!( + body["file_attachments"], + json!([{ "fileName": "notes.pdf" }]) + ); +} + +#[tokio::test] +async fn list_file_attachments_rejects_bad_scope_before_calling_the_service() { + let mut mock = MockRemoteFileServiceImpl::new(); + mock.expect_list_remote_files().never(); + + let (server, _h) = server_with_mock(mock).await; + let err = server + .list_file_attachments(list_params(Some(&["run-1", " "]), None, "")) + .await + .expect_err("empty id"); + assert_eq!(err.code, ErrorCode::INVALID_PARAMS); + + // An empty array must not widen the listing to the whole organization. + let err = server + .list_file_attachments(list_params(Some(&[]), None, "")) + .await + .expect_err("empty entity_ids"); + assert_eq!(err.code, ErrorCode::INVALID_PARAMS); + + let err = server + .list_file_attachments(list_params(None, Some("artifact"), "")) + .await + .expect_err("unknown type"); + assert_eq!(err.code, ErrorCode::INVALID_PARAMS); +} + +#[tokio::test] +async fn list_file_attachments_maps_an_invalid_filter() { + let mut mock = MockRemoteFileServiceImpl::new(); + mock.expect_list_remote_files() + .returning(|_| Err(Status::invalid_argument("bad filter"))); + + let (server, _h) = server_with_mock(mock).await; + let err = server + .list_file_attachments(list_params(None, None, "file_name ==")) + .await + .expect_err("invalid filter"); + assert_eq!(err.code, ErrorCode::INVALID_PARAMS); +} + +#[tokio::test] +async fn download_file_attachment_returns_the_signed_url() { + let mut mock = MockRemoteFileServiceImpl::new(); + mock.expect_get_remote_file_download_url() + .withf(|req| req.get_ref().remote_file_id == "rf-1") + .times(1) + .returning(|_| { + Ok(Response::new(GetRemoteFileDownloadUrlResponse { + download_url: "https://files.test.local/rf-1?sig=abc".into(), + })) + }); + + let (server, _h) = server_with_mock(mock).await; + let result = server + .download_file_attachment(Parameters(DownloadFileAttachmentParams { + remote_file_id: " rf-1 ".into(), + })) + .await + .expect("download"); + assert_eq!( + structured(result), + json!({ + "remote_file_id": "rf-1", + "download_url": "https://files.test.local/rf-1?sig=abc", + }) + ); +} + +#[tokio::test] +async fn download_file_attachment_rejects_an_empty_id() { + let mut mock = MockRemoteFileServiceImpl::new(); + mock.expect_get_remote_file_download_url().never(); + + let (server, _h) = server_with_mock(mock).await; + let err = server + .download_file_attachment(Parameters(DownloadFileAttachmentParams { + remote_file_id: " ".into(), + })) + .await + .expect_err("empty id"); + assert_eq!(err.code, ErrorCode::INVALID_PARAMS); +} + +#[tokio::test] +async fn download_file_attachment_maps_not_found() { + let mut mock = MockRemoteFileServiceImpl::new(); + mock.expect_get_remote_file_download_url() + .returning(|_| Err(Status::not_found("remote file not found"))); + + let (server, _h) = server_with_mock(mock).await; + let err = server + .download_file_attachment(Parameters(DownloadFileAttachmentParams { + remote_file_id: "missing".into(), + })) + .await + .expect_err("not found"); + assert_eq!(err.code, ErrorCode::RESOURCE_NOT_FOUND); +} diff --git a/rust/crates/sift_mcp/src/tool/mod.rs b/rust/crates/sift_mcp/src/tool/mod.rs index fe517047ac..f97455a9da 100644 --- a/rust/crates/sift_mcp/src/tool/mod.rs +++ b/rust/crates/sift_mcp/src/tool/mod.rs @@ -7,6 +7,7 @@ pub mod common; pub mod data; pub mod docs; pub mod explore; +pub mod file_attachments; pub mod ping; pub mod report_templates; pub mod reports; diff --git a/rust/crates/sift_mcp/src/tool_events.json b/rust/crates/sift_mcp/src/tool_events.json index 3e068b80b5..c02aee6320 100644 --- a/rust/crates/sift_mcp/src/tool_events.json +++ b/rust/crates/sift_mcp/src/tool_events.json @@ -17,6 +17,7 @@ "create_test_report": "CLIENT_EVENT_USER_CALLED_MCP_TOOL_CREATE_TEST_REPORT", "create_user_defined_function": "CLIENT_EVENT_USER_CALLED_MCP_TOOL_CREATE_USER_DEFINED_FUNCTION", "download_artifact": "CLIENT_EVENT_USER_CALLED_MCP_TOOL_DOWNLOAD_ARTIFACT", + "download_file_attachment": "CLIENT_EVENT_USER_CALLED_MCP_TOOL_DOWNLOAD_FILE_ATTACHMENT", "explore_url": "CLIENT_EVENT_USER_CALLED_MCP_TOOL_EXPLORE_URL", "get_chart_schema": "CLIENT_EVENT_USER_CALLED_MCP_TOOL_GET_CHART_SCHEMA", "get_data": "CLIENT_EVENT_USER_CALLED_MCP_TOOL_GET_DATA", @@ -27,6 +28,7 @@ "list_calculated_channel_versions": "CLIENT_EVENT_USER_CALLED_MCP_TOOL_LIST_CALCULATED_CHANNEL_VERSIONS", "list_calculated_channels": "CLIENT_EVENT_USER_CALLED_MCP_TOOL_LIST_CALCULATED_CHANNELS", "list_channels": "CLIENT_EVENT_USER_CALLED_MCP_TOOL_LIST_CHANNELS", + "list_file_attachments": "CLIENT_EVENT_USER_CALLED_MCP_TOOL_LIST_FILE_ATTACHMENTS", "list_report_rule_summaries": "CLIENT_EVENT_USER_CALLED_MCP_TOOL_LIST_REPORT_RULE_SUMMARIES", "list_report_templates": "CLIENT_EVENT_USER_CALLED_MCP_TOOL_LIST_REPORT_TEMPLATES", "list_reports": "CLIENT_EVENT_USER_CALLED_MCP_TOOL_LIST_REPORTS", From 5288cc9eed96694b3538f1a764ca37217aa1a71b Mon Sep 17 00:00:00 2001 From: Bill Raj-Derouin Date: Wed, 14 Oct 2026 20:12:21 -0700 Subject: [PATCH 2/4] rust(docs): point agents at linked artifacts from the file attachment skill notes --- rust/crates/sift_cli/assets/skills/sift/SKILL.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/rust/crates/sift_cli/assets/skills/sift/SKILL.md b/rust/crates/sift_cli/assets/skills/sift/SKILL.md index 166141fb01..1204cb7f41 100644 --- a/rust/crates/sift_cli/assets/skills/sift/SKILL.md +++ b/rust/crates/sift_cli/assets/skills/sift/SKILL.md @@ -101,7 +101,10 @@ tool. scope it with `entity_ids`. `download_file_attachment` returns a short-lived signed URL for one file that you can fetch without Sift credentials. Use these when a user asks for a file attached to a run or asset, instead of sending them to - the run page to download it. + the run page to download it. Artifact files never appear there, so when the + user wants everything on a run or asset, also call `list_artifacts` with + `links.exists(l, l.entity_type == "RUN" && l.entity_id == "")` + (`"ASSET"` for an asset). - **Derived channels:** `list_calculated_channels`, `list_calculated_channel_versions`, `list_user_defined_functions`, `list_user_defined_function_versions`. From 0cfc4a0e6d15f8d8f0ab55f1064c38ca12f1afff Mon Sep 17 00:00:00 2001 From: Bill Raj-Derouin Date: Tue, 17 Nov 2026 13:11:29 -0800 Subject: [PATCH 3/4] rust(fix): keep file attachment listings in scope when the filter escapes it --- .../sift_mcp/src/service/remote_files/mod.rs | 42 ++++++++++- .../sift_mcp/src/service/remote_files/test.rs | 74 ++++++++++++++++++- .../src/tool/file_attachments/test.rs | 1 + 3 files changed, 113 insertions(+), 4 deletions(-) diff --git a/rust/crates/sift_mcp/src/service/remote_files/mod.rs b/rust/crates/sift_mcp/src/service/remote_files/mod.rs index 071cd9407f..6519f75de1 100644 --- a/rust/crates/sift_mcp/src/service/remote_files/mod.rs +++ b/rust/crates/sift_mcp/src/service/remote_files/mod.rs @@ -6,8 +6,8 @@ use reqwest::header::USER_AGENT; use sift_rs::{ SiftChannel, remote_files::v1::{ - GetRemoteFileDownloadUrlRequest, ListRemoteFilesRequest, ListRemoteFilesResponse, - RemoteFile, remote_file_service_client::RemoteFileServiceClient, + EntityType, GetRemoteFileDownloadUrlRequest, ListRemoteFilesRequest, + ListRemoteFilesResponse, RemoteFile, remote_file_service_client::RemoteFileServiceClient, }, }; @@ -78,6 +78,40 @@ impl AttachmentEntityType { Self::TestStep => "test_steps", } } + + /// The `entity_type` listed rows carry. + pub fn proto(self) -> EntityType { + match self { + Self::Run => EntityType::Run, + Self::Asset => EntityType::Asset, + Self::Annotation => EntityType::Annotation, + Self::AnnotationLog => EntityType::AnnotationLog, + Self::TestReport => EntityType::TestReport, + Self::TestStep => EntityType::TestStep, + } + } + + fn from_proto(value: i32) -> Option { + Self::ALL + .into_iter() + .find(|entity_type| entity_type.proto() as i32 == value) + } +} + +/// Whether a listed row is inside the scope [`attachment_filter`] sends. The +/// caller's filter is joined in as text, so one that closes the wrapping +/// parenthesis, such as `true) || (true`, widens the server's match past the +/// scope. Checking each row keeps the scope regardless of the filter. +fn in_scope( + file: &RemoteFile, + entity_ids: &[String], + entity_type: Option, +) -> bool { + let Some(file_type) = AttachmentEntityType::from_proto(file.entity_type) else { + return false; + }; + entity_type.is_none_or(|entity_type| entity_type == file_type) + && (entity_ids.is_empty() || entity_ids.iter().any(|id| id.trim() == file.entity_id)) } /// ANDs the scope onto the caller's CEL `filter`. With no `entity_type`, the @@ -132,7 +166,8 @@ impl RemoteFileService { } /// Lists the attachments matching the scope and the caller's CEL `filter`, - /// held to [`AttachmentEntityType`] even when no type is given. + /// held to [`AttachmentEntityType`] even when no type is given. Rows outside + /// the scope are dropped even if the filter let the server return them. /// /// Makes one request only. The backend's page tokens do not advance past /// the first page, so following one returns the same rows again. A page can @@ -171,6 +206,7 @@ impl RemoteFileService { mut remote_files, next_page_token, } = resp; + remote_files.retain(|file| in_scope(file, &entity_ids, entity_type)); let has_more = remote_files.len() > record_limit || !next_page_token.is_empty(); remote_files.truncate(record_limit); Ok(common::Page { diff --git a/rust/crates/sift_mcp/src/service/remote_files/test.rs b/rust/crates/sift_mcp/src/service/remote_files/test.rs index eb7ef28f2a..746574a1eb 100644 --- a/rust/crates/sift_mcp/src/service/remote_files/test.rs +++ b/rust/crates/sift_mcp/src/service/remote_files/test.rs @@ -1,7 +1,7 @@ use std::io::Write; use sift_rs::remote_files::v1::{ - GetRemoteFileDownloadUrlResponse, ListRemoteFilesResponse, RemoteFile, + EntityType, GetRemoteFileDownloadUrlResponse, ListRemoteFilesResponse, RemoteFile, remote_file_service_server::RemoteFileServiceServer, }; use sift_test_util::{ @@ -40,11 +40,20 @@ fn remote_file(remote_file_id: &str) -> RemoteFile { RemoteFile { remote_file_id: remote_file_id.into(), entity_id: "run-1".into(), + entity_type: EntityType::Run as i32, file_name: format!("{remote_file_id}.csv"), ..Default::default() } } +fn remote_file_on(remote_file_id: &str, entity_type: EntityType, entity_id: &str) -> RemoteFile { + RemoteFile { + entity_type: entity_type as i32, + entity_id: entity_id.into(), + ..remote_file(remote_file_id) + } +} + fn ids(page: &crate::service::common::Page) -> Vec<&str> { page.items .iter() @@ -93,8 +102,12 @@ fn every_attachment_type_has_a_distinct_name_and_filter_value() { let values: std::collections::HashSet<_> = AttachmentEntityType::ALL .map(AttachmentEntityType::filter_value) .into(); + let protos: std::collections::HashSet<_> = AttachmentEntityType::ALL + .map(|entity_type| entity_type.proto() as i32) + .into(); assert_eq!(names.len(), AttachmentEntityType::ALL.len()); assert_eq!(values.len(), AttachmentEntityType::ALL.len()); + assert_eq!(protos.len(), AttachmentEntityType::ALL.len()); } #[tokio::test] @@ -195,6 +208,65 @@ async fn list_attachments_truncates_to_limit() { assert!(page.has_more); } +#[tokio::test] +async fn list_attachments_keeps_the_scope_when_the_filter_escapes_it() { + // A filter that closes the wrapping parenthesis ORs past the scope, so + // the server can return rows the scope excludes. + let mut mock = MockRemoteFileServiceImpl::new(); + mock.expect_list_remote_files() + .withf(|req| { + req.get_ref().filter + == "entity_id in [\"run-1\"] && entity_type == \"runs\" && (true) || (true)" + }) + .times(1) + .returning(|_| { + Ok(Response::new(ListRemoteFilesResponse { + remote_files: vec![ + remote_file_on("rf-artifact", EntityType::ArtifactVersion, "run-1"), + remote_file_on("rf-asset", EntityType::Asset, "run-1"), + remote_file_on("rf-other-run", EntityType::Run, "run-2"), + remote_file_on("rf-unspecified", EntityType::Unspecified, "run-1"), + remote_file("rf-1"), + ], + next_page_token: String::new(), + })) + }); + + let (service, _h) = service_with_mock(mock).await; + let page = service + .list_attachments( + vec![" run-1 ".into()], + Some(AttachmentEntityType::Run), + "true) || (true".into(), + None, + ) + .await + .expect("list"); + assert_eq!(ids(&page), ["rf-1"]); + assert!(!page.has_more); +} + +#[tokio::test] +async fn list_attachments_drops_non_attachment_rows_without_a_scope() { + let mut mock = MockRemoteFileServiceImpl::new(); + mock.expect_list_remote_files().times(1).returning(|_| { + Ok(Response::new(ListRemoteFilesResponse { + remote_files: vec![ + remote_file_on("rf-chat", EntityType::ChatConversation, "conv-1"), + remote_file_on("rf-step", EntityType::TestStep, "step-1"), + ], + next_page_token: String::new(), + })) + }); + + let (service, _h) = service_with_mock(mock).await; + let page = service + .list_attachments(Vec::new(), None, "true) || (true".into(), None) + .await + .expect("list"); + assert_eq!(ids(&page), ["rf-step"]); +} + #[tokio::test] async fn list_attachments_propagates_invalid_argument() { let mut mock = MockRemoteFileServiceImpl::new(); diff --git a/rust/crates/sift_mcp/src/tool/file_attachments/test.rs b/rust/crates/sift_mcp/src/tool/file_attachments/test.rs index 6a2962a54b..287f301f8a 100644 --- a/rust/crates/sift_mcp/src/tool/file_attachments/test.rs +++ b/rust/crates/sift_mcp/src/tool/file_attachments/test.rs @@ -145,6 +145,7 @@ async fn list_file_attachments_projects_fields() { Ok(Response::new(ListRemoteFilesResponse { remote_files: vec![RemoteFile { remote_file_id: "rf-1".into(), + entity_type: EntityType::Asset as i32, file_name: "notes.pdf".into(), ..Default::default() }], From 3648b76f38eadd60f8cab51df38a163a32fc1b87 Mon Sep 17 00:00:00 2001 From: Bill Raj-Derouin Date: Wed, 18 Nov 2026 11:33:38 -0800 Subject: [PATCH 4/4] rust(feat): page through file attachment listings and accept order_by ListRemoteFiles page tokens now advance and order_by is honored, so list_file_attachments follows tokens up to the limit and passes order_by through. Backends without that fix answer a later token with rows already returned, so paging stops at the first page with no new row. --- .../sift_mcp/src/service/remote_files/mod.rs | 93 ++++++++++----- .../sift_mcp/src/service/remote_files/test.rs | 110 +++++++++++++++--- .../sift_mcp/src/tool/file_attachments/mod.rs | 14 ++- .../src/tool/file_attachments/test.rs | 1 + 4 files changed, 169 insertions(+), 49 deletions(-) diff --git a/rust/crates/sift_mcp/src/service/remote_files/mod.rs b/rust/crates/sift_mcp/src/service/remote_files/mod.rs index 6519f75de1..889ad913aa 100644 --- a/rust/crates/sift_mcp/src/service/remote_files/mod.rs +++ b/rust/crates/sift_mcp/src/service/remote_files/mod.rs @@ -1,3 +1,4 @@ +use std::collections::HashSet; use std::path::Path; use std::time::Duration; @@ -169,48 +170,82 @@ impl RemoteFileService { /// held to [`AttachmentEntityType`] even when no type is given. Rows outside /// the scope are dropped even if the filter let the server return them. /// - /// Makes one request only. The backend's page tokens do not advance past - /// the first page, so following one returns the same rows again. A page can - /// also come back short, or empty, with a token when the caller can't view - /// some of its files, so `has_more` comes from the token, not the row count. + /// Backends from before the paging fix return rows again for a later page + /// token, so paging stops at the first page that brings no new row. A page + /// can also come back empty with a token when the caller can't view its + /// files, so `has_more` comes from the token, not the row count. pub async fn list_attachments( &self, entity_ids: Vec, entity_type: Option, filter: String, + order_by: Option, limit: Option, ) -> Result> { let (page_size, record_limit) = common::paging(limit); let filter = attachment_filter(&entity_ids, entity_type, &filter); + let order_by = order_by.unwrap_or_default(); - let channel = self.channel.clone(); - let resp = with_retry(&self.policy, move || { - let channel = channel.clone(); + let mut page_token = String::new(); + let mut seen = HashSet::new(); + let mut results = Vec::new(); + let mut has_more = false; + + loop { + let channel = self.channel.clone(); let filter = filter.clone(); - async move { - let mut client = RemoteFileServiceClient::new(channel); - client - .list_remote_files(ListRemoteFilesRequest { - page_size, - filter, - ..Default::default() - }) - .await - .map(|resp| resp.into_inner()) + let order_by = order_by.clone(); + let token = page_token.clone(); + + let resp = with_retry(&self.policy, move || { + let channel = channel.clone(); + let filter = filter.clone(); + let order_by = order_by.clone(); + let token = token.clone(); + async move { + let mut client = RemoteFileServiceClient::new(channel); + client + .list_remote_files(ListRemoteFilesRequest { + page_size, + page_token: token, + filter, + order_by, + ..Default::default() + }) + .await + .map(|resp| resp.into_inner()) + } + }) + .await + .context("failed to query file attachments")?; + + let ListRemoteFilesResponse { + remote_files, + next_page_token, + } = resp; + let mut new_files = remote_files + .into_iter() + .filter(|file| seen.insert(file.remote_file_id.clone())) + .peekable(); + if new_files.peek().is_none() { + has_more = !next_page_token.is_empty(); + break; } - }) - .await - .context("failed to query file attachments")?; - - let ListRemoteFilesResponse { - mut remote_files, - next_page_token, - } = resp; - remote_files.retain(|file| in_scope(file, &entity_ids, entity_type)); - let has_more = remote_files.len() > record_limit || !next_page_token.is_empty(); - remote_files.truncate(record_limit); + results.extend(new_files.filter(|file| in_scope(file, &entity_ids, entity_type))); + + if results.len() >= record_limit { + has_more = results.len() > record_limit || !next_page_token.is_empty(); + break; + } + if next_page_token.is_empty() { + break; + } + page_token = next_page_token; + } + + results.truncate(record_limit); Ok(common::Page { - items: remote_files, + items: results, has_more, }) } diff --git a/rust/crates/sift_mcp/src/service/remote_files/test.rs b/rust/crates/sift_mcp/src/service/remote_files/test.rs index 746574a1eb..5c0b4ccb24 100644 --- a/rust/crates/sift_mcp/src/service/remote_files/test.rs +++ b/rust/crates/sift_mcp/src/service/remote_files/test.rs @@ -111,12 +111,13 @@ fn every_attachment_type_has_a_distinct_name_and_filter_value() { } #[tokio::test] -async fn list_attachments_sends_the_scoped_filter_and_limit() { +async fn list_attachments_sends_the_scoped_filter_order_and_limit() { let mut mock = MockRemoteFileServiceImpl::new(); mock.expect_list_remote_files() .withf(|req| { let req = req.get_ref(); req.filter == "entity_id in [\"run-1\"] && entity_type == \"runs\"" + && req.order_by == "created_date desc" && req.page_size == 50 && req.page_token.is_empty() }) @@ -134,6 +135,7 @@ async fn list_attachments_sends_the_scoped_filter_and_limit() { vec!["run-1".into()], Some(AttachmentEntityType::Run), String::new(), + Some("created_date desc".into()), None, ) .await @@ -142,22 +144,97 @@ async fn list_attachments_sends_the_scoped_filter_and_limit() { assert!(!page.has_more); } +/// Answers each page token with its rows and the next token, and fails the +/// test on a token it was not given. +fn paged_mock( + pages: Vec<(&'static str, Vec, &'static str)>, +) -> MockRemoteFileServiceImpl { + let mut mock = MockRemoteFileServiceImpl::new(); + for (token, files, next) in pages { + mock.expect_list_remote_files() + .withf(move |req| req.get_ref().page_token == token) + .times(1) + .returning(move |_| { + Ok(Response::new(ListRemoteFilesResponse { + remote_files: files.clone(), + next_page_token: next.into(), + })) + }); + } + mock +} + +#[tokio::test] +async fn list_attachments_follows_page_tokens() { + let mock = paged_mock(vec![ + ("", vec![remote_file("rf-1"), remote_file("rf-2")], "t1"), + ("t1", vec![remote_file("rf-3")], ""), + ]); + + let (service, _h) = service_with_mock(mock).await; + let page = service + .list_attachments(Vec::new(), None, String::new(), None, Some(5)) + .await + .expect("list"); + assert_eq!(ids(&page), ["rf-1", "rf-2", "rf-3"]); + assert!(!page.has_more); +} + +#[tokio::test] +async fn list_attachments_reports_more_when_the_limit_falls_mid_page() { + let mock = paged_mock(vec![ + ("", vec![remote_file("rf-1"), remote_file("rf-2")], "t1"), + ("t1", vec![remote_file("rf-3"), remote_file("rf-4")], "t2"), + ]); + + let (service, _h) = service_with_mock(mock).await; + let page = service + .list_attachments(Vec::new(), None, String::new(), None, Some(3)) + .await + .expect("list"); + assert_eq!(ids(&page), ["rf-1", "rf-2", "rf-3"]); + assert!(page.has_more); +} + #[tokio::test] -async fn list_attachments_reads_has_more_from_the_token_without_following_it() { +async fn list_attachments_pages_past_rows_outside_the_scope() { + let mock = paged_mock(vec![ + ( + "", + vec![remote_file_on( + "rf-chat", + EntityType::ChatConversation, + "conv-1", + )], + "t1", + ), + ("t1", vec![remote_file("rf-1")], ""), + ]); + + let (service, _h) = service_with_mock(mock).await; + let page = service + .list_attachments(Vec::new(), None, String::new(), None, None) + .await + .expect("list"); + assert_eq!(ids(&page), ["rf-1"]); + assert!(!page.has_more); +} + +#[tokio::test] +async fn list_attachments_stops_when_a_token_repeats_rows() { + // Backends from before the paging fix answer a later token with rows + // already returned, so following tokens would never end. let mut mock = MockRemoteFileServiceImpl::new(); - mock.expect_list_remote_files() - .withf(|req| req.get_ref().page_size == 5) - .times(1) - .returning(|_| { - Ok(Response::new(ListRemoteFilesResponse { - remote_files: vec![remote_file("rf-1"), remote_file("rf-2")], - next_page_token: "next".into(), - })) - }); + mock.expect_list_remote_files().times(2).returning(|_| { + Ok(Response::new(ListRemoteFilesResponse { + remote_files: vec![remote_file("rf-1"), remote_file("rf-2")], + next_page_token: "t1".into(), + })) + }); let (service, _h) = service_with_mock(mock).await; let page = service - .list_attachments(Vec::new(), None, String::new(), Some(5)) + .list_attachments(Vec::new(), None, String::new(), None, Some(5)) .await .expect("list"); assert_eq!(ids(&page), ["rf-1", "rf-2"]); @@ -178,7 +255,7 @@ async fn list_attachments_reports_more_behind_an_empty_page() { let (service, _h) = service_with_mock(mock).await; let page = service - .list_attachments(Vec::new(), None, String::new(), None) + .list_attachments(Vec::new(), None, String::new(), None, None) .await .expect("list"); assert!(page.items.is_empty()); @@ -201,7 +278,7 @@ async fn list_attachments_truncates_to_limit() { let (service, _h) = service_with_mock(mock).await; let page = service - .list_attachments(Vec::new(), None, String::new(), Some(2)) + .list_attachments(Vec::new(), None, String::new(), None, Some(2)) .await .expect("list"); assert_eq!(ids(&page), ["rf-1", "rf-2"]); @@ -239,6 +316,7 @@ async fn list_attachments_keeps_the_scope_when_the_filter_escapes_it() { Some(AttachmentEntityType::Run), "true) || (true".into(), None, + None, ) .await .expect("list"); @@ -261,7 +339,7 @@ async fn list_attachments_drops_non_attachment_rows_without_a_scope() { let (service, _h) = service_with_mock(mock).await; let page = service - .list_attachments(Vec::new(), None, "true) || (true".into(), None) + .list_attachments(Vec::new(), None, "true) || (true".into(), None, None) .await .expect("list"); assert_eq!(ids(&page), ["rf-step"]); @@ -275,7 +353,7 @@ async fn list_attachments_propagates_invalid_argument() { let (service, _h) = service_with_mock(mock).await; let err = service - .list_attachments(Vec::new(), None, "file_name ==".into(), None) + .list_attachments(Vec::new(), None, "file_name ==".into(), None, None) .await .expect_err("expected error"); let status = err.downcast_ref::().expect("status"); diff --git a/rust/crates/sift_mcp/src/tool/file_attachments/mod.rs b/rust/crates/sift_mcp/src/tool/file_attachments/mod.rs index 42db65237f..df3044c2de 100644 --- a/rust/crates/sift_mcp/src/tool/file_attachments/mod.rs +++ b/rust/crates/sift_mcp/src/tool/file_attachments/mod.rs @@ -22,6 +22,7 @@ pub struct ListFileAttachmentsParams { entity_ids: Option>, entity_type: Option, filter: String, + order_by: Option, limit: Option, fields: Option>, } @@ -97,7 +98,7 @@ impl SiftMcpServer { `entity_id`, `entity_type`, `file_name`, `file_mime_type`, `file_size` (bytes, as a string), `description`, `metadata_values`, `remote_file_type`, `created_by_user_id`, and `created_date`. `remote_file_type` is `REMOTE_FILE_TYPE_TELEMETRY` for the source file a - data import read. Rows come back sorted by file name. + data import read. - `count`: how many items THIS response carries — read it instead of counting the array yourself. It is the size of the page you got back, not how many files match. @@ -119,6 +120,9 @@ impl SiftMcpServer { for an exact value from a prior result. `contains`/`startsWith`/`endsWith` are case-SENSITIVE: `contains(\"Flight\")` silently misses `flight_log.csv`. `.` is a regex wildcard, so use `contains` to match a full literal file name. + - `order_by`: optional comma-separated `FIELD_NAME[ desc]` list. Orderable fields: `file_name`, + `created_date`, `modified_date`. Default sort is `file_name` ascending, with ties broken by + `remote_file_id`. Example: `\"created_date desc,file_name\"`. - `limit`: max items to return. Start at 50 and only raise it if the result is capped and you still need more. Values are clamped to `1..=200`; omitting it defaults to 50. - `fields`: optional array of field names to keep on each item, e.g. @@ -128,8 +132,9 @@ impl SiftMcpServer { is listed in `unmatched_fields`; an empty page reports none. Errors: - - `INVALID_PARAMS` for an unknown `entity_type`, an empty `entity_ids` array or id, or an - invalid `filter`, including an `entity_type` value copied from a row into it. + - `INVALID_PARAMS` for an unknown `entity_type`, an empty `entity_ids` array or id, an + invalid `filter`, including an `entity_type` value copied from a row into it, or an + `order_by` that references an unknown field. - `INTERNAL_ERROR` for upstream failures. ", annotations( @@ -145,6 +150,7 @@ impl SiftMcpServer { entity_ids, entity_type, filter, + order_by, limit, fields, }) = params; @@ -154,7 +160,7 @@ impl SiftMcpServer { let page = self .remote_file_service - .list_attachments(entity_ids, entity_type, filter, limit) + .list_attachments(entity_ids, entity_type, filter, order_by, limit) .await .map_err(from_anyhow)?; diff --git a/rust/crates/sift_mcp/src/tool/file_attachments/test.rs b/rust/crates/sift_mcp/src/tool/file_attachments/test.rs index 287f301f8a..c2e4780469 100644 --- a/rust/crates/sift_mcp/src/tool/file_attachments/test.rs +++ b/rust/crates/sift_mcp/src/tool/file_attachments/test.rs @@ -52,6 +52,7 @@ fn list_params( entity_ids: entity_ids.map(|ids| ids.iter().map(|id| (*id).to_string()).collect()), entity_type: entity_type.map(str::to_string), filter: filter.into(), + order_by: None, limit: None, fields: None, })