[codex-apps] Filter optional file fields by tool schema

codex-rs/codex-mcp/src/codex_apps.rs

@@ -5,6 +5,11 @@
 
 use codex_utils_plugins::mcp_connector::sanitize_name;
 
+mod file_params;
+
+pub use file_params::declared_openai_file_input_param_names;
+pub(crate) use file_params::prepare_openai_file_params_for_model;
+
 pub(crate) fn normalize_codex_apps_tool_title(connector_name: Option<&str>, value: &str) -> String {
     let Some(connector_name) = connector_name
         .map(str::trim)

codex-rs/codex-mcp/src/codex_apps/file_params.rs

@@ -0,0 +1,219 @@
+//! Apps SDK `openai/fileParams` metadata and schema shaping.
+//!
+//! For each declared file argument, this module derives the provided-file fields
+//! accepted by its input schema and records them on `ToolInfo` for execution-time
+//! argument rewriting. It also presents file arguments to the model as local paths.
+//!
+//! See <https://developers.openai.com/apps-sdk/reference#tool-descriptor-parameters>.
+
+use std::collections::HashMap;
+use std::collections::HashSet;
+use std::sync::Arc;
+
+use rmcp::model::Tool;
+use serde_json::Map;
+use serde_json::Value as JsonValue;
+
+use crate::tools::ToolInfo;
+
+const META_OPENAI_FILE_PARAMS: &str = "openai/fileParams";
+
+#[derive(Default)]
+struct OpenAiFileSchemaInfo {
+    accepts_mime_type: bool,
+    accepts_file_name: bool,
+}
+
+pub fn declared_openai_file_input_param_names(
+    meta: Option<&Map<String, JsonValue>>,
+) -> Vec<String> {
+    let Some(meta) = meta else {
+        return Vec::new();
+    };
+
+    meta.get(META_OPENAI_FILE_PARAMS)
+        .and_then(JsonValue::as_array)
+        .into_iter()
+        .flatten()
+        .filter_map(JsonValue::as_str)
+        .filter(|value| !value.is_empty())
+        .map(str::to_string)
+        .collect()
+}
+
+/// Derives execution-time file capabilities from the raw schema, then masks
+/// declared file arguments as local paths for the model.
+pub(crate) fn prepare_openai_file_params_for_model(tool_info: &mut ToolInfo) {
+    let file_params = declared_openai_file_input_param_names(tool_info.tool.meta.as_deref());
+    tool_info.openai_file_input_optional_fields =
+        supported_openai_file_input_optional_fields(&tool_info.tool, &file_params);
+
+    if file_params.is_empty() {
+        return;
+    }
+
+    let mut tool = tool_info.tool.clone();
+    let mut input_schema = JsonValue::Object(tool.input_schema.as_ref().clone());
+    rewrite_input_schema_for_local_file_paths(&mut input_schema, &file_params);
+    if let JsonValue::Object(input_schema) = input_schema {
+        tool.input_schema = Arc::new(input_schema);
+    }
+    tool_info.tool = tool;
+}
+
+fn supported_openai_file_input_optional_fields(
+    tool: &Tool,
+    file_params: &[String],
+) -> HashMap<String, Vec<String>> {
+    let properties = tool
+        .input_schema
+        .get("properties")
+        .and_then(JsonValue::as_object);
+
+    file_params
+        .iter()
+        .map(|field_name| {
+            let optional_fields = properties
+                .and_then(|properties| properties.get(field_name))
+                .map(|schema| {
+                    let schema_info = openai_file_schema_info(schema, tool.input_schema.as_ref());
+                    let mut optional_fields = Vec::new();
+                    if schema_info.accepts_mime_type {
+                        optional_fields.push("mime_type".to_string());
+                    }
+                    if schema_info.accepts_file_name {
+                        optional_fields.push("file_name".to_string());
+                    }
+                    optional_fields
+                })
+                .unwrap_or_default();
+            (field_name.clone(), optional_fields)
+        })
+        .collect()
+}
+
+fn openai_file_schema_info(
+    schema: &JsonValue,
+    root_schema: &Map<String, JsonValue>,
+) -> OpenAiFileSchemaInfo {
+    let mut info = OpenAiFileSchemaInfo::default();
+    let mut pending = vec![schema];
+    let mut visited_refs = HashSet::new();
+
+    while let Some(schema) = pending.pop() {
+        let Some(schema) = schema.as_object() else {
+            continue;
+        };
+
+        if let Some(schema_ref) = schema.get("$ref").and_then(JsonValue::as_str)
+            && visited_refs.insert(schema_ref)
+            && let Some(referenced_schema) = resolve_local_schema_ref(root_schema, schema_ref)
+        {
+            pending.push(referenced_schema);
+        }
+
+        for keyword in ["anyOf", "oneOf", "allOf"] {
+            if let Some(variants) = schema.get(keyword).and_then(JsonValue::as_array) {
+                pending.extend(variants);
+            }
+        }
+
+        if schema.get("type").and_then(JsonValue::as_str) == Some("array")
+            || schema.contains_key("items")
+        {
+            if let Some(items) = schema.get("items") {
+                pending.push(items);
+            }
+            continue;
+        }
+
+        let properties = schema.get("properties").and_then(JsonValue::as_object);
+        let is_object_schema = schema.get("type").and_then(JsonValue::as_str) == Some("object")
+            || properties.is_some()
+            || schema.contains_key("additionalProperties");
+        if !is_object_schema {
+            continue;
+        }
+        let accepts_additional_properties = !matches!(
+            schema.get("additionalProperties"),
+            Some(JsonValue::Bool(false) | JsonValue::Object(_))
+        );
+        info.accepts_mime_type |= accepts_additional_properties
+            || properties.is_some_and(|properties| properties.contains_key("mime_type"));
+        info.accepts_file_name |= accepts_additional_properties
+            || properties.is_some_and(|properties| properties.contains_key("file_name"));
+    }
+
+    info
+}
+
+fn resolve_local_schema_ref<'a>(
+    root_schema: &'a Map<String, JsonValue>,
+    schema_ref: &str,
+) -> Option<&'a JsonValue> {
+    let pointer = schema_ref.strip_prefix("#/")?;
+    let mut segments = pointer.split('/');
+    let first_segment = segments.next()?.replace("~1", "/").replace("~0", "~");
+    let mut referenced_schema = root_schema.get(&first_segment)?;
+
+    for segment in segments {
+        let segment = segment.replace("~1", "/").replace("~0", "~");
+        referenced_schema = match referenced_schema {
+            JsonValue::Object(object) => object.get(&segment)?,
+            JsonValue::Array(array) => array.get(segment.parse::<usize>().ok()?)?,
+            _ => return None,
+        };
+    }
+
+    Some(referenced_schema)
+}
+
+fn rewrite_input_schema_for_local_file_paths(input_schema: &mut JsonValue, file_params: &[String]) {
+    let Some(properties) = input_schema
+        .as_object_mut()
+        .and_then(|schema| schema.get_mut("properties"))
+        .and_then(JsonValue::as_object_mut)
+    else {
+        return;
+    };
+
+    for field_name in file_params {
+        let Some(property_schema) = properties.get_mut(field_name) else {
+            continue;
+        };
+        rewrite_input_property_schema_as_local_file_path(property_schema);
+    }
+}
+
+fn rewrite_input_property_schema_as_local_file_path(schema: &mut JsonValue) {
+    let Some(object) = schema.as_object_mut() else {
+        return;
+    };
+
+    let mut description = object
+        .get("description")
+        .and_then(JsonValue::as_str)
+        .map(str::to_string)
+        .unwrap_or_default();
+    let guidance = "This parameter expects an absolute local file path. If you want to upload a file, provide the absolute path to that file here.";
+    if description.is_empty() {
+        description = guidance.to_string();
+    } else if !description.contains(guidance) {
+        description = format!("{description} {guidance}");
+    }
+
+    let is_array = object.get("type").and_then(JsonValue::as_str) == Some("array")
+        || object.get("items").is_some();
+    object.clear();
+    object.insert("description".to_string(), JsonValue::String(description));
+    if is_array {
+        object.insert("type".to_string(), JsonValue::String("array".to_string()));
+        object.insert("items".to_string(), serde_json::json!({ "type": "string" }));
+    } else {
+        object.insert("type".to_string(), JsonValue::String("string".to_string()));
+    }
+}
+
+#[cfg(test)]
+#[path = "file_params_tests.rs"]
+mod tests;