plugin-ai-api 1.0.24 → 1.0.28

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

@@ -26,13 +26,14 @@ import {
   isStreamingRequested,
   writeResponse,
 } from '../utils/streaming';
-import { checkEmployeeAccess } from '../middleware/role-permission';
 import { enforceModelAccess } from '../utils/user-permissions';
+import { getAiApiConfig } from '../utils/request-cache';
 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
@@ -130,7 +131,7 @@ export async function handleChatCompletions(ctx: Context, plugin: PluginAiApiSer
     }
 
     // ─── Check whitelist (global config ∩ per-user grant) ───
-    const config = await ctx.db.getRepository('aiApiConfig').findOne();
+    const config = await getAiApiConfig(ctx);
     if (!(await enforceModelAccess(ctx, config?.enabledLlmServices, service, modelId))) {
       return;
     }
@@ -165,35 +166,18 @@ 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;
 
-    // ─── Build system prompt from AI Employee ───
-    let systemPrompt = '';
-    if (config?.defaultAiEmployee) {
-      // Check role is allowed to use this employee
-      if (!checkEmployeeAccess(ctx, config.defaultAiEmployee)) {
-        ctx.status = 403;
-        ctx.body = toOpenAIError(
-          403,
-          `Role is not permitted to use AI Employee '${config.defaultAiEmployee}'. ` +
-            `An admin must grant access in Settings → Users & Permissions → [Role] → AI API.`,
-          'permission_denied',
-          'employee_not_permitted',
-        );
-        return;
-      }
-      const employee = await ctx.db.getRepository('aiEmployees').findOne({
-        filter: { username: config.defaultAiEmployee },
-      });
-      if (employee) {
-        systemPrompt = employee.about || employee.defaultPrompt || '';
-      }
-    }
-
-    // ─── Build messages (inject system prompt if not provided by client) ───
+    // Direct LLM mode ignores the default AI Employee: its prompt belongs to agent
+    // mode only. The model metadata system prompt is still applied later by
+    // prepareDirectLlmContext.
     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,
@@ -271,13 +255,14 @@ export async function handleChatCompletions(ctx: Context, plugin: PluginAiApiSer
     if (!ctx.res?.headersSent) {
       const isQuotaError = err instanceof AiApiQuotaError;
       const isContextError = err instanceof DirectLlmContextError;
-      ctx.status = isQuotaError ? 429 : isContextError ? 400 : 500;
+      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' : isContextError ? 'invalid_request_error' : 'server_error',
-        isQuotaError || isContextError ? err.code : undefined,
+        isQuotaError ? 'quota_error' : isContextError || isFileError ? 'invalid_request_error' : 'server_error',
+        isQuotaError || isContextError || isFileError ? err.code : undefined,
       );
     }
   }
@@ -305,19 +290,26 @@ 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);
+  const providerFinishReason = extractFinishReason(result);
   ctx.body = toOpenAIResponse({
     id: completionId,
     model: modelName,
     content,
     usage: usage ?? { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
     toolCalls,
+    ...(providerFinishReason ? { finishReason: providerFinishReason } : {}),
   });
 }
 
@@ -354,8 +346,10 @@ async function handleStreamingCompletion(
 
   const requestAbort = createRequestAbortController(ctx);
   let usage: Usage | undefined;
+  let usageResponseMetadata: unknown;
   let providerRequestId: string | undefined;
-  let finishReason = 'stop';
+  let providerFinishReason: string | undefined;
+  let sawToolCalls = false;
   try {
     const stream = await chatModel.stream(messages, { ...providerRequestParameters, signal: requestAbort.signal });
 
@@ -386,7 +380,7 @@ async function handleStreamingCompletion(
       const toolCallChunks = normalizeToolCallChunks(chunk.tool_call_chunks);
       if (toolCallChunks.length) {
         markAiApiFirstProviderOutput(ctx);
-        finishReason = 'tool_calls';
+        sawToolCalls = true;
         await writeResponse(
           ctx,
           formatSSE(
@@ -399,8 +393,14 @@ async function handleStreamingCompletion(
         );
       }
       if (chunk.usage_metadata) {
-        usage = normalizeUsage(chunk.usage_metadata) ?? usage;
+        const normalized = normalizeUsage(chunk.usage_metadata);
+        if (normalized) {
+          usage = normalized;
+          usageResponseMetadata = chunk.response_metadata;
+        }
       }
+      const chunkFinishReason = extractFinishReason(chunk);
+      if (chunkFinishReason) providerFinishReason = chunkFinishReason;
       providerRequestId = providerRequestId ?? extractProviderRequestId(chunk);
     }
 
@@ -412,7 +412,7 @@ async function handleStreamingCompletion(
           id: completionId,
           model: modelName,
           delta: {},
-          finishReason,
+          finishReason: providerFinishReason ?? (sawToolCalls ? 'tool_calls' : 'stop'),
         }),
       ),
     );
@@ -432,7 +432,7 @@ async function handleStreamingCompletion(
 
     // Send [DONE]
     await writeResponse(ctx, formatSSEDone());
-    setAiApiUsageResult(ctx, usage, { gatewayResponseId: completionId, providerRequestId });
+    setAiApiUsageResult(ctx, usage, { gatewayResponseId: completionId, providerRequestId }, usageResponseMetadata);
     ctx.state.aiApiStreamResult = { succeeded: true, id: completionId };
   } catch (err) {
     const cancelled = isClientDisconnected(ctx, err);
@@ -449,7 +449,7 @@ async function handleStreamingCompletion(
         }),
       );
     }
-    setAiApiUsageResult(ctx, usage, { gatewayResponseId: completionId, providerRequestId });
+    setAiApiUsageResult(ctx, usage, { gatewayResponseId: completionId, providerRequestId }, usageResponseMetadata);
     ctx.state.aiApiStreamResult = {
       succeeded: false,
       id: completionId,
@@ -465,6 +465,24 @@ function getErrorMessage(error: unknown, fallback: string) {
   return error instanceof Error && error.message ? error.message : fallback;
 }
 
+/**
+ * Reads the provider's finish_reason from a LangChain result or stream chunk.
+ * LangChain surfaces it in response_metadata.finish_reason; some adapters put it
+ * in additional_kwargs.finish_reason instead. Returns undefined when the provider
+ * reported nothing, so callers can fall back to their own default.
+ */
+export function extractFinishReason(value: unknown): string | undefined {
+  if (!isRecord(value)) return undefined;
+  const candidates = [
+    isRecord(value.response_metadata) ? value.response_metadata.finish_reason : undefined,
+    isRecord(value.additional_kwargs) ? value.additional_kwargs.finish_reason : undefined,
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate.length > 0) return candidate;
+  }
+  return undefined;
+}
+
 /**
  * Content block types every provider adapter in `@nocobase/plugin-ai` maps to a
  * native equivalent.
@@ -475,7 +493,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`
@@ -486,6 +504,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
@@ -591,8 +617,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`
     );
   }
 
@@ -600,9 +626,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 === '') {
@@ -681,7 +754,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,6 +23,8 @@ import {
   isStreamingRequested,
   writeResponse,
 } from '../utils/streaming';
+import { getProviderRequestParameters, applyProviderRequestParameters, extractFinishReason } from './chat-completions';
+import { getAiApiConfig } from '../utils/request-cache';
 import { extractProviderRequestId, normalizeUsage, setAiApiUsageResult, type Usage } from '../usage';
 import type PluginAiApiServer from '../plugin';
 import { AiApiQuotaError, markLlmProviderAttempted, prepareLlmBilling } from '../billing';
@@ -102,7 +104,7 @@ export async function handleCompletions(ctx: Context, plugin: PluginAiApiServer)
     }
 
     // ─── Check whitelist (global config ∩ per-user grant) ───
-    const config = await ctx.db.getRepository('aiApiConfig').findOne();
+    const config = await getAiApiConfig(ctx);
     if (!(await enforceModelAccess(ctx, config?.enabledLlmServices, service, modelId))) {
       return;
     }
@@ -133,20 +135,8 @@ export async function handleCompletions(ctx: Context, plugin: PluginAiApiServer)
           ? body.prompt.join('\n')
           : String(body.prompt);
 
-    // Inject system prompt from AI Employee if configured
-    const messages: OpenAIMessage[] = [];
-    if (config?.defaultAiEmployee) {
-      const employee = await ctx.db.getRepository('aiEmployees').findOne({
-        filter: { username: config.defaultAiEmployee },
-      });
-      if (employee) {
-        const systemPrompt = employee.about || employee.defaultPrompt || '';
-        if (systemPrompt) {
-          messages.push({ role: 'system', content: systemPrompt });
-        }
-      }
-    }
-    messages.push({ role: 'user', content: prompt });
+    // Direct LLM mode ignores the default AI Employee: its prompt belongs to agent mode only.
+    const messages: OpenAIMessage[] = [{ role: 'user', content: prompt }];
 
     const preparedContext = await prepareDirectLlmContext(ctx, {
       serviceName: service.name,
@@ -169,6 +159,8 @@ export async function handleCompletions(ctx: Context, plugin: PluginAiApiServer)
 
     const completionId = generateCompletionId().replace('chatcmpl-', 'cmpl-');
     const chatModel = provider.createModel();
+    const providerRequestParameters = getProviderRequestParameters(body);
+    applyProviderRequestParameters(chatModel, providerRequestParameters);
     markLlmProviderAttempted(ctx);
 
     if (stream) {
@@ -179,9 +171,17 @@ 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);
@@ -208,8 +208,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') {
@@ -219,10 +220,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 = {
@@ -236,10 +242,17 @@ async function handleNonStreamingTextCompletion(
         text,
         index: 0,
         logprobs: null,
-        finish_reason: 'stop',
+        finish_reason: extractFinishReason(result) ?? '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 } },
   };
 }
 
@@ -252,6 +265,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',
@@ -263,9 +277,12 @@ async function handleStreamingTextCompletion(
 
   const requestAbort = createRequestAbortController(ctx);
   let usage: Usage | undefined;
+  let usageResponseMetadata: unknown;
   let providerRequestId: string | undefined;
+  let providerFinishReason: string | undefined;
   try {
     const stream = await chatModel.stream(messages, {
+      ...providerRequestParameters,
       stream_options: { ...streamOptions, include_usage: true },
       signal: requestAbort.signal,
     });
@@ -303,8 +320,14 @@ async function handleStreamingTextCompletion(
         );
       }
       if (chunk.usage_metadata) {
-        usage = normalizeUsage(chunk.usage_metadata) ?? usage;
+        const normalized = normalizeUsage(chunk.usage_metadata);
+        if (normalized) {
+          usage = normalized;
+          usageResponseMetadata = chunk.response_metadata;
+        }
       }
+      const chunkFinishReason = extractFinishReason(chunk);
+      if (chunkFinishReason) providerFinishReason = chunkFinishReason;
       providerRequestId = providerRequestId ?? extractProviderRequestId(chunk);
     }
 
@@ -322,7 +345,7 @@ async function handleStreamingTextCompletion(
             text: '',
             index: 0,
             logprobs: null,
-            finish_reason: 'stop',
+            finish_reason: providerFinishReason ?? 'stop',
           },
         ],
         usage: null,
@@ -344,7 +367,7 @@ async function handleStreamingTextCompletion(
     }
 
     await writeResponse(ctx, formatSSEDone());
-    setAiApiUsageResult(ctx, usage, { gatewayResponseId: completionId, providerRequestId });
+    setAiApiUsageResult(ctx, usage, { gatewayResponseId: completionId, providerRequestId }, usageResponseMetadata);
     ctx.state.aiApiStreamResult = { succeeded: true, id: completionId };
   } catch (err) {
     const cancelled = isClientDisconnected(ctx, err);
@@ -360,7 +383,7 @@ async function handleStreamingTextCompletion(
         }),
       );
     }
-    setAiApiUsageResult(ctx, usage, { gatewayResponseId: completionId, providerRequestId });
+    setAiApiUsageResult(ctx, usage, { gatewayResponseId: completionId, providerRequestId }, usageResponseMetadata);
     ctx.state.aiApiStreamResult = {
       succeeded: false,
       id: completionId,

package/src/server/routes/embeddings.ts

@@ -11,6 +11,7 @@ import { Context } from '@nocobase/actions';
 import { toOpenAIError, toOpenAIEmbeddingsResponse } from '../utils/openai-format';
 import { resolveModelString } from '../utils/resolve-service';
 import { enforceModelAccess } from '../utils/user-permissions';
+import { getAiApiConfig } from '../utils/request-cache';
 import { setAiApiUsageUnavailable } from '../usage';
 import type PluginAiApiServer from '../plugin';
 
@@ -118,7 +119,7 @@ export async function handleEmbeddings(ctx: Context, plugin: PluginAiApiServer)
   // still enforced: an explicit deny must never be bypassed by an unreadable config.
   let globalEnabledServices: unknown = [];
   try {
-    const config = await ctx.db.getRepository('aiApiConfig').findOne();
+    const config = await getAiApiConfig(ctx);
     globalEnabledServices = config?.enabledLlmServices ?? [];
   } catch {
     // Config read failure: fail open on the global whitelist only.

package/src/server/routes/models.ts

@@ -10,6 +10,7 @@
 import { Context } from '@nocobase/actions';
 import { toOpenAIError } from '../utils/openai-format';
 import { isModelAllowed, isServiceAllowed, resolveUserAccessScope } from '../utils/user-permissions';
+import { getAiApiConfig } from '../utils/request-cache';
 import type PluginAiApiServer from '../plugin';
 
 /**
@@ -20,8 +21,8 @@ import type PluginAiApiServer from '../plugin';
  * so clients can copy-paste the ID directly into POST /v1/chat/completions
  * without needing to configure a defaultLlmService.
  *
- * The catalog is scoped to the caller: a user with an aiApiUserPermissions row only
- * sees the intersection of the global whitelist and their own grant.
+ * The catalog is scoped to the caller: it starts from the global whitelist and is
+ * narrowed by the caller's usage group settings (allowedLlmServices / allowedModels).
  *
  * Backward compatibility: resolveModelString() in resolve-service.ts still
  * accepts bare model IDs via its 3-tier fallback (defaultLlmService / single service).
@@ -251,7 +252,7 @@ function toPositiveInt(value: unknown): number | null {
 }
 
 async function getPluginConfig(ctx: Context) {
-  return ctx.db.getRepository('aiApiConfig').findOne();
+  return getAiApiConfig(ctx);
 }
 
 /**

package/src/server/routes/router.ts

@@ -20,6 +20,7 @@ import { createRateLimitMiddleware } from '../middleware/rate-limit';
 import { checkRolePermission } from '../middleware/role-permission';
 import { startUsageRecord, finishUsageRecord } from '../usage';
 import { isStreamingRequested } from '../utils/streaming';
+import { getAiApiConfig } from '../utils/request-cache';
 import type PluginAiApiServer from '../plugin';
 import { finalizeLlmBilling } from '../billing';
 import { finishAiApiObservation, startAiApiObservation } from '../utils/app-observability';
@@ -43,7 +44,7 @@ type DataWrappingContext = Context & { withoutDataWrapping?: boolean };
  * - OPTIONS preflight handling (204)
  * - X-Request-Id on every response
  * - Bearer token authentication
- * - Sliding window rate limiting (enforces rateLimitPerMinute from config)
+ * - Sliding window rate limiting (enforces rateLimitPerMinute from the user's usage group)
  * - Structured request logging via app.logger
  *
  * Supported endpoints:
@@ -353,7 +354,7 @@ export function normalizeMaxRequestBodyMb(value: unknown): number {
 async function resolveMaxBodyBytes(ctx: Context): Promise<number> {
   let configuredMb: unknown;
   try {
-    const config = await ctx.db.getRepository('aiApiConfig').findOne();
+    const config = await getAiApiConfig(ctx);
     configuredMb = config?.get('maxRequestBodyMb');
   } catch (err) {
     ctx.log?.warn?.('AI API: could not read maxRequestBodyMb, using default:', err);
@@ -431,7 +432,7 @@ async function resolveMode(ctx: Context): Promise<'llm' | 'agent'> {
   }
 
   try {
-    const config = await ctx.db.getRepository('aiApiConfig').findOne();
+    const config = await getAiApiConfig(ctx);
     if (config) {
       const dbMode = config.get('mode') || config.mode;
       if (dbMode === 'agent' || dbMode === 'llm') {