@jsonstudio/rcc 0.89.333 → 0.89.524

package/dist/server/runtime/http-server/index.js

@@ -18,7 +18,7 @@ import { buildProviderProfiles } from '../../../providers/profile/provider-profi
 import { emitProviderError } from '../../../providers/core/utils/provider-error-reporter.js';
 import { isStageLoggingEnabled, logPipelineStage } from '../../utils/stage-logger.js';
 import { registerDefaultMiddleware } from './middleware.js';
-import { registerHttpRoutes } from './routes.js';
+import { registerHttpRoutes, registerOAuthPortalRoute } from './routes.js';
 import { mapProviderProtocol, normalizeProviderType, resolveProviderIdentity, asRecord } from './provider-utils.js';
 import { resolveRepoRoot, loadLlmswitchModule } from './llmswitch-loader.js';
 import { importCoreModule } from '../../../modules/llmswitch/core-loader.js';
@@ -98,6 +98,11 @@ export class RouteCodexHttpServer {
             console.warn('[RouteCodexHttpServer] Failed to initialize PipelineDebugLogger; falling back to noop logger.', error);
             this.pipelineLogger = createNoopPipelineLogger();
         }
+        // Register critical routes early (before provider initialization)
+        // This ensures OAuth Portal is available when providers check token validity
+        registerDefaultMiddleware(this.app);
+        registerOAuthPortalRoute(this.app);
+        console.log('[RouteCodexHttpServer] OAuth Portal route registered (early initialization)');
         console.log('[RouteCodexHttpServer] Initialized (pipeline=hub)');
     }
     resolveVirtualRouterInput(userConfig) {
@@ -334,7 +339,8 @@ export class RouteCodexHttpServer {
             // 初始化错误处理
             await this.errorHandling.initialize();
             await this.initializeRouteErrorHub();
-            registerDefaultMiddleware(this.app);
+            // registerDefaultMiddleware and registerOAuthPortalRoute already called in constructor
+            // Register remaining HTTP routes
             registerHttpRoutes({
                 app: this.app,
                 config: this.config,
@@ -624,14 +630,14 @@ export class RouteCodexHttpServer {
         if (!this.isPipelineReady()) {
             throw new Error('Hub pipeline runtime is not initialized');
         }
-        const metadata = this.buildRequestMetadata(input);
+        const initialMetadata = this.buildRequestMetadata(input);
         const providerRequestId = input.requestId;
-        const clientRequestId = typeof metadata.clientRequestId === 'string' && metadata.clientRequestId.trim()
-            ? metadata.clientRequestId.trim()
+        const clientRequestId = typeof initialMetadata.clientRequestId === 'string' && initialMetadata.clientRequestId.trim()
+            ? initialMetadata.clientRequestId.trim()
             : providerRequestId;
         this.logStage('request.received', providerRequestId, {
             endpoint: input.entryEndpoint,
-            stream: input.metadata?.stream === true
+            stream: initialMetadata.stream === true
         });
         try {
             const headerUa = (typeof input.headers?.['user-agent'] === 'string' && input.headers['user-agent']) ||
@@ -644,7 +650,7 @@ export class RouteCodexHttpServer {
                 headers: asRecord(input.headers),
                 body: input.body,
                 metadata: {
-                    ...metadata,
+                    ...initialMetadata,
                     userAgent: headerUa,
                     clientOriginator: headerOriginator
                 }
@@ -654,155 +660,161 @@ export class RouteCodexHttpServer {
             // snapshot failure should not block request path
         }
         const pipelineLabel = 'hub';
-        this.logStage(`${pipelineLabel}.start`, providerRequestId, {
-            endpoint: input.entryEndpoint,
-            stream: metadata.stream
-        });
-        const originalRequestSnapshot = this.cloneRequestPayload(input.body);
-        const pipelineResult = await this.runHubPipeline(input, metadata);
-        const pipelineMetadata = pipelineResult.metadata ?? {};
-        const mergedMetadata = { ...metadata, ...pipelineMetadata };
-        this.logStage(`${pipelineLabel}.completed`, providerRequestId, {
-            route: pipelineResult.routingDecision?.routeName,
-            target: pipelineResult.target?.providerKey
-        });
-        const providerPayload = pipelineResult.providerPayload;
-        const target = pipelineResult.target;
-        if (!providerPayload || !target?.providerKey) {
-            throw Object.assign(new Error('Virtual router did not produce a provider target'), {
-                code: 'ERR_NO_PROVIDER_TARGET',
-                requestId: input.requestId
-            });
-        }
-        const runtimeKey = target.runtimeKey || this.providerKeyToRuntimeKey.get(target.providerKey);
-        if (!runtimeKey) {
-            throw Object.assign(new Error(`Runtime for provider ${target.providerKey} not initialized`), {
-                code: 'ERR_RUNTIME_NOT_FOUND',
-                requestId: input.requestId
-            });
-        }
-        const handle = this.providerHandles.get(runtimeKey);
-        if (!handle) {
-            throw Object.assign(new Error(`Provider runtime ${runtimeKey} not found`), {
-                code: 'ERR_PROVIDER_NOT_FOUND',
-                requestId: input.requestId
+        let iterationMetadata = initialMetadata;
+        let followupTriggered = false;
+        while (true) {
+            this.logStage(`${pipelineLabel}.start`, providerRequestId, {
+                endpoint: input.entryEndpoint,
+                stream: iterationMetadata.stream
             });
-        }
-        const providerProtocol = target.outboundProfile ||
-            handle.providerProtocol;
-        const metadataModel = mergedMetadata?.target && typeof mergedMetadata.target === 'object'
-            ? mergedMetadata.target.clientModelId
-            : undefined;
-        const rawModel = this.extractProviderModel(providerPayload) ||
-            (typeof metadataModel === 'string' ? metadataModel : undefined);
-        const providerIdToken = target.providerKey || handle.providerId || runtimeKey;
-        if (!providerIdToken) {
-            throw Object.assign(new Error('Provider identifier missing for request'), {
-                code: 'ERR_PROVIDER_ID_MISSING',
-                requestId: providerRequestId
+            const originalRequestSnapshot = this.cloneRequestPayload(input.body);
+            const pipelineResult = await this.runHubPipeline(input, iterationMetadata);
+            const pipelineMetadata = pipelineResult.metadata ?? {};
+            const mergedMetadata = { ...iterationMetadata, ...pipelineMetadata };
+            this.logStage(`${pipelineLabel}.completed`, providerRequestId, {
+                route: pipelineResult.routingDecision?.routeName,
+                target: pipelineResult.target?.providerKey
             });
-        }
-        const enhancedRequestId = enhanceProviderRequestId(providerRequestId, {
-            entryEndpoint: input.entryEndpoint,
-            providerId: providerIdToken,
-            model: rawModel
-        });
-        if (providerProtocol === 'openai-responses') {
-            try {
-                await rebindResponsesConversationRequestId(pipelineResult.requestId, enhancedRequestId);
+            const providerPayload = pipelineResult.providerPayload;
+            const target = pipelineResult.target;
+            if (!providerPayload || !target?.providerKey) {
+                throw Object.assign(new Error('Virtual router did not produce a provider target'), {
+                    code: 'ERR_NO_PROVIDER_TARGET',
+                    requestId: input.requestId
+                });
             }
-            catch {
-                /* ignore rebind failures */
+            const runtimeKey = target.runtimeKey || this.providerKeyToRuntimeKey.get(target.providerKey);
+            if (!runtimeKey) {
+                throw Object.assign(new Error(`Runtime for provider ${target.providerKey} not initialized`), {
+                    code: 'ERR_RUNTIME_NOT_FOUND',
+                    requestId: input.requestId
+                });
             }
-        }
-        if (enhancedRequestId !== input.requestId) {
-            input.requestId = enhancedRequestId;
-        }
-        mergedMetadata.clientRequestId = clientRequestId;
-        const providerModel = rawModel;
-        const providerLabel = this.buildProviderLabel(target.providerKey, providerModel);
-        this.logStage('provider.prepare', input.requestId, {
-            providerKey: target.providerKey,
-            runtimeKey,
-            protocol: providerProtocol,
-            providerType: handle.providerType,
-            providerFamily: handle.providerFamily,
-            model: providerModel,
-            providerLabel
-        });
-        attachProviderRuntimeMetadata(providerPayload, {
-            requestId: input.requestId,
-            providerId: handle.providerId,
-            providerKey: target.providerKey,
-            providerType: handle.providerType,
-            providerFamily: handle.providerFamily,
-            providerProtocol,
-            pipelineId: target.providerKey,
-            routeName: pipelineResult.routingDecision?.routeName,
-            runtimeKey,
-            target,
-            metadata: mergedMetadata
-        });
-        this.logStage('provider.send.start', input.requestId, {
-            providerKey: target.providerKey,
-            runtimeKey,
-            protocol: providerProtocol,
-            providerType: handle.providerType,
-            providerFamily: handle.providerFamily,
-            model: providerModel,
-            providerLabel
-        });
-        try {
-            const providerResponse = await handle.instance.processIncoming(providerPayload);
-            const responseStatus = this.extractResponseStatus(providerResponse);
-            this.logStage('provider.send.completed', input.requestId, {
-                providerKey: target.providerKey,
-                status: responseStatus,
-                providerType: handle.providerType,
-                providerFamily: handle.providerFamily,
-                model: providerModel,
-                providerLabel
-            });
-            const normalized = this.normalizeProviderResponse(providerResponse);
-            return await this.convertProviderResponseIfNeeded({
+            const handle = this.providerHandles.get(runtimeKey);
+            if (!handle) {
+                throw Object.assign(new Error(`Provider runtime ${runtimeKey} not found`), {
+                    code: 'ERR_PROVIDER_NOT_FOUND',
+                    requestId: input.requestId
+                });
+            }
+            const providerProtocol = target.outboundProfile ||
+                handle.providerProtocol;
+            const metadataModel = mergedMetadata?.target && typeof mergedMetadata.target === 'object'
+                ? mergedMetadata.target.clientModelId
+                : undefined;
+            const rawModel = this.extractProviderModel(providerPayload) ||
+                (typeof metadataModel === 'string' ? metadataModel : undefined);
+            const providerIdToken = target.providerKey || handle.providerId || runtimeKey;
+            if (!providerIdToken) {
+                throw Object.assign(new Error('Provider identifier missing for request'), {
+                    code: 'ERR_PROVIDER_ID_MISSING',
+                    requestId: providerRequestId
+                });
+            }
+            const enhancedRequestId = enhanceProviderRequestId(providerRequestId, {
                 entryEndpoint: input.entryEndpoint,
-                providerType: handle.providerType,
-                requestId: input.requestId,
-                wantsStream: Boolean(input.metadata?.inboundStream ?? input.metadata?.stream),
-                originalRequest: originalRequestSnapshot,
-                processMode: pipelineResult.processMode,
-                response: normalized,
-                pipelineMetadata: mergedMetadata
+                providerId: providerIdToken,
+                model: rawModel
             });
-        }
-        catch (error) {
-            this.logStage('provider.send.error', input.requestId, {
+            if (providerProtocol === 'openai-responses') {
+                try {
+                    await rebindResponsesConversationRequestId(pipelineResult.requestId, enhancedRequestId);
+                }
+                catch {
+                    /* ignore rebind failures */
+                }
+            }
+            if (enhancedRequestId !== input.requestId) {
+                input.requestId = enhancedRequestId;
+            }
+            mergedMetadata.clientRequestId = clientRequestId;
+            const providerModel = rawModel;
+            const providerLabel = this.buildProviderLabel(target.providerKey, providerModel);
+            this.logStage('provider.prepare', input.requestId, {
                 providerKey: target.providerKey,
-                message: error instanceof Error ? error.message : String(error ?? 'Unknown error'),
+                runtimeKey,
+                protocol: providerProtocol,
                 providerType: handle.providerType,
                 providerFamily: handle.providerFamily,
                 model: providerModel,
                 providerLabel
             });
-            const runtimeMetadata = {
+            attachProviderRuntimeMetadata(providerPayload, {
                 requestId: input.requestId,
-                providerKey: target.providerKey,
                 providerId: handle.providerId,
+                providerKey: target.providerKey,
                 providerType: handle.providerType,
+                providerFamily: handle.providerFamily,
                 providerProtocol,
-                routeName: pipelineResult.routingDecision?.routeName,
                 pipelineId: target.providerKey,
+                routeName: pipelineResult.routingDecision?.routeName,
                 runtimeKey,
-                target
-            };
-            runtimeMetadata.providerFamily = handle.providerFamily;
-            emitProviderError({
-                error,
-                stage: 'provider.send',
-                runtime: runtimeMetadata,
-                dependencies: this.getModuleDependencies()
+                target,
+                metadata: mergedMetadata
             });
-            throw error;
+            this.logStage('provider.send.start', input.requestId, {
+                providerKey: target.providerKey,
+                runtimeKey,
+                protocol: providerProtocol,
+                providerType: handle.providerType,
+                providerFamily: handle.providerFamily,
+                model: providerModel,
+                providerLabel
+            });
+            try {
+                const providerResponse = await handle.instance.processIncoming(providerPayload);
+                const responseStatus = this.extractResponseStatus(providerResponse);
+                this.logStage('provider.send.completed', input.requestId, {
+                    providerKey: target.providerKey,
+                    status: responseStatus,
+                    providerType: handle.providerType,
+                    providerFamily: handle.providerFamily,
+                    model: providerModel,
+                    providerLabel
+                });
+                const wantsStreamBase = Boolean(input.metadata?.inboundStream ?? input.metadata?.stream);
+                const normalized = this.normalizeProviderResponse(providerResponse);
+                const converted = await this.convertProviderResponseIfNeeded({
+                    entryEndpoint: input.entryEndpoint,
+                    providerType: handle.providerType,
+                    requestId: input.requestId,
+                    wantsStream: wantsStreamBase,
+                    originalRequest: originalRequestSnapshot,
+                    processMode: pipelineResult.processMode,
+                    response: normalized,
+                    pipelineMetadata: mergedMetadata
+                });
+                return converted;
+            }
+            catch (error) {
+                this.logStage('provider.send.error', input.requestId, {
+                    providerKey: target.providerKey,
+                    message: error instanceof Error ? error.message : String(error ?? 'Unknown error'),
+                    providerType: handle.providerType,
+                    providerFamily: handle.providerFamily,
+                    model: providerModel,
+                    providerLabel
+                });
+                const runtimeMetadata = {
+                    requestId: input.requestId,
+                    providerKey: target.providerKey,
+                    providerId: handle.providerId,
+                    providerType: handle.providerType,
+                    providerProtocol,
+                    routeName: pipelineResult.routingDecision?.routeName,
+                    pipelineId: target.providerKey,
+                    runtimeKey,
+                    target
+                };
+                runtimeMetadata.providerFamily = handle.providerFamily;
+                emitProviderError({
+                    error,
+                    stage: 'provider.send',
+                    runtime: runtimeMetadata,
+                    dependencies: this.getModuleDependencies()
+                });
+                throw error;
+            }
         }
     }
     async runHubPipeline(input, metadata) {
@@ -940,12 +952,28 @@ export class RouteCodexHttpServer {
             const metadataBag = asRecord(options.pipelineMetadata);
             const aliasMap = extractAnthropicToolAliasMap(metadataBag);
             const originalModelId = this.extractClientModelId(metadataBag, options.originalRequest);
-            const adapterContext = {
-                requestId: options.requestId,
-                entryEndpoint: options.entryEndpoint || entry,
-                providerProtocol,
-                originalModelId
+            // 以 HubPipeline metadata 为基础构建 AdapterContext，确保诸如
+            // capturedChatRequest / webSearch / routeHint 等字段在响应侧可见，
+            // 便于 llmswitch-core 内部实现 servertool/web_search 的第三跳。
+            const baseContext = {
+                ...(metadataBag ?? {})
             };
+            // 将 HubPipeline metadata.routeName 映射为 AdapterContext.routeId，
+            // 便于 llmswitch-core 在第三跳中使用 routeHint 复用首次路由决策。
+            if (typeof metadataBag?.routeName === 'string') {
+                baseContext.routeId = metadataBag.routeName;
+            }
+            baseContext.requestId = options.requestId;
+            baseContext.entryEndpoint = options.entryEndpoint || entry;
+            baseContext.providerProtocol = providerProtocol;
+            baseContext.originalModelId = originalModelId;
+            const adapterContext = baseContext;
+            // 将 serverToolFollowup 等标记从 pipelineMetadata 透传到 AdapterContext，
+            // 便于 convertProviderResponse 正确识别内部二跳请求并跳过 servertool。
+            if (metadataBag && Object.prototype.hasOwnProperty.call(metadataBag, 'serverToolFollowup')) {
+                adapterContext.serverToolFollowup = metadataBag
+                    .serverToolFollowup;
+            }
             const compatProfile = metadataBag &&
                 typeof metadataBag === 'object' &&
                 metadataBag.target &&
@@ -959,18 +987,85 @@ export class RouteCodexHttpServer {
             if (aliasMap) {
                 adapterContext.anthropicToolNameMap = aliasMap;
             }
+            if (metadataBag && typeof metadataBag === 'object') {
+                const webSearchConfig = metadataBag.webSearch;
+                if (webSearchConfig && typeof webSearchConfig === 'object') {
+                    adapterContext.webSearch = webSearchConfig;
+                }
+                if (metadataBag.forceWebSearch === true) {
+                    adapterContext.forceWebSearch = true;
+                }
+                if (metadataBag.forceVision === true) {
+                    adapterContext.forceVision = true;
+                }
+            }
             const [convertProviderResponse, createSnapshotRecorder] = await Promise.all([
                 loadConvertProviderResponse(),
                 loadSnapshotRecorderFactory()
             ]);
-            const stageRecorder = createSnapshotRecorder(adapterContext, adapterContext.entryEndpoint);
+            const stageRecorder = createSnapshotRecorder(adapterContext, typeof adapterContext.entryEndpoint === 'string'
+                ? adapterContext.entryEndpoint
+                : options.entryEndpoint || entry);
+            const providerInvoker = async (invokeOptions) => {
+                const runtimeKey = this.providerKeyToRuntimeKey.get(invokeOptions.providerKey) || invokeOptions.providerKey;
+                const handle = this.providerHandles.get(runtimeKey);
+                if (!handle) {
+                    throw new Error(`Provider runtime ${runtimeKey} not found`);
+                }
+                const providerResponse = await handle.instance.processIncoming(invokeOptions.payload);
+                const normalized = this.normalizeProviderResponse(providerResponse);
+                const bodyPayload = normalized.body && typeof normalized.body === 'object'
+                    ? normalized.body
+                    : normalized;
+                return { providerResponse: bodyPayload };
+            };
+            const reenterPipeline = async (reenterOpts) => {
+                const nestedEntry = reenterOpts.entryEndpoint || options.entryEndpoint || entry;
+                const nestedExtra = asRecord(reenterOpts.metadata) ?? {};
+                const nestedEntryLower = nestedEntry.toLowerCase();
+                // 基于首次 HubPipeline metadata + 调用方注入的 metadata 构建新的请求 metadata。
+                // 不在 Host 层编码 servertool/web_search 等语义，由 llmswitch-core 负责。
+                const nestedMetadata = {
+                    ...(metadataBag ?? {}),
+                    ...nestedExtra,
+                    entryEndpoint: nestedEntry,
+                    direction: 'request',
+                    stage: 'inbound'
+                };
+                // 针对 reenterPipeline 的入口端点，纠正 providerProtocol，避免沿用外层协议。
+                if (nestedEntryLower.includes('/v1/chat/completions')) {
+                    nestedMetadata.providerProtocol = 'openai-chat';
+                }
+                else if (nestedEntryLower.includes('/v1/responses')) {
+                    nestedMetadata.providerProtocol = 'openai-responses';
+                }
+                else if (nestedEntryLower.includes('/v1/messages')) {
+                    nestedMetadata.providerProtocol = 'anthropic-messages';
+                }
+                const nestedInput = {
+                    entryEndpoint: nestedEntry,
+                    method: 'POST',
+                    requestId: reenterOpts.requestId,
+                    headers: {},
+                    query: {},
+                    body: reenterOpts.body,
+                    metadata: nestedMetadata
+                };
+                const nestedResult = await this.executePipeline(nestedInput);
+                const nestedBody = nestedResult.body && typeof nestedResult.body === 'object'
+                    ? nestedResult.body
+                    : undefined;
+                return { body: nestedBody };
+            };
             const converted = await convertProviderResponse({
                 providerProtocol,
                 providerResponse: body,
                 context: adapterContext,
                 entryEndpoint: options.entryEndpoint || entry,
                 wantsStream: options.wantsStream,
-                stageRecorder
+                providerInvoker,
+                stageRecorder,
+                reenterPipeline
             });
             if (converted.__sse_responses) {
                 return {
@@ -1020,6 +1115,279 @@ export class RouteCodexHttpServer {
             return undefined;
         }
     }
+    buildVisionFollowupPayload(options) {
+        const { originalPayload, visionResponse } = options;
+        if (!originalPayload || typeof originalPayload !== 'object') {
+            return null;
+        }
+        const clone = this.cloneRequestPayload(originalPayload) ?? { ...originalPayload };
+        if (!clone) {
+            return null;
+        }
+        const visionText = this.extractVisionDescription(visionResponse?.body);
+        if (!visionText) {
+            return null;
+        }
+        if (this.rewriteResponsesInput(clone, visionText)) {
+            return clone;
+        }
+        if (this.rewriteChatMessages(clone, visionText)) {
+            return clone;
+        }
+        return null;
+    }
+    rewriteResponsesInput(payload, visionText) {
+        const inputList = payload.input;
+        if (!Array.isArray(inputList)) {
+            return false;
+        }
+        for (let i = inputList.length - 1; i >= 0; i -= 1) {
+            const item = inputList[i];
+            if (!item || typeof item !== 'object') {
+                continue;
+            }
+            const role = typeof item.role === 'string'
+                ? item.role
+                : '';
+            if (role !== 'user') {
+                continue;
+            }
+            const contentBlocks = Array.isArray(item.content)
+                ? [...item.content]
+                : [];
+            const originalText = this.extractTextFromContentBlocks(contentBlocks, ['input_text', 'text']);
+            const textType = this.detectContentTextType(contentBlocks, 'input_text');
+            const composed = this.composeVisionUserText(visionText, originalText);
+            item.content = [
+                {
+                    type: textType,
+                    text: composed
+                }
+            ];
+            inputList[i] = item;
+            return true;
+        }
+        return false;
+    }
+    rewriteChatMessages(payload, visionText) {
+        const messages = payload.messages;
+        if (!Array.isArray(messages)) {
+            return false;
+        }
+        for (let i = messages.length - 1; i >= 0; i -= 1) {
+            const message = messages[i];
+            if (!message || typeof message !== 'object') {
+                continue;
+            }
+            const role = typeof message.role === 'string'
+                ? message.role
+                : '';
+            if (role !== 'user') {
+                continue;
+            }
+            const contentBlocks = Array.isArray(message.content)
+                ? [...message.content]
+                : [];
+            const originalText = this.extractTextFromContentBlocks(contentBlocks, ['text']);
+            const textType = this.detectContentTextType(contentBlocks, 'text');
+            const composed = this.composeVisionUserText(visionText, originalText);
+            message.content = [
+                {
+                    type: textType,
+                    text: composed
+                }
+            ];
+            messages[i] = message;
+            return true;
+        }
+        return false;
+    }
+    extractTextFromContentBlocks(content, allowedTypes) {
+        if (typeof content === 'string') {
+            return content;
+        }
+        if (!Array.isArray(content)) {
+            return '';
+        }
+        const collected = [];
+        for (const block of content) {
+            if (!block || typeof block !== 'object') {
+                continue;
+            }
+            const typeValue = typeof block.type === 'string'
+                ? block.type
+                : '';
+            if (allowedTypes.length && !allowedTypes.includes(typeValue)) {
+                continue;
+            }
+            const textValue = block.text;
+            if (typeof textValue === 'string' && textValue.trim()) {
+                collected.push(textValue.trim());
+            }
+        }
+        return collected.join('\n');
+    }
+    detectContentTextType(content, fallback) {
+        if (Array.isArray(content)) {
+            for (const block of content) {
+                if (!block || typeof block !== 'object') {
+                    continue;
+                }
+                const typeValue = block.type;
+                if (typeof typeValue === 'string' && (typeValue === 'text' || typeValue === 'input_text')) {
+                    return typeValue;
+                }
+            }
+        }
+        return fallback;
+    }
+    composeVisionUserText(visionText, originalText) {
+        const sections = [];
+        const cleanedVision = (visionText || '').trim();
+        if (cleanedVision) {
+            sections.push(`【图片分析】\n${cleanedVision}`);
+        }
+        const cleanedOriginal = (originalText || '').trim();
+        if (cleanedOriginal) {
+            sections.push(`【用户原始请求】\n${cleanedOriginal}`);
+        }
+        return sections.join('\n\n');
+    }
+    extractVisionDescription(body) {
+        if (!body) {
+            return null;
+        }
+        if (typeof body === 'string') {
+            const trimmed = body.trim();
+            return trimmed.length ? trimmed : null;
+        }
+        if (typeof body !== 'object') {
+            return null;
+        }
+        const record = body;
+        const direct = this.extractTextCandidate(record);
+        if (direct) {
+            return direct;
+        }
+        if (record.response && typeof record.response === 'object') {
+            const responseNode = record.response;
+            const nested = this.extractTextCandidate(responseNode);
+            if (nested) {
+                return nested;
+            }
+            const output = responseNode.output;
+            if (Array.isArray(output)) {
+                for (const entry of output) {
+                    if (entry && typeof entry === 'object') {
+                        const nestedText = this.extractTextCandidate(entry);
+                        if (nestedText) {
+                            return nestedText;
+                        }
+                    }
+                }
+            }
+        }
+        if (Array.isArray(record.output)) {
+            for (const entry of record.output) {
+                if (entry && typeof entry === 'object') {
+                    const nested = this.extractTextCandidate(entry);
+                    if (nested) {
+                        return nested;
+                    }
+                }
+            }
+        }
+        const choices = record.choices;
+        if (Array.isArray(choices)) {
+            for (const choice of choices) {
+                if (!choice || typeof choice !== 'object') {
+                    continue;
+                }
+                const message = choice.message;
+                if (message && typeof message === 'object') {
+                    const msg = message;
+                    const content = msg.content;
+                    if (typeof content === 'string' && content.trim()) {
+                        return content.trim();
+                    }
+                    if (Array.isArray(content)) {
+                        for (const part of content) {
+                            if (part && typeof part === 'object' && typeof part.text === 'string') {
+                                const textValue = part.text.trim();
+                                if (textValue) {
+                                    return textValue;
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        return null;
+    }
+    extractTextCandidate(record) {
+        const candidates = [
+            { key: 'output_text', allowJson: true },
+            { key: 'text' },
+            { key: 'content' }
+        ];
+        for (const candidate of candidates) {
+            if (!(candidate.key in record)) {
+                continue;
+            }
+            const text = this.normalizeTextCandidateValue(record[candidate.key], candidate.allowJson === true);
+            if (text) {
+                return text;
+            }
+        }
+        return null;
+    }
+    normalizeTextCandidateValue(value, allowJsonStringify = false) {
+        if (!value) {
+            return null;
+        }
+        if (typeof value === 'string') {
+            const trimmed = value.trim();
+            return trimmed.length ? trimmed : null;
+        }
+        if (Array.isArray(value)) {
+            const collected = [];
+            for (const entry of value) {
+                const nested = this.normalizeTextCandidateValue(entry, allowJsonStringify);
+                if (nested) {
+                    collected.push(nested);
+                }
+            }
+            return collected.length ? collected.join('\n') : null;
+        }
+        if (typeof value === 'object') {
+            const bag = value;
+            const textField = bag.text;
+            if (typeof textField === 'string' && textField.trim()) {
+                return textField.trim();
+            }
+            const summaryField = bag.summary;
+            if (typeof summaryField === 'string' && summaryField.trim()) {
+                return summaryField.trim();
+            }
+            if ('content' in bag) {
+                const nested = this.normalizeTextCandidateValue(bag.content, allowJsonStringify);
+                if (nested) {
+                    return nested;
+                }
+            }
+            if (allowJsonStringify) {
+                try {
+                    const serialized = JSON.stringify(value, null, 2);
+                    return serialized.trim() || null;
+                }
+                catch {
+                    return null;
+                }
+            }
+        }
+        return null;
+    }
     async initializeRouteErrorHub() {
         try {
             this.routeErrorHub = initializeRouteErrorHub({ errorHandlingCenter: this.errorHandling });