@jsonstudio/rcc 0.89.168 → 0.89.524

package/dist/server/runtime/http-server/request-executor.js

@@ -36,6 +36,7 @@ export class HubRequestExecutor {
     }
     async execute(input) {
         this.deps.stats.recordRequestStart(input.requestId);
+        const requestStartedAt = Date.now();
         let statsRecorded = false;
         const finalizeStats = (options) => {
             if (statsRecorded) {
@@ -46,12 +47,13 @@ export class HubRequestExecutor {
         };
         try {
             const hubPipeline = this.ensureHubPipeline();
-            const metadata = this.buildRequestMetadata(input);
+            const initialMetadata = this.buildRequestMetadata(input);
+            const inboundClientHeaders = this.cloneClientHeaders(initialMetadata?.clientHeaders);
             const providerRequestId = input.requestId;
-            const clientRequestId = this.resolveClientRequestId(metadata, providerRequestId);
+            const clientRequestId = this.resolveClientRequestId(initialMetadata, providerRequestId);
             this.logStage('request.received', providerRequestId, {
                 endpoint: input.entryEndpoint,
-                stream: metadata.stream === true
+                stream: initialMetadata.stream === true
             });
             try {
                 const headerUa = (typeof input.headers?.['user-agent'] === 'string' && input.headers['user-agent']) ||
@@ -64,7 +66,7 @@ export class HubRequestExecutor {
                     headers: asRecord(input.headers),
                     body: input.body,
                     metadata: {
-                        ...metadata,
+                        ...initialMetadata,
                         userAgent: headerUa,
                         clientOriginator: headerOriginator
                     }
@@ -74,158 +76,187 @@ export class HubRequestExecutor {
                 /* 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(hubPipeline, 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
+            let iterationMetadata = initialMetadata;
+            let aggregatedUsage;
+            let attempt = 0;
+            let followupTriggered = false;
+            while (true) {
+                this.logStage(`${pipelineLabel}.start`, providerRequestId, {
+                    endpoint: input.entryEndpoint,
+                    stream: iterationMetadata.stream,
+                    attempt
                 });
-            }
-            const runtimeKey = target.runtimeKey || this.deps.runtimeManager.resolveRuntimeKey(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.deps.runtimeManager.getHandleByRuntimeKey(runtimeKey);
-            if (!handle) {
-                throw Object.assign(new Error(`Provider runtime ${runtimeKey} not found`), {
-                    code: 'ERR_PROVIDER_NOT_FOUND',
-                    requestId: input.requestId
+                // 获取原始请求快照，用于后续响应转换（不包含任何 server-side 工具语义）。
+                const originalRequestSnapshot = this.cloneRequestPayload(input.body);
+                const pipelineResult = await this.runHubPipeline(hubPipeline, input, iterationMetadata);
+                const pipelineMetadata = pipelineResult.metadata ?? {};
+                const mergedMetadata = { ...iterationMetadata, ...pipelineMetadata };
+                const mergedClientHeaders = this.cloneClientHeaders(mergedMetadata?.clientHeaders) || inboundClientHeaders;
+                if (mergedClientHeaders) {
+                    mergedMetadata.clientHeaders = mergedClientHeaders;
+                }
+                mergedMetadata.clientRequestId = clientRequestId;
+                this.logStage(`${pipelineLabel}.completed`, providerRequestId, {
+                    route: pipelineResult.routingDecision?.routeName,
+                    target: pipelineResult.target?.providerKey,
+                    attempt
                 });
-            }
-            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 providerAlias = typeof target.providerKey === 'string' && target.providerKey.includes('.')
-                ? target.providerKey.split('.').slice(0, 2).join('.')
-                : target.providerKey;
-            const providerIdToken = providerAlias || handle.providerId || runtimeKey;
-            if (!providerIdToken) {
-                throw Object.assign(new Error('Provider identifier missing for request'), {
-                    code: 'ERR_PROVIDER_ID_MISSING',
-                    requestId: providerRequestId
+                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.deps.runtimeManager.resolveRuntimeKey(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.deps.runtimeManager.getHandleByRuntimeKey(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 providerAlias = typeof target.providerKey === 'string' && target.providerKey.includes('.')
+                    ? target.providerKey.split('.').slice(0, 2).join('.')
+                    : target.providerKey;
+                const providerIdToken = providerAlias || 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,
+                    providerId: providerIdToken,
+                    model: rawModel
                 });
-            }
-            const enhancedRequestId = enhanceProviderRequestId(providerRequestId, {
-                entryEndpoint: input.entryEndpoint,
-                providerId: providerIdToken,
-                model: rawModel
-            });
-            if (enhancedRequestId !== input.requestId) {
-                input.requestId = enhancedRequestId;
-            }
-            mergedMetadata.clientRequestId = clientRequestId;
-            const providerModel = rawModel;
-            const providerLabel = this.buildProviderLabel(target.providerKey, providerModel);
-            this.deps.stats.bindProvider(input.requestId, {
-                providerKey: target.providerKey,
-                providerType: handle.providerType,
-                model: 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,
-                compatibilityProfile: target.compatibilityProfile
-            });
-            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, {
+                if (enhancedRequestId !== input.requestId) {
+                    input.requestId = enhancedRequestId;
+                }
+                mergedMetadata.clientRequestId = clientRequestId;
+                const providerModel = rawModel;
+                const providerLabel = this.buildProviderLabel(target.providerKey, providerModel);
+                if (inboundClientHeaders) {
+                    this.ensureClientHeadersOnPayload(providerPayload, inboundClientHeaders);
+                }
+                this.deps.stats.bindProvider(input.requestId, {
                     providerKey: target.providerKey,
-                    status: responseStatus,
                     providerType: handle.providerType,
-                    providerFamily: handle.providerFamily,
-                    model: providerModel,
-                    providerLabel
+                    model: providerModel
                 });
-                const normalized = this.normalizeProviderResponse(providerResponse);
-                const converted = await this.convertProviderResponseIfNeeded({
-                    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
-                });
-                const usage = this.extractUsageFromResult(converted, mergedMetadata);
-                finalizeStats({ usage, error: false });
-                return converted;
-            }
-            catch (error) {
-                this.logStage('provider.send.error', input.requestId, {
+                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
+                    providerLabel,
+                    attempt
                 });
-                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.deps.getModuleDependencies()
+                    target,
+                    metadata: mergedMetadata,
+                    compatibilityProfile: target.compatibilityProfile
                 });
-                throw error;
+                this.logStage('provider.send.start', input.requestId, {
+                    providerKey: target.providerKey,
+                    runtimeKey,
+                    protocol: providerProtocol,
+                    providerType: handle.providerType,
+                    providerFamily: handle.providerFamily,
+                    model: providerModel,
+                    providerLabel,
+                    attempt
+                });
+                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,
+                        attempt
+                    });
+                    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
+                    });
+                    const usage = this.extractUsageFromResult(converted, mergedMetadata);
+                    aggregatedUsage = this.mergeUsageMetrics(aggregatedUsage, usage);
+                    finalizeStats({ usage: aggregatedUsage, error: false });
+                    this.logUsageSummary(input.requestId, {
+                        providerKey: target.providerKey,
+                        model: providerModel,
+                        usage: aggregatedUsage,
+                        latencyMs: Date.now() - requestStartedAt
+                    });
+                    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,
+                        attempt
+                    });
+                    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.deps.getModuleDependencies()
+                    });
+                    throw error;
+                }
             }
         }
         catch (error) {
@@ -265,6 +296,31 @@ export class HubRequestExecutor {
             metadata: result.metadata ?? {}
         };
     }
+    cloneClientHeaders(source) {
+        if (!source || typeof source !== 'object') {
+            return undefined;
+        }
+        const normalized = {};
+        for (const [key, value] of Object.entries(source)) {
+            if (typeof value === 'string' && value.trim()) {
+                normalized[key] = value;
+            }
+        }
+        return Object.keys(normalized).length ? normalized : undefined;
+    }
+    ensureClientHeadersOnPayload(payload, headers) {
+        if (!payload || typeof payload !== 'object') {
+            return;
+        }
+        const carrier = payload;
+        const existing = carrier.metadata && typeof carrier.metadata === 'object'
+            ? carrier.metadata
+            : {};
+        carrier.metadata = {
+            ...existing,
+            clientHeaders: existing.clientHeaders ?? headers
+        };
+    }
     resolveClientRequestId(metadata, fallback) {
         const clientRequestId = typeof metadata.clientRequestId === 'string' && metadata.clientRequestId.trim()
             ? metadata.clientRequestId.trim()
@@ -273,6 +329,15 @@ export class HubRequestExecutor {
     }
     buildRequestMetadata(input) {
         const userMeta = asRecord(input.metadata);
+        const headers = asRecord(input.headers);
+        const inboundUserAgent = this.extractHeaderValue(headers, 'user-agent');
+        const inboundOriginator = this.extractHeaderValue(headers, 'originator');
+        const resolvedUserAgent = typeof userMeta.userAgent === 'string' && userMeta.userAgent.trim()
+            ? userMeta.userAgent.trim()
+            : inboundUserAgent;
+        const resolvedOriginator = typeof userMeta.clientOriginator === 'string' && userMeta.clientOriginator.trim()
+            ? userMeta.clientOriginator.trim()
+            : inboundOriginator;
         const routeHint = this.extractRouteHint(input) ?? userMeta.routeHint;
         const processMode = userMeta.processMode || 'chat';
         return {
@@ -282,9 +347,30 @@ export class HubRequestExecutor {
             direction: 'request',
             stage: 'inbound',
             routeHint,
-            stream: userMeta.stream === true
+            stream: userMeta.stream === true,
+            ...(resolvedUserAgent ? { userAgent: resolvedUserAgent } : {}),
+            ...(resolvedOriginator ? { clientOriginator: resolvedOriginator } : {})
         };
     }
+    extractHeaderValue(headers, name) {
+        if (!headers) {
+            return undefined;
+        }
+        const target = name.toLowerCase();
+        for (const [key, value] of Object.entries(headers)) {
+            if (key.toLowerCase() !== target) {
+                continue;
+            }
+            if (typeof value === 'string') {
+                return value.trim() || undefined;
+            }
+            if (Array.isArray(value) && value.length) {
+                return String(value[0]).trim() || undefined;
+            }
+            return undefined;
+        }
+        return undefined;
+    }
     extractRouteHint(input) {
         const header = input.headers?.['x-route-hint'];
         if (typeof header === 'string' && header.trim()) {
@@ -342,12 +428,17 @@ export class HubRequestExecutor {
             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
+            const baseContext = {
+                ...(metadataBag ?? {})
             };
+            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;
             if (aliasMap) {
                 adapterContext.anthropicToolNameMap = aliasMap;
             }
@@ -355,14 +446,85 @@ export class HubRequestExecutor {
                 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) => {
+                // 将 server-side 工具的 routeHint 注入到内部 payload 的 metadata，
+                // 以便后续在标准 HubPipeline 中保持路由上下文一致（例如强制 web_search）。
+                if (invokeOptions.routeHint) {
+                    const carrier = invokeOptions.payload;
+                    const existingMeta = carrier.metadata && typeof carrier.metadata === 'object'
+                        ? carrier.metadata
+                        : {};
+                    carrier.metadata = {
+                        ...existingMeta,
+                        routeHint: existingMeta.routeHint ?? invokeOptions.routeHint
+                    };
+                }
+                // Delegate to existing runtimeManager / Provider V2 stack.
+                const runtimeKey = this.deps.runtimeManager.resolveRuntimeKey(invokeOptions.providerKey);
+                if (!runtimeKey) {
+                    throw new Error(`Runtime for provider ${invokeOptions.providerKey} not initialized`);
+                }
+                const handle = this.deps.runtimeManager.getHandleByRuntimeKey(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.execute(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 {
@@ -376,6 +538,20 @@ export class HubRequestExecutor {
             };
         }
         catch (error) {
+            const err = error;
+            const message = err instanceof Error ? err.message : String(err ?? 'Unknown error');
+            const providerProtocol = mapProviderProtocol(options.providerType);
+            // 对于 Gemini 等基于 SSE 的 provider，如果 llmswitch-core 报告
+            // “Failed to convert SSE payload ...” 之类错误，说明上游流式响应已异常
+            // 终止（如 Cloud Code 终止/上下文超限），继续回退到原始 SSE 只会让
+            // 客户端挂起。因此在此类场景下直接抛出错误，让 HTTP 层返回明确的
+            // 5xx/4xx，而不是静默退回原始 payload。
+            const isSseConvertFailure = typeof message === 'string' &&
+                message.toLowerCase().includes('failed to convert sse payload');
+            if (providerProtocol === 'gemini-chat' && isSseConvertFailure) {
+                console.error('[RequestExecutor] Fatal SSE decode error for Gemini provider, bubbling as HTTP error', error);
+                throw error;
+            }
             console.error('[RequestExecutor] Failed to convert provider response via llmswitch-core', error);
             return options.response;
         }
@@ -439,6 +615,18 @@ export class HubRequestExecutor {
     logStage(stage, requestId, details) {
         this.deps.logStage(stage, requestId, details);
     }
+    logUsageSummary(requestId, info) {
+        if (process.env.ROUTECODEX_USAGE_LOG === '0') {
+            return;
+        }
+        const providerLabel = this.buildProviderLabel(info.providerKey, info.model) ?? '-';
+        const prompt = info.usage?.prompt_tokens;
+        const completion = info.usage?.completion_tokens;
+        const total = info.usage?.total_tokens ?? (prompt !== undefined && completion !== undefined ? prompt + completion : undefined);
+        const usageText = `prompt=${prompt ?? 'n/a'} completion=${completion ?? 'n/a'} total=${total ?? 'n/a'}`;
+        const latency = info.latencyMs.toFixed(1);
+        console.log(`[usage] request ${requestId} provider=${providerLabel} latency=${latency}ms (${usageText})`);
+    }
     extractUsageFromResult(result, metadata) {
         const candidates = [];
         if (metadata && typeof metadata === 'object') {
@@ -472,9 +660,22 @@ export class HubRequestExecutor {
             return undefined;
         }
         const record = value;
-        const prompt = typeof record.prompt_tokens === 'number' ? record.prompt_tokens : undefined;
-        const completion = typeof record.completion_tokens === 'number' ? record.completion_tokens : undefined;
-        const total = typeof record.total_tokens === 'number' ? record.total_tokens : undefined;
+        const prompt = typeof record.prompt_tokens === 'number'
+            ? record.prompt_tokens
+            : typeof record.input_tokens === 'number'
+                ? record.input_tokens
+                : undefined;
+        const completion = typeof record.completion_tokens === 'number'
+            ? record.completion_tokens
+            : typeof record.output_tokens === 'number'
+                ? record.output_tokens
+                : undefined;
+        let total = typeof record.total_tokens === 'number'
+            ? record.total_tokens
+            : undefined;
+        if (total === undefined && prompt !== undefined && completion !== undefined) {
+            total = prompt + completion;
+        }
         if (prompt === undefined && completion === undefined && total === undefined) {
             return undefined;
         }
@@ -484,6 +685,294 @@ export class HubRequestExecutor {
             total_tokens: total
         };
     }
+    mergeUsageMetrics(base, delta) {
+        if (!delta) {
+            return base;
+        }
+        if (!base) {
+            return { ...delta };
+        }
+        const merged = {
+            prompt_tokens: (base.prompt_tokens ?? 0) + (delta.prompt_tokens ?? 0),
+            completion_tokens: (base.completion_tokens ?? 0) + (delta.completion_tokens ?? 0)
+        };
+        const total = (base.total_tokens ?? 0) + (delta.total_tokens ?? 0);
+        merged.total_tokens = total || undefined;
+        return merged;
+    }
+    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;
+    }
 }
 export function createRequestExecutor(deps) {
     return new HubRequestExecutor(deps);