plugin-ai-api 1.1.1 → 1.1.2

package/src/server/plugin.ts

@@ -12,11 +12,12 @@ import type { Transactionable } from '@nocobase/database';
 import { createAiLlmRouter, AI_LLM_PREFIX } from './routes/router';
 import aiApiConfigResource from './resource/ai-api-config';
 import aiApiUsageMonitorResource from './resource/ai-api-usage-monitor';
-import aiApiUsageGroupsResource from './resource/ai-api-usage-groups';
 import { RateLimiter } from './utils/rate-limiter';
 import { invalidateRolePermissionCache } from './middleware/role-permission';
+import { blockResponseRecordResource } from './middleware/response-record-resource';
 import { invalidateGroupAccessCache } from './utils/user-permissions';
-import { validateModelPrice, validateModelMetadata, validateQuotaPolicy } from './validation';
+import { cleanupExpiredResponseRecords } from './utils/response-store';
+import { validateModelPrice, validateModelMetadata, validateQuotaPolicy, validateVirtualModel } from './validation';
 import { AI_API_ACL_SNIPPET } from '../constants';
 import {
   FileProcessorService,
@@ -52,6 +53,7 @@ export class PluginAiApiServer extends Plugin {
   fileProcessorService = new FileProcessorService();
 
   private gcInterval: NodeJS.Timeout | null = null;
+  private responseCleanupInterval: NodeJS.Timeout | null = null;
 
   async afterAdd() {}
 
@@ -62,6 +64,9 @@ export class PluginAiApiServer extends Plugin {
     this.app.db.on('aiApiModelMetadata.beforeSave', (model) => {
       validateModelMetadata(model);
     });
+    this.app.db.on('aiApiVirtualModels.beforeSave', (model) => {
+      validateVirtualModel(model);
+    });
     this.app.db.on('aiApiUsageGroups.beforeSave', async (model, options) => {
       validateQuotaPolicy(model);
       // The partial unique index on isDefault is not supported on MySQL,
@@ -82,6 +87,19 @@ export class PluginAiApiServer extends Plugin {
     this.app.db.on('aiApiGroupMembers.beforeSave', async (model, options) => {
       const userId = model.get('userId');
       if (!userId) return;
+      // The default group is a fallback, not a membership target: an explicit row would pin the
+      // user there and make them invisible to any unassigned-users filter. Reject it here so the
+      // rule holds whether the row comes from a custom action or a plain aiApiGroupMembers:create.
+      const targetGroupId = model.get('groupId');
+      if (targetGroupId) {
+        const targetGroup = await this.db.getRepository('aiApiUsageGroups').findOne({
+          filterByTk: targetGroupId,
+          transaction: options?.transaction,
+        });
+        if (targetGroup?.get('isDefault')) {
+          throw new Error('Cannot add members to the default group: users without another group use it automatically.');
+        }
+      }
       const existing = await this.db.getRepository('aiApiGroupMembers').findOne({
         filter: { userId },
         transaction: options?.transaction,
@@ -95,24 +113,16 @@ export class PluginAiApiServer extends Plugin {
       if (model.get('isDefault')) {
         throw new Error('The default usage group cannot be deleted.');
       }
+      // Drop membership rows so the affected users fall back to the default group
+      // implicitly. Rows are destroyed one by one to keep the repository-level
+      // destroy events firing for any listener that tracks membership changes.
       const members = await this.db.getRepository('aiApiGroupMembers').find({
         filter: { groupId: model.get('id') },
         transaction: options?.transaction,
       });
-      if (members.length === 0) return;
-
-      const defaultGroup = await this.db.getRepository('aiApiUsageGroups').findOne({
-        filter: { isDefault: true },
-        transaction: options?.transaction,
-      });
-      if (!defaultGroup) {
-        throw new Error('Default usage group is missing; cannot reassign members.');
-      }
-
       for (const member of members) {
-        await this.db.getRepository('aiApiGroupMembers').update({
+        await this.db.getRepository('aiApiGroupMembers').destroy({
           filterByTk: member.get('id'),
-          values: { groupId: defaultGroup.get('id') },
           transaction: options?.transaction,
         });
       }
@@ -151,13 +161,20 @@ export class PluginAiApiServer extends Plugin {
     // 2. Register admin config resource
     this.app.resourceManager.define(aiApiConfigResource);
     this.app.resourceManager.define(aiApiUsageMonitorResource);
-    this.app.resourceManager.define(aiApiUsageGroupsResource);
 
-    this.app.db.on('aiApiRolePermissions.afterSave', (model) => {
-      invalidateRolePermissionCache(model.get('roleName'));
+    // Stored prompts are only exposed through the owner-scoped OpenAI routes. This
+    // explicit policy also blocks root, whose generic NocoBase ACL bypass is unconditional.
+    this.app.resourceManager.use(blockResponseRecordResource(), {
+      tag: 'aiApiResponseRecordsPrivate',
+      after: 'auth',
+      before: 'acl',
     });
-    this.app.db.on('aiApiRolePermissions.afterDestroy', (model) => {
-      invalidateRolePermissionCache(model.get('roleName'));
+
+    this.app.db.on('aiApiRolePermissions.afterSave', (model, options) => {
+      this.invalidateRolePermissionSync(model.get('roleName'), options?.transaction);
+    });
+    this.app.db.on('aiApiRolePermissions.afterDestroy', (model, options) => {
+      this.invalidateRolePermissionSync(model.get('roleName'), options?.transaction);
     });
 
     this.app.db.on('aiApiUsageGroups.afterSave', (model, options) => {
@@ -175,6 +192,7 @@ export class PluginAiApiServer extends Plugin {
         'aiApiRolePermissions:*',
         'aiApiModelPrices:*',
         'aiApiModelMetadata:*',
+        'aiApiVirtualModels:*',
         'aiApiUsageGroups:*',
         'aiApiGroupMembers:*',
         'aiApiGroupQuotaBuckets:list',
@@ -189,6 +207,24 @@ export class PluginAiApiServer extends Plugin {
     //    .unref() prevents this timer from keeping the process alive on shutdown.
     this.gcInterval = setInterval(() => this.rateLimiter.gc(), 5 * 60 * 1000);
     this.gcInterval.unref();
+
+    // Expired stored responses are removed daily; run once at startup as well.
+    this.cleanupResponseRecords();
+    this.responseCleanupInterval = setInterval(() => this.cleanupResponseRecords(), 24 * 60 * 60 * 1000);
+    this.responseCleanupInterval.unref();
+  }
+
+  /**
+   * Drop a role's cached permission record on every node.
+   *
+   * Mirrors invalidateGroupAccess: the local call is not redundant because
+   * syncMessageManager hardcodes skipSelf, so the publishing node never receives
+   * its own message. Passing the transaction defers the broadcast until the
+   * write commits, so other nodes cannot re-read the old row and re-cache it.
+   */
+  private invalidateRolePermissionSync(roleName: unknown, transaction?: Transactionable['transaction']) {
+    invalidateRolePermissionCache(roleName as string | undefined);
+    this.sendSyncMessage({ type: 'invalidateRolePermission', roleName }, { transaction });
   }
 
   /**
@@ -206,9 +242,11 @@ export class PluginAiApiServer extends Plugin {
   /**
    * Received only on the *other* nodes (skipSelf), so this must not re-broadcast.
    */
-  async handleSyncMessage(message: { type?: string; groupId?: unknown }) {
+  async handleSyncMessage(message: { type?: string; groupId?: unknown; roleName?: unknown }) {
     if (message?.type === 'invalidateGroupAccess') {
       invalidateGroupAccessCache(message.groupId as string | number | bigint);
+    } else if (message?.type === 'invalidateRolePermission') {
+      invalidateRolePermissionCache(message.roleName as string | undefined);
     }
   }
 
@@ -227,6 +265,19 @@ export class PluginAiApiServer extends Plugin {
       });
     }
 
+    // Root and admin get explicit AI API permission rows on fresh installs. There is no
+    // built-in role bypass anymore, so without these rows even root/admin would be denied
+    // until an admin grants access in Settings → Users & Permissions.
+    for (const roleName of ['root', 'admin']) {
+      const perm = await this.db.getRepository('aiApiRolePermissions').findOne({
+        filter: { roleName },
+      });
+      if (!perm) {
+        await this.db.getRepository('aiApiRolePermissions').create({
+          values: { roleName, enabled: true, allowAllEmployees: true, allowedEmployees: [] },
+        });
+      }
+    }
     // Create default usage group on first install
     const defaultGroup = await this.db.getRepository('aiApiUsageGroups').findOne({
       filter: { isDefault: true },
@@ -256,6 +307,15 @@ export class PluginAiApiServer extends Plugin {
     }
   }
 
+  private async cleanupResponseRecords(): Promise<void> {
+    try {
+      const deleted = await cleanupExpiredResponseRecords({ db: this.db });
+      if (deleted > 0) this.app.logger.info(`[ai-api] Cleaned up ${deleted} expired response records`);
+    } catch (error) {
+      this.app.logger.warn('[ai-api] Failed to clean up expired response records:', error);
+    }
+  }
+
   async afterEnable() {}
 
   async afterDisable() {}
@@ -266,6 +326,10 @@ export class PluginAiApiServer extends Plugin {
       clearInterval(this.gcInterval);
       this.gcInterval = null;
     }
+    if (this.responseCleanupInterval) {
+      clearInterval(this.responseCleanupInterval);
+      this.responseCleanupInterval = null;
+    }
     this.rateLimiter.clear();
   }
 }

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

@@ -59,7 +59,8 @@ const aiApiConfigResource: ResourceOptions = {
     },
 
     async save(ctx, next) {
-      const values = ctx.action.params.values || (ctx.request.body as any) || {};
+      const values: Record<string, unknown> =
+        ctx.action.params.values || (ctx.request.body as Record<string, unknown>) || {};
       const repo = ctx.db.getRepository('aiApiConfig');
       let config = await repo.findOne();
 

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

@@ -104,6 +104,9 @@ export async function handleAgentCompletions(ctx: Context, plugin: PluginAiApiSe
   }
 
   // ─── Resolve model ─────────────────────────────────────────────────────────
+  // Agent mode runs the AI Employee pipeline, so virtual aliases ("auto") are intentionally
+  // not resolved here: capability-bucket routing is a direct-LLM concept. The model field
+  // selects the concrete model the employee uses.
   const resolved = await resolveModelString(ctx, body.model);
   if (!resolved) {
     ctx.status = 404;

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

@@ -20,6 +20,7 @@ import {
   OpenAIToolCallChunk,
 } from '../utils/openai-format';
 import { resolveModelString } from '../utils/resolve-service';
+import { resolveVirtualModel, respondVirtualModelUnavailable } from '../utils/virtual-models';
 import {
   createRequestAbortController,
   isClientDisconnected,
@@ -96,8 +97,17 @@ export async function handleChatCompletions(ctx: Context, plugin: PluginAiApiSer
 
   const stream = isStreamingRequested(body.stream);
 
-  // ─── Resolve model string against DB ───
-  const resolved = await resolveModelString(ctx, body.model);
+  // ─── Resolve model string against DB (virtual alias first, then concrete) ───
+  const virtual = await resolveVirtualModel(ctx, body.model, body, 'chat');
+  if (virtual?.status === 'unavailable') {
+    respondVirtualModelUnavailable(ctx, virtual);
+    return;
+  }
+  if (virtual?.status === 'resolved') {
+    ctx.state.aiApiVirtualModel = virtual.virtualModel;
+    ctx.state.aiApiRoutingReason = virtual.reason;
+  }
+  const resolved = virtual?.resolved ?? (await resolveModelString(ctx, body.model));
   if (!resolved) {
     ctx.status = 404;
     ctx.body = toOpenAIError(
@@ -236,7 +246,7 @@ export async function handleChatCompletions(ctx: Context, plugin: PluginAiApiSer
         chatModel,
         langchainMessages,
         completionId,
-        body.model,
+        `${service.name}/${modelId}`,
         providerRequestParameters,
       );
     } else {
@@ -246,7 +256,7 @@ export async function handleChatCompletions(ctx: Context, plugin: PluginAiApiSer
         chatModel,
         langchainMessages,
         completionId,
-        body.model,
+        `${service.name}/${modelId}`,
         providerRequestParameters,
       );
     }
@@ -722,7 +732,7 @@ function describeImageUrlProblem(imageUrl: unknown): string | 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>[];
+export type MessageContent = string | Record<string, unknown>[];
 
 /**
  * Normalize an OpenAI `message.content` into something LangChain accepts.
@@ -763,7 +773,7 @@ export function normalizeMessageContent(content: unknown): MessageContent {
  * block (e.g. a `file_url` becomes a `file` block, which may then be converted
  * to images by the PDF processor).
  */
-async function processMessageContentFileBlocks(
+export async function processMessageContentFileBlocks(
   content: unknown,
   ctx: Context,
   plugin: PluginAiApiServer,
@@ -807,7 +817,21 @@ async function processFileBlockChain(
   return next;
 }
 
-const GATEWAY_MANAGED_PARAMETERS = new Set(['model', 'messages', 'prompt', 'tools', 'tool_choice', 'stream', 'n']);
+const GATEWAY_MANAGED_PARAMETERS = new Set([
+  'model',
+  'messages',
+  'prompt',
+  'tools',
+  'tool_choice',
+  'stream',
+  'n',
+  // Responses API specific fields that should not be passed to providers
+  'input',
+  'previous_response_id',
+  'store',
+  'truncation',
+  'metadata',
+]);
 
 export function getProviderRequestParameters(body: Record<string, unknown>): Record<string, unknown> {
   return Object.fromEntries(
@@ -836,7 +860,7 @@ export function applyProviderRequestParameters(chatModel: unknown, parameters: R
   model.modelKwargs = { ...modelKwargs, ...parameters };
 }
 
-function bindRequestTools(
+export function bindRequestTools(
   chatModel: any,
   tools: unknown,
   toolChoice: unknown,
@@ -865,7 +889,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-function normalizeToolCalls(value: unknown): OpenAIToolCall[] | undefined {
+export function normalizeToolCalls(value: unknown): OpenAIToolCall[] | undefined {
   if (!Array.isArray(value) || value.length === 0) return undefined;
   return value.map((call: any) => ({
     id: String(call.id || ''),
@@ -877,7 +901,7 @@ function normalizeToolCalls(value: unknown): OpenAIToolCall[] | undefined {
   }));
 }
 
-function normalizeToolCallChunks(value: unknown): OpenAIToolCallChunk[] {
+export function normalizeToolCallChunks(value: unknown): OpenAIToolCallChunk[] {
   if (!Array.isArray(value)) return [];
   return value.map((call: any, fallbackIndex) => ({
     index: typeof call.index === 'number' ? call.index : fallbackIndex,

package/src/server/routes/completions.ts

@@ -16,6 +16,7 @@ import {
   toOpenAIUsageChunk,
 } from '../utils/openai-format';
 import { resolveModelString } from '../utils/resolve-service';
+import { resolveVirtualModel, respondVirtualModelUnavailable } from '../utils/virtual-models';
 import { enforceModelAccess } from '../utils/user-permissions';
 import {
   createRequestAbortController,
@@ -70,7 +71,16 @@ export async function handleCompletions(ctx: Context, plugin: PluginAiApiServer)
   const stream = isStreamingRequested(body.stream);
 
   // ─── Resolve model string against DB ───
-  const resolved = await resolveModelString(ctx, body.model);
+  const virtual = await resolveVirtualModel(ctx, body.model, body, 'chat');
+  if (virtual?.status === 'unavailable') {
+    respondVirtualModelUnavailable(ctx, virtual);
+    return;
+  }
+  if (virtual?.status === 'resolved') {
+    ctx.state.aiApiVirtualModel = virtual.virtualModel;
+    ctx.state.aiApiRoutingReason = virtual.reason;
+  }
+  const resolved = virtual?.resolved ?? (await resolveModelString(ctx, body.model));
   if (!resolved) {
     ctx.status = 404;
     ctx.body = toOpenAIError(
@@ -124,7 +134,8 @@ export async function handleCompletions(ctx: Context, plugin: PluginAiApiServer)
 
     if (body.temperature !== undefined) modelOptions.temperature = body.temperature;
     if (body.top_p !== undefined) modelOptions.topP = body.top_p;
-    if (body.max_tokens !== undefined) modelOptions.maxTokens = body.max_tokens;
+    if (body.max_completion_tokens !== undefined) modelOptions.maxTokens = body.max_completion_tokens;
+    else if (body.max_tokens !== undefined) modelOptions.maxTokens = body.max_tokens;
     if (body.stop !== undefined) modelOptions.stop = body.stop;
 
     // ─── Convert prompt to message tuple ───
@@ -142,6 +153,7 @@ export async function handleCompletions(ctx: Context, plugin: PluginAiApiServer)
       serviceName: service.name,
       modelId,
       messages,
+      maxCompletionTokens: body.max_completion_tokens,
       maxTokens: body.max_tokens,
     });
     await prepareLlmBilling(ctx, resolved);
@@ -169,7 +181,7 @@ export async function handleCompletions(ctx: Context, plugin: PluginAiApiServer)
         chatModel,
         langchainMessages,
         completionId,
-        body.model,
+        `${service.name}/${modelId}`,
         body.stream_options,
         providerRequestParameters,
       );
@@ -179,7 +191,7 @@ export async function handleCompletions(ctx: Context, plugin: PluginAiApiServer)
         chatModel,
         langchainMessages,
         completionId,
-        body.model,
+        `${service.name}/${modelId}`,
         providerRequestParameters,
       );
     }

package/src/server/routes/embeddings.ts

@@ -10,11 +10,12 @@
 import { Context } from '@nocobase/actions';
 import { toOpenAIError, toOpenAIEmbeddingsResponse } from '../utils/openai-format';
 import { resolveModelString } from '../utils/resolve-service';
+import { resolveVirtualModel, respondVirtualModelUnavailable } from '../utils/virtual-models';
 import { enforceModelAccess } from '../utils/user-permissions';
 import { getAiApiConfig } from '../utils/request-cache';
 import { setAiApiUsageResult } from '../usage';
 import type PluginAiApiServer from '../plugin';
-import { markLlmProviderAttempted, prepareLlmBilling, finalizeLlmBilling } from '../billing';
+import { markLlmProviderAttempted, prepareLlmBilling, AiApiQuotaError } from '../billing';
 
 /**
  * POST /api/ai-llm/v1/embeddings
@@ -90,7 +91,16 @@ export async function handleEmbeddings(ctx: Context, plugin: PluginAiApiServer)
   }
 
   // ─── Resolve model ────────────────────────────────────────────────────────
-  const resolved = await resolveModelString(ctx, body.model);
+  const virtual = await resolveVirtualModel(ctx, body.model, body, 'embedding');
+  if (virtual?.status === 'unavailable') {
+    respondVirtualModelUnavailable(ctx, virtual);
+    return;
+  }
+  if (virtual?.status === 'resolved') {
+    ctx.state.aiApiVirtualModel = virtual.virtualModel;
+    ctx.state.aiApiRoutingReason = virtual.reason;
+  }
+  const resolved = virtual?.resolved ?? (await resolveModelString(ctx, body.model));
   if (!resolved) {
     ctx.status = 404;
     ctx.body = toOpenAIError(
@@ -104,9 +114,6 @@ export async function handleEmbeddings(ctx: Context, plugin: PluginAiApiServer)
 
   const { service, modelId } = resolved;
 
-  // ─── Prepare billing/quota ────────────────────────────────────────────────
-  await prepareLlmBilling(ctx, resolved);
-
   if (service.enabled === false) {
     ctx.status = 404;
     ctx.body = toOpenAIError(
@@ -160,7 +167,12 @@ export async function handleEmbeddings(ctx: Context, plugin: PluginAiApiServer)
     return;
   }
 
+  // ─── Prepare billing/quota after access checks ────────────────────────────
+  // Running this after service.enabled and enforceModelAccess avoids a needless
+  // reserve/release round-trip on every rejected request.
+
   try {
+    await prepareLlmBilling(ctx, resolved);
     // ─── Instantiate and call the embedding provider ──────────────────────
     const EmbeddingClass = providerMeta.embedding;
     const embeddingProvider = new EmbeddingClass({
@@ -183,12 +195,11 @@ export async function handleEmbeddings(ctx: Context, plugin: PluginAiApiServer)
       total_tokens: estimatedInputTokens,
     };
     setAiApiUsageResult(ctx, usage);
-    await finalizeLlmBilling(ctx, usage, true);
 
     ctx.status = 200;
     ctx.set('Content-Type', 'application/json');
     ctx.body = toOpenAIEmbeddingsResponse({
-      model: body.model,
+      model: `${service.name}/${modelId}`,
       embeddings: vectors,
       // LangChain's EmbeddingsInterface does not expose token counts.
       promptTokens: null,
@@ -196,8 +207,19 @@ export async function handleEmbeddings(ctx: Context, plugin: PluginAiApiServer)
   } catch (err) {
     ctx.log.error('AI API embeddings error:', err);
     if (!ctx.res.headersSent) {
-      ctx.status = 500;
-      ctx.body = toOpenAIError(500, err.message || 'Failed to generate embeddings', 'server_error');
+      const isQuotaError = err instanceof AiApiQuotaError;
+      ctx.status = isQuotaError ? 429 : 500;
+      if (isQuotaError) ctx.set('X-RateLimit-Reason', err.code);
+      ctx.body = toOpenAIError(
+        ctx.status,
+        getErrorMessage(err, 'Failed to generate embeddings'),
+        isQuotaError ? 'quota_error' : 'server_error',
+        isQuotaError ? err.code : undefined,
+      );
     }
   }
-}
+}
+
+function getErrorMessage(error: unknown, fallback: string) {
+  return error instanceof Error && error.message ? error.message : fallback;
+}

package/src/server/routes/models.ts

@@ -11,6 +11,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 { listAccessibleVirtualModels, type VirtualModel } from '../utils/virtual-models';
 import type PluginAiApiServer from '../plugin';
 
 /**
@@ -75,6 +76,17 @@ export async function handleListModels(ctx: Context, plugin: PluginAiApiServer)
       }
     }
 
+    // Expose enabled virtual aliases (e.g. "auto") so clients can discover and use them.
+    // They carry virtual:true and a description, but no capability overrides of their own.
+    try {
+      const virtualModels = await listAccessibleVirtualModels(ctx, scope, config?.enabledLlmServices);
+      for (const virtualModel of virtualModels) {
+        models.push(buildVirtualModelObject(virtualModel, now));
+      }
+    } catch {
+      // Virtual models table may not exist yet during a rolling upgrade — skip silently.
+    }
+
     ctx.status = 200;
     ctx.body = {
       object: 'list',
@@ -137,6 +149,16 @@ export async function handleGetModel(ctx: Context, modelId: string, plugin: Plug
       if (found) break;
     }
 
+    if (!found) {
+      try {
+        const virtualModels = await listAccessibleVirtualModels(ctx, scope, config?.enabledLlmServices);
+        const virtualModel = virtualModels.find((candidate) => candidate.name === modelId);
+        if (virtualModel) found = buildVirtualModelObject(virtualModel, now);
+      } catch {
+        // Virtual models table may not exist yet during a rolling upgrade.
+      }
+    }
+
     if (!found) {
       ctx.status = 404;
       ctx.body = toOpenAIError(404, `Model '${modelId}' not found`, 'invalid_request_error', 'model_not_found');
@@ -246,6 +268,18 @@ export function buildModelObject(
   return model;
 }
 
+export function buildVirtualModelObject(virtualModel: VirtualModel, created: number): Record<string, unknown> {
+  return {
+    id: virtualModel.name,
+    object: 'model',
+    created,
+    owned_by: 'ai-api-gateway',
+    virtual: true,
+    mode: virtualModel.mode,
+    description: `Virtual ${virtualModel.mode} alias routed to a concrete model based on the request shape.`,
+  };
+}
+
 function toPositiveInt(value: unknown): number | null {
   const n = Number(value);
   return Number.isSafeInteger(n) && n > 0 ? n : null;