fix: normalize Xiaomi array tool schemas (#82575)

steipete · web-flow · commit 862be9fb3d6c · 2026-05-16T13:34:52.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -28,6 +28,7 @@ Docs: https://docs.openclaw.ai
 - CLI: hide decorative startup and status emoji on terminals that are unlikely to render them correctly, keeping semantic message and identity emoji intact.
 - CLI/gateway: recover the Linux user systemd bus environment when `openclaw dashboard` starts the Gateway from stripped desktop shells such as VNC terminals.
 - Gateway/WebSocket: log expected startup `1013 gateway starting` retry closes at debug instead of warn while preserving WARN for unexpected pre-connect failures. Fixes #76361. (#82457) Thanks @IWhatsskill.
+- Providers/Xiaomi: strip synthetic empty array `items` from MiMo tool schemas while preserving typed array items, avoiding strict OpenAI-compatible schema rejection.
 - CLI/context engines: bootstrap and finalize non-legacy context engines for CLI turns while preserving transcript snapshots and deferred maintenance ownership. (#81869) Thanks @sahilsatralkar.
 - Telegram: persist polling updates through restart replay so queued same-topic messages resume in order instead of losing context after a gateway restart. (#82256) Thanks @VACInc.
 - Gateway/Gmail: abort in-flight Gmail watcher startup and hot-reload restarts before shutdown so reloads cannot spawn `gog serve` after the Gateway is closing. Thanks @frankekn.
diff --git a/extensions/xiaomi/index.test.ts b/extensions/xiaomi/index.test.ts
@@ -242,6 +242,22 @@ describe("xiaomi provider plugin", () => {
     expect(replayPolicy?.validateAnthropicTurns).toBe(true);
   });
 
+  it("marks resolved MiMo models for empty array items omission", async () => {
+    const provider = await registerSingleProviderPlugin(xiaomiPlugin);
+    const model = mimoReasoningModel("mimo-v2.5");
+
+    const normalized = provider.normalizeResolvedModel?.({
+      provider: "xiaomi",
+      modelId: model.id,
+      modelApi: model.api,
+      model,
+    } as never);
+
+    expect(
+      (normalized?.compat as { omitEmptyArrayItems?: unknown } | undefined)?.omitEmptyArrayItems,
+    ).toBe(true);
+  });
+
   it("advertises thinking profiles for MiMo reasoning models only", async () => {
     const provider = await registerSingleProviderPlugin(xiaomiPlugin);
     const resolveThinkingProfile = requireThinkingProfileResolver(provider);
diff --git a/extensions/xiaomi/index.ts b/extensions/xiaomi/index.ts
@@ -1,5 +1,8 @@
 import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry";
-import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared";
+import {
+  applyModelCompatPatch,
+  buildProviderReplayFamilyHooks,
+} from "openclaw/plugin-sdk/provider-model-shared";
 import { PROVIDER_LABELS } from "openclaw/plugin-sdk/provider-usage";
 import { applyXiaomiConfig, XIAOMI_DEFAULT_MODEL_REF } from "./onboard.js";
 import { buildXiaomiProvider } from "./provider-catalog.js";
@@ -36,6 +39,8 @@ export default defineSingleProviderPluginEntry({
       family: "openai-compatible",
       dropReasoningFromHistory: false,
     }),
+    normalizeResolvedModel: ({ model }) =>
+      applyModelCompatPatch(model, { omitEmptyArrayItems: true }),
     wrapStreamFn: (ctx) => createMiMoThinkingWrapper(ctx.streamFn, ctx.thinkingLevel),
     resolveThinkingProfile: ({ modelId }) => resolveMiMoThinkingProfile(modelId),
     isModernModelRef: ({ modelId }) => Boolean(resolveMiMoThinkingProfile(modelId)),
diff --git a/src/agents/openai-tool-schema.ts b/src/agents/openai-tool-schema.ts
@@ -4,6 +4,7 @@ export { resolveOpenAIStrictToolSetting } from "./openai-strict-tool-setting.js"
 
 type ToolSchemaCompatInput = {
   unsupportedToolSchemaKeywords?: unknown;
+  omitEmptyArrayItems?: unknown;
 };
 
 type ToolWithParameters = {
@@ -14,13 +15,20 @@ type ToolWithParameters = {
 function resolveToolSchemaModelCompat(
   compat: ToolSchemaCompatInput | null | undefined,
 ): ModelCompatConfig | undefined {
-  if (!compat || !Array.isArray(compat.unsupportedToolSchemaKeywords)) {
+  if (!compat) {
+    return undefined;
+  }
+  const unsupportedToolSchemaKeywords = Array.isArray(compat.unsupportedToolSchemaKeywords)
+    ? compat.unsupportedToolSchemaKeywords.filter(
+        (keyword): keyword is string => typeof keyword === "string",
+      )
+    : [];
+  if (unsupportedToolSchemaKeywords.length === 0 && compat.omitEmptyArrayItems !== true) {
     return undefined;
   }
   return {
-    unsupportedToolSchemaKeywords: compat.unsupportedToolSchemaKeywords.filter(
-      (keyword): keyword is string => typeof keyword === "string",
-    ),
+    ...(unsupportedToolSchemaKeywords.length > 0 ? { unsupportedToolSchemaKeywords } : {}),
+    ...(compat.omitEmptyArrayItems === true ? { omitEmptyArrayItems: true } : {}),
   };
 }
 
diff --git a/src/agents/openai-transport-stream.test.ts b/src/agents/openai-transport-stream.test.ts
@@ -3807,6 +3807,54 @@ describe("openai transport stream", () => {
     expect(params.tools?.[0]?.function?.parameters?.properties?.forbidden).toStrictEqual({});
   });
 
+  it("applies model compat empty array items omission after completions normalization", () => {
+    const params = buildOpenAICompletionsParams(
+      {
+        id: "mimo-v2.5",
+        name: "MiMo V2.5",
+        api: "openai-completions",
+        provider: "xiaomi",
+        baseUrl: "https://api.xiaomimimo.com/v1",
+        reasoning: true,
+        input: ["text"],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 256000,
+        maxTokens: 256000,
+        compat: {
+          omitEmptyArrayItems: true,
+        } as never,
+      } satisfies Model<"openai-completions">,
+      {
+        systemPrompt: "system",
+        messages: [],
+        tools: [
+          {
+            name: "collect",
+            description: "Collect hints",
+            parameters: {
+              type: "object",
+              properties: {
+                hints: { type: "array" },
+                typedHints: { type: "array", items: { type: "string" } },
+              },
+            },
+          },
+        ],
+      } as never,
+      undefined,
+    ) as {
+      tools?: Array<{ function?: { parameters?: { properties?: Record<string, unknown> } } }>;
+    };
+
+    expect(params.tools?.[0]?.function?.parameters?.properties?.hints).toStrictEqual({
+      type: "array",
+    });
+    expect(params.tools?.[0]?.function?.parameters?.properties?.typedHints).toStrictEqual({
+      type: "array",
+      items: { type: "string" },
+    });
+  });
+
   describe("Gemini thought_signature round-trip on OpenAI-compatible completions", () => {
     const geminiModel = {
       id: "gemini-3-flash-preview",
diff --git a/src/agents/pi-tools-parameter-schema.ts b/src/agents/pi-tools-parameter-schema.ts
@@ -1,7 +1,10 @@
 import type { TSchema } from "typebox";
 import type { ModelCompatConfig } from "../config/types.models.js";
 import { stripUnsupportedSchemaKeywords } from "../plugin-sdk/provider-tools.js";
-import { resolveUnsupportedToolSchemaKeywords } from "../plugins/provider-model-compat.js";
+import {
+  resolveUnsupportedToolSchemaKeywords,
+  shouldOmitEmptyArrayItems,
+} from "../plugins/provider-model-compat.js";
 import { normalizeLowercaseStringOrEmpty } from "../shared/string-coerce.js";
 import { cleanSchemaForGemini } from "./schema/clean-for-gemini.js";
 
@@ -224,6 +227,88 @@ function normalizeArraySchemasMissingItems(schema: unknown): unknown {
   return changed ? nextSchema : schema;
 }
 
+function schemaAllowsArrayType(schema: Record<string, unknown>): boolean {
+  const type = schema.type;
+  return type === "array" || (Array.isArray(type) && type.includes("array"));
+}
+
+const ARRAY_ITEMS_SCHEMA_OBJECT_KEYS = new Set([
+  "additionalProperties",
+  "contains",
+  "else",
+  "if",
+  "items",
+  "not",
+  "propertyNames",
+  "then",
+]);
+
+const ARRAY_ITEMS_SCHEMA_ARRAY_KEYS = new Set(["allOf", "anyOf", "oneOf", "prefixItems"]);
+
+const ARRAY_ITEMS_SCHEMA_MAP_KEYS = new Set([
+  "$defs",
+  "definitions",
+  "dependentSchemas",
+  "patternProperties",
+  "properties",
+]);
+
+function stripEmptyArrayItemsFromArraySchemas(schema: unknown): unknown {
+  if (Array.isArray(schema)) {
+    let changed = false;
+    const entries = schema.map((entry) => {
+      const next = stripEmptyArrayItemsFromArraySchemas(entry);
+      changed ||= next !== entry;
+      return next;
+    });
+    return changed ? entries : schema;
+  }
+  if (!isSchemaRecord(schema)) {
+    return schema;
+  }
+
+  let changed = false;
+  const entries = Object.entries(schema).flatMap(([key, value]) => {
+    if (
+      key === "items" &&
+      schemaAllowsArrayType(schema) &&
+      isSchemaRecord(value) &&
+      isTrulyEmptySchema(value)
+    ) {
+      changed = true;
+      return [];
+    }
+
+    if (ARRAY_ITEMS_SCHEMA_OBJECT_KEYS.has(key)) {
+      const next = stripEmptyArrayItemsFromArraySchemas(value);
+      changed ||= next !== value;
+      return [[key, next] as const];
+    }
+
+    if (ARRAY_ITEMS_SCHEMA_ARRAY_KEYS.has(key) && Array.isArray(value)) {
+      const next = stripEmptyArrayItemsFromArraySchemas(value);
+      changed ||= next !== value;
+      return [[key, next] as const];
+    }
+
+    if (ARRAY_ITEMS_SCHEMA_MAP_KEYS.has(key) && isSchemaRecord(value)) {
+      let mapChanged = false;
+      const next = Object.fromEntries(
+        Object.entries(value).map(([entryKey, entryValue]) => {
+          const entryNext = stripEmptyArrayItemsFromArraySchemas(entryValue);
+          mapChanged ||= entryNext !== entryValue;
+          return [entryKey, entryNext] as const;
+        }),
+      );
+      changed ||= mapChanged;
+      return [[key, mapChanged ? next : value] as const];
+    }
+
+    return [[key, value] as const];
+  });
+  return changed ? Object.fromEntries(entries) : schema;
+}
+
 export function normalizeToolParameterSchema(
   schema: unknown,
   options?: { modelProvider?: string; modelId?: string; modelCompat?: ModelCompatConfig },
@@ -247,16 +332,23 @@ export function normalizeToolParameterSchema(
     normalizedProvider.includes("google") || normalizedProvider.includes("gemini");
   const isAnthropicProvider = normalizedProvider.includes("anthropic");
   const unsupportedToolSchemaKeywords = resolveUnsupportedToolSchemaKeywords(options?.modelCompat);
+  const omitEmptyArrayItems = shouldOmitEmptyArrayItems(options?.modelCompat);
 
   function applyProviderCleaning(s: unknown): TSchema {
     const normalizedSchema = normalizeArraySchemasMissingItems(s);
+    const arrayItemsCompatibleSchema = omitEmptyArrayItems
+      ? stripEmptyArrayItemsFromArraySchemas(normalizedSchema)
+      : normalizedSchema;
     if (isGeminiProvider && !isAnthropicProvider) {
-      return cleanSchemaForGemini(normalizedSchema);
+      return cleanSchemaForGemini(arrayItemsCompatibleSchema);
     }
     if (unsupportedToolSchemaKeywords.size > 0) {
-      return stripUnsupportedSchemaKeywords(normalizedSchema, unsupportedToolSchemaKeywords) as TSchema;
+      return stripUnsupportedSchemaKeywords(
+        arrayItemsCompatibleSchema,
+        unsupportedToolSchemaKeywords,
+      ) as TSchema;
     }
-    return normalizedSchema as TSchema;
+    return arrayItemsCompatibleSchema as TSchema;
   }
 
   const conditionalKey = getTopLevelConditionalKey(schemaRecord);
diff --git a/src/agents/pi-tools.schema.test.ts b/src/agents/pi-tools.schema.test.ts
@@ -525,6 +525,50 @@ describe("normalizeToolParameters", () => {
     expect(parameters.properties?.query.type).toBe("string");
   });
 
+  it("omits empty array items when model compat requires it", () => {
+    const tool: AnyAgentTool = {
+      name: "demo",
+      label: "demo",
+      description: "demo",
+      parameters: {
+        type: "object",
+        properties: Object.fromEntries([
+          ["__proto__", { type: "array", items: {} }],
+          ["emptyItems", { type: "array" }],
+          ["typedItems", { type: "array", items: { type: "string" } }],
+          ["falseItems", { type: "array", items: false }],
+          ["nullItems", { type: "array", items: null }],
+          ["literalDefault", { type: "string", default: { type: "array", items: {} } }],
+          ["literalEnum", { type: "string", enum: [{ type: "array", items: {} }] }],
+        ]),
+      },
+      execute: vi.fn(),
+    };
+
+    const normalized = normalizeToolParameters(tool, {
+      modelCompat: { omitEmptyArrayItems: true } as never,
+    });
+
+    expect(normalized.parameters).toEqual({
+      type: "object",
+      properties: Object.fromEntries([
+        ["__proto__", { type: "array" }],
+        ["emptyItems", { type: "array" }],
+        ["typedItems", { type: "array", items: { type: "string" } }],
+        ["falseItems", { type: "array", items: false }],
+        ["nullItems", { type: "array", items: null }],
+        ["literalDefault", { type: "string", default: { type: "array", items: {} } }],
+        ["literalEnum", { type: "string", enum: [{ type: "array", items: {} }] }],
+      ]),
+    });
+    expect(
+      Object.prototype.hasOwnProperty.call(
+        (normalized.parameters as { properties?: Record<string, unknown> }).properties,
+        "__proto__",
+      ),
+    ).toBe(true);
+  });
+
   it("filters required to match properties when flattening anyOf for Gemini", () => {
     const tool = makeTool({
       type: "object",
diff --git a/src/plugins/provider-model-compat.ts b/src/plugins/provider-model-compat.ts
@@ -18,14 +18,13 @@ export function extractModelCompat(
 /** @deprecated Provider-owned model compat helper; do not use from third-party plugins. */
 export function applyModelCompatPatch<T extends { compat?: ModelCompatConfig }>(
   model: T,
-  patch: ModelCompatConfig,
+  patch: Partial<ModelCompatConfig> & Record<string, unknown>,
 ): T {
-  const nextCompat = { ...model.compat, ...patch };
+  const nextCompat = { ...model.compat, ...patch } as ModelCompatConfig;
+  const currentCompat = model.compat as (Record<string, unknown> & ModelCompatConfig) | undefined;
   if (
     model.compat &&
-    Object.entries(patch).every(
-      ([key, value]) => model.compat?.[key as keyof ModelCompatConfig] === value,
-    )
+    Object.entries(patch).every(([key, value]) => currentCompat?.[key] === value)
   ) {
     return model;
   }
@@ -66,6 +65,15 @@ export function resolveUnsupportedToolSchemaKeywords(
   );
 }
 
+export function shouldOmitEmptyArrayItems(
+  modelOrCompat: { compat?: unknown } | ModelCompatConfig | undefined,
+): boolean {
+  const compat = extractModelCompat(modelOrCompat) as
+    | (ModelCompatConfig & { omitEmptyArrayItems?: unknown })
+    | undefined;
+  return compat?.omitEmptyArrayItems === true;
+}
+
 function isOpenAiCompletionsModel(model: Model<Api>): model is Model<"openai-completions"> {
   return model.api === "openai-completions";
 }
