Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(mcp): inline $defs refs in the moonshot schema dialect
Lucas Oliveiraad546e16b1c1
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 20b2a554..f666f479 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -12,6 +12,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0provider. (#1026)### Fixed+- Fixed Codex on the Kimi coding endpoint failing every model call with+ "tools.function.parameters is not a valid moonshot flavored json schema+ (... detected infinite recursion without termination condition ...)".+ Moonshot's validator never resolves `$ref`, so the `$defs`/`$ref` pairs+ Codex forwards from MCP input schemas failed the request at any depth —+ including the `ReasoningTier` reference on `memory_query` and+ `memory_explore` and the `FeedbackKind` reference on `memory_feedback` —+ not just at the root. The `?flavor=moonshot` dialect now inlines every+ `#/$defs/*` reference and drops the emptied `$defs` table; nested+ combinators (which Moonshot accepts) and runtime validation are unchanged.+ `?flavor=bedrock` and `?flavor=gemini` keep serving `$defs`/`$ref` as+ before.- Fixed `memory_handoff_list` MCP tool calls being counted under writes in`client_activity`: the read-only inspection tool is now classified as a readin `tool_call_is_write`. (#1088)diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex b0bf0873..cdb6d89c 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -5491,30 +5491,43 @@ impl ServerHandler for AiMemoryServer {}/// Tool input-schema dialect served for one `tools/list`, ordered by-/// strictness: each variant applies every rewrite of the one before it, plus-/// its own. That ordering is what lets the operator's configured floor and a-/// request's `?flavor=` marker combine with a plain `max`.+/// strictness: the operator's configured floor and a request's `?flavor=`+/// marker combine with a plain `max`, and the winning dialect's rewrite set+/// applies.#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord)]enum SchemaDialect {/// The schemas `schemars` generated, verbatim.#[default]Upstream,- /// Root-level `anyOf`/`oneOf`/`allOf` stripped (Moonshot, Bedrock).+ /// Root-level `anyOf`/`oneOf`/`allOf` stripped (Bedrock).RootCombinators,- /// Also collapses the nullable unions `Option<T>` produces into Google's- /// single-`type` plus `nullable` form (Gemini / Vertex).+ /// [`RootCombinators`], plus every `#/$defs/*` reference inlined and the+ /// emptied `$defs` table dropped (Moonshot). Moonshot's validator never+ /// resolves `$ref` and fails the request with "detected infinite+ /// recursion", so no reference may survive at any depth; nested+ /// combinators stay inline, which Moonshot accepts.+ FlatDefs,+ /// [`RootCombinators`], plus the nullable-union collapses in+ /// [`gemini_safe_schema`] (Gemini / Vertex). Deliberately *not*+ /// [`FlatDefs`]: Vertex accepts `$defs`/`$ref`, and the schemas Gemini+ /// CLI already ships keep them, so reference-flattening is out of+ /// scope there.GeminiSafe,}/// Bedrock and Moonshot reject root-level/// `anyOf`/`oneOf`/`allOf` in tool parameter schemas with a 400 at-/// `tools/list` time. Kimi's legacy `?flavor=moonshot` and Kiro's-/// `?flavor=bedrock` both get schemas with those root keys stripped;-/// nested combinators stay, and runtime validation remains unchanged.-/// [`SchemaDialect::GeminiSafe`] strips the same root keys and additionally-/// rewrites every subschema through [`gemini_safe_schema`].+/// `tools/list` time. Kiro's `?flavor=bedrock` gets schemas with those root+/// keys stripped; Moonshot's `?flavor=moonshot` gets+/// [`SchemaDialect::FlatDefs`], which additionally inlines every `$ref` (its+/// validator rejects references at any depth, not just combinators at the+/// root). Runtime validation remains unchanged in both dialects.+/// [`SchemaDialect::GeminiSafe`] strips the same root keys — and keeps+/// `$defs`/`$ref` by design — while additionally rewriting every subschema+/// through [`gemini_safe_schema`].fn restricted_schema_tool_list(tools: Vec<Tool>, dialect: SchemaDialect) -> Vec<Tool> {const ROOT_COMBINATORS: [&str; 3] = ["anyOf", "oneOf", "allOf"];+ let inline_defs = dialect == SchemaDialect::FlatDefs;let gemini_safe = dialect >= SchemaDialect::GeminiSafe;tools.into_iter()@@ -5522,13 +5535,16 @@ fn restricted_schema_tool_list(tools: Vec<Tool>, dialect: SchemaDialect) -> Vec<let has_root_combinator = ROOT_COMBINATORS.iter().any(|key| tool.input_schema.contains_key(*key));- if !has_root_combinator && !gemini_safe {+ if !has_root_combinator && !inline_defs && !gemini_safe {return tool;}let mut schema = (*tool.input_schema).clone();for key in ROOT_COMBINATORS {schema.shift_remove(key);}+ if inline_defs {+ inline_schema_defs(&mut schema);+ }if gemini_safe {gemini_safe_schema(&mut schema);}@@ -5538,6 +5554,97 @@ fn restricted_schema_tool_list(tools: Vec<Tool>, dialect: SchemaDialect) -> Vec<.collect()}+/// Inline every local `#/$defs/*` reference and drop the emptied `$defs`+/// table, recursively through the whole input schema.+///+/// Moonshot's "moonshot flavored json schema" validator never resolves+/// `$ref`: any reference — at the root or nested five levels deep — fails+/// the whole request with "detected infinite recursion without termination+/// condition". Codex forwards MCP input schemas into Responses+/// `tools.function.parameters` verbatim, so a served `$defs`/`$ref` pair+/// 400s every model call even though the referenced subschema would be+/// valid inline. Nested combinators themselves are fine (inline `anyOf` /+/// `oneOf` pass), so only the references are rewritten. Sibling keys on the+/// `$ref` object win over the definition's own, mirroring+/// [`flatten_sibling_combinator`]'s parent-wins rule. Definitions that+/// reference each other resolve over successive passes; if the pass budget+/// is exhausted or a name is missing, the schema is left untouched rather+/// than shipping a dangling reference without its table.+fn inline_schema_defs(schema: &mut serde_json::Map<String, serde_json::Value>) {+ const PASS_BUDGET: usize = 32;++ let Some(defs) = schema+ .get("$defs")+ .and_then(serde_json::Value::as_object)+ .cloned()+ else {+ return;+ };+ let mut root = serde_json::Value::Object(std::mem::take(schema));+ let mut all_resolved = false;+ for _ in 0..PASS_BUDGET {+ let (replaced, pending) = resolve_def_pass(&mut root, &defs);+ all_resolved = !pending;+ if !replaced {+ break;+ }+ }+ if let serde_json::Value::Object(mut map) = root {+ if all_resolved {+ map.shift_remove("$defs");+ }+ *schema = map;+ }+}++/// One sweep replacing every resolvable `#/$defs/*` reference. Returns+/// whether any replacement happened and whether any local `$ref` is still+/// present afterwards (`true` means the inlined payloads may have pulled in+/// further references, so another sweep is due; a still-pending reference+/// after the budget keeps the `$defs` table so nothing dangles).+fn resolve_def_pass(+ node: &mut serde_json::Value,+ defs: &serde_json::Map<String, serde_json::Value>,+) -> (bool, bool) {+ let mut replaced = false;+ let mut pending = false;+ match node {+ serde_json::Value::Object(map) => {+ if let Some(reference) = map.get("$ref").and_then(serde_json::Value::as_str) {+ if let Some(definition) = reference+ .strip_prefix("#/$defs/")+ .and_then(|name| defs.get(name))+ .and_then(serde_json::Value::as_object)+ {+ let mut overlay = definition.clone();+ map.shift_remove("$ref");+ for (key, value) in std::mem::take(map) {+ overlay.insert(key, value);+ }+ *map = overlay;+ replaced = true;+ } else {+ pending = true;+ }+ }+ for value in map.values_mut() {+ let (child_replaced, child_pending) = resolve_def_pass(value, defs);+ replaced |= child_replaced;+ pending |= child_pending;+ }+ }+ serde_json::Value::Array(items) => {+ for item in items.iter_mut() {+ let (child_replaced, child_pending) = resolve_def_pass(item, defs);+ replaced |= child_replaced;+ pending |= child_pending;+ }+ }+ _ => {}+ }+ (replaced, pending)+}+/// Rewrite one subschema — and everything below it — into the subset Google's/// `Schema` (Vertex/Gemini `functionDeclaration.parameters`) accepts.///@@ -5666,7 +5773,8 @@ fn restricted_schema_flavor(query: &str) -> Option<SchemaDialect> {query.split('&').filter_map(|pair| match pair {- "flavor=moonshot" | "flavor=bedrock" => Some(SchemaDialect::RootCombinators),+ "flavor=moonshot" => Some(SchemaDialect::FlatDefs),+ "flavor=bedrock" => Some(SchemaDialect::RootCombinators),"flavor=gemini" | "flavor=vertex" => Some(SchemaDialect::GeminiSafe),_ => None,})@@ -9879,7 +9987,7 @@ mod tests {fn restricted_schema_flavor_matches_complete_query_pairs_only() {assert_eq!(restricted_schema_flavor("flavor=moonshot"),- Some(SchemaDialect::RootCombinators)+ Some(SchemaDialect::FlatDefs));assert_eq!(restricted_schema_flavor("client=kiro&flavor=bedrock&debug=false"),@@ -9898,6 +10006,10 @@ mod tests {restricted_schema_flavor("flavor=gemini&flavor=moonshot"),Some(SchemaDialect::GeminiSafe));+ assert_eq!(+ restricted_schema_flavor("flavor=moonshot&flavor=bedrock"),+ Some(SchemaDialect::FlatDefs)+ );assert_eq!(restricted_schema_flavor("flavor=unknown"), None);assert_eq!(restricted_schema_flavor("note=flavor=bedrock&client=kiro"),@@ -9905,6 +10017,174 @@ mod tests {);}+ fn inlined_defs(schema: serde_json::Value) -> serde_json::Value {+ let mut map: serde_json::Map<String, serde_json::Value> =+ serde_json::from_value(schema).unwrap();+ inline_schema_defs(&mut map);+ serde_json::Value::Object(map)+ }++ // Codex + the Kimi coding endpoint 400s every call: the Moonshot+ // validator never resolves `$ref`, so the `ReasoningTier` /+ // `FeedbackKind` references must be inlined at any depth.+ #[test]+ fn inline_schema_defs_replaces_refs_and_drops_the_table() {+ let out = inlined_defs(serde_json::json!({+ "type": "object",+ "$defs": {+ "ReasoningTier": {+ "description": "Operator-facing tier.",+ "oneOf": [+ { "type": "string", "const": "minimal" },+ { "type": "string", "const": "max" }+ ]+ }+ },+ "properties": {+ "reasoning": {+ "description": "Field docs.",+ "anyOf": [+ { "$ref": "#/$defs/ReasoningTier" },+ { "type": "null" }+ ]+ },+ "signal": { "$ref": "#/$defs/ReasoningTier" }+ }+ }));++ assert!(+ out.get("$defs").is_none(),+ "the emptied table must go: {out}"+ );+ assert_eq!(+ out["properties"]["reasoning"],+ serde_json::json!({+ "description": "Field docs.",+ "anyOf": [+ {+ "description": "Operator-facing tier.",+ "oneOf": [+ { "type": "string", "const": "minimal" },+ { "type": "string", "const": "max" }+ ]+ },+ { "type": "null" }+ ]+ }),+ "the reference inlines the definition; the sibling description and the null branch stay"+ );+ assert_eq!(+ out["properties"]["signal"],+ serde_json::json!({+ "description": "Operator-facing tier.",+ "oneOf": [+ { "type": "string", "const": "minimal" },+ { "type": "string", "const": "max" }+ ]+ }),+ "a bare $ref becomes the definition itself"+ );+ }++ #[test]+ fn inline_schema_defs_resolves_chained_definitions() {+ let out = inlined_defs(serde_json::json!({+ "$defs": {+ "Inner": { "type": "string", "enum": ["a", "b"] },+ "Outer": { "type": "object", "properties": { "inner": { "$ref": "#/$defs/Inner" } } }+ },+ "type": "object",+ "properties": { "outer": { "$ref": "#/$defs/Outer" } }+ }));++ assert!(+ out.get("$defs").is_none(),+ "chained definitions must fully resolve: {out}"+ );+ assert_eq!(+ out["properties"]["outer"]["properties"]["inner"],+ serde_json::json!({ "type": "string", "enum": ["a", "b"] })+ );+ }++ #[test]+ fn inline_schema_defs_keeps_the_table_when_a_reference_dangles() {+ let out = inlined_defs(serde_json::json!({+ "$defs": {+ "Known": { "type": "string" }+ },+ "type": "object",+ "properties": {+ "known": { "$ref": "#/$defs/Known" },+ "missing": { "$ref": "#/$defs/Missing" }+ }+ }));++ assert!(+ out.get("$defs").is_some(),+ "an unresolvable reference must keep its table: {out}"+ );+ assert_eq!(+ out["properties"]["known"],+ serde_json::json!({ "type": "string" })+ );+ assert_eq!(+ out["properties"]["missing"],+ serde_json::json!({ "$ref": "#/$defs/Missing" })+ );+ }++ // The Bedrock dialect is a narrower patch on purpose: it must not start+ // flattening references just because Moonshot's stricter sibling does.+ #[test]+ fn restricted_schema_tool_list_keeps_defs_for_root_combinator_dialect() {+ let schema: serde_json::Map<String, serde_json::Value> =+ serde_json::from_value(serde_json::json!({+ "type": "object",+ "$defs": { "Kind": { "type": "string", "enum": ["a"] } },+ "properties": { "kind": { "$ref": "#/$defs/Kind" } }+ }))+ .unwrap();+ let tool = Tool::new("memory_feedback", "Feedback", schema);++ let patched = restricted_schema_tool_list(vec![tool], SchemaDialect::RootCombinators);++ assert_eq!(+ patched[0].input_schema["properties"]["kind"],+ serde_json::json!({ "$ref": "#/$defs/Kind" }),+ "bedrock schemas keep their $defs/$ref pairs"+ );+ assert!(+ patched[0].input_schema.get("$defs").is_some(),+ "bedrock schemas keep the $defs table"+ );+ }++ #[test]+ fn restricted_schema_tool_list_inlines_defs_for_flat_dialect() {+ let schema: serde_json::Map<String, serde_json::Value> =+ serde_json::from_value(serde_json::json!({+ "type": "object",+ "$defs": { "Kind": { "type": "string", "enum": ["a"] } },+ "properties": { "kind": { "$ref": "#/$defs/Kind" } }+ }))+ .unwrap();+ let tool = Tool::new("memory_feedback", "Feedback", schema);++ let patched = restricted_schema_tool_list(vec![tool], SchemaDialect::FlatDefs);++ let serialized =+ serde_json::to_string(&patched[0].input_schema).expect("schema serializes");+ assert!(+ !serialized.contains("$ref"),+ "moonshot schemas must not contain a single $ref: {serialized}"+ );+ assert_eq!(+ patched[0].input_schema["properties"]["kind"],+ serde_json::json!({ "type": "string", "enum": ["a"] })+ );+ }+fn gemini_safe(schema: serde_json::Value) -> serde_json::Value {let mut map: serde_json::Map<String, serde_json::Value> =serde_json::from_value(schema).unwrap();diff --git a/crates/ai-memory-mcp/tests/suite/mcp_stateless_http.rs b/crates/ai-memory-mcp/tests/suite/mcp_stateless_http.rsindex 3a8fb79e..d3e5ebe6 100644--- a/crates/ai-memory-mcp/tests/suite/mcp_stateless_http.rs+++ b/crates/ai-memory-mcp/tests/suite/mcp_stateless_http.rs@@ -194,6 +194,11 @@ async fn stateful_tools_call_without_session_is_rejected() {/// Pull `memory_read_page`'s inputSchema from a tools/list response body.fn read_page_input_schema(body: &str) -> serde_json::Value {+ input_schema_of(body, "memory_read_page")+}++/// Pull any named tool's inputSchema from a tools/list response body.+fn input_schema_of(body: &str, name: &str) -> serde_json::Value {let json: serde_json::Value = serde_json::from_str(body).unwrap_or_else(|e| panic!("tools/list response must be JSON, got: {body}\nerr: {e}"));let tools = json["result"]["tools"]@@ -201,11 +206,9 @@ fn read_page_input_schema(body: &str) -> serde_json::Value {.unwrap_or_else(|| panic!("missing result.tools: {body}"));tools.iter()- .find(|tool| tool["name"] == "memory_read_page")- .unwrap_or_else(|| panic!("memory_read_page missing from tools/list: {body}"))[- "inputSchema"- ]- .clone()+ .find(|tool| tool["name"] == name)+ .unwrap_or_else(|| panic!("{name} missing from tools/list: {body}"))["inputSchema"]+ .clone()}/// Kimi Code's real flow: independent stateless POSTs against@@ -386,6 +389,93 @@ async fn stateless_moonshot_flavor_keeps_nullable_unions() {);}+/// Codex forwards MCP input schemas into Responses `tools.function.parameters`+/// verbatim, and Moonshot's validator never resolves `$ref` — every reference+/// 400s the call with "detected infinite recursion without termination+/// condition". `?flavor=moonshot` must therefore inline every `#/$defs/*`+/// reference (nested combinators themselves pass, so the nullable union on+/// `reasoning` stays).+#[tokio::test]+async fn stateless_moonshot_flavor_inlines_defs() {+ let tmp = TempDir::new().unwrap();+ let (router, _store) = make_router(&tmp, false).await;++ let resp = router+ .oneshot(post_to("/mcp?flavor=moonshot", TOOLS_LIST))+ .await+ .unwrap();+ assert_eq!(resp.status(), StatusCode::OK);+ let body = body_string(resp).await;+ for tool_name in ["memory_query", "memory_explore", "memory_feedback"] {+ let schema = input_schema_of(&body, tool_name);+ assert!(+ schema.get("$defs").is_none(),+ "moonshot flavor must drop the $defs table from {tool_name}: {schema}"+ );+ assert!(+ !serde_json::to_string(&schema)+ .expect("schema serializes")+ .contains("$ref"),+ "moonshot flavor must not leave a single $ref in {tool_name}: {schema}"+ );+ }+ let query = input_schema_of(&body, "memory_query");+ assert!(+ query["properties"]["reasoning"]["anyOf"].is_array(),+ "the nested nullable union must survive inlining: {query}"+ );+}++/// Kiro's Bedrock dialect is deliberately narrower than Moonshot's: it strips+/// root combinators but keeps `$defs`/`$ref` pairs, which Bedrock resolves.+#[tokio::test]+async fn stateless_bedrock_flavor_keeps_defs() {+ let tmp = TempDir::new().unwrap();+ let (router, _store) = make_router(&tmp, false).await;++ let resp = router+ .oneshot(post_to("/mcp?flavor=bedrock", TOOLS_LIST))+ .await+ .unwrap();+ assert_eq!(resp.status(), StatusCode::OK);+ let schema = input_schema_of(&body_string(resp).await, "memory_feedback");+ assert!(+ schema.get("$defs").is_some(),+ "bedrock flavor must keep the $defs table: {schema}"+ );+ assert!(+ serde_json::to_string(&schema)+ .expect("schema serializes")+ .contains("$ref"),+ "bedrock flavor must keep $ref pairs: {schema}"+ );+}++/// Vertex accepts `$defs`/`$ref` and Gemini CLI ships them untouched, so the+/// Gemini dialect must keep flattening references out of scope.+#[tokio::test]+async fn stateless_gemini_flavor_keeps_defs() {+ let tmp = TempDir::new().unwrap();+ let (router, _store) = make_router(&tmp, false).await;++ let resp = router+ .oneshot(post_to("/mcp?flavor=gemini", TOOLS_LIST))+ .await+ .unwrap();+ assert_eq!(resp.status(), StatusCode::OK);+ let schema = input_schema_of(&body_string(resp).await, "memory_feedback");+ assert!(+ schema.get("$defs").is_some(),+ "gemini flavor must keep the $defs table: {schema}"+ );+ assert!(+ serde_json::to_string(&schema)+ .expect("schema serializes")+ .contains("$ref"),+ "gemini flavor must keep $ref pairs: {schema}"+ );+}+/// Unflavored tools/list is root-combinator-free too (#577): the safe/// shape is the default, not a per-flavor patch.#[tokio::test]diff --git a/docs/mcp-install.md b/docs/mcp-install.mdindex 371667ac..07c81ab3 100644--- a/docs/mcp-install.md+++ b/docs/mcp-install.md@@ -1264,9 +1264,17 @@ validation is identical in every dialect — only the advertised schema changes.| Marker | Config key | What it changes | Who needs it || --- | --- | --- | --- |-| `?flavor=moonshot` | `strip_root_combinators` | Drops root-level `anyOf`/`oneOf`/`allOf` | Kimi Code (Moonshot); appended by `install-mcp` |-| `?flavor=bedrock` | `strip_root_combinators` | Same as above | Kiro CLI (Bedrock); appended by `install-mcp` |-| `?flavor=gemini` (alias `vertex`) | `gemini_safe_schemas` | The above, plus nullable unions collapsed to a single `type` + `nullable: true` | Clients that forward schemas verbatim to Gemini/Vertex, e.g. OpenCode on a Vertex model |+| `?flavor=moonshot` | `strip_root_combinators` | Drops root-level `anyOf`/`oneOf`/`allOf`, plus inlines every `#/$defs/*` reference and drops the emptied `$defs` table | Kimi Code (Moonshot); appended by `install-mcp` |+| `?flavor=bedrock` | `strip_root_combinators` | Drops root-level `anyOf`/`oneOf`/`allOf` | Kiro CLI (Bedrock); appended by `install-mcp` |+| `?flavor=gemini` (alias `vertex`) | `gemini_safe_schemas` | Drops root-level `anyOf`/`oneOf`/`allOf`, plus nullable unions collapsed to a single `type` + `nullable: true` | Clients that forward schemas verbatim to Gemini/Vertex, e.g. OpenCode on a Vertex model |++Moonshot's validator never resolves `$ref` — any reference, at the root or+nested, fails the request with "detected infinite recursion without termination+condition" — while inline combinators such as the nullable union on+`Option<T>` arguments pass. Codex forwards MCP input schemas into Responses+`tools.function.parameters` verbatim, so it needs the Moonshot marker even+though it is not Kimi Code. `?flavor=bedrock` and `?flavor=gemini` keep+`$defs`/`$ref` pairs, which their upstreams resolve.`install-mcp` appends the first two itself for the clients whose upstream isfixed. For any other client, pass the dialect explicitly: