fix(gateway): make invoke result truncation opt-in via filter

Remove default row/byte shaping when filter is omitted so backends
return payloads as-is. Explicit filter still bounds JSON arrays and
plain text with returned/total/truncated metadata.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>

Author: crimsonsunset

crates/mcpmux-gateway/src/services/meta_tools/invoke.rs

@@ -10,12 +10,6 @@ use crate::pool::{format_invoke_permission_denied, format_server_inactive_error}
 use crate::services::tool_discovery::ToolDiscoveryService;
 use mcpmux_core::FeatureType;
 
-/// Default row cap for smart truncation when `filter` is omitted.
-pub const DEFAULT_MAX_ROWS: usize = 50;
-
-/// Default byte cap for smart truncation when `filter` is omitted.
-pub const DEFAULT_MAX_BYTES: usize = 65_536;
-
 /// Object keys that commonly hold large list payloads from backend tools.
 const HEAVY_ARRAY_KEYS: &[&str] = &[
     "items", "data", "results", "rows", "records", "issues", "entries", "values", "list",
@@ -61,16 +55,6 @@ pub fn parse_invoke_filter(value: Option<&Value>) -> Option<InvokeResultFilter>
 }
 
 impl InvokeResultFilter {
-    fn effective_max_rows(&self, use_defaults: bool) -> Option<usize> {
-        self.max_rows
-            .or_else(|| use_defaults.then_some(DEFAULT_MAX_ROWS))
-    }
-
-    fn effective_max_bytes(&self, use_defaults: bool) -> Option<usize> {
-        self.max_bytes
-            .or_else(|| use_defaults.then_some(DEFAULT_MAX_BYTES))
-    }
-
     fn is_summary(&self) -> bool {
         self.format.as_deref() == Some("summary")
     }
@@ -80,14 +64,12 @@ impl InvokeResultFilter {
 pub fn apply_invoke_result_filter(
     content: Vec<Value>,
     structured_content: Option<Value>,
-    filter: Option<&InvokeResultFilter>,
-    use_defaults: bool,
+    filter: &InvokeResultFilter,
 ) -> (Vec<Value>, Option<Value>) {
-    let filter = filter.cloned().unwrap_or_default();
-    let shaped_structured = structured_content.map(|value| shape_json_value(value, &filter, use_defaults));
+    let shaped_structured = structured_content.map(|value| shape_json_value(value, filter));
     let shaped_content = content
         .into_iter()
-        .map(|block| shape_content_block(block, &filter, use_defaults))
+        .map(|block| shape_content_block(block, filter))
         .collect();
     (shaped_content, shaped_structured)
 }
@@ -105,8 +87,8 @@ impl MetaTool for InvokeToolTool {
         "Invoke a backend MCP tool by server_id and tool name. Requires the \
          server to be active (binding or session enable) and the tool to be \
          in the current permission set. Use mcpmux_search_tools and \
-         mcpmux_get_tool_schema before calling. Large list payloads are \
-         truncated by default; pass an optional filter object to control shaping."
+         mcpmux_get_tool_schema before calling. Pass an optional filter object \
+         to bound large payloads; omit filter to return the backend response as-is."
     }
 
     fn input_schema(&self) -> Value {
@@ -129,7 +111,7 @@ impl MetaTool for InvokeToolTool {
                 },
                 "filter": {
                     "type": "object",
-                    "description": "Optional result shaping. When omitted, large arrays are truncated with returned/total/truncated metadata.",
+                    "description": "Optional result shaping (max_rows, max_bytes, fields, format). Omit to return the backend response as-is.",
                     "properties": {
                         "max_rows": {
                             "type": "integer",
@@ -176,7 +158,6 @@ impl MetaTool for InvokeToolTool {
             .to_string();
         let args = call.args.get("args").cloned().unwrap_or_else(|| json!({}));
         let filter = parse_invoke_filter(call.args.get("filter"));
-        let use_defaults = call.args.get("filter").is_none();
 
         let resolved = caller_resolution(&call).await?;
         let space_id = caller_space_id(&call).await?;
@@ -292,12 +273,11 @@ impl MetaTool for InvokeToolTool {
                     return Ok(mcp_result);
                 }
 
-                let (content, structured_content) = apply_invoke_result_filter(
-                    result.content,
-                    result.structured_content,
-                    filter.as_ref(),
-                    use_defaults,
-                );
+                let (content, structured_content) = if let Some(ref filter) = filter {
+                    apply_invoke_result_filter(result.content, result.structured_content, filter)
+                } else {
+                    (result.content, result.structured_content)
+                };
                 let parsed_content: Vec<Content> = content
                     .into_iter()
                     .filter_map(|v| serde_json::from_value(v).ok())
@@ -312,72 +292,69 @@ impl MetaTool for InvokeToolTool {
 }
 
 /// Shape one MCP content block (typically `{ "type": "text", "text": "..." }`).
-fn shape_content_block(block: Value, filter: &InvokeResultFilter, use_defaults: bool) -> Value {
+fn shape_content_block(block: Value, filter: &InvokeResultFilter) -> Value {
     let Some(text) = block.get("text").and_then(|v| v.as_str()) else {
         return block;
     };
 
     if let Ok(parsed) = serde_json::from_str::<Value>(text) {
-        let shaped = shape_json_value(parsed, filter, use_defaults);
+        let shaped = shape_json_value(parsed, filter);
         return json!({
             "type": "text",
             "text": shaped.to_string(),
         });
     }
 
-    let max_bytes = filter.effective_max_bytes(use_defaults);
-    let Some(max_bytes) = max_bytes else {
+    let Some(max_bytes) = filter.max_bytes else {
         return block;
     };
     if text.len() <= max_bytes {
         return block;
     }
 
-    let mut truncated = text[..max_bytes].to_string();
-    truncated.push_str("\n...[truncated]");
+    let envelope = byte_truncation_envelope(text, max_bytes);
     json!({
         "type": "text",
-        "text": truncated,
+        "text": envelope.to_string(),
     })
 }
 
-/// Shape a JSON value, applying smart truncation for large arrays when enabled.
-pub fn shape_json_value(value: Value, filter: &InvokeResultFilter, use_defaults: bool) -> Value {
+/// Shape a JSON value, applying truncation when explicit filter limits are set.
+pub fn shape_json_value(value: Value, filter: &InvokeResultFilter) -> Value {
     match value {
-        Value::Array(items) => shape_array(items, filter, use_defaults, "items"),
-        Value::Object(map) => shape_object(map, filter, use_defaults),
-        other => enforce_byte_limit(other, filter, use_defaults),
+        Value::Array(items) => shape_array(items, filter, "items"),
+        Value::Object(map) => shape_object(map, filter),
+        other => enforce_byte_limit(other, filter),
     }
 }
 
-fn shape_object(map: Map<String, Value>, filter: &InvokeResultFilter, use_defaults: bool) -> Value {
+fn shape_object(map: Map<String, Value>, filter: &InvokeResultFilter) -> Value {
     for key in HEAVY_ARRAY_KEYS {
         if let Some(Value::Array(items)) = map.get(*key).cloned() {
-            if should_truncate(items.len(), filter, use_defaults) {
-                return shape_object_with_truncated_array(map, key, items, filter, use_defaults);
+            if should_truncate(items.len(), filter) {
+                return shape_object_with_truncated_array(map, key, items, filter);
             }
         }
     }
 
     for (key, value) in &map {
         if let Value::Array(items) = value {
-            if should_truncate(items.len(), filter, use_defaults) {
-                return shape_object_with_truncated_array(map.clone(), key, items.clone(), filter, use_defaults);
+            if should_truncate(items.len(), filter) {
+                return shape_object_with_truncated_array(map.clone(), key, items.clone(), filter);
             }
         }
     }
 
-    enforce_byte_limit(Value::Object(map), filter, use_defaults)
+    enforce_byte_limit(Value::Object(map), filter)
 }
 
 fn shape_object_with_truncated_array(
     mut map: Map<String, Value>,
     array_key: &str,
     items: Vec<Value>,
     filter: &InvokeResultFilter,
-    use_defaults: bool,
 ) -> Value {
-    let shaped_array = shape_array(items, filter, use_defaults, array_key);
+    let shaped_array = shape_array(items, filter, array_key);
     if let Value::Object(truncation) = &shaped_array {
         if truncation.get("truncated") == Some(&Value::Bool(true)) {
             for (meta_key, meta_value) in truncation {
@@ -388,25 +365,19 @@ fn shape_object_with_truncated_array(
             if let Some(data) = truncation.get(array_key) {
                 map.insert(array_key.to_string(), data.clone());
             }
-            return enforce_byte_limit(Value::Object(map), filter, use_defaults);
+            return enforce_byte_limit(Value::Object(map), filter);
         }
     }
 
     map.insert(array_key.to_string(), shaped_array);
-    enforce_byte_limit(Value::Object(map), filter, use_defaults)
+    enforce_byte_limit(Value::Object(map), filter)
 }
 
-fn shape_array(
-    items: Vec<Value>,
-    filter: &InvokeResultFilter,
-    use_defaults: bool,
-    data_key: &str,
-) -> Value {
+fn shape_array(items: Vec<Value>, filter: &InvokeResultFilter, data_key: &str) -> Value {
     let total = items.len();
     let filtered_items = apply_fields_filter(items, filter);
-    let max_rows = filter.effective_max_rows(use_defaults);
 
-    let Some(max_rows) = max_rows else {
+    let Some(max_rows) = filter.max_rows else {
         return Value::Array(filtered_items);
     };
 
@@ -455,15 +426,15 @@ fn pick_fields(value: Value, fields: &[String]) -> Value {
     Value::Object(picked)
 }
 
-fn should_truncate(length: usize, filter: &InvokeResultFilter, use_defaults: bool) -> bool {
-    match filter.effective_max_rows(use_defaults) {
+fn should_truncate(length: usize, filter: &InvokeResultFilter) -> bool {
+    match filter.max_rows {
         Some(max_rows) => length > max_rows,
         None => false,
     }
 }
 
-fn enforce_byte_limit(value: Value, filter: &InvokeResultFilter, use_defaults: bool) -> Value {
-    let Some(max_bytes) = filter.effective_max_bytes(use_defaults) else {
+fn enforce_byte_limit(value: Value, filter: &InvokeResultFilter) -> Value {
+    let Some(max_bytes) = filter.max_bytes else {
         return value;
     };
 
@@ -472,8 +443,13 @@ fn enforce_byte_limit(value: Value, filter: &InvokeResultFilter, use_defaults: b
         return value;
     }
 
-    let total_bytes = serialized.len();
-    let mut truncated = serialized;
+    byte_truncation_envelope(&serialized, max_bytes)
+}
+
+/// Build a `{ returned, total, truncated, text }` envelope for byte-capped plain text or JSON.
+fn byte_truncation_envelope(text: &str, max_bytes: usize) -> Value {
+    let total_bytes = text.len();
+    let mut truncated = text.to_string();
     truncated.truncate(max_bytes);
     truncated.push_str("...[truncated]");
     json!({
@@ -498,22 +474,20 @@ mod tests {
     use super::*;
 
     #[test]
-    fn default_truncates_large_top_level_array() {
+    fn no_filter_passes_through_large_array() {
         let items: Vec<Value> = (0..100).map(|i| json!({ "id": i, "name": format!("n{i}") })).collect();
-        let shaped = shape_json_value(Value::Array(items), &InvokeResultFilter::default(), true);
-        assert_eq!(shaped.get("returned"), Some(&json!(50)));
-        assert_eq!(shaped.get("total"), Some(&json!(100)));
-        assert_eq!(shaped.get("truncated"), Some(&json!(true)));
+        let shaped = shape_json_value(Value::Array(items.clone()), &InvokeResultFilter::default());
+        assert_eq!(shaped, Value::Array(items));
     }
 
     #[test]
-    fn explicit_max_rows_overrides_default() {
+    fn explicit_max_rows_truncates() {
         let items: Vec<Value> = (0..20).map(|i| json!({ "id": i })).collect();
         let filter = InvokeResultFilter {
             max_rows: Some(3),
             ..Default::default()
         };
-        let shaped = shape_json_value(Value::Array(items), &filter, false);
+        let shaped = shape_json_value(Value::Array(items), &filter);
         assert_eq!(shaped.get("returned"), Some(&json!(3)));
         assert_eq!(shaped.get("total"), Some(&json!(20)));
         assert_eq!(shaped.get("truncated"), Some(&json!(true)));
@@ -529,9 +503,23 @@ mod tests {
             fields: Some(vec!["id".into(), "name".into()]),
             ..Default::default()
         };
-        let shaped = shape_json_value(Value::Array(items), &filter, false);
+        let shaped = shape_json_value(Value::Array(items), &filter);
         let kept = shaped.as_array().unwrap();
         assert_eq!(kept[0], json!({ "id": 1, "name": "a" }));
         assert_eq!(kept[1], json!({ "id": 2, "name": "b" }));
     }
+
+    #[test]
+    fn plain_text_byte_trunc_includes_metadata() {
+        let text = "x".repeat(100);
+        let filter = InvokeResultFilter {
+            max_bytes: Some(50),
+            ..Default::default()
+        };
+        let block = json!({ "type": "text", "text": text });
+        let shaped = shape_content_block(block, &filter);
+        let parsed: Value = serde_json::from_str(shaped.get("text").unwrap().as_str().unwrap()).unwrap();
+        assert_eq!(parsed.get("truncated"), Some(&json!(true)));
+        assert_eq!(parsed.get("total"), Some(&json!(100)));
+    }
 }

docs/planning/meta-gateway-invoke-qa.md

@@ -129,44 +129,49 @@ What did compact strip?
 
 | Check | Pass | Fail | Notes |
 | ----- | ---- | ---- | ----- |
-| Search empty / no github matches when disabled | ☐ | ☐ | |
-| Meta tool count unchanged across enable/disable | ☐ | ☐ | |
+| Search empty / no github matches when disabled | ☑ | ☐ | `total: 0`, `tools: []` after session disable |
+| Meta tool count unchanged across enable/disable | ☑ | ☐ | 10 `mcpmux_*` before and after |
 
 ---
 
-## 5. Default truncation (Phase B)
+## 5. Pass-through without filter (Phase B)
 
-**Setup:** Enable a heavy server — `posthog-personal`, `firebase-dev`, or GWorkspace clone.
+**Setup:** GWorkspace Personal bound (`taylorwilsdon.google-workspace-mcp-uvx`) or any heavy server in FeatureSet ACL.
 
 **Prompt:**
 
 ```
-Enable [heavy server]. Find a list/analytics tool via search, read schema, invoke WITHOUT filter.
+Find a list tool via search (e.g. GWorkspace list_drive_items), read schema, invoke WITHOUT filter.
 
-Show whether response includes { returned, total, truncated: true } or similar metadata.
-Paste payload size estimate (rough char count is fine).
+Confirm the full backend response is returned with no { returned, total, truncated } metadata.
+Paste rough char count.
 ```
 
 | Check | Pass | Fail | Notes |
 | ----- | ---- | ---- | ----- |
-| Large array auto-truncated | ☐ | ☐ | Default ~50 rows / 64KB |
-| Truncation metadata present | ☐ | ☐ | |
+| Full backend response returned | ☐ | ☐ | |
+| No truncation metadata without filter | ☐ | ☐ | Design: opt-in filter only (May 25) |
 
 ---
 
 ## 6. Explicit filter (Phase B)
 
+**Setup:** Same tool as test 5, or GitHub `list_issues` for JSON row truncation.
+
 **Prompt:**
 
 ```
-Same tool as test 5. Invoke with filter: { "max_rows": 3, "format": "summary" }
+Invoke with filter: { "max_rows": 3, "format": "summary" }
+
+For plain-text tools (GWorkspace), also try filter: { "max_bytes": 4096 }.
 
-Then again with fields projection if the tool returns objects with id/name/title fields.
+Then fields projection if the tool returns JSON objects with id/name/title fields.
 ```
 
 | Check | Pass | Fail | Notes |
 | ----- | ---- | ---- | ----- |
-| `max_rows: 3` honored | ☐ | ☐ | |
+| `max_rows: 3` honored (JSON tools) | ☐ | ☐ | |
+| `max_bytes` honored with metadata (plain text) | ☐ | ☐ | |
 | `format: summary` applied | ☐ | ☐ | |
 | `fields` projection limits keys per row (if tested) | ☐ | ☐ | |
 
@@ -279,7 +284,7 @@ Rules: McpMux meta tools only, read schemas before invoke, note truncation if an
 - [ ] Enable server expands `tools/list` beyond meta + surfaced
 - [ ] Search returns tools from inactive or unbound servers
 - [ ] Invoke succeeds for tools outside FeatureSet ACL
-- [ ] Large list invoke returns unbounded payload with no truncation metadata
+- [ ] Invoke with explicit filter fails to truncate or return metadata
 - [ ] Opaque errors (no enable/invoke redirect hints)
 
 ---