plugin-ai-api 1.0.20 → 1.0.21

package/src/server/plugin.ts

@@ -8,12 +8,13 @@
  */
 
 import { Plugin } from '@nocobase/server';
-import { createAiLlmRouter } from './routes/router';
+import { createAiLlmRouter, AI_LLM_PREFIX } from './routes/router';
 import aiApiConfigResource from './resource/ai-api-config';
 import aiApiUsageMonitorResource from './resource/ai-api-usage-monitor';
 import { RateLimiter } from './utils/rate-limiter';
 import { invalidateRolePermissionCache } from './middleware/role-permission';
-import { validateModelPrice, validateQuotaPolicy } from './validation';
+import { validateModelPrice, validateModelMetadata, validateQuotaPolicy } from './validation';
+import { AI_API_ACL_SNIPPET } from '../constants';
 
 // Ensure dayjs timezone + utc plugins are loaded.
 // Some Docker builds ship an older @nocobase/utils whose dayjs.js does not
@@ -43,13 +44,31 @@ export class PluginAiApiServer extends Plugin {
     this.app.db.on('aiApiModelPrices.beforeSave', async (model) => {
       await validateModelPrice(this.db, model);
     });
+    this.app.db.on('aiApiModelMetadata.beforeSave', (model) => {
+      validateModelMetadata(model);
+    });
     this.app.db.on('aiApiUserQuotaPolicies.beforeSave', (model) => {
       validateQuotaPolicy(model);
     });
   }
 
   async load() {
-    // 1. Register raw Koa middleware for OpenAI-compatible endpoints
+    // 1. Claim body parsing for our own routes before the core bodyParser runs.
+    //    Core registers koa-bodyparser with a global REQUEST_BODY_LIMIT (10mb by
+    //    default) much earlier in the stack, so without this the gateway's own
+    //    configurable limit is unreachable: an oversized vision request would be
+    //    rejected by core with a non-OpenAI error shape. `disableBodyParser` makes
+    //    koa-bodyparser skip the request, leaving ctx.request.body undefined so
+    //    createAiLlmRouter reads and caps the raw stream itself.
+    this.app.use(
+      async (ctx, next) => {
+        if (ctx.path.startsWith(AI_LLM_PREFIX)) ctx.disableBodyParser = true;
+        await next();
+      },
+      { tag: 'aiApiDisableBodyParser', before: 'bodyParser' },
+    );
+
+    // 2. Register raw Koa middleware for OpenAI-compatible endpoints
     //    Must run before 'resourcer' so URL paths match OpenAI convention
     // OIDC access tokens must first pass through plugin-idp-oauth, which validates
     // issuer/audience/scope and rewrites them to a NocoBase internal token.
@@ -68,11 +87,12 @@ export class PluginAiApiServer extends Plugin {
 
     // 3. Set ACL permissions for admin config + role permissions management
     this.app.acl.registerSnippet({
-      name: `pm.${this.name}.configuration`,
+      name: AI_API_ACL_SNIPPET,
       actions: [
         'aiApiConfig:*',
         'aiApiRolePermissions:*',
         'aiApiModelPrices:*',
+        'aiApiModelMetadata:*',
         'aiApiUserQuotaPolicies:*',
         'aiApiUserQuotaBuckets:list',
         'aiApiUserQuotaBuckets:get',

package/src/server/resource/ai-api-config.ts

@@ -8,6 +8,24 @@
  */
 
 import { ResourceOptions } from '@nocobase/resourcer';
+import { MAX_REQUEST_BODY_MB_LIMIT } from '../routes/router';
+
+const DEFAULT_MAX_REQUEST_BODY_MB = 10;
+
+/**
+ * The gateway buffers each request body in memory, so an out-of-range value
+ * here is a denial-of-service footgun rather than a harmless setting.
+ */
+function coerceMaxRequestBodyMb(value: unknown): number {
+  const mb = Number(value);
+  if (!Number.isSafeInteger(mb) || mb <= 0) {
+    throw new Error(`maxRequestBodyMb must be a positive integer (1-${MAX_REQUEST_BODY_MB_LIMIT}).`);
+  }
+  if (mb > MAX_REQUEST_BODY_MB_LIMIT) {
+    throw new Error(`maxRequestBodyMb cannot exceed ${MAX_REQUEST_BODY_MB_LIMIT}.`);
+  }
+  return mb;
+}
 
 /**
  * Resource for managing AI API configuration via NocoBase admin UI.
@@ -29,6 +47,7 @@ const aiApiConfigResource: ResourceOptions = {
             defaultLlmService: '',
             enabledLlmServices: [],
             rateLimitPerMinute: 60,
+            maxRequestBodyMb: 10,
             quotaEnabled: false,
             defaultReservationOutputTokens: 4096,
             options: {},
@@ -52,6 +71,7 @@ const aiApiConfigResource: ResourceOptions = {
             defaultLlmService: values.defaultLlmService ?? '',
             enabledLlmServices: values.enabledLlmServices ?? [],
             rateLimitPerMinute: values.rateLimitPerMinute ?? 60,
+            maxRequestBodyMb: coerceMaxRequestBodyMb(values.maxRequestBodyMb ?? DEFAULT_MAX_REQUEST_BODY_MB),
             quotaEnabled: values.quotaEnabled ?? false,
             defaultReservationOutputTokens: values.defaultReservationOutputTokens ?? 4096,
             options: values.options ?? {},
@@ -64,6 +84,9 @@ const aiApiConfigResource: ResourceOptions = {
         if (values.defaultLlmService !== undefined) updateData.defaultLlmService = values.defaultLlmService;
         if (values.enabledLlmServices !== undefined) updateData.enabledLlmServices = values.enabledLlmServices;
         if (values.rateLimitPerMinute !== undefined) updateData.rateLimitPerMinute = values.rateLimitPerMinute;
+        if (values.maxRequestBodyMb !== undefined) {
+          updateData.maxRequestBodyMb = coerceMaxRequestBodyMb(values.maxRequestBodyMb);
+        }
         if (values.quotaEnabled !== undefined) updateData.quotaEnabled = values.quotaEnabled;
         if (values.defaultReservationOutputTokens !== undefined) {
           updateData.defaultReservationOutputTokens = values.defaultReservationOutputTokens;

package/src/server/routes/agent-completions.ts

@@ -27,6 +27,7 @@ import {
 } from '../utils/ai-employee-runtime';
 import { setAiApiUsageUnavailable } from '../usage';
 import type PluginAiApiServer from '../plugin';
+import { markAiApiFirstProviderOutput } from '../utils/app-observability';
 
 /**
  * POST /api/ai-llm/v1/chat/completions (agent mode)
@@ -281,85 +282,97 @@ export async function handleAgentCompletions(ctx: Context, plugin: PluginAiApiSe
         // Don't actually end — we control this
       };
 
-      // Intercept write() — translate NocoBase SSE → OpenAI SSE
-      (ctx.res as any).write = (data: Buffer | string): boolean => {
-        pendingSse += typeof data === 'string' ? data : data.toString('utf8');
-        const frames = pendingSse.split('\n\n');
-        pendingSse = frames.pop() || '';
-
-        for (const frame of frames) {
-          for (const line of frame.split('\n')) {
-            const trimmed = line.trim();
-            if (!trimmed.startsWith('data: ')) continue;
-
-            const jsonStr = trimmed.substring(6);
-            if (!jsonStr) continue;
-
-            try {
-              const event = JSON.parse(jsonStr);
-
-              if (event.type === 'content' && event.body) {
-                // Content chunk — forward as OpenAI delta
+      // Translate one buffered NocoBase SSE frame → OpenAI SSE.
+      const processSseFrame = (frame: string): void => {
+        for (const line of frame.split('\n')) {
+          const trimmed = line.trim();
+          if (!trimmed.startsWith('data: ')) continue;
+
+          const jsonStr = trimmed.substring(6);
+          if (!jsonStr) continue;
+
+          try {
+            const event = JSON.parse(jsonStr);
+
+            if (event.type === 'content' && event.body) {
+              markAiApiFirstProviderOutput(ctx);
+              // Content chunk — forward as OpenAI delta
+              originalWrite(
+                formatSSE(
+                  toOpenAIStreamChunk({
+                    id: completionId,
+                    model: body.model,
+                    delta: { content: String(event.body) },
+                  }),
+                ),
+              );
+            } else if (event.type === 'tool_call_chunks' && Array.isArray(event.body)) {
+              const chunks = toOpenAIToolCallChunks(event.body);
+              if (chunks.length) {
+                markAiApiFirstProviderOutput(ctx);
+                sawToolCalls = true;
                 originalWrite(
                   formatSSE(
                     toOpenAIStreamChunk({
                       id: completionId,
                       model: body.model,
-                      delta: { content: String(event.body) },
+                      delta: { tool_calls: chunks },
                     }),
                   ),
                 );
-              } else if (event.type === 'tool_call_chunks' && Array.isArray(event.body)) {
-                const chunks = toOpenAIToolCallChunks(event.body);
-                if (chunks.length) {
-                  sawToolCalls = true;
-                  originalWrite(
-                    formatSSE(
-                      toOpenAIStreamChunk({
-                        id: completionId,
-                        model: body.model,
-                        delta: { tool_calls: chunks },
-                      }),
-                    ),
-                  );
-                }
-              } else if (!sawToolCalls && event.type === 'tool_calls' && Array.isArray(event.body?.toolCalls)) {
-                const chunks = toOpenAIToolCallChunks(event.body.toolCalls);
-                if (chunks.length) {
-                  sawToolCalls = true;
-                  originalWrite(
-                    formatSSE(
-                      toOpenAIStreamChunk({
-                        id: completionId,
-                        model: body.model,
-                        delta: { tool_calls: chunks },
-                      }),
-                    ),
-                  );
-                }
-              } else if (event.type === 'error' && event.body) {
-                // Error from the agent — surface as SSE error object
+              }
+            } else if (!sawToolCalls && event.type === 'tool_calls' && Array.isArray(event.body?.toolCalls)) {
+              const chunks = toOpenAIToolCallChunks(event.body.toolCalls);
+              if (chunks.length) {
+                markAiApiFirstProviderOutput(ctx);
+                sawToolCalls = true;
                 originalWrite(
-                  formatSSE({
-                    error: {
-                      message: String(event.body),
-                      type: 'server_error',
-                      code: 'agent_error',
-                    },
-                  }),
+                  formatSSE(
+                    toOpenAIStreamChunk({
+                      id: completionId,
+                      model: body.model,
+                      delta: { tool_calls: chunks },
+                    }),
+                  ),
                 );
               }
-              // stream_start, stream_end, tool_call_status, web_search,
-              // reasoning and new_message are NocoBase-only events and are ignored.
-              // These are NocoBase-internal events not part of the OpenAI protocol.
-            } catch {
-              // Non-JSON SSE line — ignore
+            } else if (event.type === 'error' && event.body) {
+              // Error from the agent — surface as SSE error object
+              originalWrite(
+                formatSSE({
+                  error: {
+                    message: String(event.body),
+                    type: 'server_error',
+                    code: 'agent_error',
+                  },
+                }),
+              );
             }
+            // stream_start, stream_end, tool_call_status, web_search,
+            // reasoning and new_message are NocoBase-only events and are ignored.
+            // These are NocoBase-internal events not part of the OpenAI protocol.
+          } catch {
+            // Non-JSON SSE line — ignore
           }
         }
+      };
+
+      // Intercept write() — buffer input and translate complete frames.
+      (ctx.res as any).write = (data: Buffer | string): boolean => {
+        pendingSse += typeof data === 'string' ? data : data.toString('utf8');
+        const frames = pendingSse.split('\n\n');
+        pendingSse = frames.pop() || '';
+        for (const frame of frames) processSseFrame(frame);
         return true;
       };
 
+      // Flush any trailing frame that was not terminated by '\n\n'.
+      const flushPendingSse = (): void => {
+        if (!pendingSse.trim()) return;
+        processSseFrame(pendingSse);
+        pendingSse = '';
+      };
+
       try {
         const aiEmployee = new AIEmployee(
           createAIEmployeeOptions(ctx, employeeRecord, sessionId, {
@@ -385,6 +398,8 @@ export async function handleAgentCompletions(ctx: Context, plugin: PluginAiApiSe
         ctx.res.off('close', abortAgent);
 
         if (streamSucceeded && !ctx.res.destroyed) {
+          // Emit any final frame the agent left unterminated before closing.
+          flushPendingSse();
           originalWrite(
             formatSSE(
               toOpenAIStreamChunk({

package/src/server/routes/auth.ts

@@ -47,7 +47,20 @@ export async function authenticateBearer(ctx: Context): Promise<boolean> {
         const rolesRepository = ctx.db.getRepository('users.roles', ctx.state.currentUser.id);
         const roles = await rolesRepository.find({ fields: ['name'] });
         const roleNames = roles.map((role: { name: string }) => role.name);
-        ctx.state.currentRole = roleNames.includes(requestedRole) ? requestedRole : roleNames[0];
+        // An explicit X-Role that the user does not hold must be rejected, not
+        // silently downgraded to the first role — otherwise a caller could probe
+        // for access under a role they were never granted.
+        if (requestedRole && !roleNames.includes(requestedRole)) {
+          ctx.status = 403;
+          ctx.body = toOpenAIError(
+            403,
+            `Requested role '${requestedRole}' is not assigned to this user`,
+            'permission_denied',
+            'role_not_permitted',
+          );
+          return false;
+        }
+        ctx.state.currentRole = requestedRole || roleNames[0];
         ctx.state.currentRoles = ctx.state.currentRole ? [ctx.state.currentRole] : roleNames;
       }
       return true;

package/src/server/routes/chat-completions.ts

@@ -19,11 +19,17 @@ import {
   OpenAIToolCallChunk,
 } from '../utils/openai-format';
 import { resolveModelString } from '../utils/resolve-service';
-import { createRequestAbortController, isStreamingRequested, writeResponse } from '../utils/streaming';
+import {
+  createRequestAbortController,
+  isClientDisconnected,
+  isStreamingRequested,
+  writeResponse,
+} from '../utils/streaming';
 import { checkEmployeeAccess } from '../middleware/role-permission';
 import { extractProviderRequestId, normalizeUsage, setAiApiUsageResult, type Usage } from '../usage';
 import type PluginAiApiServer from '../plugin';
 import { AiApiQuotaError, markLlmProviderAttempted, prepareLlmBilling } from '../billing';
+import { markAiApiFirstProviderOutput } from '../utils/app-observability';
 
 /**
  * POST /api/ai-llm/v1/chat/completions
@@ -47,6 +53,30 @@ export async function handleChatCompletions(ctx: Context, plugin: PluginAiApiSer
     return;
   }
 
+  const messageProblem = findMessageProblem(body.messages);
+  if (messageProblem) {
+    ctx.status = 400;
+    ctx.body = toOpenAIError(
+      400,
+      `Invalid messages[${messageProblem.index}]: ${messageProblem.reason}.`,
+      'invalid_request_error',
+      'invalid_message',
+    );
+    return;
+  }
+
+  const blockProblem = findContentBlockProblem(body.messages);
+  if (blockProblem) {
+    ctx.status = 400;
+    ctx.body = toOpenAIError(
+      400,
+      `Invalid content block in messages[${blockProblem.index}]: ${blockProblem.reason}.`,
+      'invalid_request_error',
+      'invalid_content_block',
+    );
+    return;
+  }
+
   // ─── Reject unsupported n parameter ───
   if (body.n !== undefined && body.n !== null && body.n !== 1) {
     ctx.status = 400;
@@ -179,9 +209,14 @@ export async function handleChatCompletions(ctx: Context, plugin: PluginAiApiSer
     // ─── Build message tuples for LangChain model ───
     // LangChain chat models accept [role, content] tuples or BaseMessage objects.
     // We use tuples to avoid importing @langchain/core directly.
+    //
+    // `content` may be a string OR an array of content blocks (OpenAI vision
+    // format: [{type:'text'}, {type:'image_url', image_url:{url:'data:...'}}]).
+    // Arrays must be forwarded structurally — stringifying them would turn an
+    // image into literal JSON text and the model would never see the picture.
     const langchainMessages = messages.map((msg: any) => {
       const role = msg.role === 'assistant' ? 'ai' : msg.role;
-      const content = typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content);
+      const content = normalizeMessageContent(msg.content);
       if (msg.role === 'assistant' && msg.tool_calls) {
         return {
           role,
@@ -193,7 +228,7 @@ export async function handleChatCompletions(ctx: Context, plugin: PluginAiApiSer
       if (msg.role === 'tool') {
         return { role: 'tool', content, tool_call_id: msg.tool_call_id, name: msg.name };
       }
-      return [role, content] as [string, string];
+      return [role, content] as [string, MessageContent];
     });
 
     const completionId = generateCompletionId();
@@ -326,6 +361,7 @@ async function handleStreamingCompletion(
       }
 
       if (content) {
+        markAiApiFirstProviderOutput(ctx);
         await writeResponse(
           ctx,
           formatSSE(
@@ -340,6 +376,7 @@ async function handleStreamingCompletion(
 
       const toolCallChunks = normalizeToolCallChunks(chunk.tool_call_chunks);
       if (toolCallChunks.length) {
+        markAiApiFirstProviderOutput(ctx);
         finishReason = 'tool_calls';
         await writeResponse(
           ctx,
@@ -370,6 +407,7 @@ async function handleStreamingCompletion(
     setAiApiUsageResult(ctx, usage, { gatewayResponseId: completionId, providerRequestId });
     ctx.state.aiApiStreamResult = { succeeded: true, id: completionId };
   } catch (err) {
+    const cancelled = isClientDisconnected(ctx, err);
     ctx.log.error('AI API streaming error:', err);
     // Send error as SSE event before closing
     if (!ctx.res.destroyed && !ctx.res.writableEnded) {
@@ -384,7 +422,11 @@ async function handleStreamingCompletion(
       );
     }
     setAiApiUsageResult(ctx, usage, { gatewayResponseId: completionId, providerRequestId });
-    ctx.state.aiApiStreamResult = { succeeded: false, id: completionId, errorCode: 'stream_error' };
+    ctx.state.aiApiStreamResult = {
+      succeeded: false,
+      id: completionId,
+      errorCode: cancelled ? 'client_disconnected' : 'stream_error',
+    };
   } finally {
     requestAbort.dispose();
     if (!ctx.res.writableEnded && !ctx.res.destroyed) ctx.res.end();
@@ -395,6 +437,222 @@ function getErrorMessage(error: unknown, fallback: string) {
   return error instanceof Error && error.message ? error.message : fallback;
 }
 
+/**
+ * Content block types every provider adapter in `@nocobase/plugin-ai` maps to a
+ * native equivalent.
+ *
+ * Anything else is rejected rather than forwarded: the LangChain block
+ * converters are if/else-if chains with no fallback branch, so an unrecognized
+ * block (OpenAI's `{type:'file'}` on Anthropic, for example) yields nothing and
+ * the model answers as if the attachment was never sent. A 400 is far easier to
+ * debug than a confidently wrong completion.
+ */
+const SUPPORTED_CONTENT_BLOCK_TYPES = new Set(['text', 'image_url']);
+
+/**
+ * Deliberately mirrors the exact grammar `@langchain/core`'s `parseBase64DataUrl`
+ * accepts (`\w+/\w+`, standard base64). A looser pattern here would admit URLs
+ * the provider adapter then fails to parse — it falls through to `new URL()`,
+ * sees the `data:` protocol and throws, which reaches the client as a 500.
+ * Compound subtypes such as `image/svg+xml` are rejected for that reason.
+ */
+const BASE64_DATA_URL_PATTERN = /^data:(\w+\/\w+);base64,([A-Za-z0-9+/]+=*)$/;
+
+/**
+ * The regex above is LangChain's, and LangChain's is lenient: `A===`, `A=`,
+ * `AAAAA` and `AAAA=` all match it but are not decodable base64. LangChain then
+ * calls `atob` on the payload, which throws a DOMException for each of them, and
+ * that escapes as an HTTP 500. Re-encoding is the cheapest exact check — the
+ * canonical form of a valid payload is the payload itself.
+ */
+function isDecodableBase64(payload: string): boolean {
+  try {
+    return Buffer.from(payload, 'base64').toString('base64') === payload;
+  } catch {
+    return false;
+  }
+}
+
+export interface ContentBlockProblem {
+  index: number;
+  reason: string;
+}
+
+/**
+ * Roles `_constructMessageFromParams` can turn into a message. Anything else
+ * reaches its final `else` and throws MESSAGE_COERCION_FAILURE.
+ *
+ * `function` is deliberately absent: OpenAI deprecated it, and LangChain has no
+ * branch for it despite mapping the class name internally.
+ */
+const SUPPORTED_MESSAGE_ROLES = new Set(['system', 'developer', 'user', 'human', 'assistant', 'ai', 'tool']);
+
+/**
+ * Validate the shape of each message before any provider work happens.
+ *
+ * Requiring only "non-empty array" lets `messages: [null]` through to
+ * `messages.some((m) => m.role === 'system')`, which throws a TypeError and is
+ * reported as a 500. An unsupported role travels further still and dies inside
+ * LangChain with MESSAGE_COERCION_FAILURE. Both are caller errors, so both
+ * should be a 400 that names the offending index.
+ */
+export function findMessageProblem(messages: unknown[]): ContentBlockProblem | undefined {
+  for (const [index, message] of messages.entries()) {
+    if (!isRecord(message)) return { index, reason: 'each message must be an object' };
+
+    const role = typeof message.role === 'string' ? message.role : undefined;
+    if (!role) return { index, reason: "each message requires a string 'role' field" };
+    if (!SUPPORTED_MESSAGE_ROLES.has(role)) {
+      return {
+        index,
+        reason: `role '${role}' is not supported — use one of ` + `${[...SUPPORTED_MESSAGE_ROLES].join(', ')}`,
+      };
+    }
+
+    if (role === 'tool' && typeof message.tool_call_id !== 'string') {
+      return { index, reason: "a 'tool' message requires a string 'tool_call_id' field" };
+    }
+
+    const { content } = message;
+    const hasToolCalls = Array.isArray(message.tool_calls) && message.tool_calls.length > 0;
+    if (content === undefined || content === null) {
+      // An assistant turn that only calls tools legitimately carries no content.
+      if ((role === 'assistant' || role === 'ai') && hasToolCalls) continue;
+      return { index, reason: "each message requires a 'content' field" };
+    }
+    if (typeof content !== 'string' && !Array.isArray(content)) {
+      return { index, reason: "'content' must be a string or an array of content blocks" };
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Validate the multimodal content blocks of a chat request.
+ *
+ * Checking `type` alone is not enough. The provider adapters either drop or
+ * throw on malformed blocks, and both outcomes surface badly:
+ *
+ * - A block whose payload fails every branch of the converter yields nothing,
+ *   so the model answers as if the attachment was never sent.
+ * - `_formatImage` throws on a malformed or non-http(s) URL, and that escapes as
+ *   a generic HTTP 500 instead of telling the caller what was wrong.
+ * - `parseBase64DataUrl` matches any `data:<type>/<subtype>;base64,` URL without
+ *   checking for `image/*`, so a PDF becomes an `image` block with
+ *   `media_type: application/pdf` that the model cannot read.
+ *
+ * Validating up front turns all of those into an actionable 400.
+ */
+export function findContentBlockProblem(messages: unknown[]): ContentBlockProblem | undefined {
+  for (const [index, message] of messages.entries()) {
+    const content = isRecord(message) ? message.content : undefined;
+    if (!Array.isArray(content)) continue;
+    for (const block of content) {
+      if (typeof block === 'string') continue;
+      const reason = describeContentBlockProblem(block);
+      if (reason) return { index, reason };
+    }
+  }
+  return undefined;
+}
+
+function describeContentBlockProblem(block: unknown): string | undefined {
+  if (!isRecord(block)) return 'each content block must be an object';
+
+  const type = typeof block.type === 'string' ? block.type : undefined;
+  if (!type) return "each content block requires a 'type' field";
+  if (!SUPPORTED_CONTENT_BLOCK_TYPES.has(type)) {
+    return (
+      `content block type '${type}' is not supported — this gateway forwards 'text' and 'image_url' only. ` +
+      `Send documents as text, or inline them as an 'image_url' data URL if the model reads images`
+    );
+  }
+
+  if (type === 'text') {
+    return typeof block.text === 'string' ? undefined : "a 'text' block requires a string 'text' field";
+  }
+
+  return describeImageUrlProblem(block.image_url);
+}
+
+function describeImageUrlProblem(imageUrl: unknown): string | undefined {
+  const url = typeof imageUrl === 'string' ? imageUrl : isRecord(imageUrl) ? imageUrl.url : undefined;
+  if (typeof url !== 'string' || url === '') {
+    return "an 'image_url' block requires a non-empty 'image_url.url' string";
+  }
+
+  if (url.startsWith('data:')) {
+    const match = BASE64_DATA_URL_PATTERN.exec(url);
+    if (!match) {
+      return (
+        `malformed base64 data URL. Expected 'data:<mime-type>;base64,<base64>' ` +
+        `with standard base64 (no whitespace or URL-safe characters)`
+      );
+    }
+    const mimeType = match[1].toLowerCase();
+    if (!mimeType.startsWith('image/')) {
+      return (
+        `data URL MIME type '${mimeType}' is not an image. Only 'image/*' data URLs are forwarded, ` +
+        `because providers reject or ignore other types on an 'image_url' block`
+      );
+    }
+    if (!isDecodableBase64(match[2])) {
+      return (
+        `base64 payload is not decodable. Check the padding and length — ` +
+        `the data must be a multiple of 4 characters with at most two trailing '='`
+      );
+    }
+    return undefined;
+  }
+
+  let protocol: string;
+  try {
+    protocol = new URL(url).protocol;
+  } catch {
+    return `'${url}' is not a valid URL. Use an http(s) URL or a base64 data URL`;
+  }
+  if (protocol !== 'http:' && protocol !== 'https:') {
+    return `URL protocol '${protocol}' is not supported. Use an http(s) URL or a base64 data URL`;
+  }
+  return undefined;
+}
+
+/**
+ * A LangChain message content value: plain text, or an array of content blocks
+ * (`{type:'text'}`, `{type:'image_url'}`, ...) for multimodal requests.
+ */
+type MessageContent = string | Record<string, unknown>[];
+
+/**
+ * Normalize an OpenAI `message.content` into something LangChain accepts.
+ *
+ * Content blocks are passed through unchanged so vision requests reach the
+ * provider intact — `@langchain/core` coerces `image_url` blocks into the
+ * provider's native format. Only genuinely unusable shapes (numbers, objects)
+ * are stringified as a last resort.
+ *
+ * The one rewrite is `image_url: '<url>'` → `image_url: { url: '<url>' }`.
+ * `isOpenAIDataBlock` gates on `_isObject(block.image_url)`, so the string form
+ * is never recognised as a data block: core forwards it untouched and only
+ * Anthropic's adapter happens to accept it. Widening it here keeps the lenient
+ * request working on every provider instead of just one.
+ */
+export function normalizeMessageContent(content: unknown): MessageContent {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content.map((block) => {
+      if (typeof block === 'string') return { type: 'text', text: block };
+      const record = block as Record<string, unknown>;
+      if (record?.type === 'image_url' && typeof record.image_url === 'string') {
+        return { ...record, image_url: { url: record.image_url } };
+      }
+      return record;
+    });
+  }
+  if (content === null || content === undefined) return '';
+  return JSON.stringify(content);
+}
+
 const GATEWAY_MANAGED_PARAMETERS = new Set(['model', 'messages', 'tools', 'tool_choice', 'stream', 'n']);
 
 export function getProviderRequestParameters(body: Record<string, unknown>): Record<string, unknown> {