plugin-ai-api 1.0.20 → 1.0.23

package/src/server/routes/router.ts

@@ -22,9 +22,13 @@ import { startUsageRecord, finishUsageRecord } from '../usage';
 import { isStreamingRequested } from '../utils/streaming';
 import type PluginAiApiServer from '../plugin';
 import { finalizeLlmBilling } from '../billing';
+import { finishAiApiObservation, startAiApiObservation } from '../utils/app-observability';
 
 const API_PREFIX = '/api/ai-llm/v1';
 
+/** Shared so the plugin can disable the core body parser for exactly these routes. */
+export const AI_LLM_PREFIX = API_PREFIX;
+
 type DataWrappingContext = Context & { withoutDataWrapping?: boolean };
 
 /**
@@ -90,22 +94,9 @@ export function createAiLlmRouter(plugin: PluginAiApiServer) {
     const requestId = `req-${crypto.randomBytes(12).toString('hex')}`;
     ctx.set('X-Request-Id', requestId);
 
-    // ─── Parse body for POST requests if not already parsed ───────────────
-    if (method === 'POST' && !ctx.request.body) {
-      try {
-        const rawBody = await getRawBody(ctx);
-        ctx.request.body = JSON.parse(rawBody);
-      } catch (bodyErr: unknown) {
-        const status =
-          bodyErr && typeof bodyErr === 'object' && 'statusCode' in bodyErr && bodyErr.statusCode === 413 ? 413 : 400;
-        const message = status === 413 ? 'Request body too large (max 10 MB)' : 'Invalid JSON in request body';
-        ctx.status = status;
-        ctx.body = toOpenAIError(status, message, 'invalid_request_error');
-        return;
-      }
-    }
-
     // ─── Authenticate ─────────────────────────────────────────────────────
+    // Runs before the body is read: buffering a multi-megabyte payload for an
+    // anonymous caller would let unauthenticated traffic pin memory.
     const isAuth = await authenticateBearer(ctx);
     if (!isAuth) {
       logRequest(ctx, requestId, '-', 'auth_failed', 0);
@@ -126,6 +117,32 @@ export function createAiLlmRouter(plugin: PluginAiApiServer) {
       return;
     }
 
+    // ─── Parse body for POST requests if not already parsed ───────────────
+    if (method === 'POST' && !ctx.request.body) {
+      const maxBodyBytes = await resolveMaxBodyBytes(ctx);
+      const declaredLength = Number(ctx.get('Content-Length'));
+      if (Number.isFinite(declaredLength) && declaredLength > maxBodyBytes) {
+        respondBodyTooLarge(ctx, maxBodyBytes);
+        logRequest(ctx, requestId, '-', 'body_too_large', 0);
+        return;
+      }
+      try {
+        const rawBody = await getRawBody(ctx, maxBodyBytes);
+        ctx.request.body = JSON.parse(rawBody);
+      } catch (bodyErr: unknown) {
+        const tooLarge =
+          bodyErr && typeof bodyErr === 'object' && 'statusCode' in bodyErr && bodyErr.statusCode === 413;
+        if (tooLarge) {
+          respondBodyTooLarge(ctx, maxBodyBytes);
+          logRequest(ctx, requestId, '-', 'body_too_large', 0);
+          return;
+        }
+        ctx.status = 400;
+        ctx.body = toOpenAIError(400, 'Invalid JSON in request body', 'invalid_request_error');
+        return;
+      }
+    }
+
     // ─── Route matching ───────────────────────────────────────────────────
     const requestBody = (ctx.request.body || {}) as Record<string, unknown>;
     const model = requestBody.model === undefined || requestBody.model === null ? '-' : String(requestBody.model);
@@ -145,6 +162,23 @@ export function createAiLlmRouter(plugin: PluginAiApiServer) {
       };
     }
     const t0 = Date.now();
+    if (isUsageEndpoint) {
+      const service =
+        subPath === '/embeddings'
+          ? 'llm.embedding'
+          : resolvedMode === 'agent'
+            ? 'llm.agent'
+            : subPath === '/completions'
+              ? 'llm.completion'
+              : 'llm.chat';
+      startAiApiObservation(ctx, {
+        service,
+        operation: subPath,
+        streaming,
+        model: model === '-' ? undefined : model,
+        mode: resolvedMode,
+      });
+    }
     let usageId: unknown;
     try {
       usageId = isUsageEndpoint
@@ -275,32 +309,108 @@ export function createAiLlmRouter(plugin: PluginAiApiServer) {
           ctx.log.error('AI API quota reservation could not be finalized:', billingError);
         }
       }
+      if (isUsageEndpoint) {
+        const streamResult = ctx.state.aiApiStreamResult;
+        finishAiApiObservation(ctx, {
+          status:
+            streamResult?.errorCode === 'client_disconnected'
+              ? 'cancelled'
+              : streamResult
+                ? streamResult.succeeded
+                  ? 'succeeded'
+                  : 'failed'
+                : ctx.status >= 200 && ctx.status < 400
+                  ? 'succeeded'
+                  : ctx.status >= 500
+                    ? 'failed'
+                    : 'rejected',
+          errorCode: streamResult?.errorCode,
+        });
+      }
     }
   };
 }
 
-/** Maximum allowed request body size (10 MB) to prevent OOM DoS attacks. */
-const MAX_BODY_BYTES = 10 * 1024 * 1024;
+/** Body size cap used when aiApiConfig has no usable maxRequestBodyMb. */
+const DEFAULT_MAX_BODY_MB = 10;
+
+/**
+ * Upper bound an admin can configure.
+ *
+ * The gateway buffers the whole payload in memory (raw chunks, the decoded
+ * string, and the parsed object all coexist briefly), so an unbounded value
+ * would turn a config typo into an out-of-memory risk.
+ */
+export const MAX_REQUEST_BODY_MB_LIMIT = 100;
+
+/** Clamp a configured megabyte value into the supported range. */
+export function normalizeMaxRequestBodyMb(value: unknown): number {
+  const mb = Number(value);
+  if (!Number.isSafeInteger(mb) || mb <= 0) return DEFAULT_MAX_BODY_MB;
+  return Math.min(mb, MAX_REQUEST_BODY_MB_LIMIT);
+}
+
+async function resolveMaxBodyBytes(ctx: Context): Promise<number> {
+  let configuredMb: unknown;
+  try {
+    const config = await ctx.db.getRepository('aiApiConfig').findOne();
+    configuredMb = config?.get('maxRequestBodyMb');
+  } catch (err) {
+    ctx.log?.warn?.('AI API: could not read maxRequestBodyMb, using default:', err);
+  }
+  return normalizeMaxRequestBodyMb(configuredMb) * 1024 * 1024;
+}
+
+function formatMb(bytes: number): string {
+  return `${Math.round(bytes / (1024 * 1024))} MB`;
+}
+
+function respondBodyTooLarge(ctx: Context, maxBodyBytes: number): void {
+  ctx.status = 413;
+  ctx.body = toOpenAIError(
+    413,
+    `Request body too large (max ${formatMb(maxBodyBytes)}). ` +
+      `Inline base64 images inflate payloads by ~33%; raise "Max request body size" in Settings → AI API Gateway if needed.`,
+    'invalid_request_error',
+  );
+}
 
 /**
- * Read raw body from request stream (fallback if bodyparser didn't handle it).
- * Rejects with a 413-style error if the body exceeds MAX_BODY_BYTES.
+ * Read the raw request body.
+ *
+ * The plugin disables the core koa-bodyparser for these routes (see plugin.ts),
+ * so this cap is the one that actually governs gateway payload size.
+ * Rejects with a 413-style error once maxBodyBytes is exceeded.
+ *
+ * Exported so tests can drive the real implementation over a live socket rather
+ * than a copy that cannot catch a regression here.
  */
-function getRawBody(ctx: Context): Promise<string> {
+export function getRawBody(ctx: Pick<Context, 'req'>, maxBodyBytes: number): Promise<string> {
   return new Promise((resolve, reject) => {
-    let body = '';
+    const chunks: Buffer[] = [];
     let byteCount = 0;
+    let aborted = false;
 
     ctx.req.on('data', (chunk: Buffer) => {
+      if (aborted) return;
       byteCount += chunk.length;
-      if (byteCount > MAX_BODY_BYTES) {
-        ctx.req.destroy();
-        reject(Object.assign(new Error('Request body too large (max 10 MB)'), { statusCode: 413 }));
+      if (byteCount > maxBodyBytes) {
+        // Drop what we buffered and drain the rest instead of destroying the
+        // socket: ctx.req and the response share one connection, so destroying
+        // it replaces our 413 JSON with an ECONNRESET on the client.
+        aborted = true;
+        chunks.length = 0;
+        ctx.req.resume();
+        reject(Object.assign(new Error(`Request body too large (max ${formatMb(maxBodyBytes)})`), { statusCode: 413 }));
         return;
       }
-      body += chunk.toString();
+      chunks.push(chunk);
+    });
+    // Decode once at the end: a multi-byte UTF-8 character can straddle a chunk
+    // boundary, and per-chunk toString() would corrupt it.
+    ctx.req.on('end', () => {
+      if (!aborted) resolve(Buffer.concat(chunks).toString('utf8'));
     });
-    ctx.req.on('end', () => resolve(body));
     ctx.req.on('error', reject);
   });
 }

package/src/server/usage.ts

@@ -1,5 +1,6 @@
 import { Context } from '@nocobase/actions';
 import { finalizeLlmBilling, type LlmBillingState } from './billing';
+import { addAiApiUsage } from './utils/app-observability';
 
 export type Usage = {
   prompt_tokens: number | null;
@@ -76,6 +77,7 @@ export function setAiApiUsageResult(
   getAiApiState(ctx).aiApiUsageResult = usage
     ? { source: 'provider', usage, ...metadata }
     : { source: 'unavailable', ...metadata };
+  addAiApiUsage(ctx, usage);
   return usage;
 }
 

package/src/server/utils/app-observability.ts

@@ -0,0 +1,105 @@
+import type { Context } from '@nocobase/actions';
+
+interface ObservationFinish {
+  status: 'succeeded' | 'failed' | 'cancelled' | 'rejected';
+  errorCode?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+}
+interface ObservationHandle {
+  markFirstByte(): void;
+  addInputTokens(value: number): void;
+  addOutputTokens(value: number): void;
+  finish(result: ObservationFinish): void;
+}
+interface AppObservabilityContract {
+  start(input: {
+    service: string;
+    operation: string;
+    streaming?: boolean;
+    attributes?: Record<string, string | number | boolean | null>;
+  }): ObservationHandle;
+}
+interface AiApiObservabilityState {
+  aiApiObservabilityHandle?: ObservationHandle;
+  aiApiObservabilityOutcome?: ObservationFinish;
+}
+
+const CONTRACT_SYMBOL = Symbol.for('nocobase.app-observability.contract');
+const NOOP_HANDLE: ObservationHandle = {
+  markFirstByte() {},
+  addInputTokens() {},
+  addOutputTokens() {},
+  finish() {},
+};
+
+function state(ctx: Context): AiApiObservabilityState {
+  return ctx.state as AiApiObservabilityState;
+}
+
+function safely(ctx: Context, callback: () => void): void {
+  try {
+    callback();
+  } catch (error) {
+    ctx.app?.logger?.warn?.('[ai-api] App observability callback failed', { error });
+  }
+}
+
+export function startAiApiObservation(
+  ctx: Context,
+  input: {
+    service: 'llm.chat' | 'llm.agent' | 'llm.completion' | 'llm.embedding';
+    operation: string;
+    streaming: boolean;
+    model?: string;
+    mode: 'llm' | 'agent';
+  },
+): void {
+  let handle = NOOP_HANDLE;
+  safely(ctx, () => {
+    const contract = (ctx.app as object & { [CONTRACT_SYMBOL]?: AppObservabilityContract })[CONTRACT_SYMBOL];
+    if (!contract || typeof contract.start !== 'function') return;
+    const candidate = contract.start({
+      service: input.service,
+      operation: input.operation,
+      streaming: input.streaming,
+      attributes: {
+        mode: input.mode,
+        endpoint: input.operation,
+        ...(input.model ? { model: input.model } : {}),
+      },
+    });
+    if (candidate && typeof candidate.finish === 'function') handle = candidate;
+  });
+  state(ctx).aiApiObservabilityHandle = handle;
+}
+
+export function markAiApiFirstProviderOutput(ctx: Context): void {
+  safely(ctx, () => state(ctx).aiApiObservabilityHandle?.markFirstByte());
+}
+
+export function addAiApiUsage(
+  ctx: Context,
+  usage?: { prompt_tokens: number | null; completion_tokens: number | null },
+): void {
+  if (!usage) return;
+  safely(ctx, () => {
+    const handle = state(ctx).aiApiObservabilityHandle;
+    if (usage.prompt_tokens !== null) handle?.addInputTokens(usage.prompt_tokens);
+    if (usage.completion_tokens !== null) handle?.addOutputTokens(usage.completion_tokens);
+  });
+}
+
+export function setAiApiObservationOutcome(ctx: Context, outcome: ObservationFinish): void {
+  state(ctx).aiApiObservabilityOutcome = outcome;
+}
+
+export function finishAiApiObservation(ctx: Context, fallback: ObservationFinish): void {
+  const current = state(ctx);
+  const handle = current.aiApiObservabilityHandle;
+  if (!handle) return;
+  current.aiApiObservabilityHandle = undefined;
+  const outcome = current.aiApiObservabilityOutcome ?? fallback;
+  current.aiApiObservabilityOutcome = undefined;
+  safely(ctx, () => handle.finish(outcome));
+}

package/src/server/utils/openai-format.ts

@@ -97,6 +97,14 @@ export function toOpenAIResponse(options: {
 
 // ─── OpenAI Streaming chunk format ───
 
+export type OpenAIUsage = {
+  prompt_tokens: number | null;
+  completion_tokens: number | null;
+  total_tokens: number | null;
+};
+
+export type OpenAIStreamObject = 'chat.completion.chunk' | 'text_completion';
+
 export function toOpenAIStreamChunk(options: {
   id: string;
   model: string;
@@ -118,6 +126,24 @@ export function toOpenAIStreamChunk(options: {
         finish_reason: finishReason,
       },
     ],
+    usage: null,
+  };
+}
+
+export function toOpenAIUsageChunk(options: {
+  id: string;
+  model: string;
+  usage: OpenAIUsage;
+  object?: OpenAIStreamObject;
+}) {
+  const { id, model, usage, object = 'chat.completion.chunk' } = options;
+  return {
+    id,
+    object,
+    created: Math.floor(Date.now() / 1000),
+    model,
+    choices: [],
+    usage,
   };
 }
 

package/src/server/utils/streaming.ts

@@ -1,5 +1,17 @@
 import type { Context } from '@nocobase/actions';
 
+export class AiApiClientDisconnectedError extends Error {
+  readonly code = 'client_disconnected';
+  constructor() {
+    super('Client disconnected');
+    this.name = 'AiApiClientDisconnectedError';
+  }
+}
+
+export function isClientDisconnected(ctx: Context, error: unknown): boolean {
+  return ctx.req.aborted === true || error instanceof AiApiClientDisconnectedError;
+}
+
 export function isStreamingRequested(value: unknown) {
   return value !== false;
 }
@@ -7,7 +19,7 @@ export function isStreamingRequested(value: unknown) {
 export function createRequestAbortController(ctx: Context) {
   const controller = new AbortController();
   const abort = () => {
-    if (!ctx.res.writableEnded) controller.abort(new Error('Client disconnected'));
+    if (!ctx.res.writableEnded) controller.abort(new AiApiClientDisconnectedError());
   };
   ctx.req.once('aborted', abort);
   ctx.res.once('close', abort);

package/src/server/utils/user-permissions.ts

@@ -0,0 +1,218 @@
+/**
+ * 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 { Context } from '@nocobase/actions';
+import { toOpenAIError } from './openai-format';
+
+const SCOPE_TTL_MS = 15_000;
+
+interface CachedScope {
+  scope: AiApiAccessScope;
+  expiresAt: number;
+}
+
+const scopeCache = new Map<string, CachedScope>();
+
+/**
+ * Resolved per-user LLM access, layered *under* the global `aiApiConfig.enabledLlmServices`
+ * whitelist. A user grant can only ever narrow global access, never widen it.
+ */
+export interface AiApiAccessScope {
+  /** False when the user has no aiApiUserPermissions row — global config alone decides. */
+  hasUserRecord: boolean;
+  /** True when a row exists but is switched off, denying every service. */
+  denyAll: boolean;
+  /** null means "no user-level narrowing"; an empty array denies every service. */
+  allowedServices: string[] | null;
+  allowAllModels: boolean;
+  allowedModels: Set<string>;
+  /**
+   * True when the lookup itself failed. Distinct from hasUserRecord:false — "this user has no
+   * restrictions" and "we cannot tell whether this user has restrictions" must not be conflated,
+   * or a mid-rolling-upgrade missing table silently lifts every user's restrictions.
+   */
+  lookupFailed: boolean;
+}
+
+const NO_RECORD_SCOPE: AiApiAccessScope = {
+  hasUserRecord: false,
+  denyAll: false,
+  allowedServices: null,
+  allowAllModels: true,
+  allowedModels: new Set(),
+  lookupFailed: false,
+};
+
+const LOOKUP_FAILED_SCOPE: AiApiAccessScope = { ...NO_RECORD_SCOPE, denyAll: true, lookupFailed: true };
+
+/**
+ * Invalidate cached scopes for one user across every app in this process, or all users when
+ * called with no argument. Keys are `${appName}:${userId}`, and the afterSave hook only knows
+ * the user id, so the match is on the suffix.
+ *
+ * This is per-process only: in a multi-node deployment other nodes keep serving their cached
+ * scope until the 15s TTL expires.
+ */
+export function invalidateUserPermissionCache(userId?: string | number | bigint): void {
+  if (userId === undefined || userId === null) {
+    scopeCache.clear();
+    return;
+  }
+  const suffix = `:${userId}`;
+  for (const key of scopeCache.keys()) {
+    if (key.endsWith(suffix)) scopeCache.delete(key);
+  }
+}
+
+/**
+ * Sequelize instances expose columns through .get() only — a plain property read returns
+ * undefined for most fields. Mirrors valueOf() in billing.ts so plain-object test fixtures
+ * work too.
+ */
+function valueOf<T>(row: unknown, name: string): T {
+  if (!row) return undefined as T;
+  const candidate = row as { get?: (key: string) => unknown };
+  if (typeof candidate.get === 'function') return candidate.get(name) as T;
+  return (row as Record<string, unknown>)[name] as T;
+}
+
+function toStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => typeof item === 'string' && item.length > 0);
+}
+
+/** Build a scope from an aiApiUserPermissions row (or absence of one). */
+export function buildAccessScope(row: unknown): AiApiAccessScope {
+  if (!row) return NO_RECORD_SCOPE;
+  if (valueOf<boolean>(row, 'enabled') === false) {
+    return { ...NO_RECORD_SCOPE, hasUserRecord: true, denyAll: true, allowedServices: [] };
+  }
+  return {
+    hasUserRecord: true,
+    denyAll: false,
+    allowedServices: toStringArray(valueOf(row, 'allowedLlmServices')),
+    allowAllModels: valueOf<boolean>(row, 'allowAllModels') !== false,
+    allowedModels: new Set(toStringArray(valueOf(row, 'allowedModels'))),
+    lookupFailed: false,
+  };
+}
+
+/**
+ * Load the current user's access scope, cached for 15s per user id — the same TTL the role
+ * permission cache uses. Invalidated by afterSave/afterDestroy hooks in plugin.ts.
+ */
+export async function resolveUserAccessScope(ctx: Context): Promise<AiApiAccessScope> {
+  const userId = ctx.state.currentUser?.id;
+  if (userId === undefined || userId === null) return NO_RECORD_SCOPE;
+
+  // Sub-apps share this process but have separate databases, so user id 1 in one app is a
+  // different person than user id 1 in another. Without the app prefix they collide here.
+  const key = `${ctx.app?.name ?? 'main'}:${userId}`;
+  const cached = scopeCache.get(key);
+  if (cached && cached.expiresAt > Date.now()) return cached.scope;
+
+  let scope: AiApiAccessScope;
+  try {
+    const row = await ctx.db.getRepository('aiApiUserPermissions').findOne({ filter: { userId } });
+    scope = buildAccessScope(row);
+  } catch (err) {
+    // Fail closed. A failed lookup cannot be treated as "no restrictions": during a rolling
+    // upgrade the table may not exist yet, and that must not lift every user's restrictions.
+    ctx.log?.error?.('AI API user permissions lookup failed, denying access:', err);
+    return LOOKUP_FAILED_SCOPE;
+  }
+
+  scopeCache.set(key, { scope, expiresAt: Date.now() + SCOPE_TTL_MS });
+  return scope;
+}
+
+function matchesService(list: string[], serviceName?: string, serviceTitle?: string): boolean {
+  return list.some((entry) => entry === serviceName || entry === serviceTitle);
+}
+
+/**
+ * Effective service check: the global whitelist AND the user grant must both allow it.
+ *
+ * An empty global whitelist means "expose all services", preserving existing behaviour.
+ * An empty user grant means "deny everything" — the record itself is the opt-in.
+ */
+export function isServiceAllowed(
+  scope: AiApiAccessScope,
+  globalEnabledServices: unknown,
+  service: { name?: string; title?: string },
+): boolean {
+  // denyAll is checked before hasUserRecord: a failed lookup denies without having a record.
+  if (scope.denyAll) return false;
+  const globalList = toStringArray(globalEnabledServices);
+  if (globalList.length && !matchesService(globalList, service.name, service.title)) return false;
+  if (!scope.hasUserRecord) return true;
+  return matchesService(scope.allowedServices ?? [], service.name, service.title);
+}
+
+/** Model-level narrowing on top of isServiceAllowed, keyed by "serviceName/modelId". */
+export function isModelAllowed(scope: AiApiAccessScope, fullModelId: string): boolean {
+  if (scope.denyAll) return false;
+  if (!scope.hasUserRecord) return true;
+  if (scope.allowAllModels) return true;
+  return scope.allowedModels.has(fullModelId);
+}
+
+/**
+ * Gate a completion/embedding request on the caller's effective service+model access.
+ *
+ * Writes a 403 in OpenAI error shape and returns false when access is denied, so callers
+ * can `if (!(await enforceModelAccess(...))) return;`.
+ */
+export async function enforceModelAccess(
+  ctx: Context,
+  globalEnabledServices: unknown,
+  service: { name?: string; title?: string },
+  modelId: string,
+): Promise<boolean> {
+  const scope = await resolveUserAccessScope(ctx);
+  const serviceLabel = service.title || service.name;
+
+  // The denial is ours, not the caller's — report it as retryable rather than as a permission
+  // decision, so clients back off instead of treating the grant as permanently revoked.
+  if (scope.lookupFailed) {
+    ctx.status = 503;
+    ctx.body = toOpenAIError(
+      503,
+      'Unable to verify LLM permissions for this user. Please retry shortly.',
+      'service_unavailable',
+      'permission_check_failed',
+    );
+    return false;
+  }
+
+  if (!isServiceAllowed(scope, globalEnabledServices, service)) {
+    ctx.status = 403;
+    ctx.body = toOpenAIError(
+      403,
+      `LLM service '${serviceLabel}' is not enabled for API access`,
+      'permission_denied',
+      'model_not_available',
+    );
+    return false;
+  }
+
+  if (!isModelAllowed(scope, `${service.name}/${modelId}`)) {
+    ctx.status = 403;
+    ctx.body = toOpenAIError(
+      403,
+      `Model '${service.name}/${modelId}' is not permitted for this user. ` +
+        `Use GET /v1/models to see available models.`,
+      'permission_denied',
+      'model_not_available',
+    );
+    return false;
+  }
+
+  return true;
+}

package/src/server/validation.ts

@@ -42,6 +42,33 @@ export async function validateModelPrice(db: Database, model: Model): Promise<vo
   if (overlap) throw new Error('An enabled price already overlaps this effective period.');
 }
 
+function requirePositiveIntegerOrNull(value: unknown, field: string): void {
+  if (value === null || value === undefined || value === '') return;
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) throw new Error(`${field} must be a positive integer.`);
+}
+
+export function validateModelMetadata(model: Model): void {
+  if (!String(model.get('llmService') ?? '').trim()) throw new Error('llmService is required.');
+  if (!String(model.get('model') ?? '').trim()) throw new Error('model is required.');
+  requirePositiveIntegerOrNull(model.get('contextWindow'), 'contextWindow');
+  requirePositiveIntegerOrNull(model.get('maxCompletionTokens'), 'maxCompletionTokens');
+
+  const contextWindow = model.get('contextWindow');
+  const maxCompletionTokens = model.get('maxCompletionTokens');
+  if (
+    contextWindow !== null &&
+    contextWindow !== undefined &&
+    contextWindow !== '' &&
+    maxCompletionTokens !== null &&
+    maxCompletionTokens !== undefined &&
+    maxCompletionTokens !== '' &&
+    Number(maxCompletionTokens) > Number(contextWindow)
+  ) {
+    throw new Error('maxCompletionTokens cannot exceed contextWindow.');
+  }
+}
+
 export function validateQuotaPolicy(model: Model): void {
   if (!['daily', 'monthly'].includes(String(model.get('periodType')))) {
     throw new Error('periodType must be daily or monthly.');