fix(cli): omit null/empty request fields so older instances accept them (#2799)

The CLI unconditionally attaches optional fields to the find/search/add_resource
request bodies — `args` as an empty `{}` and `tags`/`context_type` as `null` —
even when the user never set them. OpenViking kernels use
`model_config = ConfigDict(extra="forbid")` on these routes, so any instance that
predates a field rejects the whole request with
`body.<field>: Extra inputs are not permitted`. This breaks whenever the CLI is
newer than the target instance (and, symmetrically, when a field is later
renamed/removed): e.g. `ov add-resource` fails on `body.args` against a pre-#2549
instance, and `ov find` fails on `body.tags` against a strict pre-#2706 instance.

- Add `compact_request_body()` and apply it in find/search/add_resource: drop
  null-valued keys and an empty `args` object before sending. Scoped to these
  read/create routes only, where a missing optional field and an explicit null
  are equivalent — not applied globally, since null may mean "clear" on a future
  update/PATCH route. This mirrors the existing `create_parent` backward-compat
  convention.
- When a field is explicitly set but unsupported, translate the raw pydantic
  `Extra inputs are not permitted` error into a version-mismatch hint and suggest
  `ov health`, instead of surfacing the opaque API error.

Tests: unit tests for `compact_request_body` and `extra_forbidden_field`.

Author: t0saki

crates/ov_cli/src/client.rs

@@ -7,6 +7,32 @@ pub use crate::base_client::{BaseClient, FileUploader, TimeoutConfig};
 
 use crate::error::{Error, Result};
 
+/// Drop null-valued keys (and an empty `args` object) from a request body before
+/// sending it. Older, stricter servers use `extra="forbid"` and reject any field
+/// they do not yet define, so unconditionally attaching optional fields (even as
+/// `null`/`{}`) breaks against instances that predate that field. Omitting them is
+/// safe for read/create routes where a missing optional field and an explicit
+/// `null` are equivalent — do NOT use this for update/PATCH bodies where `null`
+/// may mean "clear this field".
+fn compact_request_body(body: &mut Value) {
+    let Some(obj) = body.as_object_mut() else {
+        return;
+    };
+    obj.retain(|key, value| {
+        if value.is_null() {
+            return false;
+        }
+        // `args` is always attached by the CLI but absent from pre-#2549 models;
+        // only forward it when the caller actually provided arguments.
+        if key == "args" {
+            if let Some(map) = value.as_object() {
+                return !map.is_empty();
+            }
+        }
+        true
+    });
+}
+
 // ============ HttpClient ============
 
 /// High-level HTTP client for OpenViking API
@@ -441,6 +467,7 @@ impl HttpClient {
             "tags": tags,
         });
         self.attach_legacy_agent_scope(&mut body);
+        compact_request_body(&mut body);
         self.post("/api/v1/search/find", &body).await
     }
 
@@ -472,6 +499,7 @@ impl HttpClient {
             "tags": tags,
         });
         self.attach_legacy_agent_scope(&mut body);
+        compact_request_body(&mut body);
         self.post("/api/v1/search/search", &body).await
     }
 
@@ -558,6 +586,7 @@ impl HttpClient {
                     .expect("add_resource request body must be an object")
                     .insert("create_parent".to_string(), serde_json::Value::Bool(true));
             }
+            compact_request_body(&mut body);
             body
         };
 
@@ -1432,6 +1461,37 @@ mod tests {
     use tokio::net::TcpListener;
     use tokio::sync::oneshot;
 
+    #[test]
+    fn compact_request_body_drops_null_and_empty_args() {
+        let mut body = json!({
+            "query": "hi",
+            "score_threshold": null,
+            "tags": null,
+            "args": {},
+            "wait": false,
+            "create_parent": true,
+            "filter": {"k": "v"},
+        });
+        super::compact_request_body(&mut body);
+        let obj = body.as_object().unwrap();
+        // Non-null values are kept, including `false` and non-empty objects.
+        assert!(obj.contains_key("query"));
+        assert!(obj.contains_key("wait"));
+        assert!(obj.contains_key("create_parent"));
+        assert!(obj.contains_key("filter"));
+        // Null fields and an empty `args` are dropped so pre-field servers accept it.
+        assert!(!obj.contains_key("score_threshold"));
+        assert!(!obj.contains_key("tags"));
+        assert!(!obj.contains_key("args"));
+    }
+
+    #[test]
+    fn compact_request_body_keeps_non_empty_args() {
+        let mut body = json!({"path": "x", "args": {"feishu_access_token": "u-x"}});
+        super::compact_request_body(&mut body);
+        assert!(body.as_object().unwrap().contains_key("args"));
+    }
+
     #[test]
     fn timeout_config_calculation() {
         let config = TimeoutConfig::new(60, 2.0);

crates/ov_cli/src/error_classifier.rs

@@ -9,9 +9,51 @@ pub(crate) fn looks_like_auth_error(message: &str) -> bool {
             .any(|token| token == "auth")
 }
 
+/// Detect the kernel's pydantic `extra="forbid"` rejection — e.g.
+/// "body.tags: Extra inputs are not permitted" — and return the offending field
+/// name. This usually means the target OpenViking instance is on a different
+/// version than the CLI (the field is missing, renamed, or removed), so callers
+/// can surface a version-mismatch hint instead of the raw API error.
+pub(crate) fn extra_forbidden_field(message: &str) -> Option<String> {
+    if !message.contains("Extra inputs are not permitted") {
+        return None;
+    }
+    // The kernel reports the location as `body.<field>: Extra inputs ...`.
+    let after = message.split("body.").nth(1)?;
+    let field = after
+        .split(|ch: char| ch == ':' || ch.is_whitespace())
+        .next()?
+        .trim();
+    if field.is_empty() {
+        None
+    } else {
+        Some(field.to_string())
+    }
+}
+
 #[cfg(test)]
 mod tests {
-    use super::looks_like_auth_error;
+    use super::{extra_forbidden_field, looks_like_auth_error};
+
+    #[test]
+    fn extracts_extra_forbidden_field() {
+        assert_eq!(
+            extra_forbidden_field(
+                "[INVALID_ARGUMENT] Invalid request parameters: body.tags: Extra inputs are not permitted."
+            ),
+            Some("tags".to_string())
+        );
+        assert_eq!(
+            extra_forbidden_field("body.args: Extra inputs are not permitted"),
+            Some("args".to_string())
+        );
+    }
+
+    #[test]
+    fn ignores_non_extra_forbidden_errors() {
+        assert_eq!(extra_forbidden_field("API key is invalid"), None);
+        assert_eq!(extra_forbidden_field("body.query: Field required"), None);
+    }
 
     #[test]
     fn detects_auth_errors() {

crates/ov_cli/src/error_ui.rs

@@ -5,7 +5,7 @@ use unicode_width::UnicodeWidthStr;
 
 use crate::{
     error::Error,
-    error_classifier::looks_like_auth_error,
+    error_classifier::{extra_forbidden_field, looks_like_auth_error},
     i18n::{Language, copy},
     terminal_ui::{fit_to_display_width, truncate_to_display_width},
     theme,
@@ -241,6 +241,27 @@ pub(crate) fn report_for_runtime_error(command: impl Into<String>, error: &Error
             ErrorAction::new("ov config", copy(language, "Edit this config", "编辑这个配置")),
             ErrorAction::new("ov config switch", copy(language, "Use another config", "使用其他配置")),
         ]),
+        Error::Api { message, .. } if extra_forbidden_field(message).is_some() => {
+            let field = extra_forbidden_field(message).unwrap_or_default();
+            ErrorReport::new(
+                copy(language, "OpenViking API Error", "OpenViking API 错误"),
+                match language {
+                    Language::En => format!(
+                        "OpenViking rejected an unsupported field \"{field}\". This instance's version likely does not match your CLI (the field may be missing, renamed, or removed)."
+                    ),
+                    Language::ZhCn => format!(
+                        "OpenViking 拒绝了不支持的字段 \"{field}\"：该实例版本可能与当前 CLI 不匹配（字段可能缺失、改名或已被移除）。"
+                    ),
+                },
+            )
+            .with_command(command)
+            .with_detail(message)
+            .with_actions(vec![
+                ErrorAction::new("ov health", copy(language, "Check the instance version", "查看实例版本")),
+                ErrorAction::new("ov config validate", copy(language, "Check the active config", "检查当前配置")),
+                ErrorAction::new("ov status", copy(language, "Check OpenViking status", "查看 OpenViking 状态")),
+            ])
+        }
         Error::Api { message, .. } => ErrorReport::new(
             copy(language, "OpenViking API Error", "OpenViking API 错误"),
             api_error_message(language, message),