nolo-cli 0.1.29 → 0.1.31

package/server/handlers/agentRun/loop.ts

@@ -33,8 +33,11 @@ import {
     toResponsesTools,
 } from "../../../integrations/openai/responsesHelpers";
 import { normalizeChatCompletionsBodyForProvider } from "../../../integrations/openai/providerBodyCompatibility";
-import { fetchUpstreamWithGentleRetry } from "../chatUpstreamRetry";
-import { executeToolOnServer } from "./toolExecutor";
+import { fetchUpstreamWithGentleRetry } from "../chatUpstreamRetry";
+import type { ProviderCallStore } from "../../../ai/token/providerCallWriter";
+import type { ProviderApiKeySource } from "../../../ai/token/providerCredential";
+import { resolveRuntimeProviderCredential } from "../../../ai/token/providerCredentialRuntime";
+import { executeToolOnServer } from "./toolExecutor";
 import type {
     AgentRunRuntimeContext,
     ChatMessage,
@@ -161,21 +164,41 @@ async function hydrateApiKeyReferenceIfNeeded(
     return {
         ...agentConfig,
         apiKey,
+        apiKeySource: "agent_reference",
     };
 }
 
+function resolveApiKeySource(agentConfig: any): ProviderApiKeySource {
+    if (agentConfig?.apiKeySource === "agent_reference") return "agent_reference";
+    if (agentConfig?.apiKey?.trim()) return "agent_secret";
+    return "platform_env";
+}
+
 async function fetchLoopUpstream(
-    endpoint: string,
-    agentConfig: any,
-    body: Record<string, any>,
-): Promise<{
-    response: Response;
-    provider?: string;
-    model?: string;
-    inputPrice?: number;
-    outputPrice?: number;
-}> {
-    const apiKey = getApiKey(agentConfig);
+    endpoint: string,
+    agentConfig: any,
+    body: Record<string, any>,
+    providerCallContext?: {
+        userId?: string | null;
+        dialogId?: string | null;
+        agentId?: string | null;
+    },
+    providerCallStore?: ProviderCallStore,
+): Promise<{
+    response: Response;
+    provider?: string;
+    model?: string;
+    inputPrice?: number;
+    outputPrice?: number;
+    providerCallIds?: string[];
+}> {
+    const apiKey = getApiKey(agentConfig);
+    const credential = await resolveRuntimeProviderCredential({
+        provider: String(agentConfig?.provider || "unknown"),
+        apiKey,
+        apiKeySource: resolveApiKeySource(agentConfig),
+        registryStore: providerCallStore,
+    });
     const llmRequestTimeoutMs = resolveLlmRequestTimeoutMs(agentConfig, endpoint);
     const init: RequestInit = {
         method: "POST",
@@ -243,10 +266,16 @@ async function fetchLoopUpstream(
     const googleFallbackRequest =
         shouldUseGoogleOpenRouterFallback && openRouterApiKey
             ? {
-                url: OPENROUTER_CHAT_COMPLETIONS_URL,
-                provider: "openrouter",
-                model: toOpenRouterGoogleModelName(agentConfig.model),
-                init: {
+                url: OPENROUTER_CHAT_COMPLETIONS_URL,
+                provider: "openrouter",
+                model: toOpenRouterGoogleModelName(agentConfig.model),
+                credential: await resolveRuntimeProviderCredential({
+                    provider: "openrouter",
+                    apiKey: openRouterApiKey,
+                    apiKeySource: "platform_env",
+                    registryStore: providerCallStore,
+                }),
+                init: {
                     method: "POST",
                     headers: buildUpstreamHeaders(
                         OPENROUTER_CHAT_COMPLETIONS_URL,
@@ -270,6 +299,12 @@ async function fetchLoopUpstream(
                     url: fireworksKimiFallbackUrl,
                     provider: "fireworks",
                     model: FIREWORKS_KIMI_CURRENT_MODEL,
+                    credential: await resolveRuntimeProviderCredential({
+                        provider: "fireworks",
+                        apiKey: fireworksKimiFallbackApiKey,
+                        apiKeySource: "platform_env",
+                        registryStore: providerCallStore,
+                    }),
                     init: {
                         method: "POST",
                         headers: buildUpstreamHeaders(
@@ -292,6 +327,12 @@ async function fetchLoopUpstream(
                     url: deepInfraKimiFallbackUrl,
                     provider: "deepinfra",
                     model: DEEPINFRA_KIMI_FALLBACK_MODEL,
+                    credential: await resolveRuntimeProviderCredential({
+                        provider: "deepinfra",
+                        apiKey: deepInfraKimiFallbackApiKey,
+                        apiKeySource: "platform_env",
+                        registryStore: providerCallStore,
+                    }),
                     init: {
                         method: "POST",
                         headers: buildUpstreamHeaders(
@@ -314,6 +355,12 @@ async function fetchLoopUpstream(
                     url: OPENROUTER_CHAT_COMPLETIONS_URL,
                     provider: "openrouter",
                     model: OPENROUTER_KIMI_FALLBACK_MODEL,
+                    credential: await resolveRuntimeProviderCredential({
+                        provider: "openrouter",
+                        apiKey: openRouterKimiFallbackApiKey,
+                        apiKeySource: "platform_env",
+                        registryStore: providerCallStore,
+                    }),
                     init: {
                         method: "POST",
                         headers: buildUpstreamHeaders(
@@ -337,9 +384,15 @@ async function fetchLoopUpstream(
         shouldUseConfiguredFallback && configuredFallbackApiKey
             ? {
                 url: OPENROUTER_CHAT_COMPLETIONS_URL,
-                provider: "openrouter",
-                model: agentConfig.fallbackModel,
-                init: {
+                provider: "openrouter",
+                model: agentConfig.fallbackModel,
+                credential: await resolveRuntimeProviderCredential({
+                    provider: "openrouter",
+                    apiKey: configuredFallbackApiKey,
+                    apiKeySource: "platform_env",
+                    registryStore: providerCallStore,
+                }),
+                init: {
                     method: "POST",
                     headers: buildUpstreamHeaders(
                         OPENROUTER_CHAT_COMPLETIONS_URL,
@@ -408,9 +461,10 @@ async function fetchLoopUpstream(
             ? {
                 url: endpoint,
                 init,
-                provider: agentConfig.provider,
-                model: agentConfig.model,
-                log: console,
+                provider: agentConfig.provider,
+                model: agentConfig.model,
+                credential,
+                log: console,
                 fallbackRequest: googleFallbackRequest,
                 fallbackOnStatuses:
                     String(agentConfig?.provider || "").toLowerCase() === "google"
@@ -423,6 +477,7 @@ async function fetchLoopUpstream(
                     init,
                     provider: agentConfig.provider,
                     model: agentConfig.model,
+                    credential,
                     log: console,
                     fallbackRequests: kimiPlatformFallbackRequests,
                     fallbackOnStatuses: KIMI_PLATFORM_FALLBACK_STATUSES,
@@ -430,23 +485,36 @@ async function fetchLoopUpstream(
             : configuredFallbackRequest
                 ? {
                     url: endpoint,
-                    init,
-                    provider: agentConfig.provider,
-                    model: agentConfig.model,
-                    log: console,
-                    fallbackRequest: configuredFallbackRequest,
+                    init,
+                    provider: agentConfig.provider,
+                    model: agentConfig.model,
+                    credential,
+                    log: console,
+                    fallbackRequest: configuredFallbackRequest,
                     fallbackOnStatuses: FIREWORKS_OPENROUTER_FALLBACK_STATUSES,
                 }
             : {
                 url: endpoint,
-                init,
-                provider: agentConfig.provider,
-                model: agentConfig.model,
-                log: console,
-            };
-        const upstreamResponse = await fetchUpstreamWithGentleRetry({
-            ...requestArgs,
-        });
+                init,
+                provider: agentConfig.provider,
+                model: agentConfig.model,
+                credential,
+                log: console,
+            };
+        const upstreamResponse = await fetchUpstreamWithGentleRetry({
+            ...requestArgs,
+            ...(providerCallStore && providerCallContext?.userId
+                ? {
+                    providerCallStore,
+                    providerCallContext: {
+                        userId: providerCallContext.userId,
+                        dialogId: providerCallContext.dialogId ?? undefined,
+                        agentId: providerCallContext.agentId ?? undefined,
+                        endpoint: "agentRun",
+                    },
+                }
+                : {}),
+        });
         const actualProvider = upstreamResponse.provider;
         const actualModel = upstreamResponse.model;
         const actualModelConfig =
@@ -456,10 +524,11 @@ async function fetchLoopUpstream(
         return {
             response: upstreamResponse.response,
             provider: actualProvider,
-            model: actualModel,
-            inputPrice: actualModelConfig?.price.input ?? agentConfig.inputPrice,
-            outputPrice: actualModelConfig?.price.output ?? agentConfig.outputPrice,
-        };
+            model: actualModel,
+            inputPrice: actualModelConfig?.price.input ?? agentConfig.inputPrice,
+            outputPrice: actualModelConfig?.price.output ?? agentConfig.outputPrice,
+            providerCallIds: upstreamResponse.providerCallIds,
+        };
     } catch (error: any) {
         if (error?.name === "TimeoutError" || error?.name === "AbortError") {
             throw new Error(`LLM API timeout after ${llmRequestTimeoutMs}ms: ${endpoint}`);
@@ -1223,22 +1292,22 @@ async function runWereadGatewayPreflightIfNeeded(args: {
     args.send?.({ type: "tool_start", calls: ["wereadGateway"] });
 
     const startedAt = Date.now();
-    const toolResult = await executeToolOnServer(toolCall, args.serverBase, args.authToken, {
-        policy: args.runtimePolicy,
-        runtimeState: args.runtimeState,
-        userId: args.userId,
-        agentKey:
-            typeof args.agentConfig?.dbKey === "string" && args.agentConfig.dbKey.trim()
-                ? args.agentConfig.dbKey.trim()
-                : typeof args.agentConfig?.id === "string" && args.agentConfig.id.trim()
-                  ? args.agentConfig.id.trim()
-                  : null,
-        dialogId: args.dialogId,
-        currentSpaceId: args.currentSpaceId,
-        userInput: args.userInput,
-        runtimeContext: args.runtimeContext,
-        imageUrls: collectLatestImageUrls(args.messages),
-    });
+    const toolResult = await executeToolOnServer(
+        toolCall,
+        args.serverBase,
+        args.authToken,
+        buildLoopToolExecutionOptions({
+            agentConfig: args.agentConfig,
+            messages: args.messages,
+            runtimePolicy: args.runtimePolicy,
+            runtimeState: args.runtimeState,
+            userId: args.userId,
+            dialogId: args.dialogId,
+            currentSpaceId: args.currentSpaceId,
+            userInput: args.userInput,
+            runtimeContext: args.runtimeContext,
+        }),
+    );
     const completedAt = Date.now();
     args.messages.push({
         role: "tool",
@@ -1323,8 +1392,116 @@ export function applyLoopStreamMode(body: Record<string, any>, stream: boolean)
     }
     return body;
 }
-
-function buildAssistantMessageFromResponse(data: any): ChatMessage | null {
+
+function addNumericUsageField(
+    target: Record<string, any>,
+    field: string,
+    next: Record<string, any>,
+) {
+    if (typeof next[field] !== "number" || !Number.isFinite(next[field])) return;
+    target[field] = (typeof target[field] === "number" && Number.isFinite(target[field]) ? target[field] : 0) + next[field];
+}
+
+function uniqueStringList(...values: unknown[]): string[] {
+    return Array.from(
+        new Set(
+            values
+                .flatMap((value) => Array.isArray(value) ? value : [value])
+                .filter((item): item is string => typeof item === "string")
+                .map((item) => item.trim())
+                .filter(Boolean)
+        )
+    );
+}
+
+function addStringListUsageField(
+    target: Record<string, any>,
+    field: string,
+    next: Record<string, any>,
+) {
+    const merged = uniqueStringList(target[field], next[field]);
+    if (merged.length > 0) target[field] = merged;
+}
+
+function buildProviderAuditUsageMetadata(
+    response?: Response | null,
+    payload?: any,
+): Record<string, any> | undefined {
+    const providerRequestIds = uniqueStringList(
+        response?.headers.get("x-request-id"),
+        response?.headers.get("x-openai-request-id"),
+        response?.headers.get("openai-request-id"),
+        response?.headers.get("cf-ray"),
+    );
+    const providerResponseIds = uniqueStringList(
+        typeof payload?.id === "string" ? payload.id : undefined,
+        typeof payload?.response?.id === "string" ? payload.response.id : undefined,
+    );
+    if (providerRequestIds.length === 0 && providerResponseIds.length === 0) {
+        return undefined;
+    }
+    return {
+        ...(providerRequestIds.length > 0 ? { provider_request_ids: providerRequestIds } : {}),
+        ...(providerResponseIds.length > 0 ? { provider_response_ids: providerResponseIds } : {}),
+    };
+}
+
+function addUsageTotal(
+    current: Record<string, any> | undefined | null,
+    next: Record<string, any> | undefined | null,
+): Record<string, any> | undefined {
+    if (!next || typeof next !== "object") return current ?? undefined;
+    if (!current || typeof current !== "object") return { ...next };
+
+    const merged: Record<string, any> = { ...current };
+    for (const field of [
+        "prompt_tokens",
+        "completion_tokens",
+        "total_tokens",
+        "input_tokens",
+        "output_tokens",
+        "cache_creation_input_tokens",
+        "cache_read_input_tokens",
+        "prompt_cache_hit_tokens",
+        "prompt_cache_miss_tokens",
+        "cost",
+    ]) {
+        addNumericUsageField(merged, field, next);
+    }
+    for (const field of ["provider_response_ids", "provider_request_ids"]) {
+        addStringListUsageField(merged, field, next);
+    }
+
+    for (const [key, value] of Object.entries(next)) {
+        if (
+            !(key in merged) &&
+            typeof value !== "number" &&
+            !["provider_response_ids", "provider_request_ids"].includes(key)
+        ) {
+            merged[key] = value;
+        }
+    }
+    return merged;
+}
+
+function mergeUsageSnapshot(
+    current: Record<string, any> | undefined | null,
+    next: Record<string, any> | undefined | null,
+): Record<string, any> | undefined {
+    if (!next || typeof next !== "object") return current ?? undefined;
+    const merged: Record<string, any> =
+        current && typeof current === "object" ? { ...current, ...next } : { ...next };
+    for (const field of ["provider_response_ids", "provider_request_ids"]) {
+        const values = uniqueStringList(
+            current && typeof current === "object" ? current[field] : undefined,
+            next[field],
+        );
+        if (values.length > 0) merged[field] = values;
+    }
+    return merged;
+}
+
+function buildAssistantMessageFromResponse(data: any): ChatMessage | null {
     const toolCalls = extractToolCallsFromResponseOutput(data);
     const contentText = extractTextFromResponseOutput(data);
     const contentImages = extractImagePartsFromResponseOutput(data);
@@ -1352,10 +1529,10 @@ function extractTextFromResponseOutputItem(item: any): string {
         .join("");
 }
 
-function buildLatencyProfile(args: {
-    startedAt: number;
-    llmRequestCount: number;
-    llmWaitMs: number;
+function buildLatencyProfile(args: {
+    startedAt: number;
+    llmRequestCount: number;
+    llmWaitMs: number;
     llmJsonParseMs: number;
     toolExecutionMs: number;
     firstAssistantAt?: number;
@@ -1374,11 +1551,210 @@ function buildLatencyProfile(args: {
         ...(typeof args.firstToolResultAt === "number"
             ? { timeToFirstToolResultMs: Math.max(0, args.firstToolResultAt - args.startedAt) }
             : {}),
-        endedAt,
-    };
-}
-
-// ── 非流式 ────────────────────────────────────────────────────────────────────
+        endedAt,
+    };
+}
+
+function buildLoopCompletion(args: {
+    content: string;
+    model: string;
+    provider?: string;
+    inputPrice?: number;
+    outputPrice?: number;
+    usage?: Record<string, any>;
+    trace: ChatMessage[];
+    runtimeToolNames: string[];
+    toolCallCount: number;
+    runtimePolicy?: ResolvedRuntimePolicy;
+    runtimeState: ToolPolicyRuntimeState;
+    startedAt: number;
+    llmRequestCount: number;
+    llmWaitMs: number;
+    llmJsonParseMs: number;
+    toolExecutionMs: number;
+    firstAssistantAt?: number;
+    firstToolResultAt?: number;
+    providerCallIds?: string[];
+}): LoopResult {
+    return {
+        content: args.content,
+        model: args.model,
+        provider: args.provider,
+        inputPrice: args.inputPrice,
+        outputPrice: args.outputPrice,
+        usage: args.usage,
+        ...(args.providerCallIds && args.providerCallIds.length > 0
+            ? { providerCallIds: [...args.providerCallIds] }
+            : {}),
+        trace: args.trace,
+        runtimeToolNames: args.runtimeToolNames,
+        toolCallCount: args.toolCallCount,
+        policyState: {
+            autoKnowledgeCaptureCount:
+                (args.runtimePolicy?.knowledgeCapture.currentAutoCreates ?? 0) +
+                args.runtimeState.autoKnowledgeCaptureCountThisRun,
+            autoSpaceReadCount:
+                (args.runtimePolicy?.spaceContext.currentAutoReads ?? 0) +
+                args.runtimeState.autoSpaceReadCountThisRun,
+            updatedAt: Date.now(),
+        },
+        latencyProfile: buildLatencyProfile({
+            startedAt: args.startedAt,
+            llmRequestCount: args.llmRequestCount,
+            llmWaitMs: args.llmWaitMs,
+            llmJsonParseMs: args.llmJsonParseMs,
+            toolExecutionMs: args.toolExecutionMs,
+            firstAssistantAt: args.firstAssistantAt,
+            firstToolResultAt: args.firstToolResultAt,
+        }),
+    };
+}
+
+function buildStreamDoneEvent(args: {
+    usage?: Record<string, any>;
+    provider?: string;
+    model?: string;
+    inputPrice?: number;
+    outputPrice?: number;
+    elapsed?: number;
+    providerCallIds?: string[];
+}) {
+    return {
+        type: "done" as const,
+        ...(args.usage ? { usage: args.usage } : {}),
+        ...(args.provider ? { provider: args.provider } : {}),
+        ...(args.model ? { model: args.model } : {}),
+        ...(typeof args.inputPrice === "number" ? { inputPrice: args.inputPrice } : {}),
+        ...(typeof args.outputPrice === "number" ? { outputPrice: args.outputPrice } : {}),
+        ...(typeof args.elapsed === "number" ? { elapsed: args.elapsed } : {}),
+        ...(args.providerCallIds?.length ? { providerCallIds: [...args.providerCallIds] } : {}),
+    };
+}
+
+function buildRepairRequestMessages(args: {
+    messages: ChatMessage[];
+    finalParallelSummaryRepairPending: boolean;
+    emptyAssistantRepairPending: boolean;
+}): ChatMessage[] {
+    if (args.finalParallelSummaryRepairPending) {
+        return [
+            ...args.messages,
+            { role: "system", content: FINAL_PARALLEL_SUMMARY_REPAIR_PROMPT } satisfies ChatMessage,
+        ];
+    }
+    if (args.emptyAssistantRepairPending) {
+        return [
+            ...args.messages,
+            { role: "system", content: EMPTY_ASSISTANT_REPAIR_PROMPT } satisfies ChatMessage,
+        ];
+    }
+    return args.messages;
+}
+
+function resolveAssistantRepairDecision(args: {
+    messages: ChatMessage[];
+    assistantMsg: ChatMessage;
+    finalParallelSummaryRepairUsed: boolean;
+    emptyAssistantRepairUsed: boolean;
+}): "parallel-summary" | "empty-assistant" | null {
+    const assistantText = extractAssistantText(args.assistantMsg).trim();
+    if (
+        !args.assistantMsg.tool_calls?.length &&
+        !assistantText &&
+        !args.finalParallelSummaryRepairUsed &&
+        hasParallelBranchMessages(args.messages)
+    ) {
+        return "parallel-summary";
+    }
+    if (
+        !args.assistantMsg.tool_calls?.length &&
+        !assistantText &&
+        !args.emptyAssistantRepairUsed
+    ) {
+        return "empty-assistant";
+    }
+    return null;
+}
+
+async function requestLoopUpstreamTurn(args: {
+    endpoint: string;
+    agentConfig: any;
+    messages: ChatMessage[];
+    tools: ReturnType<typeof buildTools>;
+    stream: boolean;
+    finalParallelSummaryRepairPending: boolean;
+    emptyAssistantRepairPending: boolean;
+    resolvedProvider?: string;
+    resolvedModel: string;
+    resolvedInputPrice?: number;
+    resolvedOutputPrice?: number;
+    providerCallContext?: {
+        userId?: string | null;
+        dialogId?: string | null;
+        agentId?: string | null;
+    };
+    providerCallStore?: ProviderCallStore;
+}): Promise<{
+    response: Response;
+    provider?: string;
+    model: string;
+    inputPrice?: number;
+    outputPrice?: number;
+    providerCallIds?: string[];
+}> {
+    const requestMessages = buildRepairRequestMessages({
+        messages: args.messages,
+        finalParallelSummaryRepairPending: args.finalParallelSummaryRepairPending,
+        emptyAssistantRepairPending: args.emptyAssistantRepairPending,
+    });
+    const body = buildLoopRequestBody(args.agentConfig, requestMessages, args.tools, args.stream);
+    const upstreamResult = await fetchLoopUpstream(
+        args.endpoint,
+        args.agentConfig,
+        body,
+        args.providerCallContext,
+        args.providerCallStore,
+    );
+    return {
+        response: upstreamResult.response,
+        provider: upstreamResult.provider ?? args.resolvedProvider,
+        model: upstreamResult.model ?? args.resolvedModel,
+        inputPrice: upstreamResult.inputPrice ?? args.resolvedInputPrice,
+        outputPrice: upstreamResult.outputPrice ?? args.resolvedOutputPrice,
+        providerCallIds: upstreamResult.providerCallIds,
+    };
+}
+
+function buildLoopToolExecutionOptions(args: {
+    agentConfig: any;
+    messages: ChatMessage[];
+    runtimePolicy?: ResolvedRuntimePolicy;
+    runtimeState: ToolPolicyRuntimeState;
+    userId?: string | null;
+    dialogId?: string | null;
+    currentSpaceId?: string | null;
+    userInput?: string | null;
+    runtimeContext?: AgentRunRuntimeContext | null;
+}) {
+    return {
+        policy: args.runtimePolicy,
+        runtimeState: args.runtimeState,
+        userId: args.userId,
+        agentKey:
+            typeof args.agentConfig?.dbKey === "string" && args.agentConfig.dbKey.trim()
+                ? args.agentConfig.dbKey.trim()
+                : typeof args.agentConfig?.id === "string" && args.agentConfig.id.trim()
+                  ? args.agentConfig.id.trim()
+                  : null,
+        dialogId: args.dialogId,
+        currentSpaceId: args.currentSpaceId,
+        userInput: args.userInput,
+        runtimeContext: args.runtimeContext,
+        imageUrls: collectLatestImageUrls(args.messages),
+    };
+}
+
+// ── 非流式 ────────────────────────────────────────────────────────────────────
 
 export async function runAgentLoop(
     agentConfig: any,
@@ -1392,130 +1768,144 @@ export async function runAgentLoop(
     currentSpaceId?: string | null,
     userInput?: string | null,
     runtimeContext?: AgentRunRuntimeContext | null,
+    providerCallStore?: ProviderCallStore,
 ): Promise<LoopResult> {
     const startTime = Date.now();
     agentConfig = await hydrateApiKeyReferenceIfNeeded(agentConfig, serverBase, authToken);
+    const dispatchCliLoop = async () => {
+        // CLI 与普通 model 共享 prompt/model/最近历史，但这里有意保持“单次文本委托”的边界。
+        const provider: CliProvider = (agentConfig.cliProvider ?? "copilot") as CliProvider;
+        const taskPrompt = buildCliTaskPrompt(initialMessages, userInput);
+        const fullPrompt = buildCliPrompt(agentConfig.prompt, taskPrompt);
+        const result = await executeCli(provider, fullPrompt, {
+            model: agentConfig.model || undefined,
+            yolo: true,
+        });
+
+        return buildLoopCompletion({
+            content: result.text,
+            model: agentConfig.model ?? "unknown",
+            provider: agentConfig.provider ?? undefined,
+            inputPrice: agentConfig.inputPrice,
+            outputPrice: agentConfig.outputPrice,
+            usage: undefined,
+            trace: [
+                {
+                    role: "assistant",
+                    content: result.text,
+                },
+            ],
+            runtimeToolNames: [],
+            toolCallCount: 0,
+            runtimePolicy,
+            runtimeState: {
+                autoKnowledgeCaptureCountThisRun: 0,
+                autoSpaceReadCountThisRun: 0,
+            },
+            startedAt: startTime,
+            llmRequestCount: 0,
+            llmWaitMs: 0,
+            llmJsonParseMs: 0,
+            toolExecutionMs: 0,
+            firstAssistantAt: startTime + Math.max(0, result.elapsed ?? 0),
+        });
+    };
     if (agentConfig.apiSource === "cli") {
-        // CLI 与普通 model 共享 prompt/model/最近历史，但这里有意保持“单次文本委托”的边界。
-        const provider: CliProvider = (agentConfig.cliProvider ?? "copilot") as CliProvider;
-        const taskPrompt = buildCliTaskPrompt(initialMessages, userInput);
-        const fullPrompt = buildCliPrompt(agentConfig.prompt, taskPrompt);
-        const result = await executeCli(provider, fullPrompt, {
-            model: agentConfig.model || undefined,
-            yolo: true,
-        });
-
-        return {
-            content: result.text,
-            model: agentConfig.model ?? "unknown",
-            provider: agentConfig.provider ?? undefined,
-            inputPrice: agentConfig.inputPrice,
-            outputPrice: agentConfig.outputPrice,
-            usage: undefined,
-            trace: [
-                {
-                    role: "assistant",
-                    content: result.text,
-                },
-            ],
-            runtimeToolNames: [],
-            toolCallCount: 0,
-            policyState: {
-                autoKnowledgeCaptureCount:
-                    (runtimePolicy?.knowledgeCapture.currentAutoCreates ?? 0),
-                autoSpaceReadCount:
-                    (runtimePolicy?.spaceContext.currentAutoReads ?? 0),
-                updatedAt: Date.now(),
-            },
-            latencyProfile: buildLatencyProfile({
-                startedAt: startTime,
-                llmRequestCount: 0,
-                llmWaitMs: 0,
-                llmJsonParseMs: 0,
-                toolExecutionMs: 0,
-                firstAssistantAt: startTime + Math.max(0, result.elapsed ?? 0),
-            }),
-        };
-    }
-
-    const endpoint = getApiEndpoint(agentConfig);
-    const tools = buildTools(agentConfig);
-    const runtimeToolNames = getPreparedToolNames(tools);
-    // maxRounds 仅为兼容旧请求字段保留；工具轮次不再做硬限制。
-    // 后续如需控制，应改为基于成本/预算的策略，而不是轮次数量。
-    void _maxRounds;
-
-    const messages: ChatMessage[] = [...initialMessages];
-    const traceStartIndex = messages.length;
-    let finalContent = "";
-    let lastUsage: Record<string, any> | undefined;
-    let lastResolvedProvider = agentConfig.provider ?? undefined;
-    let lastResolvedModel = agentConfig.model ?? "unknown";
-    let lastResolvedInputPrice = agentConfig.inputPrice;
-    let lastResolvedOutputPrice = agentConfig.outputPrice;
-    let toolCallCount = 0;
-    let llmRequestCount = 0;
-    let llmWaitMs = 0;
-    let llmJsonParseMs = 0;
-    let toolExecutionMs = 0;
-    let firstAssistantAt: number | undefined;
-    let firstToolResultAt: number | undefined;
-    const runtimeState: ToolPolicyRuntimeState = {
-        autoKnowledgeCaptureCountThisRun: 0,
-        autoSpaceReadCountThisRun: 0,
-    };
-    let finalParallelSummaryRepairPending = false;
-    let finalParallelSummaryRepairUsed = false;
-    let emptyAssistantRepairPending = false;
-    let emptyAssistantRepairUsed = false;
-
-    const wereadPreflight = await runWereadGatewayPreflightIfNeeded({
-        agentConfig,
-        tools,
-        messages,
-        serverBase,
-        authToken,
-        runtimePolicy,
-        runtimeState,
-        userId,
-        dialogId,
-        currentSpaceId,
-        userInput,
-        runtimeContext,
-    });
-    if (wereadPreflight.ran) {
-        toolCallCount += 1;
-        toolExecutionMs += wereadPreflight.elapsedMs;
-        firstToolResultAt = wereadPreflight.completedAt;
+        return await dispatchCliLoop();
     }
+    const dispatchModelLoop = async () => {
+
+        const endpoint = getApiEndpoint(agentConfig);
+        const tools = buildTools(agentConfig);
+        const runtimeToolNames = getPreparedToolNames(tools);
+        // maxRounds 仅为兼容旧请求字段保留；工具轮次不再做硬限制。
+        // 后续如需控制，应改为基于成本/预算的策略，而不是轮次数量。
+        void _maxRounds;
+
+        const messages: ChatMessage[] = [...initialMessages];
+        const traceStartIndex = messages.length;
+        let finalContent = "";
+        let lastUsage: Record<string, any> | undefined;
+        let lastResolvedProvider = agentConfig.provider ?? undefined;
+        let lastResolvedModel = agentConfig.model ?? "unknown";
+        let lastResolvedInputPrice = agentConfig.inputPrice;
+        let lastResolvedOutputPrice = agentConfig.outputPrice;
+        const providerCallIds: string[] = [];
+        let toolCallCount = 0;
+        let llmRequestCount = 0;
+        let llmWaitMs = 0;
+        let llmJsonParseMs = 0;
+        let toolExecutionMs = 0;
+        let firstAssistantAt: number | undefined;
+        let firstToolResultAt: number | undefined;
+        const runtimeState: ToolPolicyRuntimeState = {
+            autoKnowledgeCaptureCountThisRun: 0,
+            autoSpaceReadCountThisRun: 0,
+        };
+        let finalParallelSummaryRepairPending = false;
+        let finalParallelSummaryRepairUsed = false;
+        let emptyAssistantRepairPending = false;
+        let emptyAssistantRepairUsed = false;
+
+        const wereadPreflight = await runWereadGatewayPreflightIfNeeded({
+            agentConfig,
+            tools,
+            messages,
+            serverBase,
+            authToken,
+            runtimePolicy,
+            runtimeState,
+            userId,
+            dialogId,
+            currentSpaceId,
+            userInput,
+            runtimeContext,
+        });
+        if (wereadPreflight.ran) {
+            toolCallCount += 1;
+            toolExecutionMs += wereadPreflight.elapsedMs;
+            firstToolResultAt = wereadPreflight.completedAt;
+        }
 
-    for (;;) {
-        if (Date.now() - startTime > MAX_TIME_MS) break;
-
-        const requestMessages = finalParallelSummaryRepairPending
-            ? [
-                ...messages,
-                { role: "system", content: FINAL_PARALLEL_SUMMARY_REPAIR_PROMPT } satisfies ChatMessage,
-            ]
-            : emptyAssistantRepairPending
-              ? [
-                  ...messages,
-                  { role: "system", content: EMPTY_ASSISTANT_REPAIR_PROMPT } satisfies ChatMessage,
-              ]
-            : messages;
-        const body = buildLoopRequestBody(agentConfig, requestMessages, tools, false);
-        finalParallelSummaryRepairPending = false;
-        emptyAssistantRepairPending = false;
-
-        const upstreamStartedAt = Date.now();
-        const upstreamResult = await fetchLoopUpstream(endpoint, agentConfig, body);
-        const res = upstreamResult.response;
-        llmRequestCount += 1;
-        llmWaitMs += Math.max(0, Date.now() - upstreamStartedAt);
-        lastResolvedProvider = upstreamResult.provider ?? lastResolvedProvider;
-        lastResolvedModel = upstreamResult.model ?? lastResolvedModel;
-        lastResolvedInputPrice = upstreamResult.inputPrice ?? lastResolvedInputPrice;
-        lastResolvedOutputPrice = upstreamResult.outputPrice ?? lastResolvedOutputPrice;
+        for (;;) {
+            if (Date.now() - startTime > MAX_TIME_MS) break;
+
+            const repairPendingState = {
+                finalParallelSummaryRepairPending,
+                emptyAssistantRepairPending,
+            };
+            const upstreamStartedAt = Date.now();
+            const upstreamTurn = await requestLoopUpstreamTurn({
+                endpoint,
+                agentConfig,
+                messages,
+                tools,
+                stream: false,
+                finalParallelSummaryRepairPending: repairPendingState.finalParallelSummaryRepairPending,
+                emptyAssistantRepairPending: repairPendingState.emptyAssistantRepairPending,
+                resolvedProvider: lastResolvedProvider,
+                resolvedModel: lastResolvedModel,
+                resolvedInputPrice: lastResolvedInputPrice,
+                resolvedOutputPrice: lastResolvedOutputPrice,
+                providerCallContext: {
+                    userId,
+                    dialogId,
+                    agentId: agentConfig.dbKey ?? agentConfig.id ?? null,
+                },
+                providerCallStore,
+            });
+            finalParallelSummaryRepairPending = false;
+            emptyAssistantRepairPending = false;
+        const res = upstreamTurn.response;
+        llmRequestCount += 1;
+        llmWaitMs += Math.max(0, Date.now() - upstreamStartedAt);
+        lastResolvedProvider = upstreamTurn.provider;
+        lastResolvedModel = upstreamTurn.model;
+        lastResolvedInputPrice = upstreamTurn.inputPrice;
+        lastResolvedOutputPrice = upstreamTurn.outputPrice;
+        if (upstreamTurn.providerCallIds?.length) {
+            providerCallIds.push(...upstreamTurn.providerCallIds);
+        }
 
         if (!res.ok) throw new Error(`LLM API error (${res.status}): ${await res.text()}`);
 
@@ -1531,23 +1921,23 @@ export async function runAgentLoop(
             firstAssistantAt = Date.now();
         }
 
-        lastUsage = data.usage ?? data.response?.usage ?? lastUsage;
-        const assistantText = extractAssistantText(assistantMsg).trim();
-        if (
-            !assistantMsg.tool_calls?.length &&
-            !assistantText &&
-            !finalParallelSummaryRepairUsed &&
-            hasParallelBranchMessages(messages)
-        ) {
-            finalParallelSummaryRepairPending = true;
+        lastUsage = addUsageTotal(
+            lastUsage,
+            addUsageTotal(data.usage ?? data.response?.usage, buildProviderAuditUsageMetadata(res, data)),
+        );
+        const assistantText = extractAssistantText(assistantMsg).trim();
+        const repairDecision = resolveAssistantRepairDecision({
+            messages,
+            assistantMsg,
+            finalParallelSummaryRepairUsed,
+            emptyAssistantRepairUsed,
+        });
+        if (repairDecision === "parallel-summary") {
+            finalParallelSummaryRepairPending = true;
             finalParallelSummaryRepairUsed = true;
             continue;
         }
-        if (
-            !assistantMsg.tool_calls?.length &&
-            !assistantText &&
-            !emptyAssistantRepairUsed
-        ) {
+        if (repairDecision === "empty-assistant") {
             emptyAssistantRepairPending = true;
             emptyAssistantRepairUsed = true;
             continue;
@@ -1562,22 +1952,22 @@ export async function runAgentLoop(
         for (const tc of assistantMsg.tool_calls!) {
             toolCallCount++;
             const toolStartedAt = Date.now();
-            const toolResult = await executeToolOnServer(tc, serverBase, authToken, {
-                policy: runtimePolicy,
-                runtimeState,
-                userId,
-                agentKey:
-                    typeof agentConfig?.dbKey === "string" && agentConfig.dbKey.trim()
-                        ? agentConfig.dbKey.trim()
-                        : typeof agentConfig?.id === "string" && agentConfig.id.trim()
-                          ? agentConfig.id.trim()
-                          : null,
-                dialogId,
-                currentSpaceId,
-                userInput,
-                runtimeContext,
-                imageUrls: collectLatestImageUrls(messages),
-            });
+            const toolResult = await executeToolOnServer(
+                tc,
+                serverBase,
+                authToken,
+                buildLoopToolExecutionOptions({
+                    agentConfig,
+                    messages,
+                    runtimePolicy,
+                    runtimeState,
+                    userId,
+                    dialogId,
+                    currentSpaceId,
+                    userInput,
+                    runtimeContext,
+                }),
+            );
             toolExecutionMs += Math.max(0, Date.now() - toolStartedAt);
             if (firstToolResultAt === undefined) {
                 firstToolResultAt = Date.now();
@@ -1588,125 +1978,103 @@ export async function runAgentLoop(
                 content: toolResult,
             });
             const directCompletion = buildDirectCompletionFromToolResult(tc.function.name, toolResult);
-            if (directCompletion) {
-                finalContent = directCompletion;
-                messages.push({
-                    role: "assistant",
-                    content: directCompletion,
-                });
-        return {
-            content: finalContent,
-            model: lastResolvedModel,
-            provider: lastResolvedProvider,
-            inputPrice: lastResolvedInputPrice,
-            outputPrice: lastResolvedOutputPrice,
-            usage: lastUsage,
-                    trace: messages.slice(traceStartIndex),
-                    runtimeToolNames,
-                    toolCallCount,
-                    policyState: {
-                        autoKnowledgeCaptureCount:
-                            (runtimePolicy?.knowledgeCapture.currentAutoCreates ?? 0) +
-                            runtimeState.autoKnowledgeCaptureCountThisRun,
-                        autoSpaceReadCount:
-                            (runtimePolicy?.spaceContext.currentAutoReads ?? 0) +
-                            runtimeState.autoSpaceReadCountThisRun,
-                        updatedAt: Date.now(),
-                    },
-                    latencyProfile: buildLatencyProfile({
-                        startedAt: startTime,
-                        llmRequestCount,
-                        llmWaitMs,
-                        llmJsonParseMs,
-                        toolExecutionMs,
-                        firstAssistantAt,
-                        firstToolResultAt,
-                    }),
-                };
-            }
+            if (directCompletion) {
+                finalContent = directCompletion;
+                messages.push({
+                    role: "assistant",
+                    content: directCompletion,
+                });
+                return buildLoopCompletion({
+            content: finalContent,
+            model: lastResolvedModel,
+            provider: lastResolvedProvider,
+            inputPrice: lastResolvedInputPrice,
+            outputPrice: lastResolvedOutputPrice,
+            usage: lastUsage,
+                    trace: messages.slice(traceStartIndex),
+                    runtimeToolNames,
+                    toolCallCount,
+                    runtimePolicy,
+                    runtimeState,
+                    startedAt: startTime,
+                    llmRequestCount,
+                    llmWaitMs,
+                    llmJsonParseMs,
+                    toolExecutionMs,
+                    firstAssistantAt,
+                    firstToolResultAt,
+                    providerCallIds,
+                });
+            }
             if (["runStreamingAgent", "streamParallelAgents"].includes(canonicalizeToolName(tc.function.name))) {
                 const parsed = parseToolResult(toolResult);
                 if (canonicalizeToolName(tc.function.name) === "streamParallelAgents") {
                     appendParallelBranchMessages(messages, parsed);
                 }
-                if (parsed?.handoff && typeof parsed.content === "string" && parsed.content.trim()) {
-                    finalContent = parsed.content;
-                    if (canonicalizeToolName(tc.function.name) !== "streamParallelAgents") {
-                        messages.push({
-                            role: "assistant",
-                            content: parsed.content,
-                        });
-                    }
-                    return {
-                        content: finalContent,
-                        model: parsed.model || lastResolvedModel,
-                        provider: parsed.provider || lastResolvedProvider,
-                        inputPrice:
-                            typeof parsed.inputPrice === "number"
+                if (parsed?.handoff && typeof parsed.content === "string" && parsed.content.trim()) {
+                    finalContent = parsed.content;
+                    if (canonicalizeToolName(tc.function.name) !== "streamParallelAgents") {
+                        messages.push({
+                            role: "assistant",
+                            content: parsed.content,
+                        });
+                    }
+                    return buildLoopCompletion({
+                        content: finalContent,
+                        model: parsed.model || lastResolvedModel,
+                        provider: parsed.provider || lastResolvedProvider,
+                        inputPrice:
+                            typeof parsed.inputPrice === "number"
                                 ? parsed.inputPrice
                                 : lastResolvedInputPrice,
                         outputPrice:
                             typeof parsed.outputPrice === "number"
-                                ? parsed.outputPrice
-                                : lastResolvedOutputPrice,
-                        usage: parsed.usage ?? lastUsage,
-                        trace: messages.slice(traceStartIndex),
-                        runtimeToolNames,
-                        toolCallCount,
-                        policyState: {
-                            autoKnowledgeCaptureCount:
-                                (runtimePolicy?.knowledgeCapture.currentAutoCreates ?? 0) +
-                                runtimeState.autoKnowledgeCaptureCountThisRun,
-                            autoSpaceReadCount:
-                                (runtimePolicy?.spaceContext.currentAutoReads ?? 0) +
-                                runtimeState.autoSpaceReadCountThisRun,
-                            updatedAt: Date.now(),
-                        },
-                        latencyProfile: buildLatencyProfile({
-                            startedAt: startTime,
-                            llmRequestCount,
-                            llmWaitMs,
-                            llmJsonParseMs,
-                            toolExecutionMs,
-                            firstAssistantAt,
-                            firstToolResultAt,
-                        }),
-                    };
-                }
-            }
-        }
-    }
-
-    return {
-        content: finalContent,
-        model: lastResolvedModel,
-        provider: lastResolvedProvider,
-        inputPrice: lastResolvedInputPrice,
-        outputPrice: lastResolvedOutputPrice,
-        usage: lastUsage,
-        trace: messages.slice(traceStartIndex),
-        runtimeToolNames,
-        toolCallCount,
-        policyState: {
-            autoKnowledgeCaptureCount:
-                (runtimePolicy?.knowledgeCapture.currentAutoCreates ?? 0) +
-                runtimeState.autoKnowledgeCaptureCountThisRun,
-            autoSpaceReadCount:
-                (runtimePolicy?.spaceContext.currentAutoReads ?? 0) +
-                runtimeState.autoSpaceReadCountThisRun,
-            updatedAt: Date.now(),
-        },
-        latencyProfile: buildLatencyProfile({
-            startedAt: startTime,
-            llmRequestCount,
-            llmWaitMs,
-            llmJsonParseMs,
-            toolExecutionMs,
-            firstAssistantAt,
-            firstToolResultAt,
-        }),
-    };
-}
+                                ? parsed.outputPrice
+                                : lastResolvedOutputPrice,
+                        usage: parsed.usage ?? lastUsage,
+                        trace: messages.slice(traceStartIndex),
+                        runtimeToolNames,
+                        toolCallCount,
+                        runtimePolicy,
+                        runtimeState,
+                        startedAt: startTime,
+                        llmRequestCount,
+                        llmWaitMs,
+                        llmJsonParseMs,
+                        toolExecutionMs,
+                        firstAssistantAt,
+                        firstToolResultAt,
+                        providerCallIds,
+                    });
+                }
+            }
+        }
+    }
+
+        return buildLoopCompletion({
+            content: finalContent,
+            model: lastResolvedModel,
+            provider: lastResolvedProvider,
+            inputPrice: lastResolvedInputPrice,
+            outputPrice: lastResolvedOutputPrice,
+            usage: lastUsage,
+            trace: messages.slice(traceStartIndex),
+            runtimeToolNames,
+            toolCallCount,
+            runtimePolicy,
+            runtimeState,
+            startedAt: startTime,
+            llmRequestCount,
+            llmWaitMs,
+            llmJsonParseMs,
+            toolExecutionMs,
+            firstAssistantAt,
+            firstToolResultAt,
+            providerCallIds,
+        });
+    };
+    return await dispatchModelLoop();
+}
 
 // ── 流式（SSE）────────────────────────────────────────────────────────────────
 
@@ -1724,104 +2092,121 @@ export function buildSseStream(
     currentSpaceId?: string | null,
     userInput?: string | null,
     runtimeContext?: AgentRunRuntimeContext | null,
+    providerCallStore?: ProviderCallStore,
 ): ReadableStream {
     const encoder = new TextEncoder();
 
-    return new ReadableStream({
-        async start(controller) {
-            const send: Send = (data) =>
-                controller.enqueue(encoder.encode(`data: ${JSON.stringify(data)}\n\n`));
-
-            try {
-                if (agentConfig.apiSource === "cli") {
-                    // CLI 流式输出仅依赖 provider 自己的 stdout 语义，不合成本地 tool 事件。
-                    const provider: CliProvider = (agentConfig.cliProvider ?? "copilot") as CliProvider;
-                    const taskPrompt = buildCliTaskPrompt(initialMessages, userInput);
-                    const fullPrompt = buildCliPrompt(agentConfig.prompt, taskPrompt);
-
-                    const result = await executeCliStreaming(provider, fullPrompt, {
-                        model: agentConfig.model || undefined,
-                        yolo: true,
-                        onChunk: (chunk: string) => {
-                            if (!chunk) return;
-                            send({ type: "text", content: chunk });
-                        },
-                    });
-
-                    send({ type: "done", usage: undefined, elapsed: result.elapsed });
-                    controller.close();
-                    return;
-                }
-
-                const endpoint = getApiEndpoint(agentConfig);
-                const tools = buildTools(agentConfig);
-                // maxRounds 仅为兼容旧请求字段保留；工具轮次不再做硬限制。
-                // 后续如需控制，应改为基于成本/预算的策略，而不是轮次数量。
-                void _maxRounds;
-                const messages: ChatMessage[] = [...initialMessages];
-                const runtimeState: ToolPolicyRuntimeState = {
-                    autoKnowledgeCaptureCountThisRun: 0,
-                    autoSpaceReadCountThisRun: 0,
-                };
-                const startTime = Date.now();
-                let lastUsage: Record<string, any> | undefined;
-                let lastResolvedProvider = agentConfig.provider ?? undefined;
-                let lastResolvedModel = agentConfig.model ?? "unknown";
-                let lastResolvedInputPrice = agentConfig.inputPrice;
-                let lastResolvedOutputPrice = agentConfig.outputPrice;
-                let finalParallelSummaryRepairPending = false;
-                let finalParallelSummaryRepairUsed = false;
-                let emptyAssistantRepairPending = false;
-                let emptyAssistantRepairUsed = false;
-
-                await runWereadGatewayPreflightIfNeeded({
-                    agentConfig,
-                    tools,
-                    messages,
-                    serverBase,
-                    authToken,
-                    runtimePolicy,
-                    runtimeState,
-                    userId,
-                    dialogId,
-                    currentSpaceId,
-                    userInput,
-                    runtimeContext,
-                    send,
-                });
+    return new ReadableStream({
+        async start(controller) {
+            const send: Send = (data) =>
+                controller.enqueue(encoder.encode(`data: ${JSON.stringify(data)}\n\n`));
 
-                for (;;) {
-                    if (Date.now() - startTime > MAX_TIME_MS) {
-                        send({ type: "error", message: "Max execution time exceeded" });
-                        break;
-                    }
-
-                    const requestMessages = finalParallelSummaryRepairPending
-                        ? [
-                            ...messages,
-                            { role: "system", content: FINAL_PARALLEL_SUMMARY_REPAIR_PROMPT } satisfies ChatMessage,
-                        ]
-                        : emptyAssistantRepairPending
-                          ? [
-                              ...messages,
-                              { role: "system", content: EMPTY_ASSISTANT_REPAIR_PROMPT } satisfies ChatMessage,
-                          ]
-                        : messages;
-                    const body = buildLoopRequestBody(agentConfig, requestMessages, tools, true);
+            try {
+                const dispatchCliStreamingLoop = async () => {
+                    // CLI 流式输出仅依赖 provider 自己的 stdout 语义，不合成本地 tool 事件。
+                    const provider: CliProvider = (agentConfig.cliProvider ?? "copilot") as CliProvider;
+                    const taskPrompt = buildCliTaskPrompt(initialMessages, userInput);
+                    const fullPrompt = buildCliPrompt(agentConfig.prompt, taskPrompt);
+
+                    const result = await executeCliStreaming(provider, fullPrompt, {
+                        model: agentConfig.model || undefined,
+                        yolo: true,
+                        onChunk: (chunk: string) => {
+                            if (!chunk) return;
+                            send({ type: "text", content: chunk });
+                        },
+                    });
+
+                    send(buildStreamDoneEvent({ elapsed: result.elapsed }));
+                    controller.close();
+                };
+                if (agentConfig.apiSource === "cli") {
+                    return await dispatchCliStreamingLoop();
+                }
+                const dispatchModelStreamingLoop = async () => {
+
+                    const endpoint = getApiEndpoint(agentConfig);
+                    const tools = buildTools(agentConfig);
+                    // maxRounds 仅为兼容旧请求字段保留；工具轮次不再做硬限制。
+                    // 后续如需控制，应改为基于成本/预算的策略，而不是轮次数量。
+                    void _maxRounds;
+                    const messages: ChatMessage[] = [...initialMessages];
+                    const runtimeState: ToolPolicyRuntimeState = {
+                        autoKnowledgeCaptureCountThisRun: 0,
+                        autoSpaceReadCountThisRun: 0,
+                    };
+                    const startTime = Date.now();
+                    let lastUsage: Record<string, any> | undefined;
+                    let lastResolvedProvider = agentConfig.provider ?? undefined;
+                    let lastResolvedModel = agentConfig.model ?? "unknown";
+                    let lastResolvedInputPrice = agentConfig.inputPrice;
+                    let lastResolvedOutputPrice = agentConfig.outputPrice;
+                    const providerCallIds: string[] = [];
+                    let finalParallelSummaryRepairPending = false;
+                    let finalParallelSummaryRepairUsed = false;
+                    let emptyAssistantRepairPending = false;
+                    let emptyAssistantRepairUsed = false;
+
+                    await runWereadGatewayPreflightIfNeeded({
+                        agentConfig,
+                        tools,
+                        messages,
+                        serverBase,
+                        authToken,
+                        runtimePolicy,
+                        runtimeState,
+                        userId,
+                        dialogId,
+                        currentSpaceId,
+                        userInput,
+                        runtimeContext,
+                        send,
+                    });
+
+                    for (;;) {
+                        if (Date.now() - startTime > MAX_TIME_MS) {
+                            send({ type: "error", message: "Max execution time exceeded" });
+                            break;
+                        }
+                    const repairPendingState = {
+                        finalParallelSummaryRepairPending,
+                        emptyAssistantRepairPending,
+                    };
                     finalParallelSummaryRepairPending = false;
                     emptyAssistantRepairPending = false;
-
-                    let res: Response;
-                    try {
-                        const upstreamResult = await fetchLoopUpstream(endpoint, agentConfig, body);
-                        res = upstreamResult.response;
-                        lastResolvedProvider = upstreamResult.provider ?? lastResolvedProvider;
-                        lastResolvedModel = upstreamResult.model ?? lastResolvedModel;
-                        lastResolvedInputPrice = upstreamResult.inputPrice ?? lastResolvedInputPrice;
-                        lastResolvedOutputPrice = upstreamResult.outputPrice ?? lastResolvedOutputPrice;
-                    } catch (error: any) {
-                        send({ type: "error", message: error?.message ?? "Unexpected error" });
-                        break;
+
+                    let res: Response;
+                    try {
+                        const upstreamTurn = await requestLoopUpstreamTurn({
+                            endpoint,
+                            agentConfig,
+                            messages,
+                            tools,
+                            stream: true,
+                            finalParallelSummaryRepairPending: repairPendingState.finalParallelSummaryRepairPending,
+                            emptyAssistantRepairPending: repairPendingState.emptyAssistantRepairPending,
+                            resolvedProvider: lastResolvedProvider,
+                            resolvedModel: lastResolvedModel,
+                            resolvedInputPrice: lastResolvedInputPrice,
+                            resolvedOutputPrice: lastResolvedOutputPrice,
+                            providerCallContext: {
+                                userId,
+                                dialogId,
+                                agentId: agentConfig.dbKey ?? agentConfig.id ?? null,
+                            },
+                            providerCallStore,
+                        });
+                        res = upstreamTurn.response;
+                        lastResolvedProvider = upstreamTurn.provider;
+                        lastResolvedModel = upstreamTurn.model;
+                        lastResolvedInputPrice = upstreamTurn.inputPrice;
+                        lastResolvedOutputPrice = upstreamTurn.outputPrice;
+                        if (upstreamTurn.providerCallIds?.length) {
+                            providerCallIds.push(...upstreamTurn.providerCallIds);
+                        }
+                    } catch (error: any) {
+                        send({ type: "error", message: error?.message ?? "Unexpected error" });
+                        break;
                     }
                     if (!res.ok || !res.body) {
                         send({ type: "error", message: `LLM API error (${res.status}): ${await res.text()}` });
@@ -1839,7 +2224,10 @@ export function buildSseStream(
                         assistantContent,
                         reasoningContent,
                     } = streamResult;
-                    lastUsage = streamResult.lastUsage ?? lastUsage;
+                    lastUsage = addUsageTotal(
+                        lastUsage,
+                        addUsageTotal(streamResult.lastUsage, buildProviderAuditUsageMetadata(res)),
+                    );
 
                     const assistantMsg: ChatMessage = {
                         role: "assistant",
@@ -1847,38 +2235,35 @@ export function buildSseStream(
                         ...(reasoningContent ? { reasoning_content: reasoningContent } : {}),
                         ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
                     };
-                    if (
-                        !hasToolCalls &&
-                        !extractAssistantText(assistantMsg).trim() &&
-                        !finalParallelSummaryRepairUsed &&
-                        hasParallelBranchMessages(messages)
-                    ) {
-                        finalParallelSummaryRepairPending = true;
+                    const repairDecision = resolveAssistantRepairDecision({
+                        messages,
+                        assistantMsg,
+                        finalParallelSummaryRepairUsed,
+                        emptyAssistantRepairUsed,
+                    });
+                    if (repairDecision === "parallel-summary") {
+                        finalParallelSummaryRepairPending = true;
                         finalParallelSummaryRepairUsed = true;
                         continue;
                     }
-                    if (
-                        !hasToolCalls &&
-                        !extractAssistantText(assistantMsg).trim() &&
-                        !emptyAssistantRepairUsed
-                    ) {
+                    if (repairDecision === "empty-assistant") {
                         emptyAssistantRepairPending = true;
                         emptyAssistantRepairUsed = true;
                         continue;
                     }
                     messages.push(assistantMsg);
 
-                    if (!hasToolCalls) {
-                        send({
-                            type: "done",
-                            usage: lastUsage,
-                            provider: lastResolvedProvider,
-                            model: lastResolvedModel,
-                            inputPrice: lastResolvedInputPrice,
-                            outputPrice: lastResolvedOutputPrice,
-                        });
-                        break;
-                    }
+                    if (!hasToolCalls) {
+                        send(buildStreamDoneEvent({
+                            usage: lastUsage,
+                            provider: lastResolvedProvider,
+                            model: lastResolvedModel,
+                            inputPrice: lastResolvedInputPrice,
+                            outputPrice: lastResolvedOutputPrice,
+                            providerCallIds,
+                        }));
+                        break;
+                    }
 
                     send({
                         type: "assistant_tool_calls",
@@ -1887,22 +2272,22 @@ export function buildSseStream(
                     });
                     send({ type: "tool_start", calls: toolCalls.map((t) => t.function.name) });
                     for (const tc of toolCalls) {
-                        const toolResult = await executeToolOnServer(tc, serverBase, authToken, {
-                            policy: runtimePolicy,
-                            runtimeState,
-                            userId,
-                            agentKey:
-                                typeof agentConfig?.dbKey === "string" && agentConfig.dbKey.trim()
-                                    ? agentConfig.dbKey.trim()
-                                    : typeof agentConfig?.id === "string" && agentConfig.id.trim()
-                                      ? agentConfig.id.trim()
-                                      : null,
-                            dialogId,
-                            currentSpaceId,
-                            userInput,
-                            runtimeContext,
-                            imageUrls: collectLatestImageUrls(messages),
-                        });
+                        const toolResult = await executeToolOnServer(
+                            tc,
+                            serverBase,
+                            authToken,
+                            buildLoopToolExecutionOptions({
+                                agentConfig,
+                                messages,
+                                runtimePolicy,
+                                runtimeState,
+                                userId,
+                                dialogId,
+                                currentSpaceId,
+                                userInput,
+                                runtimeContext,
+                            }),
+                        );
                         messages.push({
                             role: "tool",
                             tool_call_id: tc.id,
@@ -1916,46 +2301,46 @@ export function buildSseStream(
                         });
                         const directCompletion = buildDirectCompletionFromToolResult(tc.function.name, toolResult);
                         if (directCompletion) {
-                            messages.push({
-                                role: "assistant",
-                                content: directCompletion,
-                            });
-                            send({ type: "text", content: directCompletion });
-                            send({
-                                type: "done",
-                                usage: lastUsage,
-                                provider: lastResolvedProvider,
-                                model: lastResolvedModel,
-                                inputPrice: lastResolvedInputPrice,
-                                outputPrice: lastResolvedOutputPrice,
-                            });
-                            controller.close();
-                            return;
-                        }
+                            messages.push({
+                                role: "assistant",
+                                content: directCompletion,
+                            });
+                            send({ type: "text", content: directCompletion });
+                            send(buildStreamDoneEvent({
+                                usage: lastUsage,
+                                provider: lastResolvedProvider,
+                                model: lastResolvedModel,
+                                inputPrice: lastResolvedInputPrice,
+                                outputPrice: lastResolvedOutputPrice,
+                                providerCallIds,
+                            }));
+                            controller.close();
+                            return;
+                        }
                         if (["runStreamingAgent", "streamParallelAgents"].includes(canonicalizeToolName(tc.function.name))) {
                             const parsed = parseToolResult(toolResult);
                             if (canonicalizeToolName(tc.function.name) === "streamParallelAgents") {
                                 appendParallelBranchMessages(messages, parsed);
                             }
-                            if (parsed?.handoff && typeof parsed.content === "string" && parsed.content.trim()) {
-                                send({ type: "text", content: parsed.content });
-                                send({
-                                    type: "done",
-                                    usage: parsed.usage ?? lastUsage,
-                                    provider: parsed.provider || lastResolvedProvider,
-                                    model: parsed.model || lastResolvedModel,
-                                    inputPrice:
-                                        typeof parsed.inputPrice === "number"
-                                            ? parsed.inputPrice
-                                            : lastResolvedInputPrice,
-                                    outputPrice:
-                                        typeof parsed.outputPrice === "number"
-                                            ? parsed.outputPrice
-                                            : lastResolvedOutputPrice,
-                                });
-                                controller.close();
-                                return;
-                            }
+                            if (parsed?.handoff && typeof parsed.content === "string" && parsed.content.trim()) {
+                                send({ type: "text", content: parsed.content });
+                                send(buildStreamDoneEvent({
+                                    usage: parsed.usage ?? lastUsage,
+                                    provider: parsed.provider || lastResolvedProvider,
+                                    model: parsed.model || lastResolvedModel,
+                                    inputPrice:
+                                        typeof parsed.inputPrice === "number"
+                                            ? parsed.inputPrice
+                                            : lastResolvedInputPrice,
+                                    outputPrice:
+                                        typeof parsed.outputPrice === "number"
+                                            ? parsed.outputPrice
+                                            : lastResolvedOutputPrice,
+                                    providerCallIds,
+                                }));
+                                controller.close();
+                                return;
+                            }
                         }
                         // 如果是创建文档类工具，解析结果并推送 doc_created 事件让前端感知
                         if (["createDoc", "createSkillDoc", "importSkill"].includes(canonicalizeToolName(tc.function.name))) {
@@ -1966,13 +2351,16 @@ export function buildSseStream(
                                 }
                             } catch { /* 忽略解析失败 */ }
                         }
-                    }
-                    send({ type: "tool_end" });
-                }
-            } catch (e: any) {
-                controller.enqueue(
-                    encoder.encode(`data: ${JSON.stringify({ type: "error", message: e.message ?? "Unexpected error" })}\n\n`)
-                );
+                        }
+                        send({ type: "tool_end" });
+                    }
+                    controller.close();
+                };
+                return await dispatchModelStreamingLoop();
+            } catch (e: any) {
+                controller.enqueue(
+                    encoder.encode(`data: ${JSON.stringify({ type: "error", message: e.message ?? "Unexpected error" })}\n\n`)
+                );
             }
             controller.close();
         },
@@ -2028,8 +2416,15 @@ async function consumeSseStream(
             let chunk: any;
             try { chunk = JSON.parse(raw); } catch { continue; }
 
-            const delta = chunk.choices?.[0]?.delta;
-            if (!delta) { if (chunk.usage) lastUsage = chunk.usage; continue; }
+            const delta = chunk.choices?.[0]?.delta;
+            const chunkAuditUsage = buildProviderAuditUsageMetadata(null, chunk);
+            if (!delta) {
+                lastUsage = mergeUsageSnapshot(
+                    lastUsage,
+                    mergeUsageSnapshot(chunk.usage, chunkAuditUsage),
+                ) ?? null;
+                continue;
+            }
 
             if (typeof delta.content === "string" && delta.content) {
                 appendTextPart(assistantContentParts, delta.content);
@@ -2064,8 +2459,11 @@ async function consumeSseStream(
                 }
             }
 
-            if (chunk.usage) lastUsage = chunk.usage;
-        }
+            lastUsage = mergeUsageSnapshot(
+                lastUsage,
+                mergeUsageSnapshot(chunk.usage, chunkAuditUsage),
+            ) ?? null;
+        }
     }
 
     const assistantContent = finalizeAssistantContent(assistantContentParts);
@@ -2115,7 +2513,15 @@ async function consumeResponsesSseStream(
                 continue;
             }
 
-            if (event?.usage) lastUsage = event.usage;
+            const eventAuditUsage = buildProviderAuditUsageMetadata(null, event);
+            const eventUsage =
+                event?.type === "response.completed" && event.response?.usage
+                    ? undefined
+                    : event?.usage;
+            lastUsage = mergeUsageSnapshot(
+                lastUsage,
+                mergeUsageSnapshot(eventUsage, eventAuditUsage),
+            ) ?? null;
 
             switch (event?.type) {
                 case "response.output_text.delta":
@@ -2183,10 +2589,16 @@ async function consumeResponsesSseStream(
                     acc.set(key, current);
                     break;
                 }
-                case "response.completed":
-                    completedResponse = event.response ?? null;
-                    if (event.response?.usage) lastUsage = event.response.usage;
-                    break;
+                case "response.completed":
+                    completedResponse = event.response ?? null;
+                    lastUsage = mergeUsageSnapshot(
+                        lastUsage,
+                        mergeUsageSnapshot(
+                            event.response?.usage,
+                            buildProviderAuditUsageMetadata(null, event.response),
+                        ),
+                    ) ?? null;
+                    break;
                 default:
                     break;
             }