plugin-ai-api 1.0.23 → 1.0.25

package/src/server/__tests__/direct-llm-context.test.ts

@@ -0,0 +1,206 @@
+import type { Context } from '@nocobase/actions';
+import { describe, expect, it, vi } from 'vitest';
+import {
+  DirectLlmContextError,
+  prepareDirectLlmContext,
+  type OpenAIMessage,
+  parseImageDimensions,
+} from '../utils/direct-llm-context';
+
+function context({ behavior = 'reject', metadata = { contextWindow: 120, maxCompletionTokens: 40 } } = {}): Context {
+  return {
+    state: { currentUser: { id: 1 } },
+    db: {
+      getRepository: vi.fn((name: string) => {
+        if (name === 'aiApiModelMetadata') {
+          return {
+            findOne: vi.fn().mockResolvedValue({ get: (key: string) => metadata[key as keyof typeof metadata] }),
+          };
+        }
+        if (name === 'aiApiUserQuotaPolicies') {
+          return {
+            findOne: vi
+              .fn()
+              .mockResolvedValue({ get: (key: string) => (key === 'contextOverflowBehavior' ? behavior : undefined) }),
+          };
+        }
+        return { findOne: vi.fn() };
+      }),
+    },
+  } as unknown as Context;
+}
+
+function request(messages: OpenAIMessage[], tools?: unknown) {
+  return {
+    serviceName: 'test-service',
+    modelId: 'test-model',
+    messages,
+    tools,
+  };
+}
+
+// A 1x1 PNG encoded as a base64 data URL.
+const ONE_PIXEL_PNG =
+  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC';
+
+// A tiny valid base64 PDF payload (PDF header + minimal content).
+const TINY_PDF_BASE64 = 'data:application/pdf;base64,JVBERi0xLjAKPDwKPiEKZW5kb2JqCmVuZG9iagpl';
+
+// A PNG header with 1280x720 dimensions. The pixel data is truncated/invalid,
+// but the header is valid enough for dimension parsing to succeed.
+const LARGE_PNG_HEADER_BASE64 =
+  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABQAAAALQCAYAAADPfd1WAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoSAA';
+
+// The fixed conservative estimate used for http(s) image URLs.
+const VISION_HTTP_URL_ESTIMATE = 1024;
+
+function largeContext(): Context {
+  return context({ metadata: { contextWindow: 2000, maxCompletionTokens: 40 } });
+}
+
+describe('direct LLM context preparation', () => {
+  it('uses reject when the user has no enabled policy', async () => {
+    const ctx = context();
+    vi.mocked(ctx.db.getRepository).mockImplementation((name: string) => {
+      if (name === 'aiApiModelMetadata') {
+        return {
+          findOne: vi.fn().mockResolvedValue({ get: (key: string) => (key === 'contextWindow' ? 120 : 40) }),
+        } as never;
+      }
+      return { findOne: vi.fn().mockResolvedValue(null) } as never;
+    });
+
+    await expect(
+      prepareDirectLlmContext(ctx, request([{ role: 'user', content: 'x'.repeat(400) }])),
+    ).rejects.toMatchObject<Partial<DirectLlmContextError>>({ code: 'context_length_exceeded' });
+  });
+
+  it('keeps a request that fits the model input budget', async () => {
+    const messages = [{ role: 'user', content: 'hello' }];
+    const prepared = await prepareDirectLlmContext(context(), request(messages));
+
+    expect(prepared.messages).toBe(messages);
+    expect(prepared.truncated).toBe(false);
+    expect(prepared.inputTokenBudget).toBe(80);
+  });
+
+  it('rejects a requested output limit above model metadata', async () => {
+    await expect(
+      prepareDirectLlmContext(context(), { ...request([{ role: 'user', content: 'hello' }]), maxCompletionTokens: 41 }),
+    ).rejects.toMatchObject<Partial<DirectLlmContextError>>({ code: 'max_completion_tokens_exceeds_model_limit' });
+  });
+
+  it('truncates oldest complete turns while preserving instructions and newest turn', async () => {
+    const messages: OpenAIMessage[] = [
+      { role: 'system', content: 'Always answer safely.' },
+      { role: 'user', content: 'first '.repeat(30) },
+      { role: 'assistant', content: 'first answer '.repeat(20) },
+      { role: 'user', content: 'latest question' },
+    ];
+
+    const prepared = await prepareDirectLlmContext(context({ behavior: 'truncate' }), request(messages));
+
+    expect(prepared.truncated).toBe(true);
+    expect(prepared.messages).toEqual([messages[0], messages[3]]);
+    expect(messages).toHaveLength(4);
+  });
+
+  it('keeps assistant tool calls and their tool responses in the same turn', async () => {
+    const messages: OpenAIMessage[] = [
+      { role: 'user', content: 'old question '.repeat(30) },
+      { role: 'assistant', content: '', tool_calls: [{ id: 'call-old', type: 'function' }] },
+      { role: 'tool', tool_call_id: 'call-old', content: 'old result '.repeat(20) },
+      { role: 'user', content: 'latest question' },
+    ];
+
+    const prepared = await prepareDirectLlmContext(context({ behavior: 'truncate' }), request(messages));
+
+    expect(prepared.messages).toEqual([messages[3]]);
+  });
+
+  it('rejects when the newest turn cannot fit without cutting content', async () => {
+    await expect(
+      prepareDirectLlmContext(context({ behavior: 'truncate' }), request([{ role: 'user', content: 'x'.repeat(400) }])),
+    ).rejects.toMatchObject<Partial<DirectLlmContextError>>({ code: 'context_length_exceeded' });
+  });
+
+  it('estimates vision tokens for a base64 image_url and allows small payloads', async () => {
+    const prepared = await prepareDirectLlmContext(
+      largeContext(),
+      request([{ role: 'user', content: [{ type: 'image_url', image_url: { url: ONE_PIXEL_PNG } }] }]),
+    );
+
+    expect(prepared.estimatedInputTokens).toBeGreaterThan(0);
+    expect(prepared.truncated).toBe(false);
+  });
+
+  it('estimates a fixed conservative token count for http(s) image_url URLs', async () => {
+    const prepared = await prepareDirectLlmContext(
+      largeContext(),
+      request([
+        { role: 'user', content: [{ type: 'image_url', image_url: { url: 'https://example.com/image.png' } }] },
+      ]),
+    );
+
+    expect(prepared.estimatedInputTokens).toBeGreaterThanOrEqual(VISION_HTTP_URL_ESTIMATE);
+    expect(prepared.truncated).toBe(false);
+  });
+
+  it('rejects a base64 image that exceeds the input budget', async () => {
+    // Large header claims 1000x1000, so vision estimate is 85 + 4 * 170 = 765 tokens,
+    // which easily exceeds the 80 token budget of the default test context.
+    await expect(
+      prepareDirectLlmContext(
+        context(),
+        request([{ role: 'user', content: [{ type: 'image_url', image_url: { url: LARGE_PNG_HEADER_BASE64 } }] }]),
+      ),
+    ).rejects.toMatchObject<Partial<DirectLlmContextError>>({ code: 'context_length_exceeded' });
+  });
+
+  it('estimates file block tokens from decoded base64 size', async () => {
+    const prepared = await prepareDirectLlmContext(
+      context(),
+      request([{ role: 'user', content: [{ type: 'file', file: { file_data: TINY_PDF_BASE64, filename: 'x.pdf' } }] }]),
+    );
+
+    expect(prepared.estimatedInputTokens).toBeGreaterThan(0);
+    expect(prepared.truncated).toBe(false);
+  });
+
+  it('rejects a base64 file that exceeds the input budget', async () => {
+    const largeBase64 = `data:application/pdf;base64,${Buffer.alloc(100_000).toString('base64')}`;
+    await expect(
+      prepareDirectLlmContext(
+        context(),
+        request([{ role: 'user', content: [{ type: 'file', file: { file_data: largeBase64, filename: 'x.pdf' } }] }]),
+      ),
+    ).rejects.toMatchObject<Partial<DirectLlmContextError>>({ code: 'context_length_exceeded' });
+  });
+
+  it('counts tool definitions as fixed input overhead', async () => {
+    await expect(
+      prepareDirectLlmContext(
+        context(),
+        request(
+          [{ role: 'user', content: 'hello' }],
+          [{ type: 'function', function: { name: 'large', parameters: { text: 'x'.repeat(400) } } }],
+        ),
+      ),
+    ).rejects.toMatchObject<Partial<DirectLlmContextError>>({ code: 'context_length_exceeded' });
+  });
+});
+
+describe('image dimension parsing', () => {
+  it('parses PNG dimensions', () => {
+    // The shared 1x1 test PNG is a valid PNG with dimensions 1x1.
+    const base64 = ONE_PIXEL_PNG.split(',')[1];
+    const png = Buffer.from(base64, 'base64');
+    expect(parseImageDimensions(png)).toEqual({ width: 1, height: 1 });
+  });
+
+  it('parses JPEG dimensions without reading past width/height', () => {
+    // Minimal JPEG SOF0 segment: height 1024, width 1024.
+    const jpeg = Buffer.from([0xff, 0xd8, 0xff, 0xc0, 0x00, 0x0b, 0x08, 0x04, 0x00, 0x04, 0x00, 0x01, 0x22, 0x00]);
+    expect(parseImageDimensions(jpeg)).toEqual({ width: 1024, height: 1024 });
+  });
+});

package/src/server/__tests__/openai-format.test.ts

@@ -86,7 +86,12 @@ describe('AI API OpenAI usage-only streaming chunks', () => {
 
     expect(chunk.object).toBe('chat.completion.chunk');
     expect(chunk.choices).toEqual([]);
-    expect(chunk.usage).toEqual({ prompt_tokens: 8, completion_tokens: 3, total_tokens: 11 });
+    expect(chunk.usage).toEqual({
+      prompt_tokens: 8,
+      completion_tokens: 3,
+      total_tokens: 11,
+      prompt_tokens_details: { cached_tokens: null },
+    });
   });
 
   it('formats a usage-only legacy text completion chunk', () => {
@@ -99,7 +104,12 @@ describe('AI API OpenAI usage-only streaming chunks', () => {
 
     expect(chunk.object).toBe('text_completion');
     expect(chunk.choices).toEqual([]);
-    expect(chunk.usage).toEqual({ prompt_tokens: 2, completion_tokens: 5, total_tokens: 7 });
+    expect(chunk.usage).toEqual({
+      prompt_tokens: 2,
+      completion_tokens: 5,
+      total_tokens: 7,
+      prompt_tokens_details: { cached_tokens: null },
+    });
   });
 });
 

package/src/server/__tests__/request-body.test.ts

@@ -176,11 +176,54 @@ describe('AI API multimodal content block validation', () => {
   it('rejects an unsupported block type and names it', () => {
     const problem = findContentBlockProblem([
       { role: 'system', content: 'You are helpful.' },
-      { role: 'user', content: [{ type: 'file', file: { file_data: 'data:application/pdf;base64,JVBERi0=' } }] },
+      { role: 'user', content: [{ type: 'audio', audio: { url: 'https://example.com/x.mp3' } }] },
     ]);
 
     expect(problem?.index).toBe(1);
-    expect(problem?.reason).toContain("'file' is not supported");
+    expect(problem?.reason).toContain("'audio' is not supported");
+  });
+
+  it('accepts well-formed file and file_url blocks', () => {
+    expect(
+      findContentBlockProblem(wrap([{ type: 'file', file: { file_data: 'data:application/pdf;base64,JVBERi0=' } }])),
+    ).toBeUndefined();
+    expect(
+      findContentBlockProblem(wrap([{ type: 'file_url', file_url: { url: 'https://example.com/doc.pdf' } }])),
+    ).toBeUndefined();
+    // Complex MIME types with hyphens, dots, or '+' used to be rejected by the
+    // image_url grammar even though they are valid file attachments.
+    expect(
+      findContentBlockProblem(
+        wrap([
+          {
+            type: 'file',
+            file: {
+              file_data: 'data:application/vnd.openxmlformats-officedocument.wordprocessingml.document;base64,JVBERi0=',
+            },
+          },
+        ]),
+      ),
+    ).toBeUndefined();
+    expect(
+      findContentBlockProblem(wrap([{ type: 'file', file: { file_data: 'data:image/svg+xml;base64,JVBERi0=' } }])),
+    ).toBeUndefined();
+  });
+
+  it('rejects a file block with missing or malformed file_data', () => {
+    expect(findContentBlockProblem(wrap([{ type: 'file' }]))?.reason).toContain("object 'file' field");
+    expect(findContentBlockProblem(wrap([{ type: 'file', file: { file_data: 'not-a-data-url' } }]))?.reason).toContain(
+      "'data:'",
+    );
+    expect(
+      findContentBlockProblem(wrap([{ type: 'file', file: { file_data: 'data:application/pdf;base64,!!!' } }]))?.reason,
+    ).toContain('malformed base64');
+  });
+
+  it('rejects a file_url block with missing or unsupported URL', () => {
+    expect(findContentBlockProblem(wrap([{ type: 'file_url' }]))?.reason).toContain("object 'file_url' field");
+    expect(
+      findContentBlockProblem(wrap([{ type: 'file_url', file_url: { url: 'ftp://example.com/doc.pdf' } }]))?.reason,
+    ).toContain("protocol 'ftp:'");
   });
 
   it('rejects a text block with no text payload', () => {

package/src/server/__tests__/usage-route.test.ts

@@ -15,18 +15,20 @@ interface ModelResult {
   usage_metadata?: Record<string, unknown>;
 }
 
-function createContext(result: ModelResult): Context {
+function createContext(result: ModelResult) {
   const model = {
     invoke: vi.fn().mockResolvedValue(result),
     modelKwargs: {},
   };
+  let providerCreateCount = 0;
   class TestProvider {
     createModel() {
+      providerCreateCount += 1;
       return model;
     }
   }
 
-  return {
+  const ctx = {
     app: {
       pm: {
         get: vi.fn().mockReturnValue({
@@ -37,7 +39,16 @@ function createContext(result: ModelResult): Context {
       },
     },
     db: {
-      getRepository: vi.fn().mockReturnValue({ findOne: vi.fn().mockResolvedValue(null) }),
+      getRepository: vi.fn((name: string) => {
+        if (name === 'aiApiModelMetadata') {
+          return {
+            findOne: vi.fn().mockResolvedValue({
+              get: (key: string) => (key === 'contextWindow' ? 128_000 : key === 'maxCompletionTokens' ? 16_384 : true),
+            }),
+          };
+        }
+        return { findOne: vi.fn().mockResolvedValue(null) };
+      }),
     },
     log: { error: vi.fn() },
     request: {
@@ -50,6 +61,8 @@ function createContext(result: ModelResult): Context {
     state: {},
     set: vi.fn(),
   } as unknown as Context;
+
+  return { ctx, model, getProviderCreateCount: () => providerCreateCount };
 }
 
 class ListenerTarget {
@@ -139,7 +152,16 @@ function createStreamingContext(
       },
     },
     db: {
-      getRepository: vi.fn().mockReturnValue({ findOne: vi.fn().mockResolvedValue(null) }),
+      getRepository: vi.fn((name: string) => {
+        if (name === 'aiApiModelMetadata') {
+          return {
+            findOne: vi.fn().mockResolvedValue({
+              get: (key: string) => (key === 'contextWindow' ? 128_000 : key === 'maxCompletionTokens' ? 16_384 : true),
+            }),
+          };
+        }
+        return { findOne: vi.fn().mockResolvedValue(null) };
+      }),
     },
     log: { error: vi.fn() },
     req,
@@ -174,7 +196,7 @@ describe('AI API chat usage collection', () => {
   });
 
   it('keeps the public zero fallback but marks missing provider usage as unavailable internally', async () => {
-    const ctx = createContext({ content: 'Hello back' });
+    const { ctx } = createContext({ content: 'Hello back' });
 
     await handleChatCompletions(ctx, {} as PluginAiApiServer);
 
@@ -183,6 +205,7 @@ describe('AI API chat usage collection', () => {
       prompt_tokens: 0,
       completion_tokens: 0,
       total_tokens: 0,
+      prompt_tokens_details: { cached_tokens: null },
     });
     expect(ctx.state.aiApiUsageResult).toMatchObject({
       source: 'unavailable',
@@ -195,7 +218,7 @@ describe('AI API chat usage collection', () => {
   });
 
   it('stores provider usage and provider request ID separately from the gateway response ID', async () => {
-    const ctx = createContext({
+    const { ctx } = createContext({
       content: 'Hello back',
       response_metadata: { request_id: 'provider-request-1' },
       usage_metadata: { input_tokens: 8, output_tokens: 3, total_tokens: 11 },
@@ -207,6 +230,7 @@ describe('AI API chat usage collection', () => {
       prompt_tokens: 8,
       completion_tokens: 3,
       total_tokens: 11,
+      prompt_tokens_details: { cached_tokens: null },
     });
     expect(ctx.state.aiApiUsageResult).toMatchObject({
       source: 'provider',
@@ -216,6 +240,73 @@ describe('AI API chat usage collection', () => {
     });
   });
 
+  it('extracts cached prompt tokens from OpenAI-style usage metadata', async () => {
+    const { ctx } = createContext({
+      content: 'Hello back',
+      usage_metadata: {
+        input_tokens: 8,
+        output_tokens: 3,
+        total_tokens: 11,
+        prompt_tokens_details: { cached_tokens: 7 },
+      },
+    });
+
+    await handleChatCompletions(ctx, {} as PluginAiApiServer);
+
+    expect((ctx.body as { usage: object }).usage).toEqual({
+      prompt_tokens: 8,
+      completion_tokens: 3,
+      total_tokens: 11,
+      prompt_tokens_details: { cached_tokens: 7 },
+    });
+    expect(ctx.state.aiApiUsageResult).toMatchObject({
+      source: 'provider',
+      usage: { prompt_tokens: 8, completion_tokens: 3, total_tokens: 11, prompt_cache_tokens: 7 },
+    });
+  });
+
+  it('falls back to response_metadata when usage metadata omits cached tokens', async () => {
+    const { ctx } = createContext({
+      content: 'Hello back',
+      usage_metadata: { input_tokens: 8, output_tokens: 3, total_tokens: 11 },
+      response_metadata: { usage: { prompt_tokens_details: { cached_tokens: 5 } } },
+    });
+
+    await handleChatCompletions(ctx, {} as PluginAiApiServer);
+
+    expect((ctx.body as { usage: object }).usage).toEqual({
+      prompt_tokens: 8,
+      completion_tokens: 3,
+      total_tokens: 11,
+      prompt_tokens_details: { cached_tokens: 5 },
+    });
+    expect(ctx.state.aiApiUsageResult).toMatchObject({
+      source: 'provider',
+      usage: { prompt_cache_tokens: 5 },
+    });
+  });
+
+  it('extracts cached prompt tokens from LangChain-style input_token_details', async () => {
+    const { ctx } = createContext({
+      content: 'Hello back',
+      usage_metadata: {
+        input_tokens: 8,
+        output_tokens: 3,
+        total_tokens: 11,
+        input_token_details: { cache_read: 4 },
+      },
+    });
+
+    await handleChatCompletions(ctx, {} as PluginAiApiServer);
+
+    expect((ctx.body as { usage: object }).usage).toEqual({
+      prompt_tokens: 8,
+      completion_tokens: 3,
+      total_tokens: 11,
+      prompt_tokens_details: { cached_tokens: 4 },
+    });
+  });
+
   it('emits a usage-only chunk immediately before [DONE] for streaming chat completions', async () => {
     const { ctx, writes } = createStreamingContext(
       {
@@ -239,7 +330,12 @@ describe('AI API chat usage collection', () => {
 
     expect(finishChunk.choices[0].finish_reason).toBe('stop');
     expect(usageChunk.choices).toEqual([]);
-    expect(usageChunk.usage).toEqual({ prompt_tokens: 5, completion_tokens: 4, total_tokens: 9 });
+    expect(usageChunk.usage).toEqual({
+      prompt_tokens: 5,
+      completion_tokens: 4,
+      total_tokens: 9,
+      prompt_tokens_details: { cached_tokens: null },
+    });
     expect(usageChunk).toHaveProperty('usage.prompt_tokens', 5);
     expect(ctx.state.aiApiUsageResult).toMatchObject({
       source: 'provider',
@@ -265,7 +361,12 @@ describe('AI API chat usage collection', () => {
 
     expect(frames.slice(0, -1).every((frame) => frame.usage === null)).toBe(true);
     expect(usageChunk.choices).toEqual([]);
-    expect(usageChunk.usage).toEqual({ prompt_tokens: 5, completion_tokens: 4, total_tokens: 9 });
+    expect(usageChunk.usage).toEqual({
+      prompt_tokens: 5,
+      completion_tokens: 4,
+      total_tokens: 9,
+      prompt_tokens_details: { cached_tokens: null },
+    });
     expect(model.stream).toHaveBeenCalledWith(
       expect.anything(),
       expect.objectContaining({
@@ -294,7 +395,12 @@ describe('AI API chat usage collection', () => {
     expect(frames.slice(0, -1).every((frame) => frame.usage === null)).toBe(true);
     expect(usageChunk.object).toBe('text_completion');
     expect(usageChunk.choices).toEqual([]);
-    expect(usageChunk.usage).toEqual({ prompt_tokens: 2, completion_tokens: 5, total_tokens: 7 });
+    expect(usageChunk.usage).toEqual({
+      prompt_tokens: 2,
+      completion_tokens: 5,
+      total_tokens: 7,
+      prompt_tokens_details: { cached_tokens: null },
+    });
     expect(model.stream).toHaveBeenCalledWith(
       expect.anything(),
       expect.objectContaining({
@@ -303,6 +409,31 @@ describe('AI API chat usage collection', () => {
     );
   });
 
+  it('rejects context overflow before creating a provider or reserving quota', async () => {
+    const { ctx, getProviderCreateCount } = createContext({ content: 'unused' });
+    (ctx.request.body as Record<string, unknown>).messages = [{ role: 'user', content: 'x'.repeat(600_000) }];
+
+    await handleChatCompletions(ctx, {} as PluginAiApiServer);
+
+    expect(ctx.status).toBe(400);
+    expect(ctx.body).toMatchObject({ error: { code: 'context_length_exceeded' } });
+    expect(ctx.state.aiApiLlmBilling).toBeUndefined();
+    expect(getProviderCreateCount()).toBe(0);
+  });
+
+  it('rejects oversized legacy prompts before creating a provider or reserving quota', async () => {
+    const { ctx, model, getProviderCreateCount } = createContext({ content: 'unused' });
+    (ctx.request.body as Record<string, unknown>).prompt = 'x'.repeat(600_000);
+
+    await handleCompletions(ctx, {} as PluginAiApiServer);
+
+    expect(ctx.status).toBe(400);
+    expect(ctx.body).toMatchObject({ error: { code: 'context_length_exceeded' } });
+    expect(ctx.state.aiApiLlmBilling).toBeUndefined();
+    expect(getProviderCreateCount()).toBe(0);
+    expect(model.invoke).not.toHaveBeenCalled();
+  });
+
   it('does not emit a usage-only chunk when the provider omits usage metadata', async () => {
     const { ctx, writes } = createStreamingContext({ content: 'Silent' }, { include_usage: true });
 
@@ -319,4 +450,37 @@ describe('AI API chat usage collection', () => {
     expect(precedingChunk.usage).toBeNull();
     expect(ctx.state.aiApiUsageResult).toMatchObject({ source: 'unavailable' });
   });
+
+  it('forwards passthrough provider parameters in legacy non-stream completions', async () => {
+    const { ctx, model } = createContext({
+      content: 'Hello back',
+      usage_metadata: { input_tokens: 2, output_tokens: 5, total_tokens: 7 },
+    });
+    (ctx.request.body as Record<string, unknown>).prompt = 'Hello';
+    (ctx.request.body as Record<string, unknown>).seed = 42;
+    (ctx.request.body as Record<string, unknown>).reasoning_effort = 'medium';
+
+    await handleCompletions(ctx, {} as PluginAiApiServer);
+
+    expect(ctx.status).toBe(200);
+    expect(model.invoke).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ seed: 42, reasoning_effort: 'medium' }),
+    );
+  });
+
+  it('forwards passthrough provider parameters in legacy streaming completions', async () => {
+    const { ctx, model } = createStreamingContext(
+      { content: 'Hi', usage_metadata: { input_tokens: 2, output_tokens: 5, total_tokens: 7 } },
+      { include_usage: false, include_obfuscation: false },
+      { prompt: 'Hello', seed: 42, reasoning_effort: 'medium' },
+    );
+
+    await handleCompletions(ctx, {} as PluginAiApiServer);
+
+    expect(model.stream).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ seed: 42, reasoning_effort: 'medium' }),
+    );
+  });
 });

package/src/server/__tests__/usage.test.ts

@@ -24,6 +24,7 @@ describe('AI API usage normalization', () => {
       prompt_tokens: 12,
       completion_tokens: 5,
       total_tokens: 17,
+      prompt_cache_tokens: null,
     });
   });
 
@@ -32,6 +33,24 @@ describe('AI API usage normalization', () => {
       prompt_tokens: 0,
       completion_tokens: 0,
       total_tokens: 0,
+      prompt_cache_tokens: null,
+    });
+  });
+
+  it('extracts prompt_cache_tokens when present in various provider formats', () => {
+    expect(
+      normalizeUsage({ prompt_tokens: 10, completion_tokens: 5, prompt_tokens_details: { cached_tokens: 8 } }),
+    ).toEqual({
+      prompt_tokens: 10,
+      completion_tokens: 5,
+      total_tokens: 15,
+      prompt_cache_tokens: 8,
+    });
+    expect(normalizeUsage({ input_tokens: 20, output_tokens: 10, input_token_details: { cache_read: 15 } })).toEqual({
+      prompt_tokens: 20,
+      completion_tokens: 10,
+      total_tokens: 30,
+      prompt_cache_tokens: 15,
     });
   });
 

package/src/server/__tests__/validation.test.ts

@@ -0,0 +1,36 @@
+import type { Model } from '@nocobase/database';
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('dayjs', () => ({
+  default: () => ({ tz: vi.fn() }),
+}));
+
+import { validateQuotaPolicy } from '../validation';
+
+function quotaPolicy(values: Record<string, unknown>): Model {
+  return {
+    get: (key: string) => values[key],
+  } as Model;
+}
+
+const requiredPolicy = {
+  periodType: 'monthly',
+  missingUsageBehavior: 'use_reserved',
+  timezone: 'UTC',
+};
+
+describe('AI API quota policy validation', () => {
+  it('uses reject when context overflow behavior is absent', () => {
+    expect(() => validateQuotaPolicy(quotaPolicy(requiredPolicy))).not.toThrow();
+  });
+
+  it.each(['reject', 'truncate'] as const)('accepts %s context overflow behavior', (contextOverflowBehavior) => {
+    expect(() => validateQuotaPolicy(quotaPolicy({ ...requiredPolicy, contextOverflowBehavior }))).not.toThrow();
+  });
+
+  it('rejects an unsupported context overflow behavior', () => {
+    expect(() => validateQuotaPolicy(quotaPolicy({ ...requiredPolicy, contextOverflowBehavior: 'compact' }))).toThrow(
+      'contextOverflowBehavior must be reject or truncate.',
+    );
+  });
+});

package/src/server/billing.ts

@@ -373,7 +373,12 @@ export async function finalizeLlmBilling(
 
   return {
     usage: numbers
-      ? { prompt_tokens: numbers.input, completion_tokens: numbers.output, total_tokens: numbers.total }
+      ? {
+          prompt_tokens: numbers.input,
+          completion_tokens: numbers.output,
+          total_tokens: numbers.total,
+          prompt_cache_tokens: providerUsage?.prompt_cache_tokens ?? null,
+        }
       : providerUsage,
     estimatedCost: cost,
     currency: billing.price?.currency,

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

@@ -47,6 +47,14 @@ export default defineCollection({
       defaultValue: 10,
       comment: 'Max request body size in MB. Raise this to accept inline base64 images in vision requests.',
     },
+    {
+      name: 'pdfRenderPagesAsImages',
+      type: 'boolean',
+      defaultValue: false,
+      comment:
+        'When true, PDF file/file_url blocks are rendered to per-page PNG images and sent as image_url blocks. ' +
+        'Requires a registered PdfToImageRenderer. When false or no renderer is available, PDFs are forwarded as file blocks.',
+    },
     {
       name: 'quotaEnabled',
       type: 'boolean',