plugin-ai-api 1.1.0 → 1.1.2

package/src/server/routes/router.ts

@@ -15,6 +15,7 @@ import { handleChatCompletions } from './chat-completions';
 import { handleCompletions } from './completions';
 import { handleAgentCompletions } from './agent-completions';
 import { handleEmbeddings } from './embeddings';
+import { handleDeleteResponse, handleGetResponse, handleResponses } from './responses';
 import { toOpenAIError } from '../utils/openai-format';
 import { createRateLimitMiddleware } from '../middleware/rate-limit';
 import { checkRolePermission } from '../middleware/role-permission';
@@ -51,6 +52,8 @@ type DataWrappingContext = Context & { withoutDataWrapping?: boolean };
  *   POST /v1/chat/completions  — OpenAI chat completions (LLM or agent mode)
  *   POST /v1/completions       — Legacy text completions (LiteLLM compat)
  *   POST /v1/embeddings        — OpenAI embeddings
+ *   POST /v1/responses         — OpenAI Responses API
+ *   GET/DELETE /v1/responses/:id — Retrieve or delete a stored response
  *   GET  /v1/models            — List available models
  *   GET  /v1/models/:id        — Get a single model
  *   DELETE /v1/models/:id      — Not implemented (501 stub)
@@ -148,11 +151,18 @@ export function createAiLlmRouter(plugin: PluginAiApiServer) {
     const requestBody = (ctx.request.body || {}) as Record<string, unknown>;
     const model = requestBody.model === undefined || requestBody.model === null ? '-' : String(requestBody.model);
     const isUsageEndpoint =
-      method === 'POST' && (subPath === '/chat/completions' || subPath === '/completions' || subPath === '/embeddings');
-    const isStreamingEndpoint = method === 'POST' && (subPath === '/chat/completions' || subPath === '/completions');
-    const resolvedMode = isUsageEndpoint ? await resolveMode(ctx) : 'llm';
-    const streaming = isStreamingEndpoint && isStreamingRequested(requestBody.stream);
-    if (streaming) {
+      method === 'POST' &&
+      (subPath === '/chat/completions' ||
+        subPath === '/completions' ||
+        subPath === '/embeddings' ||
+        subPath === '/responses');
+    const isStreamingEndpoint =
+      method === 'POST' && (subPath === '/chat/completions' || subPath === '/completions' || subPath === '/responses');
+    const resolvedMode = subPath === '/responses' ? 'llm' : isUsageEndpoint ? await resolveMode(ctx) : 'llm';
+    const streaming =
+      isStreamingEndpoint &&
+      (subPath === '/responses' ? requestBody.stream === true : isStreamingRequested(requestBody.stream));
+    if (streaming && subPath !== '/responses') {
       const streamOptions = requestBody.stream_options;
       ctx.request.body = {
         ...requestBody,
@@ -167,11 +177,13 @@ export function createAiLlmRouter(plugin: PluginAiApiServer) {
       const service =
         subPath === '/embeddings'
           ? 'llm.embedding'
-          : resolvedMode === 'agent'
-            ? 'llm.agent'
-            : subPath === '/completions'
-              ? 'llm.completion'
-              : 'llm.chat';
+          : subPath === '/responses'
+            ? 'llm.responses'
+            : resolvedMode === 'agent'
+              ? 'llm.agent'
+              : subPath === '/completions'
+                ? 'llm.completion'
+                : 'llm.chat';
       startAiApiObservation(ctx, {
         service,
         operation: subPath,
@@ -210,6 +222,54 @@ export function createAiLlmRouter(plugin: PluginAiApiServer) {
         return;
       }
 
+      // POST /v1/responses — OpenAI Responses API
+      if (method === 'POST' && subPath === '/responses') {
+        await handleResponses(ctx, plugin);
+        logRequest(
+          ctx,
+          requestId,
+          model,
+          ctx.state.aiApiStreamResult?.succeeded === false ? 'error' : 'ok',
+          Date.now() - t0,
+        );
+        return;
+      }
+
+      // GET/DELETE /v1/responses/:id — stored Responses API objects, scoped to the authenticated user
+      if ((method === 'GET' || method === 'DELETE') && subPath.startsWith('/responses/')) {
+        const responseId = subPath.substring('/responses/'.length);
+        if (responseId) {
+          let decodedResponseId: string;
+          try {
+            decodedResponseId = decodeURIComponent(responseId);
+          } catch {
+            ctx.status = 400;
+            ctx.body = toOpenAIError(
+              400,
+              'Response ID contains invalid URL encoding',
+              'invalid_request_error',
+              'invalid_response_id',
+            );
+            logRequest(ctx, requestId, '-', 'invalid_response_id', Date.now() - t0);
+            return;
+          }
+          if (decodedResponseId.includes('/')) {
+            ctx.status = 404;
+            ctx.body = toOpenAIError(
+              404,
+              `Unknown endpoint: ${method} ${path}`,
+              'invalid_request_error',
+              'unknown_url',
+            );
+            logRequest(ctx, requestId, '-', 'not_found', Date.now() - t0);
+            return;
+          }
+          if (method === 'GET') await handleGetResponse(ctx, decodedResponseId);
+          else await handleDeleteResponse(ctx, decodedResponseId);
+          logRequest(ctx, requestId, '-', ctx.status === 404 ? 'not_found' : 'ok', Date.now() - t0);
+          return;
+        }
+      }
       // POST /v1/completions (legacy text completions — used by LiteLLM)
       if (method === 'POST' && subPath === '/completions') {
         const completionsMode = resolvedMode;
@@ -250,7 +310,16 @@ export function createAiLlmRouter(plugin: PluginAiApiServer) {
       if (method === 'GET' && subPath.startsWith('/models/')) {
         const modelId = subPath.substring('/models/'.length);
         if (modelId) {
-          await handleGetModel(ctx, decodeURIComponent(modelId), plugin);
+          let decodedModelId: string;
+          try {
+            decodedModelId = decodeURIComponent(modelId);
+          } catch {
+            ctx.status = 400;
+            ctx.body = toOpenAIError(400, 'Model ID contains invalid URL encoding', 'invalid_request_error');
+            logRequest(ctx, requestId, modelId, 'bad_request', Date.now() - t0);
+            return;
+          }
+          await handleGetModel(ctx, decodedModelId, plugin);
           logRequest(ctx, requestId, modelId, 'ok', Date.now() - t0);
           return;
         }
@@ -275,7 +344,7 @@ export function createAiLlmRouter(plugin: PluginAiApiServer) {
       ctx.body = toOpenAIError(
         404,
         `Unknown endpoint: ${method} ${path}. ` +
-          `Supported: POST /v1/chat/completions, POST /v1/completions, POST /v1/embeddings, GET /v1/models`,
+          `Supported: POST /v1/chat/completions, POST /v1/completions, POST /v1/embeddings, POST /v1/responses, GET/DELETE /v1/responses/:id, GET /v1/models`,
         'invalid_request_error',
         'unknown_url',
       );

package/src/server/services/__tests__/file-processor.test.ts

@@ -139,6 +139,7 @@ describe('pdfFileProcessor', () => {
           },
         },
         log: { warn: vi.fn() },
+        state: {},
       },
     } as any;
   }

package/src/server/usage.ts

@@ -7,6 +7,7 @@ export type Usage = {
   completion_tokens: number | null;
   total_tokens: number | null;
   prompt_cache_tokens?: number | null;
+  reasoning_tokens?: number | null;
 };
 
 export type AiApiAuthType = 'apiKey' | 'bearer' | 'oidc' | 'unknown';
@@ -39,6 +40,8 @@ interface AiApiContextState {
   currentUser?: { id?: string | number | bigint };
   oauthPrincipal?: OAuthPrincipal;
   aiApiLlmBilling?: LlmBillingState;
+  aiApiVirtualModel?: string;
+  aiApiRoutingReason?: string;
 }
 
 function getAiApiState(ctx: Context): AiApiContextState {
@@ -76,6 +79,21 @@ function extractPromptCacheTokens(source: Record<string, unknown>): number | nul
   return null;
 }
 
+function extractReasoningTokens(source: Record<string, unknown>): number | null {
+  const detailCandidates = [
+    source.output_token_details,
+    source.output_tokens_details,
+    source.completion_tokens_details,
+  ];
+  for (const details of detailCandidates) {
+    if (!details || typeof details !== 'object') continue;
+    const record = details as Record<string, unknown>;
+    const value = normalizeTokenCount(record.reasoning ?? record.reasoning_tokens);
+    if (value !== null) return value;
+  }
+  return normalizeTokenCount(source.reasoning_tokens ?? source.reasoningTokens);
+}
+
 export function normalizeUsage(value: unknown): Usage | undefined {
   if (!value || typeof value !== 'object') return undefined;
   const source = value as Record<string, unknown>;
@@ -97,6 +115,7 @@ export function normalizeUsage(value: unknown): Usage | undefined {
     // usage once and hand the result to setAiApiUsageResult, which normalizes
     // again — an already-extracted prompt_cache_tokens must survive that pass.
     prompt_cache_tokens: extractPromptCacheTokens(source) ?? normalizeTokenCount(source.prompt_cache_tokens),
+    reasoning_tokens: extractReasoningTokens(source) ?? normalizeTokenCount(source.reasoning_tokens),
   };
 }
 
@@ -180,7 +199,11 @@ export async function startUsageRecord(
     values: {
       requestId,
       userId,
-      roleName: state.currentRole || state.currentRoles?.[0] || 'unknown',
+      // When several roles granted access (union semantics), record all of them so the
+      // audit trail shows the full set, not just the first role in the list.
+      roleName: state.currentRoles?.length
+        ? (state.currentRoles as string[]).join(',')
+        : state.currentRole || 'unknown',
       authType: state.aiApiAuthType || (oauth ? 'oidc' : 'unknown'),
       oauthClientId: oauth?.clientId,
       oauthSubject: oauth?.subject,
@@ -195,7 +218,7 @@ export async function startUsageRecord(
         messageCount: messages?.length,
         promptCount,
         embeddingInputCount,
-        requestedMaxTokens: body.max_completion_tokens ?? body.max_tokens,
+        requestedMaxTokens: body.max_output_tokens ?? body.max_completion_tokens ?? body.max_tokens,
       },
     },
   });
@@ -233,6 +256,7 @@ export async function finishUsageRecord(ctx: Context, id: unknown, startedAt: nu
     quotaPolicyId: billing.quotaPolicyId ?? null,
     groupId: billing.groupId ?? null,
     inputPricePerMillionTokens: billing.inputPricePerMillionTokens ?? null,
+    cacheInputPricePerMillionTokens: billing.cacheInputPricePerMillionTokens ?? null,
     outputPricePerMillionTokens: billing.outputPricePerMillionTokens ?? null,
     fixedCostPerRequest: billing.fixedCostPerRequest ?? null,
     providerRequestId: usageResult.providerRequestId ?? null,
@@ -241,6 +265,10 @@ export async function finishUsageRecord(ctx: Context, id: unknown, startedAt: nu
     responseMetadata: {
       usageSource: usageResult.source,
       ...(gatewayResponseId ? { gatewayResponseId } : {}),
+      // When the request went through a virtual alias, keep both the alias and why
+      // it routed there; resolvedModel (from billing state) already holds the concrete model.
+      ...(state.aiApiVirtualModel ? { virtualModel: state.aiApiVirtualModel } : {}),
+      ...(state.aiApiRoutingReason ? { routingReason: state.aiApiRoutingReason } : {}),
     },
   };
   await ctx.db.getRepository('aiApiUsageRecords').update({ filterByTk: id, values });

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

@@ -48,7 +48,7 @@ function safely(ctx: Context, callback: () => void): void {
 export function startAiApiObservation(
   ctx: Context,
   input: {
-    service: 'llm.chat' | 'llm.agent' | 'llm.completion' | 'llm.embedding';
+    service: 'llm.chat' | 'llm.agent' | 'llm.completion' | 'llm.embedding' | 'llm.responses';
     operation: string;
     streaming: boolean;
     model?: string;

package/src/server/utils/direct-llm-context.ts

@@ -1,5 +1,5 @@
 import type { Context } from '@nocobase/actions';
-import { resolveRequestUserGroup } from './request-cache';
+import { getAiApiConfig, resolveRequestUserGroup } from './request-cache';
 
 export type ContextOverflowBehavior = 'reject' | 'truncate';
 
@@ -24,6 +24,7 @@ interface ContextPreparationOptions {
   tools?: unknown;
   maxCompletionTokens?: unknown;
   maxTokens?: unknown;
+  overflowBehavior?: ContextOverflowBehavior;
 }
 
 export interface PreparedDirectLlmContext {
@@ -39,8 +40,7 @@ export class DirectLlmContextError extends Error {
     readonly code:
       | 'context_length_exceeded'
       | 'context_estimation_unsupported'
-      | 'max_completion_tokens_exceeds_model_limit'
-      | 'model_context_metadata_not_configured',
+      | 'max_completion_tokens_exceeds_model_limit',
     message: string,
   ) {
     super(message);
@@ -297,18 +297,29 @@ function messagesWithTurns(messages: OpenAIMessage[], turns: OpenAIMessage[][]):
   return messages.filter((message) => isInstruction(message) || retainedMessages.has(message));
 }
 
+/**
+ * Gateway-wide context budget used when a model has no metadata override (or a
+ * partial one). Direct LLM mode must work out of the box for every model; the
+ * metadata table is an override mechanism, not a prerequisite. Providers still
+ * reject requests that exceed their real window, and admins can tighten the
+ * budget per model by adding a metadata row.
+ */
+export const DEFAULT_CONTEXT_WINDOW = 128_000;
+export const DEFAULT_MAX_COMPLETION_TOKENS = 8_192;
+
 async function loadModelMetadata(ctx: Context, serviceName: string, modelId: string): Promise<ModelMetadata> {
   const row = await ctx.db.getRepository('aiApiModelMetadata').findOne({
     filter: { llmService: serviceName, model: modelId, enabled: true },
   });
-  const contextWindow = positiveInteger(getValue<unknown>(row, 'contextWindow'));
-  const maxCompletionTokens = positiveInteger(getValue<unknown>(row, 'maxCompletionTokens'));
-  if (!contextWindow || !maxCompletionTokens) {
-    throw new DirectLlmContextError(
-      'model_context_metadata_not_configured',
-      `Context metadata is not configured for '${serviceName}/${modelId}'. Configure context window and max completion tokens.`,
-    );
-  }
+  const config = await getAiApiConfig(ctx);
+  const contextWindow =
+    positiveInteger(getValue<unknown>(row, 'contextWindow')) ??
+    positiveInteger(getValue<unknown>(config, 'defaultContextWindow')) ??
+    DEFAULT_CONTEXT_WINDOW;
+  const maxCompletionTokens =
+    positiveInteger(getValue<unknown>(row, 'maxCompletionTokens')) ??
+    positiveInteger(getValue<unknown>(config, 'defaultMaxCompletionTokens')) ??
+    DEFAULT_MAX_COMPLETION_TOKENS;
   const systemPromptValue = getValue<unknown>(row, 'systemPrompt');
   const systemPrompt = typeof systemPromptValue === 'string' ? systemPromptValue.trim() : '';
   return { contextWindow, maxCompletionTokens, ...(systemPrompt ? { systemPrompt } : {}) };
@@ -338,7 +349,7 @@ export async function prepareDirectLlmContext(
 ): Promise<PreparedDirectLlmContext> {
   const [metadata, behavior] = await Promise.all([
     loadModelMetadata(ctx, options.serviceName, options.modelId),
-    resolveOverflowBehavior(ctx),
+    options.overflowBehavior ? Promise.resolve(options.overflowBehavior) : resolveOverflowBehavior(ctx),
   ]);
   const reservedOutputTokens = resolveReservedOutputTokens(options, metadata);
   const inputTokenBudget = metadata.contextWindow - reservedOutputTokens;

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

@@ -117,6 +117,7 @@ export type OpenAIUsage = {
   completion_tokens: number | null;
   total_tokens: number | null;
   prompt_cache_tokens?: number | null;
+  reasoning_tokens?: number | null;
 };
 
 export type OpenAIStreamObject = 'chat.completion.chunk' | 'text_completion';

package/src/server/utils/resolve-service.ts

@@ -8,6 +8,7 @@
  */
 
 import { Context } from '@nocobase/actions';
+import type { Model } from '@nocobase/database';
 import { getAiApiConfig } from './request-cache';
 
 /**
@@ -36,7 +37,7 @@ export async function resolveLlmService(ctx: Context, serviceKey: string) {
 export async function resolveModelString(
   ctx: Context,
   modelString: string,
-): Promise<{ service: any; modelId: string } | null> {
+): Promise<{ service: Model; modelId: string } | null> {
   const repo = ctx.db.getRepository('llmServices');
 
   // ─── Strategy 1: Try splitting at "/" positions ───
@@ -81,3 +82,40 @@ export async function resolveModelString(
 
   return null;
 }
+/**
+ * Resolve a configured model reference strictly. Unlike resolveModelString, this never falls
+ * back to the default or single enabled service: a reference like "missing-service/gpt-4o"
+ * must fail instead of being reinterpreted as a model id on an unrelated service. Use this for
+ * admin-configured references (virtual model buckets and fallbacks), where silent misrouting
+ * would route traffic to the wrong model.
+ */
+export async function resolveModelReference(
+  ctx: Context,
+  reference: string,
+): Promise<{ service: Model; modelId: string } | null> {
+  const repo = ctx.db.getRepository('llmServices');
+
+  const slashPositions: number[] = [];
+  for (let i = 0; i < reference.length; i++) {
+    if (reference[i] === '/') {
+      slashPositions.push(i);
+    }
+  }
+
+  for (const pos of slashPositions) {
+    const serviceKey = reference.substring(0, pos);
+    const modelId = reference.substring(pos + 1);
+    if (!serviceKey || !modelId) continue;
+
+    let service = await repo.findOne({ filter: { name: serviceKey } });
+    if (!service) {
+      service = await repo.findOne({ filter: { title: serviceKey } });
+    }
+
+    if (service) {
+      return { service, modelId };
+    }
+  }
+
+  return null;
+}

package/src/server/utils/response-store.ts

@@ -0,0 +1,148 @@
+/**
+ * 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 type { Context } from '@nocobase/actions';
+import type { Model } from '@nocobase/database';
+import type { OpenAIMessage } from './direct-llm-context';
+import { responsesInputToMessages, type ResponseObject } from './responses-format';
+
+const RETENTION_DAYS = 30;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+export const RESPONSE_RETENTION_MS = RETENTION_DAYS * MS_PER_DAY;
+
+function valueOf<T>(model: unknown, key: string): T | undefined {
+  if (!model) return undefined;
+  if (typeof (model as { get?: unknown }).get === 'function') {
+    return (model as { get: (k: string) => unknown }).get(key) as T | undefined;
+  }
+  return (model as Record<string, unknown>)[key] as T | undefined;
+}
+
+function isExpired(value: unknown): boolean {
+  if (value === undefined || value === null || value === '') return true;
+  const timestamp = value instanceof Date ? value.getTime() : new Date(String(value)).getTime();
+  return !Number.isFinite(timestamp) || timestamp <= Date.now();
+}
+
+export interface ResponseRecord {
+  id: string | number | bigint;
+  responseId: string;
+  userId: string | number | bigint;
+  model: string;
+  input: unknown;
+  output: ResponseObject;
+  previousResponseId?: string;
+  metadata?: Record<string, unknown>;
+  expiresAt: Date | string;
+}
+
+export async function storeResponseRecord(
+  ctx: Context,
+  response: ResponseObject,
+  requestBody: Record<string, unknown>,
+  userId: string | number | bigint,
+): Promise<void> {
+  if (requestBody.store === false) return;
+
+  await ctx.db.getRepository('aiApiResponseRecords').create({
+    values: {
+      responseId: response.id,
+      userId,
+      model: response.model,
+      input: requestBody.input,
+      output: response,
+      previousResponseId: response.previous_response_id,
+      metadata: response.metadata,
+      expiresAt: new Date(Date.now() + RESPONSE_RETENTION_MS),
+    },
+  });
+}
+
+export async function getResponseRecord(
+  ctx: Pick<Context, 'db'>,
+  responseId: string,
+  userId: string | number | bigint,
+): Promise<ResponseRecord | null> {
+  const row = await ctx.db.getRepository('aiApiResponseRecords').findOne({
+    filter: { responseId, userId },
+  });
+  if (!row || isExpired(valueOf(row, 'expiresAt'))) return null;
+
+  return {
+    id: valueOf(row, 'id') as string | number | bigint,
+    responseId: valueOf<string>(row, 'responseId') as string,
+    userId: valueOf(row, 'userId') as string | number | bigint,
+    model: valueOf<string>(row, 'model') as string,
+    input: valueOf(row, 'input'),
+    output: valueOf<ResponseObject>(row, 'output') as ResponseObject,
+    previousResponseId: valueOf<string>(row, 'previousResponseId') ?? undefined,
+    metadata: valueOf<Record<string, unknown>>(row, 'metadata'),
+    expiresAt: valueOf<Date | string>(row, 'expiresAt') as Date | string,
+  };
+}
+
+function responseOutputToMessages(output: ResponseObject): OpenAIMessage[] {
+  return responsesInputToMessages(output.output);
+}
+
+export async function loadConversationChain(
+  ctx: Context,
+  responseId: string,
+  userId: string | number | bigint,
+  maxDepth = 100,
+): Promise<OpenAIMessage[] | null> {
+  const records: ResponseRecord[] = [];
+  const visited = new Set<string>();
+  let currentId: string | undefined = responseId;
+
+  while (currentId) {
+    if (records.length >= maxDepth || visited.has(currentId)) return null;
+    visited.add(currentId);
+    const record = await getResponseRecord(ctx, currentId, userId);
+    if (!record) return null;
+    records.unshift(record);
+    currentId = record.previousResponseId;
+  }
+
+  return records.flatMap((record) => [
+    ...responsesInputToMessages(record.input),
+    ...responseOutputToMessages(record.output),
+  ]);
+}
+
+export async function cleanupExpiredResponseRecords(ctx: Pick<Context, 'db'>): Promise<number> {
+  const repo = ctx.db.getRepository('aiApiResponseRecords');
+  const now = new Date();
+  let deleted = 0;
+  for (;;) {
+    const expired = (await repo.find({
+      filter: { expiresAt: { $lt: now } },
+      fields: ['id'],
+      limit: 1000,
+      sort: 'id',
+    })) as Model[];
+    const ids = expired.map((record) => record.get('id'));
+    if (ids.length === 0) return deleted;
+    const count = await repo.destroy({ filterByTk: ids, individualHooks: false });
+    if (typeof count === 'number') deleted += count;
+    else deleted += ids.length;
+    if (count === 0) return deleted;
+  }
+}
+
+export async function deleteResponseRecord(
+  ctx: Pick<Context, 'db'>,
+  responseId: string,
+  userId: string | number | bigint,
+): Promise<boolean> {
+  const record = await getResponseRecord(ctx, responseId, userId);
+  if (!record) return false;
+  await ctx.db.getRepository('aiApiResponseRecords').destroy({ filterByTk: record.id });
+  return true;
+}