plugin-ai-api 1.0.23 → 1.0.25

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

@@ -31,7 +31,9 @@ import { enforceModelAccess } from '../utils/user-permissions';
 import { extractProviderRequestId, normalizeUsage, setAiApiUsageResult, type Usage } from '../usage';
 import type PluginAiApiServer from '../plugin';
 import { AiApiQuotaError, markLlmProviderAttempted, prepareLlmBilling } from '../billing';
+import { DirectLlmContextError, prepareDirectLlmContext, type OpenAIMessage } from '../utils/direct-llm-context';
 import { markAiApiFirstProviderOutput } from '../utils/app-observability';
+import { FileContentBlock, FileProcessorError } from '../services/file-processor';
 
 /**
  * POST /api/ai-llm/v1/chat/completions
@@ -142,8 +144,6 @@ export async function handleChatCompletions(ctx: Context, plugin: PluginAiApiSer
       return;
     }
 
-    await prepareLlmBilling(ctx, resolved);
-
     const providerRequestParameters = getProviderRequestParameters(body);
     if (stream) {
       const streamOptions = isRecord(body.stream_options) ? body.stream_options : {};
@@ -166,13 +166,6 @@ export async function handleChatCompletions(ctx: Context, plugin: PluginAiApiSer
     if (body.presence_penalty !== undefined) modelOptions.presencePenalty = body.presence_penalty;
     if (body.stop !== undefined) modelOptions.stop = body.stop;
 
-    const Provider = providerMeta.provider;
-    const provider = new Provider({
-      app: ctx.app,
-      serviceOptions: service.options,
-      modelOptions,
-    });
-
     // ─── Build system prompt from AI Employee ───
     let systemPrompt = '';
     if (config?.defaultAiEmployee) {
@@ -197,12 +190,39 @@ export async function handleChatCompletions(ctx: Context, plugin: PluginAiApiSer
     }
 
     // ─── Build messages (inject system prompt if not provided by client) ───
-    const messages = [...body.messages];
+    let messages: OpenAIMessage[] = [...body.messages];
     const hasSystemMessage = messages.some((m: any) => m.role === 'system');
     if (systemPrompt && !hasSystemMessage) {
       messages.unshift({ role: 'system', content: systemPrompt });
     }
 
+    // ─── Process file / file_url blocks through the file processor service ───
+    messages = await Promise.all(
+      messages.map(async (msg) => ({
+        ...msg,
+        content: await processMessageContentFileBlocks(msg.content, ctx, plugin),
+      })),
+    );
+
+    const preparedContext = await prepareDirectLlmContext(ctx, {
+      serviceName: service.name,
+      modelId,
+      messages,
+      tools: body.tools,
+      maxCompletionTokens: body.max_completion_tokens,
+      maxTokens: body.max_tokens,
+    });
+    messages = preparedContext.messages;
+
+    await prepareLlmBilling(ctx, resolved);
+
+    const Provider = providerMeta.provider;
+    const provider = new Provider({
+      app: ctx.app,
+      serviceOptions: service.options,
+      modelOptions,
+    });
+
     // ─── 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.
@@ -257,15 +277,17 @@ export async function handleChatCompletions(ctx: Context, plugin: PluginAiApiSer
     }
   } catch (err) {
     ctx.log.error('AI API chat completions error:', err);
-    if (!ctx.res.headersSent) {
+    if (!ctx.res?.headersSent) {
       const isQuotaError = err instanceof AiApiQuotaError;
-      ctx.status = isQuotaError ? 429 : 500;
+      const isContextError = err instanceof DirectLlmContextError;
+      const isFileError = err instanceof FileProcessorError;
+      ctx.status = isQuotaError ? 429 : isContextError || isFileError ? 400 : 500;
       if (isQuotaError) ctx.set('X-RateLimit-Reason', err.code);
       ctx.body = toOpenAIError(
         ctx.status,
         getErrorMessage(err, 'Internal server error'),
-        isQuotaError ? 'quota_error' : 'server_error',
-        isQuotaError ? err.code : undefined,
+        isQuotaError ? 'quota_error' : isContextError || isFileError ? 'invalid_request_error' : 'server_error',
+        isQuotaError || isContextError || isFileError ? err.code : undefined,
       );
     }
   }
@@ -293,10 +315,15 @@ async function handleNonStreamingCompletion(
   }
 
   // Extract usage if available
-  const usage = setAiApiUsageResult(ctx, result.usage_metadata, {
-    gatewayResponseId: completionId,
-    providerRequestId: extractProviderRequestId(result),
-  });
+  const usage = setAiApiUsageResult(
+    ctx,
+    result.usage_metadata,
+    {
+      gatewayResponseId: completionId,
+      providerRequestId: extractProviderRequestId(result),
+    },
+    result.response_metadata,
+  );
 
   ctx.status = 200;
   const toolCalls = normalizeToolCalls(result.tool_calls);
@@ -463,7 +490,7 @@ function getErrorMessage(error: unknown, fallback: string) {
  * 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']);
+const SUPPORTED_CONTENT_BLOCK_TYPES = new Set(['text', 'image_url', 'file', 'file_url']);
 
 /**
  * Deliberately mirrors the exact grammar `@langchain/core`'s `parseBase64DataUrl`
@@ -474,6 +501,14 @@ const SUPPORTED_CONTENT_BLOCK_TYPES = new Set(['text', 'image_url']);
  */
 const BASE64_DATA_URL_PATTERN = /^data:(\w+\/\w+);base64,([A-Za-z0-9+/]+=*)$/;
 
+/**
+ * File blocks accept a wider range of MIME types than `image_url` blocks:
+ * documents such as `application/vnd.openxmlformats-officedocument.wordprocessingml.document`
+ * or `image/svg+xml` are valid attachments. The grammar still requires a proper
+ * `type/subtype` and standard base64 payload.
+ */
+const FILE_BASE64_DATA_URL_PATTERN = /^data:([^;\s]+);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
@@ -579,8 +614,8 @@ function describeContentBlockProblem(block: unknown): string | 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`
+      `content block type '${type}' is not supported — this gateway forwards 'text', 'image_url', ` +
+      `'file', and 'file_url' only. Send documents as text, or inline them as a 'file' / 'file_url' block`
     );
   }
 
@@ -588,9 +623,56 @@ function describeContentBlockProblem(block: unknown): string | undefined {
     return typeof block.text === 'string' ? undefined : "a 'text' block requires a string 'text' field";
   }
 
+  if (type === 'file') {
+    return describeFileProblem(block.file);
+  }
+
+  if (type === 'file_url') {
+    return describeFileUrlProblem(block.file_url);
+  }
+
   return describeImageUrlProblem(block.image_url);
 }
 
+function describeFileProblem(file: unknown): string | undefined {
+  if (!isRecord(file)) return "a 'file' block requires an object 'file' field";
+  const fileData = typeof file.file_data === 'string' ? file.file_data : undefined;
+  if (!fileData) return "a 'file' block requires a string 'file.file_data' field";
+  if (!fileData.startsWith('data:')) {
+    return "a 'file' block's 'file_data' must be a base64 data URL starting with 'data:'";
+  }
+  const match = FILE_BASE64_DATA_URL_PATTERN.exec(fileData);
+  if (!match || !match[1].includes('/')) {
+    return (
+      `malformed base64 data URL. Expected 'data:<mime-type>;base64,<base64>' ` +
+      `with a valid type/subtype and standard base64 (no whitespace or URL-safe characters)`
+    );
+  }
+  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;
+}
+
+function describeFileUrlProblem(fileUrl: unknown): string | undefined {
+  if (!isRecord(fileUrl)) return "a 'file_url' block requires an object 'file_url' field";
+  const url = typeof fileUrl.url === 'string' ? fileUrl.url : undefined;
+  if (!url) return "a 'file_url' block requires a string 'file_url.url' field";
+  let protocol: string;
+  try {
+    protocol = new URL(url).protocol;
+  } catch {
+    return `'${url}' is not a valid URL. Use an http(s) URL`;
+  }
+  if (protocol !== 'http:' && protocol !== 'https:') {
+    return `URL protocol '${protocol}' is not supported. Use an http(s) URL`;
+  }
+  return undefined;
+}
+
 function describeImageUrlProblem(imageUrl: unknown): string | undefined {
   const url = typeof imageUrl === 'string' ? imageUrl : isRecord(imageUrl) ? imageUrl.url : undefined;
   if (typeof url !== 'string' || url === '') {
@@ -669,7 +751,60 @@ export function normalizeMessageContent(content: unknown): MessageContent {
   return JSON.stringify(content);
 }
 
-const GATEWAY_MANAGED_PARAMETERS = new Set(['model', 'messages', 'tools', 'tool_choice', 'stream', 'n']);
+/**
+ * Run any `file` or `file_url` content blocks through the plugin's file
+ * processor service. Custom plugins can register processors to fetch URLs,
+ * extract text, OCR, etc. Other block types are left untouched.
+ *
+ * The service is invoked repeatedly if a processor returns another file-like
+ * block (e.g. a `file_url` becomes a `file` block, which may then be converted
+ * to images by the PDF processor).
+ */
+async function processMessageContentFileBlocks(
+  content: unknown,
+  ctx: Context,
+  plugin: PluginAiApiServer,
+): Promise<unknown> {
+  if (!Array.isArray(content)) return content;
+  const processed: unknown[] = [];
+  for (const block of content) {
+    processed.push(...(await processFileBlockChain(block, ctx, plugin, 0)));
+  }
+  return processed;
+}
+
+const MAX_FILE_PROCESSOR_CHAIN_DEPTH = 3;
+
+async function processFileBlockChain(
+  block: unknown,
+  ctx: Context,
+  plugin: PluginAiApiServer,
+  depth: number,
+): Promise<unknown[]> {
+  if (!isRecord(block) || (block.type !== 'file' && block.type !== 'file_url')) {
+    return [block];
+  }
+  if (depth > MAX_FILE_PROCESSOR_CHAIN_DEPTH) {
+    return [block];
+  }
+
+  const result = await plugin.fileProcessorService.process(block as FileContentBlock, { ctx });
+  const results = Array.isArray(result) ? result : [result];
+
+  const next: unknown[] = [];
+  for (const item of results) {
+    if (isRecord(item) && (item.type === 'file' || item.type === 'file_url')) {
+      // The output is still a file-like block; run it through the chain again
+      // so that a `file_url` -> `file` -> images pipeline can complete.
+      next.push(...(await processFileBlockChain(item, ctx, plugin, depth + 1)));
+    } else {
+      next.push(item);
+    }
+  }
+  return next;
+}
+
+const GATEWAY_MANAGED_PARAMETERS = new Set(['model', 'messages', 'prompt', 'tools', 'tool_choice', 'stream', 'n']);
 
 export function getProviderRequestParameters(body: Record<string, unknown>): Record<string, unknown> {
   return Object.fromEntries(

package/src/server/routes/completions.ts

@@ -23,9 +23,11 @@ import {
   isStreamingRequested,
   writeResponse,
 } from '../utils/streaming';
+import { getProviderRequestParameters, applyProviderRequestParameters } from './chat-completions';
 import { extractProviderRequestId, normalizeUsage, setAiApiUsageResult, type Usage } from '../usage';
 import type PluginAiApiServer from '../plugin';
 import { AiApiQuotaError, markLlmProviderAttempted, prepareLlmBilling } from '../billing';
+import { DirectLlmContextError, prepareDirectLlmContext, type OpenAIMessage } from '../utils/direct-llm-context';
 import { markAiApiFirstProviderOutput } from '../utils/app-observability';
 
 /**
@@ -114,8 +116,6 @@ export async function handleCompletions(ctx: Context, plugin: PluginAiApiServer)
       return;
     }
 
-    await prepareLlmBilling(ctx, resolved);
-
     const modelOptions: Record<string, any> = {
       model: modelId,
       llmService: service.name,
@@ -126,13 +126,6 @@ export async function handleCompletions(ctx: Context, plugin: PluginAiApiServer)
     if (body.max_tokens !== undefined) modelOptions.maxTokens = body.max_tokens;
     if (body.stop !== undefined) modelOptions.stop = body.stop;
 
-    const Provider = providerMeta.provider;
-    const provider = new Provider({
-      app: ctx.app,
-      serviceOptions: service.options,
-      modelOptions,
-    });
-
     // ─── Convert prompt to message tuple ───
     const prompt =
       typeof body.prompt === 'string'
@@ -142,7 +135,7 @@ export async function handleCompletions(ctx: Context, plugin: PluginAiApiServer)
           : String(body.prompt);
 
     // Inject system prompt from AI Employee if configured
-    const langchainMessages: [string, string][] = [];
+    const messages: OpenAIMessage[] = [];
     if (config?.defaultAiEmployee) {
       const employee = await ctx.db.getRepository('aiEmployees').findOne({
         filter: { username: config.defaultAiEmployee },
@@ -150,14 +143,35 @@ export async function handleCompletions(ctx: Context, plugin: PluginAiApiServer)
       if (employee) {
         const systemPrompt = employee.about || employee.defaultPrompt || '';
         if (systemPrompt) {
-          langchainMessages.push(['system', systemPrompt]);
+          messages.push({ role: 'system', content: systemPrompt });
         }
       }
     }
-    langchainMessages.push(['human', prompt]);
+    messages.push({ role: 'user', content: prompt });
+
+    const preparedContext = await prepareDirectLlmContext(ctx, {
+      serviceName: service.name,
+      modelId,
+      messages,
+      maxTokens: body.max_tokens,
+    });
+    await prepareLlmBilling(ctx, resolved);
+
+    const Provider = providerMeta.provider;
+    const provider = new Provider({
+      app: ctx.app,
+      serviceOptions: service.options,
+      modelOptions,
+    });
+    const langchainMessages = preparedContext.messages.map((message): [string, string] => [
+      message.role === 'user' ? 'human' : message.role,
+      String(message.content ?? ''),
+    ]);
 
     const completionId = generateCompletionId().replace('chatcmpl-', 'cmpl-');
     const chatModel = provider.createModel();
+    const providerRequestParameters = getProviderRequestParameters(body);
+    applyProviderRequestParameters(chatModel, providerRequestParameters);
     markLlmProviderAttempted(ctx);
 
     if (stream) {
@@ -168,21 +182,30 @@ export async function handleCompletions(ctx: Context, plugin: PluginAiApiServer)
         completionId,
         body.model,
         body.stream_options,
+        providerRequestParameters,
       );
     } else {
-      await handleNonStreamingTextCompletion(ctx, chatModel, langchainMessages, completionId, body.model);
+      await handleNonStreamingTextCompletion(
+        ctx,
+        chatModel,
+        langchainMessages,
+        completionId,
+        body.model,
+        providerRequestParameters,
+      );
     }
   } catch (err) {
     ctx.log.error('AI API completions error:', err);
-    if (!ctx.res.headersSent) {
+    if (!ctx.res?.headersSent) {
       const isQuotaError = err instanceof AiApiQuotaError;
-      ctx.status = isQuotaError ? 429 : 500;
+      const isContextError = err instanceof DirectLlmContextError;
+      ctx.status = isQuotaError ? 429 : isContextError ? 400 : 500;
       if (isQuotaError) ctx.set('X-RateLimit-Reason', err.code);
       ctx.body = toOpenAIError(
         ctx.status,
         getErrorMessage(err, 'Internal server error'),
-        isQuotaError ? 'quota_error' : 'server_error',
-        isQuotaError ? err.code : undefined,
+        isQuotaError ? 'quota_error' : isContextError ? 'invalid_request_error' : 'server_error',
+        isQuotaError || isContextError ? err.code : undefined,
       );
     }
   }
@@ -196,8 +219,9 @@ async function handleNonStreamingTextCompletion(
   messages: [string, string][],
   completionId: string,
   modelName: string,
+  providerRequestParameters: Record<string, unknown>,
 ) {
-  const result = await chatModel.invoke(messages);
+  const result = await chatModel.invoke(messages, providerRequestParameters);
 
   let text = '';
   if (typeof result.content === 'string') {
@@ -207,10 +231,15 @@ async function handleNonStreamingTextCompletion(
     text = textPart?.text || JSON.stringify(result.content);
   }
 
-  const usage = setAiApiUsageResult(ctx, result.usage_metadata, {
-    gatewayResponseId: completionId,
-    providerRequestId: extractProviderRequestId(result),
-  });
+  const usage = setAiApiUsageResult(
+    ctx,
+    result.usage_metadata,
+    {
+      gatewayResponseId: completionId,
+      providerRequestId: extractProviderRequestId(result),
+    },
+    result.response_metadata,
+  );
 
   ctx.status = 200;
   ctx.body = {
@@ -227,7 +256,14 @@ async function handleNonStreamingTextCompletion(
         finish_reason: 'stop',
       },
     ],
-    usage: usage ?? { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
+    usage: usage
+      ? {
+          prompt_tokens: usage.prompt_tokens,
+          completion_tokens: usage.completion_tokens,
+          total_tokens: usage.total_tokens,
+          prompt_tokens_details: { cached_tokens: usage.prompt_cache_tokens ?? null },
+        }
+      : { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0, prompt_tokens_details: { cached_tokens: null } },
   };
 }
 
@@ -240,6 +276,7 @@ async function handleStreamingTextCompletion(
   completionId: string,
   modelName: string,
   streamOptions: Record<string, unknown> | undefined,
+  providerRequestParameters: Record<string, unknown> | undefined,
 ) {
   ctx.set({
     'Content-Type': 'text/event-stream',
@@ -254,6 +291,7 @@ async function handleStreamingTextCompletion(
   let providerRequestId: string | undefined;
   try {
     const stream = await chatModel.stream(messages, {
+      ...providerRequestParameters,
       stream_options: { ...streamOptions, include_usage: true },
       signal: requestAbort.signal,
     });

package/src/server/services/__tests__/file-processor.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+  FileProcessorService,
+  base64FileForwarder,
+  httpFileUrlFetcher,
+  fetchFileAsBase64,
+  pdfFileProcessor,
+  type PdfToImageRenderer,
+} from '../file-processor';
+
+describe('FileProcessorService', () => {
+  it('forwards file blocks with base64 data unchanged', async () => {
+    const service = new FileProcessorService();
+    service.register(base64FileForwarder);
+
+    const block = { type: 'file', file: { file_data: 'data:application/pdf;base64,JVBERi0=' } };
+    const result = await service.process(block, { ctx: {} as any });
+
+    expect(result).toEqual(block);
+  });
+
+  it('returns the block unchanged when no processor can handle it', async () => {
+    const service = new FileProcessorService();
+    const block = { type: 'text', text: 'hello' };
+    const result = await service.process(block, { ctx: {} as any });
+
+    expect(result).toEqual(block);
+  });
+
+  it('allows custom processors to override default behavior', async () => {
+    const service = new FileProcessorService();
+    service.register(base64FileForwarder);
+
+    const customProcessor = {
+      name: 'customFileProcessor',
+      canHandle: (block: { type: string }) => block.type === 'file',
+      process: vi.fn().mockResolvedValue({ type: 'file', file: { file_data: 'data:text/plain;base64,SGVsbG8=' } }),
+    };
+    service.register(customProcessor);
+
+    const block = { type: 'file', file: { file_data: 'data:application/pdf;base64,JVBERi0=' } };
+    const result = await service.process(block, { ctx: {} as any });
+
+    expect(customProcessor.process).toHaveBeenCalledWith(block, { ctx: {} as any });
+    expect(result).toEqual({ type: 'file', file: { file_data: 'data:text/plain;base64,SGVsbG8=' } });
+  });
+
+  it('unregister removes a processor by name', () => {
+    const service = new FileProcessorService();
+    service.register(base64FileForwarder);
+    expect(service.list()).toHaveLength(1);
+
+    service.unregister(base64FileForwarder.name);
+    expect(service.list()).toHaveLength(0);
+  });
+});
+
+describe('httpFileUrlFetcher', () => {
+  it('fetches a file from an http(s) URL and converts it to a file block', async () => {
+    const originalFetch = globalThis.fetch;
+    const fileBuffer = Buffer.from('hello world');
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      headers: new Headers({
+        'content-type': 'text/plain',
+        'content-length': String(fileBuffer.length),
+      }),
+      arrayBuffer: () =>
+        Promise.resolve(fileBuffer.buffer.slice(fileBuffer.byteOffset, fileBuffer.byteOffset + fileBuffer.length)),
+    } as unknown as Response);
+
+    const result = await httpFileUrlFetcher.process(
+      { type: 'file_url', file_url: { url: 'https://example.com/hello.txt' } },
+      { ctx: {} as any },
+    );
+
+    expect(result).toMatchObject({
+      type: 'file',
+      file: {
+        file_data: expect.stringContaining('data:text/plain;base64,'),
+        mime_type: 'text/plain',
+        filename: 'hello.txt',
+      },
+    });
+
+    globalThis.fetch = originalFetch;
+  });
+
+  it('rejects unsupported protocols', async () => {
+    await expect(
+      httpFileUrlFetcher.process(
+        { type: 'file_url', file_url: { url: 'ftp://example.com/file.txt' } },
+        { ctx: {} as any },
+      ),
+    ).rejects.toThrow('protocol');
+  });
+});
+
+describe('fetchFileAsBase64', () => {
+  it('validates URL protocols', async () => {
+    await expect(fetchFileAsBase64('ftp://example.com/file.txt')).rejects.toThrow('protocol');
+  });
+
+  it('rejects malformed URLs', async () => {
+    await expect(fetchFileAsBase64('not a url')).rejects.toThrow('valid URL');
+  });
+});
+
+describe('pdfFileProcessor', () => {
+  const pdfBuffer = Buffer.from('%PDF-1.4\n1 0 obj\n<<\n>>\nendobj\n', 'binary');
+  const pdfDataUrl = `data:application/pdf;base64,${pdfBuffer.toString('base64')}`;
+
+  function createContext(config: { pdfRenderPagesAsImages?: boolean }, renderer?: PdfToImageRenderer | null) {
+    const service = new FileProcessorService();
+    if (renderer) {
+      service.registerPdfRenderer(renderer);
+    }
+    return {
+      ctx: {
+        db: {
+          getRepository: vi.fn((name: string) => {
+            if (name === 'aiApiConfig') {
+              return {
+                findOne: vi.fn().mockResolvedValue({
+                  get: (key: string) => (key === 'pdfRenderPagesAsImages' ? config.pdfRenderPagesAsImages : undefined),
+                  pdfRenderPagesAsImages: config.pdfRenderPagesAsImages,
+                }),
+              };
+            }
+            return { findOne: vi.fn() };
+          }),
+        },
+        app: {
+          pm: {
+            get: vi.fn().mockReturnValue({
+              fileProcessorService: service,
+            }),
+          },
+        },
+        log: { warn: vi.fn() },
+      },
+    } as any;
+  }
+
+  it('forwards a PDF file block when pdfRenderPagesAsImages is disabled', async () => {
+    const block = { type: 'file', file: { file_data: pdfDataUrl } } as any;
+    const result = await pdfFileProcessor.process(block, createContext({ pdfRenderPagesAsImages: false }));
+    expect(result).toBe(block);
+  });
+
+  it('forwards a PDF and warns when rendering is enabled but no renderer is registered', async () => {
+    const block = { type: 'file', file: { file_data: pdfDataUrl } } as any;
+    const context = createContext({ pdfRenderPagesAsImages: true });
+    const result = await pdfFileProcessor.process(block, context);
+
+    expect(result).toBe(block);
+    expect(context.ctx.log.warn).toHaveBeenCalledWith(
+      expect.stringContaining('pdfRenderPagesAsImages is enabled but no PdfToImageRenderer is registered'),
+    );
+  });
+
+  it('converts a PDF file block into image_url blocks when a renderer is registered', async () => {
+    const renderer: PdfToImageRenderer = {
+      name: 'mockRenderer',
+      render: vi.fn().mockResolvedValue([Buffer.from('page1'), Buffer.from('page2')]),
+    };
+    const block = { type: 'file', file: { file_data: pdfDataUrl } } as any;
+    const result = await pdfFileProcessor.process(block, createContext({ pdfRenderPagesAsImages: true }, renderer));
+
+    expect(Array.isArray(result)).toBe(true);
+    expect(result).toHaveLength(2);
+    expect((result as any[])[0]).toMatchObject({ type: 'image_url' });
+    expect((result as any[])[0].image_url.url).toMatch(/^data:image\/png;base64,/);
+  });
+
+  it('does not convert non-PDF file blocks', async () => {
+    const block = {
+      type: 'file',
+      file: { file_data: 'data:text/plain;base64,SGVsbG8=', filename: 'hello.txt' },
+    } as any;
+    expect(pdfFileProcessor.canHandle(block)).toBe(false);
+  });
+});