fix: vision handling for OpenAI-compatible models (Gitlawb#1663)

* Fix vision handling for OpenAI-compatible models

Add route-aware vision capability checks for image reads so registered non-vision models get an actionable refusal before sending image content.

Classify provider-side image/text errors as canonical vision_not_supported responses, preserve image-only tool results for OpenAI-compatible shims, and strip rejected images from retry messages.

Add focused coverage for Xiaomi MiMo/OpenGateway route collisions, canonical errors, shim image handling, and the Read prompt.

* Address vision review findings

Move the Read tool vision gate before the UNC no-I/O early return so UNC image paths cannot bypass non-vision model checks.

Add direct FileReadTool.validateInput coverage for non-vision denials, provider override/env precedence, and UNC image paths.

Add the missing OPENAI_BASE_URL exclusion assertion for the Xiaomi MiMo canonical error path.

* Isolate vision gate tests from provider env

Clear OPENAI_BASE_URL and OPENAI_API_BASE before each FileReadTool vision-gate test so full-suite provider tests cannot leak route state into these cases.

* Fix vision gate test full-suite isolation

Import FileReadTool and prompt with a cache-busted module id so compact.test's process-global mock cannot replace validateInput during test:full.

Invoke validateInput directly instead of optional chaining, matching the review finding and making missing exports fail clearly.

* Lock vision prompt env mutations

Acquire the shared mutation lock before mutating OPENAI_BASE_URL and OPENAI_API_BASE in the FileReadTool vision prompt tests, and release it after restoring the environment.

Author: jatmn

src/services/api/errors.openaiCompatibility.test.ts

@@ -28,7 +28,7 @@ test('maps endpoint_not_found category markers to actionable setup guidance', ()
   expect(text).toContain('/v1')
 })
 
-test('vision_not_supported shows image-specific guidance for remote host', () => {
+test('vision_not_supported shows image-specific guidance (issue #1421 canonical message)', () => {
   const error = APIError.generate(
     404,
     undefined,
@@ -40,9 +40,29 @@ test('vision_not_supported shows image-specific guidance for remote host', () =>
   const text = getFirstText(message)
 
   expect(message.isApiErrorMessage).toBe(true)
-  expect(text).toContain('images')
-  expect(text).toContain('mimo-v2.5-pro')
-  expect(text).toContain('opengateway.gitlawb.com')
+  expect(text).toContain('image')
+  expect(text).toContain('does not support')
+  // The command is `/model` in interactive sessions and `--model` in
+  // non-interactive (test/SDK) sessions — both forms are intentional.
+  expect(text).toMatch(/(\/model|--model)/)
+  expect(text).not.toContain('OPENAI_BASE_URL')
+})
+
+test('vision_not_supported from Xiaomi Mimo 400 "text is not set" uses the same canonical message (issue #1421)', () => {
+  const error = APIError.generate(
+    400,
+    undefined,
+    'OpenAI API error 400: {"error":{"code":"400","message":"Param Incorrect","param":"`text` is not set"}} [openai_category=vision_not_supported,host=api.xiaomimimo.com] Hint: The provider rejected an image-bearing request because it lacked a text part.',
+    new Headers(),
+  )
+
+  const message = getAssistantMessageFromError(error, 'mimo-v2.5-pro')
+  const text = getFirstText(message)
+
+  expect(message.isApiErrorMessage).toBe(true)
+  expect(text).toContain('image')
+  expect(text).toContain('does not support')
+  expect(text).toMatch(/(\/model|--model)/)
   expect(text).not.toContain('OPENAI_BASE_URL')
 })
 

src/services/api/errors.ts

@@ -99,8 +99,9 @@ function mapOpenAICompatibilityFailureToAssistantMessage(options: {
 
     case 'vision_not_supported':
       return createAssistantAPIErrorMessage({
-        content: `The provider at ${options.host} returned 404 for a request containing images. The model (${options.model}) may not support image/vision inputs. Try removing images from your message, or ${switchCmd} to a vision-capable model.`,
+        content: getVisionNotSupportedErrorMessage(),
         error: 'invalid_request',
+        errorDetails: stripOpenAICompatibilityMetadata(options.rawMessage),
       })
 
     case 'model_not_found':
@@ -399,6 +400,31 @@ export function getRequestTooLargeErrorMessage(): string {
     ? `Request too large (${limits}). Try with a smaller file.`
     : `Request too large (${limits}). Double press esc to go back and try with a smaller file.`
 }
+
+const VISION_NOT_SUPPORTED_MESSAGE_PREFIX =
+  'The active model does not support image/vision inputs. The provider rejected the request because it contained an image. Remove the image, or'
+
+export function getVisionNotSupportedErrorMessages(): string[] {
+  return [
+    `${VISION_NOT_SUPPORTED_MESSAGE_PREFIX} switch to a vision-capable model with --model.`,
+    `${VISION_NOT_SUPPORTED_MESSAGE_PREFIX} run /model to switch to a vision-capable model.`,
+  ]
+}
+
+/**
+ * Canonical message for the `vision_not_supported` OpenAI compatibility
+ * failure (issue #1421). Returned as a stable string so that
+ * `normalizeMessagesForAPI`'s `errorToBlockTypes` map can self-heal existing
+ * transcripts by stripping `image` blocks from the preceding user message
+ * on resume.
+ */
+export function getVisionNotSupportedErrorMessage(): string {
+  const [nonInteractiveMessage, interactiveMessage] =
+    getVisionNotSupportedErrorMessages()
+  return getIsNonInteractiveSession()
+    ? nonInteractiveMessage!
+    : interactiveMessage!
+}
 export const OAUTH_ORG_NOT_ALLOWED_ERROR_MESSAGE =
   'Your account does not have access to OpenClaude. Please run /login.'
 

src/services/api/openaiErrorClassification.test.ts

@@ -73,6 +73,39 @@ test('classifies 404 with images as vision_not_supported', () => {
   expect(failure.hint).toContain('image')
 })
 
+test('classifies 400 with "text is not set" + images as vision_not_supported (issue #1421)', () => {
+  const failure = classifyOpenAIHttpFailure({
+    status: 400,
+    body: '{"error":{"code":"400","message":"Param Incorrect","param":"`text` is not set","type":""}}',
+    hasImages: true,
+  })
+
+  expect(failure.category).toBe('vision_not_supported')
+  expect(failure.retryable).toBe(false)
+  expect(failure.hint).toContain('image')
+})
+
+test('classifies 400 with "text is required" + images as vision_not_supported (issue #1421)', () => {
+  const failure = classifyOpenAIHttpFailure({
+    status: 400,
+    body: '{"error":{"message":"text parameter is required"}}',
+    hasImages: true,
+  })
+
+  expect(failure.category).toBe('vision_not_supported')
+})
+
+test('does not classify 400 with "text is not set" when request has no images', () => {
+  const failure = classifyOpenAIHttpFailure({
+    status: 400,
+    body: '{"error":{"message":"text is not set"}}',
+    hasImages: false,
+  })
+
+  // Without images, "text is not set" is unrelated to vision capability.
+  expect(failure.category).not.toBe('vision_not_supported')
+})
+
 test('classifies context-overflow responses', () => {
   const failure = classifyOpenAIHttpFailure({
     status: 500,

src/services/api/openaiErrorClassification.ts

@@ -158,6 +158,34 @@ function isMalformedProviderResponse(body: string): boolean {
   )
 }
 
+/**
+ * Detect provider messages that complain about a missing/required `text`
+ * field on an otherwise image-bearing payload. Xiaomi Mimo surfaces this as
+ * `{"error":{"code":"400","message":"Param Incorrect","param":"`text` is not set"}}`
+ * (with backticks around `text`) when a `role: "tool"` message carries
+ * images but no text part. Other OpenAI-compatible providers may phrase
+ * it differently — match liberally.
+ *
+ * Only meaningful when `hasImages` is true (we never want this branch to fire
+ * for text-only requests, which legitimately lack a text field on vision-only
+ * payloads).
+ */
+function isMissingTextPartMessage(body: string): boolean {
+  // Strip backticks so `\`text\` is not set` matches the same patterns as
+  // `text is not set` — the Xiaomi Mimo 400 body wraps `text` in backticks
+  // inside the `param` field, which trips naive substring matching.
+  const lower = body.toLowerCase().replace(/`/g, '')
+  return (
+    lower.includes('text is not set') ||
+    lower.includes('text is required') ||
+    lower.includes('text parameter is required') ||
+    lower.includes('text parameter is missing') ||
+    lower.includes('missing text') ||
+    lower.includes('"param":"text"') ||
+    lower.includes('"param": "text"')
+  )
+}
+
 function isModelNotFoundMessage(body: string): boolean {
   const lower = body.toLowerCase()
   return (
@@ -344,6 +372,26 @@ export function classifyOpenAIHttpFailure(options: {
     }
   }
 
+  // Xiaomi Mimo and similar OpenAI-compatible providers reject image-bearing
+  // `role: "tool"` messages with a 400 carrying `text is not set` instead of
+  // a 404. Classify the same way as the 404 + hasImages branch so the user
+  // gets actionable guidance rather than the raw API error (issue #1421).
+  if (
+    options.status === 400 &&
+    options.hasImages &&
+    isMissingTextPartMessage(body)
+  ) {
+    return {
+      source: 'http',
+      category: 'vision_not_supported',
+      retryable: false,
+      status: options.status,
+      message: body,
+      requestUrl: options.url,
+      hint: 'The provider rejected a request containing an image (likely a tool result) because it did not include a text part. The model may not support image/vision inputs.',
+    }
+  }
+
   if (options.status === 404) {
     const isRemote = hostname !== null && !isLocalHost
     return {

src/services/api/openaiShim.test.ts

@@ -1950,7 +1950,11 @@ test('preserves image tool results as placeholders in follow-up requests', async
     text?: string
     image_url?: { url: string }
   }>
+  // Issue #1421: image-only tool results now get a placeholder text part
+  // prepended so OpenAI-compatible providers that require a `text` field on
+  // `role: "tool"` messages (e.g. Xiaomi Mimo) don't 400 with "text is not set".
   expect(parts).toEqual([
+    { type: 'text', text: 'Image attached.' },
     {
       type: 'image_url',
       image_url: { url: 'data:image/png;base64,ZmFrZQ==' },

src/services/api/openaiShim.ts

@@ -408,7 +408,12 @@ function convertToolResultContent(
     parts.unshift({ type: 'text', text: 'Error:' })
   }
 
-  return parts
+  // Defense in depth (issue #1421): some OpenAI-compatible providers (e.g.
+  // Xiaomi Mimo) reject `role: "tool"` messages whose `content` is image-only
+  // with a 400 "text is not set". Prepend a placeholder text part so the
+  // payload always carries a text component alongside any images, mirroring
+  // the existing behavior for user-role messages.
+  return ensureTextPartForImageContent(parts)
 }
 
 function convertContentBlocks(

src/tools/FileReadTool/FileReadTool.ts

@@ -64,6 +64,7 @@ import {
   isPDFSupported,
   parsePDFPageRange,
 } from '../../utils/pdfUtils.js'
+import { checkVisionCapabilityForFile } from '../../utils/visionUtils.js'
 import {
   checkReadPermissionForTool,
   matchingRuleForInput,
@@ -524,14 +525,6 @@ export const FileReadTool = buildTool({
       }
     }
 
-    // SECURITY: UNC path check (no I/O) — defer filesystem operations
-    // until after user grants permission to prevent NTLM credential leaks
-    const isUncPath =
-      fullFilePath.startsWith('\\\\') || fullFilePath.startsWith('//')
-    if (isUncPath) {
-      return { result: true }
-    }
-
     // Binary extension check (string check on extension only, no I/O).
     // PDF, images, and SVG are excluded - this tool renders them natively.
     const ext = path.extname(fullFilePath).toLowerCase()
@@ -547,6 +540,35 @@ export const FileReadTool = buildTool({
       }
     }
 
+    // Vision-capability gate: refuse image reads when the active model
+    // explicitly lacks `supportsVision` (e.g. Xiaomi Mimo V2.5 Pro / Flash,
+    // Llama, Mistral). Returning early surfaces a clear `<tool_use_error>`
+    // to the model so it can pivot to a text-based approach (Bash `file`,
+    // `identify`, OCR) or `/model` to switch to a vision-capable model —
+    // instead of producing an image-only tool result that the provider
+    // rejects with a generic 400 (issue #1421).
+    const visionCheck = checkVisionCapabilityForFile(
+      fullFilePath,
+      toolUseContext.options.mainLoopModel,
+      {
+        baseUrl:
+          toolUseContext.options.providerOverride?.baseURL ??
+          process.env.OPENAI_BASE_URL ??
+          process.env.OPENAI_API_BASE,
+      },
+    )
+    if (visionCheck.result === false) {
+      return visionCheck
+    }
+
+    // SECURITY: UNC path check (no I/O) — defer filesystem operations
+    // until after user grants permission to prevent NTLM credential leaks
+    const isUncPath =
+      fullFilePath.startsWith('\\\\') || fullFilePath.startsWith('//')
+    if (isUncPath) {
+      return { result: true }
+    }
+
     // Block specific device files that would hang (infinite output or blocking input).
     // This is a path-based check with no I/O — safe special files like /dev/null are allowed.
     if (isBlockedDevicePath(fullFilePath)) {