plugin-ai-api 1.0.24 → 1.0.28

package/src/server/migrations/20260813000000-add-prompt-cache-tokens.ts

@@ -0,0 +1,46 @@
+import { Migration } from '@nocobase/server';
+
+export default class AddPromptCacheTokensToUsageRecords extends Migration {
+  on = 'beforeLoad' as const;
+
+  async up() {
+    const collection = this.db.getCollection('aiApiUsageRecords');
+    if (!collection) return;
+
+    const field = collection.getField('promptCacheTokens');
+    if (!field) {
+      collection.addField('promptCacheTokens', { type: 'integer', allowNull: true });
+    }
+
+    if (await collection.existsInDb()) {
+      const tableName = collection.getTableNameWithSchema();
+      const exists = await this.tableColumnExists(tableName, 'promptCacheTokens');
+      if (!exists) {
+        await this.queryInterface.addColumn(tableName, 'promptCacheTokens', {
+          type: this.db.sequelize.getDialect() === 'sqlite' ? 'INTEGER' : 'INTEGER',
+          allowNull: true,
+        });
+      }
+    }
+  }
+
+  async down() {
+    const collection = this.db.getCollection('aiApiUsageRecords');
+    if (!collection) return;
+
+    if (await collection.existsInDb()) {
+      const tableName = collection.getTableNameWithSchema();
+      const exists = await this.tableColumnExists(tableName, 'promptCacheTokens');
+      if (exists) {
+        await this.queryInterface.removeColumn(tableName, 'promptCacheTokens');
+      }
+    }
+
+    collection.removeField('promptCacheTokens');
+  }
+
+  private async tableColumnExists(tableName: string, columnName: string): Promise<boolean> {
+    const columns = await this.queryInterface.describeTable(tableName);
+    return Object.prototype.hasOwnProperty.call(columns, columnName);
+  }
+}

package/src/server/migrations/20260815000000-add-usage-groups.ts

@@ -0,0 +1,147 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { Migration } from '@nocobase/server';
+
+export default class AddUsageGroups extends Migration {
+  // Must run afterSync: plugin collections are only registered once the app has
+  // loaded, and the new group tables must exist before seeding.
+  on = 'afterSync' as const;
+
+  async up() {
+    const groupCollection = this.getGroupCollection();
+
+    if (!groupCollection) {
+      throw new Error('AI API usage groups migration could not resolve the aiApiUsageGroups collection.');
+    }
+
+    const configCollection = this.db.getCollection('aiApiConfig');
+    let rateLimitPerMinute = 60;
+    let quotaEnabled = false;
+    if (configCollection && (await configCollection.existsInDb())) {
+      // rateLimitPerMinute is no longer part of the collection definition, so
+      // read the legacy column directly before dropping it.
+      const tableName = configCollection.getTableNameWithSchema();
+      const columns = await this.queryInterface.describeTable(tableName);
+      if (columns.rateLimitPerMinute) {
+        const legacyRateLimit = await this.readLegacyRateLimit(configCollection.quotedTableName());
+        if (legacyRateLimit && legacyRateLimit > 0) {
+          rateLimitPerMinute = legacyRateLimit;
+        }
+      }
+      const config = await this.db.getRepository('aiApiConfig').findOne();
+      if (config) {
+        quotaEnabled = !!config.get('quotaEnabled');
+      }
+    }
+
+    const existingDefault = await this.db.getRepository('aiApiUsageGroups').findOne({
+      filter: { isDefault: true },
+    });
+
+    if (!existingDefault) {
+      await this.db.getRepository('aiApiUsageGroups').create({
+        values: {
+          name: 'Default',
+          isDefault: true,
+          quotaMode: 'per_user',
+          rateLimitPerMinute,
+          enabled: quotaEnabled,
+          periodType: 'monthly',
+          timezone: 'UTC',
+          requestLimit: null,
+          totalTokenLimit: null,
+          costLimit: null,
+          currency: 'USD',
+          rejectUnpricedModel: true,
+          missingUsageBehavior: 'use_reserved',
+          contextOverflowBehavior: 'reject',
+        },
+      });
+    }
+
+    if (configCollection && (await configCollection.existsInDb())) {
+      const tableName = configCollection.getTableNameWithSchema();
+      const columns = await this.queryInterface.describeTable(tableName);
+      if (columns.rateLimitPerMinute) {
+        await this.queryInterface.removeColumn(tableName, 'rateLimitPerMinute');
+      }
+    }
+
+    await this.migrateLegacyQuotaPolicies();
+  }
+
+  async down() {
+    // Recreate the rateLimitPerMinute column on aiApiConfig with a sensible default.
+    const configCollection = this.db.getCollection('aiApiConfig');
+    if (configCollection && (await configCollection.existsInDb())) {
+      const tableName = configCollection.getTableNameWithSchema();
+      const columns = await this.queryInterface.describeTable(tableName);
+      if (!columns.rateLimitPerMinute) {
+        await this.queryInterface.addColumn(tableName, 'rateLimitPerMinute', {
+          type: 'INTEGER',
+          allowNull: false,
+          defaultValue: 60,
+        });
+      }
+    }
+  }
+
+  private getGroupCollection() {
+    return this.db.getCollection('aiApiUsageGroups');
+  }
+
+  private async readLegacyRateLimit(quotedTable: string): Promise<number | undefined> {
+    const qi = this.db.sequelize.getQueryInterface();
+    const [rows] = await this.db.sequelize.query(
+      `SELECT ${qi.quoteIdentifier('rateLimitPerMinute')} FROM ${quotedTable} LIMIT 1`,
+    );
+    const first = (rows as Array<Record<string, unknown>> | undefined)?.[0];
+    const value = Number(first?.rateLimitPerMinute);
+    return Number.isFinite(value) ? value : undefined;
+  }
+
+  private async migrateLegacyQuotaPolicies() {
+    const defaultGroup = await this.db.getRepository('aiApiUsageGroups').findOne({
+      filter: { isDefault: true },
+    });
+    if (!defaultGroup) return;
+
+    const policyCollection = this.db.getCollection('aiApiUserQuotaPolicies');
+    const memberCollection = this.db.getCollection('aiApiGroupMembers');
+    const bucketCollection = this.db.getCollection('aiApiGroupQuotaBuckets');
+    if (!policyCollection || !memberCollection || !bucketCollection) return;
+
+    const policies = (await this.db.getRepository('aiApiUserQuotaPolicies').find({
+      pageSize: 1000,
+    })) as unknown[];
+
+    for (const policy of policies) {
+      const userId = this.valueOf(policy, 'userId');
+      if (userId === undefined || userId === null) continue;
+
+      const existingMember = await this.db.getRepository('aiApiGroupMembers').findOne({
+        filter: { userId },
+      });
+      if (!existingMember) {
+        await this.db.getRepository('aiApiGroupMembers').create({
+          values: { groupId: this.valueOf(defaultGroup, 'id'), userId },
+        });
+      }
+    }
+  }
+
+  private valueOf(model: unknown, name: string): unknown {
+    if (!model) return undefined;
+    if (typeof (model as Record<string, unknown>).get === 'function') {
+      return (model as Record<string, unknown>).get(name);
+    }
+    return (model as Record<string, unknown>)[name];
+  }
+}

package/src/server/migrations/20260816000000-migrate-user-permissions-to-groups.ts

@@ -0,0 +1,190 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { Migration } from '@nocobase/server';
+
+interface PermissionSignature {
+  allowedLlmServices: string[];
+  allowAllModels: boolean;
+  allowedModels: string[];
+}
+
+/**
+ * Model access moved from per-user rows (aiApiUserPermissions) to usage groups.
+ * Users with identical grants share one migrated group; quota settings are copied
+ * from the default group so migrated users keep the same quota behaviour.
+ *
+ * The old per-user semantics cannot be fully expressed on groups: an empty grant
+ * meant "deny all". Rows that denied everything (enabled=false, no services, or
+ * allowAllModels=false with no models) are left unmigrated — those users inherit
+ * the default group's open access and a warning is logged.
+ */
+export default class MigrateUserPermissionsToGroups extends Migration {
+  // Must run afterSync: the new allowedLlmServices/allowAllModels/allowedModels
+  // columns on aiApiUsageGroups only exist once collections have been synced.
+  on = 'afterSync' as const;
+
+  async up() {
+    const collection = this.db.getCollection('aiApiUserPermissions');
+    if (!collection || !(await collection.existsInDb())) return;
+
+    const repository = this.db.getRepository('aiApiUserPermissions');
+    const rows: unknown[] = [];
+    for (let page = 1; ; page += 1) {
+      const batch = (await repository.find({ page, pageSize: 1000, sort: 'id' })) as unknown[];
+      rows.push(...batch);
+      if (batch.length < 1000) break;
+    }
+    if (!rows.length) return;
+
+    const migratable: { userId: unknown; sig: PermissionSignature }[] = [];
+    const deniedUserIds: unknown[] = [];
+
+    for (const row of rows) {
+      const userId = this.valueOf(row, 'userId');
+      if (userId === undefined || userId === null) continue;
+
+      const enabled = this.valueOf(row, 'enabled') !== false;
+      const allowedLlmServices = this.stringArray(this.valueOf(row, 'allowedLlmServices'));
+      const allowAllModels = this.valueOf(row, 'allowAllModels') !== false;
+      const allowedModels = this.stringArray(this.valueOf(row, 'allowedModels'));
+
+      // Old semantics: no services = deny all; allowAllModels=false with no models = deny all.
+      const hasEffectiveGrant = allowedLlmServices.length > 0 && (allowAllModels || allowedModels.length > 0);
+      if (!enabled || !hasEffectiveGrant) {
+        deniedUserIds.push(userId);
+        continue;
+      }
+      migratable.push({ userId, sig: { allowedLlmServices, allowAllModels, allowedModels } });
+    }
+
+    if (deniedUserIds.length) {
+      this.app.logger.warn(
+        `[ai-api] ${deniedUserIds.length} aiApiUserPermissions row(s) denied all access ` +
+          `(enabled=false or empty grant) and cannot be migrated to usage groups. These users now ` +
+          `inherit the default group's access. Affected userIds: ${deniedUserIds.join(', ')}. ` +
+          `Use role permissions to block API access entirely.`,
+      );
+    }
+
+    if (!migratable.length) return;
+
+    const defaultGroup = await this.db.getRepository('aiApiUsageGroups').findOne({
+      filter: { isDefault: true },
+    });
+    const quotaValues = this.quotaValuesFrom(defaultGroup);
+
+    // Group rows by access signature so users with identical grants share one group.
+    const bySignature = new Map<string, { sig: PermissionSignature; userIds: unknown[] }>();
+    for (const { userId, sig } of migratable) {
+      const key = JSON.stringify({
+        allowedLlmServices: [...sig.allowedLlmServices].sort(),
+        allowAllModels: sig.allowAllModels,
+        allowedModels: [...sig.allowedModels].sort(),
+      });
+      const entry = bySignature.get(key);
+      if (entry) {
+        entry.userIds.push(userId);
+      } else {
+        bySignature.set(key, { sig, userIds: [userId] });
+      }
+    }
+
+    let index = 0;
+    for (const { sig, userIds } of bySignature.values()) {
+      index += 1;
+      const group = await this.db.getRepository('aiApiUsageGroups').create({
+        values: {
+          ...quotaValues,
+          name: `Migrated permissions ${index}`,
+          isDefault: false,
+          quotaMode: 'per_user',
+          allowedLlmServices: sig.allowedLlmServices,
+          allowAllModels: sig.allowAllModels,
+          allowedModels: sig.allowedModels,
+        },
+      });
+      const groupId = this.valueOf(group, 'id');
+
+      for (const userId of userIds) {
+        const existing = await this.db.getRepository('aiApiGroupMembers').findOne({ filter: { userId } });
+        if (existing) {
+          await this.db.getRepository('aiApiGroupMembers').update({
+            filterByTk: this.valueOf(existing, 'id'),
+            values: { groupId },
+          });
+        } else {
+          await this.db.getRepository('aiApiGroupMembers').create({ values: { groupId, userId } });
+        }
+      }
+    }
+
+    this.app.logger.info(
+      `[ai-api] Migrated ${migratable.length} aiApiUserPermissions row(s) into ${bySignature.size} usage group(s).`,
+    );
+  }
+
+  async down() {
+    // The legacy rows are never modified, so rolling back only means removing the
+    // migrated groups and their memberships.
+    const groups = (await this.db.getRepository('aiApiUsageGroups').find({
+      filter: { 'name.$startsWith': 'Migrated permissions' },
+    })) as unknown[];
+    for (const group of groups) {
+      const groupId = this.valueOf(group, 'id');
+      await this.db.getRepository('aiApiGroupMembers').destroy({ filter: { groupId } });
+      await this.db.getRepository('aiApiUsageGroups').destroy({ filterByTk: groupId });
+    }
+  }
+
+  private quotaValuesFrom(defaultGroup: unknown): Record<string, unknown> {
+    if (!defaultGroup) {
+      return {
+        rateLimitPerMinute: 60,
+        enabled: false,
+        periodType: 'monthly',
+        timezone: 'UTC',
+        requestLimit: null,
+        totalTokenLimit: null,
+        costLimit: null,
+        currency: 'USD',
+        rejectUnpricedModel: true,
+        missingUsageBehavior: 'use_reserved',
+        contextOverflowBehavior: 'reject',
+      };
+    }
+    return {
+      rateLimitPerMinute: Number(this.valueOf(defaultGroup, 'rateLimitPerMinute') ?? 60),
+      enabled: !!this.valueOf(defaultGroup, 'enabled'),
+      periodType: this.valueOf(defaultGroup, 'periodType') ?? 'monthly',
+      timezone: this.valueOf(defaultGroup, 'timezone') ?? 'UTC',
+      requestLimit: this.valueOf(defaultGroup, 'requestLimit') ?? null,
+      totalTokenLimit: this.valueOf(defaultGroup, 'totalTokenLimit') ?? null,
+      costLimit: this.valueOf(defaultGroup, 'costLimit') ?? null,
+      currency: this.valueOf(defaultGroup, 'currency') ?? 'USD',
+      rejectUnpricedModel: !!this.valueOf(defaultGroup, 'rejectUnpricedModel'),
+      missingUsageBehavior: this.valueOf(defaultGroup, 'missingUsageBehavior') ?? 'use_reserved',
+      contextOverflowBehavior: this.valueOf(defaultGroup, 'contextOverflowBehavior') ?? 'reject',
+    };
+  }
+
+  private stringArray(value: unknown): string[] {
+    return Array.isArray(value)
+      ? value.filter((item): item is string => typeof item === 'string' && item.length > 0)
+      : [];
+  }
+
+  private valueOf(model: unknown, name: string): unknown {
+    if (!model) return undefined;
+    if (typeof (model as Record<string, unknown>).get === 'function') {
+      return (model as Record<string, unknown>).get(name);
+    }
+    return (model as Record<string, unknown>)[name];
+  }
+}

package/src/server/migrations/20260816100000-add-model-metadata-system-prompt.ts

@@ -0,0 +1,46 @@
+import { Migration } from '@nocobase/server';
+
+export default class AddSystemPromptToModelMetadata extends Migration {
+  on = 'beforeLoad' as const;
+
+  async up() {
+    const collection = this.db.getCollection('aiApiModelMetadata');
+    if (!collection) return;
+
+    const field = collection.getField('systemPrompt');
+    if (!field) {
+      collection.addField('systemPrompt', { type: 'text', allowNull: true });
+    }
+
+    if (await collection.existsInDb()) {
+      const tableName = collection.getTableNameWithSchema();
+      const exists = await this.tableColumnExists(tableName, 'systemPrompt');
+      if (!exists) {
+        await this.queryInterface.addColumn(tableName, 'systemPrompt', {
+          type: 'TEXT',
+          allowNull: true,
+        });
+      }
+    }
+  }
+
+  async down() {
+    const collection = this.db.getCollection('aiApiModelMetadata');
+    if (!collection) return;
+
+    if (await collection.existsInDb()) {
+      const tableName = collection.getTableNameWithSchema();
+      const exists = await this.tableColumnExists(tableName, 'systemPrompt');
+      if (exists) {
+        await this.queryInterface.removeColumn(tableName, 'systemPrompt');
+      }
+    }
+
+    collection.removeField('systemPrompt');
+  }
+
+  private async tableColumnExists(tableName: string, columnName: string): Promise<boolean> {
+    const columns = await this.queryInterface.describeTable(tableName);
+    return Object.prototype.hasOwnProperty.call(columns, columnName);
+  }
+}

package/src/server/plugin.ts

@@ -12,12 +12,18 @@ 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 aiApiUserPermissionsResource from './resource/ai-api-user-permissions';
+import aiApiUsageGroupsResource from './resource/ai-api-usage-groups';
 import { RateLimiter } from './utils/rate-limiter';
 import { invalidateRolePermissionCache } from './middleware/role-permission';
-import { invalidateUserPermissionCache } from './utils/user-permissions';
+import { invalidateGroupAccessCache } from './utils/user-permissions';
 import { validateModelPrice, validateModelMetadata, validateQuotaPolicy } from './validation';
-import { AI_API_ACL_SNIPPET, AI_API_USER_PERMISSIONS_SNIPPET } from '../constants';
+import { AI_API_ACL_SNIPPET } from '../constants';
+import {
+  FileProcessorService,
+  base64FileForwarder,
+  httpFileUrlFetcher,
+  pdfFileProcessor,
+} from './services/file-processor';
 
 // Ensure dayjs timezone + utc plugins are loaded.
 // Some Docker builds ship an older @nocobase/utils whose dayjs.js does not
@@ -35,10 +41,16 @@ import timezonePlugin from 'dayjs/plugin/timezone';
 export class PluginAiApiServer extends Plugin {
   /**
    * Singleton rate limiter — lives for the entire plugin lifetime, shared across all requests.
-   * Uses a 1-minute sliding window to enforce rateLimitPerMinute from aiApiConfig.
+   * Uses a 1-minute sliding window to enforce rateLimitPerMinute from the user's usage group.
    */
   rateLimiter = new RateLimiter(60_000);
 
+  /**
+   * Extensible file processor service. Other plugins can register custom processors
+   * to transform file/file_url content blocks before they reach the LLM.
+   */
+  fileProcessorService = new FileProcessorService();
+
   private gcInterval: NodeJS.Timeout | null = null;
 
   async afterAdd() {}
@@ -50,12 +62,71 @@ export class PluginAiApiServer extends Plugin {
     this.app.db.on('aiApiModelMetadata.beforeSave', (model) => {
       validateModelMetadata(model);
     });
-    this.app.db.on('aiApiUserQuotaPolicies.beforeSave', (model) => {
+    this.app.db.on('aiApiUsageGroups.beforeSave', async (model, options) => {
       validateQuotaPolicy(model);
+      // The partial unique index on isDefault is not supported on MySQL,
+      // so enforce single-default-group here as well.
+      if (model.get('isDefault')) {
+        const filter: Record<string, unknown> = { isDefault: true };
+        if (model.get('id')) filter.id = { $ne: model.get('id') };
+        const other = await this.db.getRepository('aiApiUsageGroups').findOne({
+          filter,
+          transaction: options?.transaction,
+        });
+        if (other) {
+          throw new Error('Only one default usage group is allowed.');
+        }
+      }
+    });
+
+    this.app.db.on('aiApiGroupMembers.beforeSave', async (model, options) => {
+      const userId = model.get('userId');
+      if (!userId) return;
+      const existing = await this.db.getRepository('aiApiGroupMembers').findOne({
+        filter: { userId },
+        transaction: options?.transaction,
+      });
+      if (existing && existing.get('id') !== model.get('id')) {
+        throw new Error('User already belongs to another usage group.');
+      }
+    });
+
+    this.app.db.on('aiApiUsageGroups.beforeDestroy', async (model, options) => {
+      if (model.get('isDefault')) {
+        throw new Error('The default usage group cannot be deleted.');
+      }
+      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({
+          filterByTk: member.get('id'),
+          values: { groupId: defaultGroup.get('id') },
+          transaction: options?.transaction,
+        });
+      }
     });
   }
 
   async load() {
+    // Register default file processors. Custom plugins can register additional
+    // processors by retrieving this plugin instance and calling
+    // `fileProcessorService.register(processor)`.
+    this.fileProcessorService.register(base64FileForwarder);
+    this.fileProcessorService.register(httpFileUrlFetcher);
+    this.fileProcessorService.register(pdfFileProcessor);
+
     // 1. Claim body parsing for our own routes before the core bodyParser runs.
     //    Core registers koa-bodyparser with a global REQUEST_BODY_LIMIT (10mb by
     //    default) much earlier in the stack, so without this the gateway's own
@@ -80,7 +151,7 @@ export class PluginAiApiServer extends Plugin {
     // 2. Register admin config resource
     this.app.resourceManager.define(aiApiConfigResource);
     this.app.resourceManager.define(aiApiUsageMonitorResource);
-    this.app.resourceManager.define(aiApiUserPermissionsResource);
+    this.app.resourceManager.define(aiApiUsageGroupsResource);
 
     this.app.db.on('aiApiRolePermissions.afterSave', (model) => {
       invalidateRolePermissionCache(model.get('roleName'));
@@ -89,11 +160,11 @@ export class PluginAiApiServer extends Plugin {
       invalidateRolePermissionCache(model.get('roleName'));
     });
 
-    this.app.db.on('aiApiUserPermissions.afterSave', (model, options) => {
-      this.revokeUserPermissions(model.get('userId'), options?.transaction);
+    this.app.db.on('aiApiUsageGroups.afterSave', (model, options) => {
+      this.invalidateGroupAccess(model.get('id'), options?.transaction);
     });
-    this.app.db.on('aiApiUserPermissions.afterDestroy', (model, options) => {
-      this.revokeUserPermissions(model.get('userId'), options?.transaction);
+    this.app.db.on('aiApiUsageGroups.afterDestroy', (model, options) => {
+      this.invalidateGroupAccess(model.get('id'), options?.transaction);
     });
 
     // 3. Set ACL permissions for admin config + role permissions management
@@ -104,24 +175,16 @@ export class PluginAiApiServer extends Plugin {
         'aiApiRolePermissions:*',
         'aiApiModelPrices:*',
         'aiApiModelMetadata:*',
-        'aiApiUserQuotaPolicies:*',
-        'aiApiUserQuotaBuckets:list',
-        'aiApiUserQuotaBuckets:get',
+        'aiApiUsageGroups:*',
+        'aiApiGroupMembers:*',
+        'aiApiGroupQuotaBuckets:list',
+        'aiApiGroupQuotaBuckets:get',
         'aiApiUsageRecords:list',
         'aiApiUsageRecords:get',
         'aiApiUsageMonitor:summary',
       ],
     });
 
-    // Per-user LLM grants are a separate child permission: handing out model access is a
-    // stronger capability than editing gateway settings, so it ticks independently.
-    // The wildcard also covers `listUsers`, which backs the page's user picker — without it
-    // the page would depend on `pm.plugin-users` and break for a role holding only this snippet.
-    this.app.acl.registerSnippet({
-      name: AI_API_USER_PERMISSIONS_SNIPPET,
-      actions: ['aiApiUserPermissions:*'],
-    });
-
     // 4. GC the rate limiter every 5 minutes to evict stale user entries.
     //    .unref() prevents this timer from keeping the process alive on shutdown.
     this.gcInterval = setInterval(() => this.rateLimiter.gc(), 5 * 60 * 1000);
@@ -129,23 +192,23 @@ export class PluginAiApiServer extends Plugin {
   }
 
   /**
-   * Drop a user's cached LLM scope on every node.
+   * Drop a group's cached model-access scope on every node.
    *
    * The local call is not redundant: 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 revokeUserPermissions(userId: unknown, transaction?: Transactionable['transaction']) {
-    invalidateUserPermissionCache(userId as string | number | bigint);
-    this.sendSyncMessage({ type: 'invalidateUserPermissions', userId }, { transaction });
+  private invalidateGroupAccess(groupId: unknown, transaction?: Transactionable['transaction']) {
+    invalidateGroupAccessCache(groupId as string | number | bigint);
+    this.sendSyncMessage({ type: 'invalidateGroupAccess', groupId }, { transaction });
   }
 
   /**
    * Received only on the *other* nodes (skipSelf), so this must not re-broadcast.
    */
-  async handleSyncMessage(message: { type?: string; userId?: unknown }) {
-    if (message?.type === 'invalidateUserPermissions') {
-      invalidateUserPermissionCache(message.userId as string | number | bigint);
+  async handleSyncMessage(message: { type?: string; groupId?: unknown }) {
+    if (message?.type === 'invalidateGroupAccess') {
+      invalidateGroupAccessCache(message.groupId as string | number | bigint);
     }
   }
 
@@ -157,12 +220,40 @@ export class PluginAiApiServer extends Plugin {
         values: {
           defaultAiEmployee: '',
           enabledLlmServices: [],
-          rateLimitPerMinute: 60,
           quotaEnabled: false,
+          pdfRenderPagesAsImages: false,
           defaultReservationOutputTokens: 4096,
         },
       });
     }
+
+    // Create default usage group on first install
+    const defaultGroup = await this.db.getRepository('aiApiUsageGroups').findOne({
+      filter: { isDefault: true },
+    });
+    if (!defaultGroup) {
+      await this.db.getRepository('aiApiUsageGroups').create({
+        values: {
+          name: 'Default',
+          isDefault: true,
+          quotaMode: 'per_user',
+          rateLimitPerMinute: 60,
+          enabled: false,
+          periodType: 'monthly',
+          timezone: 'UTC',
+          requestLimit: null,
+          totalTokenLimit: null,
+          costLimit: null,
+          currency: 'USD',
+          rejectUnpricedModel: true,
+          missingUsageBehavior: 'use_reserved',
+          contextOverflowBehavior: 'reject',
+          allowedLlmServices: [],
+          allowAllModels: true,
+          allowedModels: [],
+        },
+      });
+    }
   }
 
   async afterEnable() {}