nolo-cli 0.1.23 → 0.1.29

package/server/handlers/agentRun/loop.ts

@@ -0,0 +1,2210 @@
+// packages/server/handlers/agentRun/loop.ts
+//
+// 纯函数 Agent Loop（无 Redux，无持久化）。
+// - platform/custom: 直接调用 LLM API，支持本地 tool_calls 循环
+// - cli: 复用 prompt / model / 最近文本历史，但不走本地 tool_calls 协议
+// - 调用方负责传入 messages 历史并保存返回结果
+
+import { buildCliPrompt, executeCli, executeCliStreaming, type CliProvider } from "../../../ai/agent/cliExecutor";
+import { findModelConfig, getApiEndpoint } from "../../../ai/llm/providers";
+import {
+    DEEPINFRA_KIMI_FALLBACK_MODEL,
+    FIREWORKS_KIMI_CURRENT_MODEL,
+    KIMI_PLATFORM_FALLBACK_STATUSES,
+    OPENROUTER_KIMI_FALLBACK_MODEL,
+    isDeepInfraKimiModel,
+    isFireworksKimiModel,
+} from "../../../ai/llm/kimi";
+import { getModelInfo } from "../../../ai/llm/getModelContextWindow";
+import { isResponseAPIModel } from "../../../ai/llm/isResponseAPIModel";
+import { getNoloKey } from "../../../ai/llm/getNoloKey";
+import { prepareTools } from "../../../ai/tools/prepareTools";
+import { canonicalizeToolName } from "../../../ai/tools/toolNameAliases";
+import { generateRequestBody } from "../../../ai/llm/generateRequestBody";
+import {
+    fetchGoogleNativeImageCompletion,
+    fetchGoogleNativeImageChat,
+    isGoogleNativeImageModel,
+} from "../googleNativeChat";
+import {
+    extractImagePartsFromResponseOutput,
+    extractTextFromResponseOutput,
+    extractToolCallsFromResponseOutput,
+    toResponsesTools,
+} from "../../../integrations/openai/responsesHelpers";
+import { normalizeChatCompletionsBodyForProvider } from "../../../integrations/openai/providerBodyCompatibility";
+import { fetchUpstreamWithGentleRetry } from "../chatUpstreamRetry";
+import { executeToolOnServer } from "./toolExecutor";
+import type {
+    AgentRunRuntimeContext,
+    ChatMessage,
+    AssistantToolCall,
+    LoopResult,
+    ToolPolicyRuntimeState,
+} from "./types";
+import type { ResolvedRuntimePolicy } from "../../../ai/policy/runtimePolicy";
+import { isLocalEndpoint } from "./localRuntimeBootstrap";
+
+const MAX_TIME_MS = 10 * 60_000; // 10 min
+const DEFAULT_LLM_REQUEST_TIMEOUT_MS = 300_000;
+const DEFAULT_LOCAL_LLM_REQUEST_TIMEOUT_MS = MAX_TIME_MS;
+const OPENROUTER_CHAT_COMPLETIONS_URL =
+    "https://openrouter.ai/api/v1/chat/completions";
+const GOOGLE_FALLBACK_STATUSES = [404, 429, 500, 502, 503, 504];
+const FIREWORKS_OPENROUTER_FALLBACK_STATUSES = KIMI_PLATFORM_FALLBACK_STATUSES;
+const BUILTIN_NOLO_AGENT_KEY = "agent-pub-01NOLOAPPBLD000000019KCKT0";
+
+const toOpenRouterGoogleModelName = (modelName: string) => `google/${modelName}`;
+
+const parseTimeoutOverride = (rawValue: string | undefined): number | null => {
+    const parsed = Number(rawValue);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+};
+
+export const resolveLlmRequestTimeoutMs = (
+    agentConfig: any,
+    endpoint: string,
+): number => {
+    const globalOverride = parseTimeoutOverride(process.env.AGENT_LOOP_LLM_TIMEOUT_MS);
+    const localOverride = parseTimeoutOverride(process.env.AGENT_LOOP_LOCAL_LLM_TIMEOUT_MS);
+    const isLocalCustomProvider =
+        !!agentConfig?.customProviderUrl && isLocalEndpoint(endpoint);
+
+    if (isLocalCustomProvider && localOverride) {
+        return localOverride;
+    }
+    if (globalOverride) {
+        return globalOverride;
+    }
+    return isLocalCustomProvider
+        ? DEFAULT_LOCAL_LLM_REQUEST_TIMEOUT_MS
+        : DEFAULT_LLM_REQUEST_TIMEOUT_MS;
+};
+
+function buildUpstreamHeaders(
+    requestUrl: string,
+    apiKey?: string | null,
+    apiKeyHeader?: string | null,
+) {
+    const headers: Record<string, string> = {
+        "Content-Type": "application/json",
+    };
+    const normalizedApiKeyHeader =
+        apiKeyHeader?.trim() ||
+        (/xiaomimimo\.com/i.test(requestUrl) ? "api-key" : "");
+    if (apiKey) {
+        if (normalizedApiKeyHeader) {
+            headers[normalizedApiKeyHeader] = apiKey;
+        } else {
+            headers.Authorization = `Bearer ${apiKey}`;
+        }
+    }
+
+    if (requestUrl.includes("openrouter.ai")) {
+        headers["HTTP-Referer"] = "https://nolo.chat";
+        headers["X-Title"] = "nolo";
+    }
+
+    return headers;
+}
+
+async function readAgentApiKeyReference(args: {
+    agentKey: string;
+    serverBase: string;
+    authToken: string;
+}): Promise<string | undefined> {
+    const trimmedAgentKey = args.agentKey.trim();
+    if (!trimmedAgentKey) return undefined;
+
+    const url = `${args.serverBase.replace(/\/+$/, "")}/api/v1/db/read/${encodeURIComponent(trimmedAgentKey)}`;
+    const headers: Record<string, string> = {};
+    if (args.authToken) {
+        headers.Authorization = `Bearer ${args.authToken}`;
+    }
+
+    const response = await fetch(url, {
+        method: "GET",
+        headers,
+        signal: AbortSignal.timeout(30_000),
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to read apiKeyFromAgentKey agent (${response.status}).`);
+    }
+
+    const payload = await response.json() as any;
+    const record = payload?.data ?? payload;
+    const key = typeof record?.apiKey === "string" ? record.apiKey.trim() : "";
+    return key || undefined;
+}
+
+async function hydrateApiKeyReferenceIfNeeded(
+    agentConfig: any,
+    serverBase: string,
+    authToken: string,
+) {
+    if (agentConfig?.apiKey?.trim()) return agentConfig;
+    const sourceAgentKey =
+        typeof agentConfig?.apiKeyFromAgentKey === "string"
+            ? agentConfig.apiKeyFromAgentKey.trim()
+            : "";
+    if (!sourceAgentKey) return agentConfig;
+
+    const apiKey = await readAgentApiKeyReference({
+        agentKey: sourceAgentKey,
+        serverBase,
+        authToken,
+    });
+    if (!apiKey) {
+        throw new Error(`apiKeyFromAgentKey did not resolve an API key for ${sourceAgentKey}.`);
+    }
+
+    return {
+        ...agentConfig,
+        apiKey,
+    };
+}
+
+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);
+    const llmRequestTimeoutMs = resolveLlmRequestTimeoutMs(agentConfig, endpoint);
+    const init: RequestInit = {
+        method: "POST",
+        headers: {
+            ...buildUpstreamHeaders(endpoint, apiKey, agentConfig?.apiKeyHeader),
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(llmRequestTimeoutMs),
+    };
+
+    const shouldUseGoogleOpenRouterFallback =
+        String(agentConfig?.provider || "").toLowerCase() === "google" &&
+        typeof agentConfig?.model === "string" &&
+        !!agentConfig.model &&
+        !agentConfig?.customProviderUrl;
+    const openRouterApiKey = shouldUseGoogleOpenRouterFallback
+        ? getNoloKey("openrouter")
+        : null;
+    const shouldUseConfiguredFallback =
+        String(agentConfig?.provider || "").toLowerCase() === "fireworks" &&
+        typeof agentConfig?.fallbackProvider === "string" &&
+        agentConfig.fallbackProvider.trim().toLowerCase() === "openrouter" &&
+        typeof agentConfig?.fallbackModel === "string" &&
+        !!agentConfig.fallbackModel.trim() &&
+        !agentConfig?.customProviderUrl;
+    const normalizedAgentProvider = String(agentConfig?.provider || "").toLowerCase();
+    const shouldUseKimiPlatformFallback =
+        ((normalizedAgentProvider === "deepinfra" &&
+            isDeepInfraKimiModel(agentConfig?.model)) ||
+            (normalizedAgentProvider === "fireworks" &&
+                isFireworksKimiModel(agentConfig?.model))) &&
+        !agentConfig?.customProviderUrl;
+    const fireworksKimiFallbackApiKey =
+        shouldUseKimiPlatformFallback && normalizedAgentProvider !== "fireworks"
+            ? getNoloKey("fireworks")
+            : null;
+    const deepInfraKimiFallbackApiKey =
+        shouldUseKimiPlatformFallback && normalizedAgentProvider !== "deepinfra"
+            ? getNoloKey("deepinfra")
+            : null;
+    const openRouterKimiFallbackApiKey = shouldUseKimiPlatformFallback
+        ? getNoloKey("openrouter")
+        : null;
+    const configuredFallbackApiKey = shouldUseConfiguredFallback
+        ? getNoloKey("openrouter")
+        : null;
+    const deepInfraKimiFallbackUrl = getApiEndpoint({
+        provider: "deepinfra",
+        model: DEEPINFRA_KIMI_FALLBACK_MODEL,
+    } as any);
+    const fireworksKimiFallbackUrl = getApiEndpoint({
+        provider: "fireworks",
+        model: FIREWORKS_KIMI_CURRENT_MODEL,
+    } as any);
+    const buildProviderCompatibleBody = (
+        sourceBody: Record<string, any>,
+        providerName: string,
+        modelName: string,
+    ) =>
+        normalizeChatCompletionsBodyForProvider({
+            body: sourceBody,
+            provider: providerName,
+            model: modelName,
+        });
+    const googleFallbackRequest =
+        shouldUseGoogleOpenRouterFallback && openRouterApiKey
+            ? {
+                url: OPENROUTER_CHAT_COMPLETIONS_URL,
+                provider: "openrouter",
+                model: toOpenRouterGoogleModelName(agentConfig.model),
+                init: {
+                    method: "POST",
+                    headers: buildUpstreamHeaders(
+                        OPENROUTER_CHAT_COMPLETIONS_URL,
+                        openRouterApiKey,
+                    ),
+                    body: JSON.stringify(
+                        buildProviderCompatibleBody(
+                            body,
+                            "openrouter",
+                            toOpenRouterGoogleModelName(agentConfig.model),
+                        ),
+                    ),
+                    signal: init.signal,
+                } satisfies RequestInit,
+            }
+            : undefined;
+    const kimiPlatformFallbackRequests = shouldUseKimiPlatformFallback
+        ? [
+            fireworksKimiFallbackApiKey
+                ? {
+                    url: fireworksKimiFallbackUrl,
+                    provider: "fireworks",
+                    model: FIREWORKS_KIMI_CURRENT_MODEL,
+                    init: {
+                        method: "POST",
+                        headers: buildUpstreamHeaders(
+                            fireworksKimiFallbackUrl,
+                            fireworksKimiFallbackApiKey,
+                        ),
+                        body: JSON.stringify(
+                            buildProviderCompatibleBody(
+                                body,
+                                "fireworks",
+                                FIREWORKS_KIMI_CURRENT_MODEL,
+                            ),
+                        ),
+                        signal: init.signal,
+                    } satisfies RequestInit,
+                }
+                : undefined,
+            deepInfraKimiFallbackApiKey
+                ? {
+                    url: deepInfraKimiFallbackUrl,
+                    provider: "deepinfra",
+                    model: DEEPINFRA_KIMI_FALLBACK_MODEL,
+                    init: {
+                        method: "POST",
+                        headers: buildUpstreamHeaders(
+                            deepInfraKimiFallbackUrl,
+                            deepInfraKimiFallbackApiKey,
+                        ),
+                        body: JSON.stringify(
+                            buildProviderCompatibleBody(
+                                body,
+                                "deepinfra",
+                                DEEPINFRA_KIMI_FALLBACK_MODEL,
+                            ),
+                        ),
+                        signal: init.signal,
+                    } satisfies RequestInit,
+                }
+                : undefined,
+            openRouterKimiFallbackApiKey
+                ? {
+                    url: OPENROUTER_CHAT_COMPLETIONS_URL,
+                    provider: "openrouter",
+                    model: OPENROUTER_KIMI_FALLBACK_MODEL,
+                    init: {
+                        method: "POST",
+                        headers: buildUpstreamHeaders(
+                            OPENROUTER_CHAT_COMPLETIONS_URL,
+                            openRouterKimiFallbackApiKey,
+                        ),
+                        body: JSON.stringify(
+                            buildProviderCompatibleBody(
+                                body,
+                                "openrouter",
+                                OPENROUTER_KIMI_FALLBACK_MODEL,
+                            ),
+                        ),
+                        signal: init.signal,
+                    } satisfies RequestInit,
+                }
+                : undefined,
+        ].filter((request): request is NonNullable<typeof request> => !!request)
+        : [];
+    const configuredFallbackRequest =
+        shouldUseConfiguredFallback && configuredFallbackApiKey
+            ? {
+                url: OPENROUTER_CHAT_COMPLETIONS_URL,
+                provider: "openrouter",
+                model: agentConfig.fallbackModel,
+                init: {
+                    method: "POST",
+                    headers: buildUpstreamHeaders(
+                        OPENROUTER_CHAT_COMPLETIONS_URL,
+                        configuredFallbackApiKey,
+                    ),
+                    body: JSON.stringify(
+                        buildProviderCompatibleBody(
+                            body,
+                            "openrouter",
+                            agentConfig.fallbackModel,
+                        ),
+                    ),
+                    signal: init.signal,
+                } satisfies RequestInit,
+            }
+            : undefined;
+
+    if (
+        String(agentConfig?.provider || "").toLowerCase() === "google" &&
+        isGoogleNativeImageModel(agentConfig?.model)
+    ) {
+        try {
+            if (body.stream) {
+                return {
+                    response: await fetchGoogleNativeImageChat({
+                    model: agentConfig.model,
+                    body,
+                    apiKey,
+                    signal: init.signal,
+                    streamHeaders: {
+                        "Content-Type": "text/event-stream",
+                    },
+                    }),
+                    provider: agentConfig.provider,
+                    model: agentConfig.model,
+                    inputPrice: agentConfig.inputPrice,
+                    outputPrice: agentConfig.outputPrice,
+                };
+            }
+
+            return {
+                response: await fetchGoogleNativeImageCompletion({
+                    model: agentConfig.model,
+                    body,
+                    apiKey,
+                    signal: init.signal,
+                }),
+                provider: agentConfig.provider,
+                model: agentConfig.model,
+                inputPrice: agentConfig.inputPrice,
+                outputPrice: agentConfig.outputPrice,
+            };
+        } catch (error: any) {
+            const shouldFallbackToOpenRouter =
+                !!googleFallbackRequest &&
+                (!("status" in (error ?? {})) ||
+                    GOOGLE_FALLBACK_STATUSES.includes(Number(error?.status)));
+            if (!shouldFallbackToOpenRouter) {
+                throw error;
+            }
+        }
+    }
+
+    try {
+        const requestArgs = googleFallbackRequest
+            ? {
+                url: endpoint,
+                init,
+                provider: agentConfig.provider,
+                model: agentConfig.model,
+                log: console,
+                fallbackRequest: googleFallbackRequest,
+                fallbackOnStatuses:
+                    String(agentConfig?.provider || "").toLowerCase() === "google"
+                        ? GOOGLE_FALLBACK_STATUSES
+                        : undefined,
+            }
+            : kimiPlatformFallbackRequests.length > 0
+                ? {
+                    url: endpoint,
+                    init,
+                    provider: agentConfig.provider,
+                    model: agentConfig.model,
+                    log: console,
+                    fallbackRequests: kimiPlatformFallbackRequests,
+                    fallbackOnStatuses: KIMI_PLATFORM_FALLBACK_STATUSES,
+                }
+            : configuredFallbackRequest
+                ? {
+                    url: endpoint,
+                    init,
+                    provider: agentConfig.provider,
+                    model: agentConfig.model,
+                    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,
+        });
+        const actualProvider = upstreamResponse.provider;
+        const actualModel = upstreamResponse.model;
+        const actualModelConfig =
+            actualProvider && actualModel
+                ? findModelConfig(String(actualProvider), String(actualModel))
+                : null;
+        return {
+            response: upstreamResponse.response,
+            provider: actualProvider,
+            model: actualModel,
+            inputPrice: actualModelConfig?.price.input ?? agentConfig.inputPrice,
+            outputPrice: actualModelConfig?.price.output ?? agentConfig.outputPrice,
+        };
+    } catch (error: any) {
+        if (error?.name === "TimeoutError" || error?.name === "AbortError") {
+            throw new Error(`LLM API timeout after ${llmRequestTimeoutMs}ms: ${endpoint}`);
+        }
+        throw error;
+    }
+}
+
+function extractAssistantText(message: ChatMessage | null | undefined): string {
+    if (!message) return "";
+    return typeof message.content === "string"
+        ? message.content
+        : (message.content as any[] | null)
+            ?.filter((p: any) => p.type === "text")
+            .map((p: any) => p.text ?? "")
+            .join("") ?? "";
+}
+
+const FINAL_PARALLEL_SUMMARY_REPAIR_PROMPT =
+    "你刚刚没有给出最终文本回答。请基于上面的并行分支内容，直接输出最终结论，不要再调用任何工具，也不要留空。至少明确给出：共识、保留分歧、下一步。";
+
+const EMPTY_ASSISTANT_REPAIR_PROMPT =
+    "你刚刚返回了空消息。请继续完成当前任务：如果需要工具就调用工具，否则直接输出可执行的简短结果；不要留空。";
+
+function hasParallelBranchMessages(messages: ChatMessage[]): boolean {
+    return messages.some(
+        (message) =>
+            message.role === "assistant" &&
+            typeof message.parallelSessionId === "string" &&
+            !!message.parallelSessionId.trim(),
+    );
+}
+
+function extractMessageText(message: ChatMessage | null | undefined): string {
+    if (!message) return "";
+    return typeof message.content === "string"
+        ? message.content
+        : (message.content as any[] | null)
+            ?.filter((part: any) => part?.type === "text")
+            .map((part: any) => part.text ?? "")
+            .join("") ?? "";
+}
+
+function buildCliTaskPrompt(
+    initialMessages: ChatMessage[],
+    userInput?: string | null,
+): string {
+    // CLI agent 只接文本上下文，不把本地 tool 轨迹伪装成可重放的远端工具调用。
+    const history = initialMessages
+        .filter((message) => message.role === "user" || message.role === "assistant")
+        .map((message) => {
+            const text = extractMessageText(message).trim();
+            if (!text) return null;
+            const roleLabel =
+                message.role === "user"
+                    ? "用户"
+                    : "助手";
+            return `[${roleLabel}]\n${text}`;
+        })
+        .filter((message): message is string => !!message)
+        .slice(-6);
+
+    const explicitUserInput = userInput?.trim() ?? "";
+    if (explicitUserInput) {
+        const explicitUserEntry = `[用户]\n${explicitUserInput}`;
+        if (history.at(-1) !== explicitUserEntry) {
+            history.push(explicitUserEntry);
+        }
+    }
+
+    if (history.length === 0) return explicitUserInput;
+    if (history.length === 1 && history[0].startsWith("[用户]\n")) {
+        return history[0].slice("[用户]\n".length);
+    }
+
+    return `请基于以下最近对话继续完成当前任务。\n\n${history.join("\n\n")}`;
+}
+
+function appendTextPart(
+    content: NonNullable<Exclude<ChatMessage["content"], string>>,
+    text: string,
+) {
+    if (!text) return;
+    const lastPart = content.at(-1);
+    if (lastPart?.type === "text") {
+        lastPart.text += text;
+        return;
+    }
+    content.push({ type: "text", text });
+}
+
+function finalizeAssistantContent(
+    content: NonNullable<Exclude<ChatMessage["content"], string>>,
+): ChatMessage["content"] {
+    if (content.length === 0) return null;
+    if (content.every((part) => part.type === "text")) {
+        return content.map((part) => part.text).join("");
+    }
+    return content;
+}
+
+function parseToolResult(content: string | null | undefined): any {
+    if (typeof content !== "string" || !content.trim()) return null;
+    try {
+        return JSON.parse(content);
+    } catch {
+        return null;
+    }
+}
+
+function pickString(value: unknown): string | null {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function getToolError(parsed: any): string | null {
+    if (!parsed || typeof parsed !== "object") return null;
+    const error = pickString(parsed.error);
+    if (error) return error;
+    if (parsed.ok === false) return "tool returned ok=false";
+    if (parsed.success === false) return "tool returned success=false";
+    return null;
+}
+
+const TASK_RUN_DIRECT_TOOL_NAMES = new Set([
+    "taskRun",
+    "readTaskContext",
+    "queryReadyWorkItems",
+    "upsertWorkItem",
+    "claimWorkItem",
+    "openDialog",
+    "recordArtifact",
+    "setBlocker",
+    "clearBlocker",
+    "requestReview",
+    "recordReview",
+    "submitOutcome",
+    "closeWorkItem",
+]);
+
+function normalizeDirectCompletionToolName(toolName: string | undefined): string {
+    return canonicalizeToolName((toolName ?? "").replace(/^functions\./, "").trim());
+}
+
+function buildStartAgentDialogDirectCompletion(parsed: any): string | null {
+    if (!parsed || typeof parsed !== "object") return null;
+    const error = getToolError(parsed);
+    if (error) {
+        const detail = pickString(parsed.detail);
+        return [
+            "startAgentDialog failed.",
+            `error: ${error}`,
+            detail ? `detail: ${detail}` : "",
+        ].filter(Boolean).join("\n");
+    }
+
+    if (parsed.success !== true) return null;
+    const childDialogId = pickString(parsed.childDialogId);
+    if (!childDialogId) {
+        return [
+            "startAgentDialog returned success=true but did not return childDialogId.",
+            "Treat this handoff as unverified; do not claim the child agent started or completed.",
+        ].join("\n");
+    }
+
+    const lines = [
+        "startAgentDialog accepted the handoff. This means the child dialog was started or queued, not completed.",
+        `childDialogId: ${childDialogId}`,
+        pickString(parsed.status) ? `status: ${pickString(parsed.status)}` : "",
+        pickString(parsed.targetAgentKey) ? `targetAgentKey: ${pickString(parsed.targetAgentKey)}` : "",
+        pickString(parsed.parentDialogId) ? `parentDialogId: ${pickString(parsed.parentDialogId)}` : "",
+    ].filter(Boolean);
+
+    return lines.join("\n");
+}
+
+function buildTaskRunDirectCompletion(parsed: any): string | null {
+    if (!parsed || typeof parsed !== "object") return null;
+    const error = getToolError(parsed);
+    if (error) {
+        return [
+            "taskRun failed.",
+            `error: ${error}`,
+            "No task status or outcome was written by this tool call.",
+        ].join("\n");
+    }
+
+    return null;
+}
+
+function buildUpdateTableRowDirectCompletion(parsed: any): string | null {
+    if (!parsed || typeof parsed !== "object") return null;
+    const error = getToolError(parsed);
+    if (error) {
+        return [
+            "updateTableRow failed.",
+            `error: ${error}`,
+            "No table row update was confirmed by this tool call.",
+        ].join("\n");
+    }
+
+    return null;
+}
+
+function buildDirectCompletionFromToolResult(toolName: string | undefined, content: string): string | null {
+    const normalizedToolName = normalizeDirectCompletionToolName(toolName);
+    const parsed = parseToolResult(content);
+    if (!parsed || typeof parsed !== "object") return null;
+
+    if (normalizedToolName === "startAgentDialog") {
+        return buildStartAgentDialogDirectCompletion(parsed);
+    }
+    if (TASK_RUN_DIRECT_TOOL_NAMES.has(normalizedToolName)) {
+        return buildTaskRunDirectCompletion(parsed);
+    }
+    if (normalizedToolName === "updateTableRow") {
+        return buildUpdateTableRowDirectCompletion(parsed);
+    }
+
+    if (normalizedToolName !== "remotionRenderVideo") return null;
+    if (parsed.ok === false || parsed.error) return null;
+    if (typeof parsed.fileId !== "string" || !parsed.fileId.trim()) return null;
+
+    const lines = [
+        parsed.text || "Remotion 视频已生成。",
+        `fileId: ${parsed.fileId.trim()}`,
+        typeof parsed.fileDbKey === "string" && parsed.fileDbKey.trim()
+            ? `fileDbKey: ${parsed.fileDbKey.trim()}`
+            : "",
+        typeof parsed.url === "string" && parsed.url.trim()
+            ? `url: ${parsed.url.trim()}`
+            : "",
+        typeof parsed.template === "string" && parsed.template.trim()
+            ? `template: ${parsed.template.trim()}`
+            : "",
+    ].filter(Boolean);
+
+    return lines.join("\n");
+}
+
+function appendParallelBranchMessages(messages: ChatMessage[], parsed: any) {
+    if (!Array.isArray(parsed?.results)) return;
+    for (const [index, item] of parsed.results.entries()) {
+        if (!item?.ok || typeof item?.content !== "string" || !item.content.trim()) {
+            continue;
+        }
+        messages.push({
+            role: "assistant",
+            content: item.content,
+            cybotKey: item.agentKey,
+            agentKey: item.agentKey,
+            agentName:
+                typeof item.agentName === "string" && item.agentName.trim()
+                    ? item.agentName.trim()
+                    : typeof item.label === "string" && item.label.trim()
+                        ? item.label.trim()
+                        : undefined,
+            parallelSessionId:
+                typeof parsed.parallelSessionId === "string"
+                    ? parsed.parallelSessionId
+                    : undefined,
+            parallelBranchId:
+                typeof item.branchId === "string" ? item.branchId : undefined,
+            parallelLabel:
+                typeof item.label === "string" ? item.label : undefined,
+            parallelIndex:
+                typeof item.parallelIndex === "number" ? item.parallelIndex : index,
+        });
+    }
+}
+
+function normalizeLoopMessageContent(
+    content: ChatMessage["content"] | Record<string, unknown> | undefined,
+): ChatMessage["content"] {
+    if (typeof content === "string" || Array.isArray(content) || content === null) {
+        return content;
+    }
+    if (content == null) return null;
+    return JSON.stringify(content);
+}
+
+const MAX_EXEC_SHELL_COMMAND_CHARS = 500;
+const MAX_EXEC_SHELL_STDOUT_CHARS = 4000;
+const MAX_EXEC_SHELL_STDERR_CHARS = 2000;
+const MAX_READ_FILE_CONTENT_CHARS = 6000;
+const MAX_READ_DOC_CONTENT_CHARS = 6000;
+const MAX_FETCH_WEBPAGE_CONTENT_CHARS = 6000;
+const MAX_SEARCH_RESULT_ITEMS = 8;
+const MAX_SEARCH_PATH_CHARS = 240;
+const MAX_SEARCH_PREVIEW_CHARS = 220;
+const MAX_IMAGE_TOOL_TEXT_CHARS = 1200;
+
+function compactTextForUpstream(value: string, maxChars: number): string {
+    if (value.length <= maxChars) return value;
+    const hiddenChars = value.length - maxChars;
+    return `${value.slice(0, maxChars)}\n...[truncated ${hiddenChars} chars]`;
+}
+
+function compactSearchPathForUpstream(value: unknown): string | undefined {
+    if (typeof value !== "string" || !value) return undefined;
+    return compactTextForUpstream(value, MAX_SEARCH_PATH_CHARS);
+}
+
+function compactCodeSearchHitsForUpstream(hits: unknown): Array<Record<string, unknown>> | undefined {
+    if (!Array.isArray(hits) || hits.length === 0) return undefined;
+    return hits.slice(0, MAX_SEARCH_RESULT_ITEMS).flatMap((entry) => {
+        if (!entry || typeof entry !== "object") return [];
+        const item: Record<string, unknown> = {};
+        const path = compactSearchPathForUpstream((entry as any).path);
+        if (path) item.path = path;
+        if (typeof (entry as any).line === "number") item.line = (entry as any).line;
+        if (typeof (entry as any).preview === "string" && (entry as any).preview) {
+            item.preview = compactTextForUpstream(
+                (entry as any).preview,
+                MAX_SEARCH_PREVIEW_CHARS,
+            );
+        }
+        return Object.keys(item).length > 0 ? [item] : [];
+    });
+}
+
+function compactCodeSearchFilesForUpstream(files: unknown): Array<Record<string, unknown>> | undefined {
+    if (!Array.isArray(files) || files.length === 0) return undefined;
+    return files.slice(0, MAX_SEARCH_RESULT_ITEMS).flatMap((entry) => {
+        if (!entry || typeof entry !== "object") return [];
+        const path = compactSearchPathForUpstream((entry as any).path);
+        return path ? [{ path }] : [];
+    });
+}
+
+function compactToolContentForUpstream(
+    toolName: string | undefined,
+    content: ChatMessage["content"],
+): ChatMessage["content"] {
+    if (typeof content !== "string") {
+        return normalizeLoopMessageContent(content);
+    }
+    const normalizedToolName = canonicalizeToolName(toolName ?? "");
+    const parsed = parseToolResult(content);
+    if (!parsed || typeof parsed !== "object") {
+        return content;
+    }
+
+    if (normalizedToolName === "execShell") {
+        return JSON.stringify({
+            ...(typeof parsed.ok === "boolean" ? { ok: parsed.ok } : {}),
+            ...(typeof parsed.command === "string"
+                ? {
+                    command: compactTextForUpstream(
+                        parsed.command,
+                        MAX_EXEC_SHELL_COMMAND_CHARS,
+                    ),
+                }
+                : {}),
+            ...(typeof parsed.exitCode === "number" ? { exitCode: parsed.exitCode } : {}),
+            ...(typeof parsed.stdout === "string" && parsed.stdout
+                ? {
+                    stdout: compactTextForUpstream(
+                        parsed.stdout,
+                        MAX_EXEC_SHELL_STDOUT_CHARS,
+                    ),
+                }
+                : {}),
+            ...(typeof parsed.stderr === "string" && parsed.stderr
+                ? {
+                    stderr: compactTextForUpstream(
+                        parsed.stderr,
+                        MAX_EXEC_SHELL_STDERR_CHARS,
+                    ),
+                }
+                : {}),
+            ...(typeof parsed.error === "string" && parsed.error
+                ? { error: compactTextForUpstream(parsed.error, MAX_EXEC_SHELL_STDERR_CHARS) }
+                : {}),
+        });
+    }
+
+    if (normalizedToolName === "readFile") {
+        return JSON.stringify({
+            ...(typeof parsed.ok === "boolean" ? { ok: parsed.ok } : {}),
+            ...(typeof parsed.filePath === "string" ? { filePath: parsed.filePath } : {}),
+            ...(typeof parsed.lineCount === "number" ? { lineCount: parsed.lineCount } : {}),
+            ...(typeof parsed.totalLineCount === "number"
+                ? { totalLineCount: parsed.totalLineCount }
+                : {}),
+            ...(typeof parsed.lineOffset === "number" ? { lineOffset: parsed.lineOffset } : {}),
+            ...(typeof parsed.rangeStart === "number" ? { rangeStart: parsed.rangeStart } : {}),
+            ...(typeof parsed.rangeEnd === "number" ? { rangeEnd: parsed.rangeEnd } : {}),
+            ...(typeof parsed.adjustedEndLine === "number"
+                ? { adjustedEndLine: parsed.adjustedEndLine }
+                : {}),
+            ...(parsed.nextSymbol && typeof parsed.nextSymbol === "object"
+                ? { nextSymbol: parsed.nextSymbol }
+                : {}),
+            ...(typeof parsed.content === "string"
+                ? {
+                    content: compactTextForUpstream(
+                        parsed.content,
+                        MAX_READ_FILE_CONTENT_CHARS,
+                    ),
+                }
+                : {}),
+            ...(typeof parsed.error === "string" && parsed.error
+                ? { error: compactTextForUpstream(parsed.error, MAX_EXEC_SHELL_STDERR_CHARS) }
+                : {}),
+        });
+    }
+
+    if (normalizedToolName === "readDoc" || normalizedToolName === "readPage") {
+        return JSON.stringify({
+            ...(typeof parsed.success === "boolean" ? { success: parsed.success } : {}),
+            ...(typeof parsed.id === "string" ? { id: parsed.id } : {}),
+            ...(typeof parsed.title === "string" ? { title: parsed.title } : {}),
+            ...(typeof parsed.content === "string"
+                ? {
+                    content: compactTextForUpstream(
+                        parsed.content,
+                        MAX_READ_DOC_CONTENT_CHARS,
+                    ),
+                }
+                : {}),
+            ...(parsed.metadata && typeof parsed.metadata === "object"
+                ? { metadata: parsed.metadata }
+                : {}),
+            ...(typeof parsed.error === "string" && parsed.error
+                ? { error: compactTextForUpstream(parsed.error, MAX_EXEC_SHELL_STDERR_CHARS) }
+                : {}),
+        });
+    }
+
+    if (normalizedToolName === "fetchWebpage") {
+        return JSON.stringify({
+            ...(typeof parsed.preview === "string"
+                ? {
+                    preview: compactTextForUpstream(
+                        parsed.preview,
+                        MAX_SEARCH_PREVIEW_CHARS,
+                    ),
+                }
+                : {}),
+            ...(typeof parsed.fullContent === "string"
+                ? {
+                    fullContent: compactTextForUpstream(
+                        parsed.fullContent,
+                        MAX_FETCH_WEBPAGE_CONTENT_CHARS,
+                    ),
+                }
+                : {}),
+            ...(typeof parsed.rawData === "string"
+                ? {
+                    rawData: compactTextForUpstream(
+                        parsed.rawData,
+                        MAX_FETCH_WEBPAGE_CONTENT_CHARS,
+                    ),
+                }
+                : {}),
+            ...(typeof parsed.displayData === "string"
+                ? {
+                    displayData: compactTextForUpstream(
+                        parsed.displayData,
+                        MAX_FETCH_WEBPAGE_CONTENT_CHARS,
+                    ),
+                }
+                : {}),
+            ...(typeof parsed.contentType === "string" ? { contentType: parsed.contentType } : {}),
+            ...(typeof parsed.markdownTokens === "string" || typeof parsed.markdownTokens === "number"
+                ? { markdownTokens: parsed.markdownTokens }
+                : {}),
+            ...(typeof parsed.error === "string" && parsed.error
+                ? { error: compactTextForUpstream(parsed.error, MAX_EXEC_SHELL_STDERR_CHARS) }
+                : {}),
+        });
+    }
+
+    if (normalizedToolName === "openAIGptImage") {
+        const files = Array.isArray(parsed.files)
+            ? parsed.files.flatMap((entry) => {
+                if (!entry || typeof entry !== "object") return [];
+                return [{
+                    ...(
+                        typeof (entry as any).fileId === "string"
+                            ? { fileId: (entry as any).fileId }
+                            : {}
+                    ),
+                    ...(
+                        (entry as any).metadata && typeof (entry as any).metadata === "object"
+                            ? { metadata: (entry as any).metadata }
+                            : {}
+                    ),
+                }];
+            })
+            : undefined;
+
+        return JSON.stringify({
+            ...(typeof parsed.text === "string"
+                ? { text: compactTextForUpstream(parsed.text, MAX_IMAGE_TOOL_TEXT_CHARS) }
+                : {}),
+            ...(typeof parsed.imageCount === "number" ? { imageCount: parsed.imageCount } : {}),
+            ...(Array.isArray(parsed.revisedPrompts)
+                ? {
+                    revisedPrompts: parsed.revisedPrompts
+                        .filter((item: unknown): item is string => typeof item === "string" && !!item)
+                        .map((item: string) => compactTextForUpstream(item, MAX_IMAGE_TOOL_TEXT_CHARS)),
+                }
+                : {}),
+            ...(files ? { files } : {}),
+            ...(typeof parsed.error === "string" && parsed.error
+                ? { error: compactTextForUpstream(parsed.error, MAX_EXEC_SHELL_STDERR_CHARS) }
+                : {}),
+        });
+    }
+
+    if (normalizedToolName === "codeSearch") {
+        return JSON.stringify({
+            ...(typeof parsed.ok === "boolean" ? { ok: parsed.ok } : {}),
+            ...(typeof parsed.mode === "string" ? { mode: parsed.mode } : {}),
+            ...(typeof parsed.query === "string" ? { query: parsed.query } : {}),
+            ...(typeof parsed.path === "string" ? { path: parsed.path } : {}),
+            ...(typeof parsed.glob === "string" || parsed.glob === null
+                ? { glob: parsed.glob }
+                : {}),
+            ...(typeof parsed.truncated === "boolean" ? { truncated: parsed.truncated } : {}),
+            ...(typeof parsed.totalHits === "number" ? { totalHits: parsed.totalHits } : {}),
+            ...(typeof parsed.totalFiles === "number" ? { totalFiles: parsed.totalFiles } : {}),
+            ...(compactCodeSearchHitsForUpstream(parsed.hits)
+                ? { hits: compactCodeSearchHitsForUpstream(parsed.hits) }
+                : {}),
+            ...(compactCodeSearchFilesForUpstream(parsed.files)
+                ? { files: compactCodeSearchFilesForUpstream(parsed.files) }
+                : {}),
+            ...(typeof parsed.error === "string" && parsed.error
+                ? { error: compactTextForUpstream(parsed.error, MAX_EXEC_SHELL_STDERR_CHARS) }
+                : {}),
+        });
+    }
+
+    return content;
+}
+
+function shouldCompactImmediateToolReplay(toolName: string | undefined): boolean {
+    const normalizedToolName = canonicalizeToolName(toolName ?? "");
+    return (
+        normalizedToolName === "execShell" ||
+        normalizedToolName === "openAIGptImage"
+    );
+}
+
+function sanitizeLoopMessageForUpstream(message: ChatMessage): ChatMessage {
+    const sanitized: ChatMessage = {
+        role: message.role,
+        content: normalizeLoopMessageContent(message.content),
+    };
+
+    if (
+        message.role === "assistant" &&
+        typeof message.reasoning_content === "string" &&
+        message.reasoning_content
+    ) {
+        sanitized.reasoning_content = message.reasoning_content;
+    }
+
+    if (
+        message.role === "assistant" &&
+        Array.isArray(message.tool_calls) &&
+        message.tool_calls.length > 0
+    ) {
+        sanitized.tool_calls = message.tool_calls;
+    }
+
+    if (
+        message.role === "tool" &&
+        typeof message.tool_call_id === "string" &&
+        message.tool_call_id.trim()
+    ) {
+        sanitized.tool_call_id = message.tool_call_id.trim();
+    }
+
+    return sanitized;
+}
+
+function sanitizeLoopMessagesForUpstream(messages: ChatMessage[]): ChatMessage[] {
+    const toolNameByCallId = new Map<string, string>();
+    let firstTrailingToolIndex = messages.length;
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        if (messages[index]?.role !== "tool") {
+            break;
+        }
+        firstTrailingToolIndex = index;
+    }
+    return messages.map((message, index) => {
+        const sanitized = sanitizeLoopMessageForUpstream(message);
+
+        if (
+            message.role === "assistant" &&
+            Array.isArray(message.tool_calls) &&
+            message.tool_calls.length > 0
+        ) {
+            for (const toolCall of message.tool_calls) {
+                if (
+                    typeof toolCall?.id === "string" &&
+                    toolCall.id.trim() &&
+                    typeof toolCall?.function?.name === "string"
+                ) {
+                    toolNameByCallId.set(toolCall.id.trim(), toolCall.function.name);
+                }
+            }
+            sanitized.content = null;
+            return sanitized;
+        }
+
+        if (
+            message.role === "tool" &&
+            typeof sanitized.tool_call_id === "string" &&
+            sanitized.tool_call_id
+        ) {
+            const toolName = toolNameByCallId.get(sanitized.tool_call_id);
+            const shouldCompactImmediately = shouldCompactImmediateToolReplay(toolName);
+            const isTrailingToolMessage = index >= firstTrailingToolIndex;
+            sanitized.content =
+                isTrailingToolMessage && !shouldCompactImmediately
+                    ? normalizeLoopMessageContent(message.content)
+                    : compactToolContentForUpstream(toolName, sanitized.content);
+        }
+
+        return sanitized;
+    });
+}
+
+function collectLatestImageUrls(messages: ChatMessage[]): string[] {
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const content = messages[index]?.content;
+        if (!Array.isArray(content)) continue;
+
+        const urls = content
+            .map((part) =>
+                part?.type === "image_url" && typeof part.image_url?.url === "string"
+                    ? part.image_url.url.trim()
+                    : ""
+            )
+            .filter((url): url is string => !!url);
+
+        if (urls.length > 0) {
+            return [...new Set(urls)];
+        }
+    }
+
+    return [];
+}
+
+function getApiKey(agentConfig: any): string | undefined {
+    // apiSource="custom" 的 agent 使用自己的 apiKey，不走平台 key。
+    // 使用自己的 apiKey，不走平台 key，不要修改这个逻辑
+    const key = agentConfig.apiKey?.trim() || getNoloKey(agentConfig.provider);
+    // 自定义 provider URL 场景（如本地 Ollama）不强制要求 key
+    const hasCustomUrl = !!(agentConfig.customProviderUrl?.trim());
+    if (!key && !hasCustomUrl) {
+        throw new Error(`No API key configured for provider "${agentConfig.provider}".`);
+    }
+    return key || undefined;
+}
+
+function buildTools(agentConfig: any): any[] | undefined {
+    if (!agentConfig.tools?.length) return undefined;
+    const tools = prepareTools(agentConfig.tools, {
+        provider: agentConfig.provider,
+        disabledToolNames: process.env.EXA_API_KEY ? [] : ["exa_search"],
+    });
+    return tools.length > 0 ? tools : undefined;
+}
+
+function getPreparedToolNames(tools: any[] | undefined): string[] {
+    if (!tools?.length) return [];
+    return tools
+        .map((tool) => tool?.function?.name ?? tool?.name)
+        .filter((name): name is string => typeof name === "string" && !!name.trim());
+}
+
+function extractMessageContentText(content: ChatMessage["content"] | undefined | null): string {
+    if (typeof content === "string") return content;
+    if (!Array.isArray(content)) return "";
+    return content
+        .filter((part: any) => part?.type === "text" && typeof part.text === "string")
+        .map((part: any) => part.text)
+        .join("\n");
+}
+
+function extractUserInputText(
+    userInput: string | null | undefined,
+    messages: ChatMessage[],
+): string {
+    if (typeof userInput === "string" && userInput.trim()) return userInput;
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (message?.role !== "user") continue;
+        const text = extractMessageContentText(message.content);
+        if (text.trim()) return text;
+    }
+    return "";
+}
+
+function shouldRunWereadGatewayPreflight(
+    agentConfig: any,
+    tools: any[] | undefined,
+    userInput: string | null | undefined,
+    messages: ChatMessage[],
+): boolean {
+    const hasWereadTool =
+        Array.isArray(agentConfig?.tools) &&
+        agentConfig.tools.some((toolName: unknown) => canonicalizeToolName(String(toolName)) === "wereadGateway") &&
+        getPreparedToolNames(tools).some((toolName) => canonicalizeToolName(toolName) === "wereadGateway");
+    if (!hasWereadTool) return false;
+
+    const text = extractUserInputText(userInput, messages).trim();
+    if (!text) return false;
+    return /微信读书|weread|WEREAD|书架|阅读|读书|笔记|划线|想法|书评|报告|统计|进度|搜索|推荐|key|Key|KEY|密钥|授权|连接|连通|链接|配置|保存|添加|测试|检查|验证/.test(text);
+}
+
+async function runWereadGatewayPreflightIfNeeded(args: {
+    agentConfig: any;
+    tools: any[] | undefined;
+    messages: ChatMessage[];
+    serverBase: string;
+    authToken: string;
+    runtimePolicy?: ResolvedRuntimePolicy;
+    runtimeState: ToolPolicyRuntimeState;
+    userId?: string | null;
+    dialogId?: string | null;
+    currentSpaceId?: string | null;
+    userInput?: string | null;
+    runtimeContext?: AgentRunRuntimeContext | null;
+    send?: Send;
+}): Promise<{ ran: boolean; elapsedMs: number; completedAt?: number }> {
+    if (
+        !shouldRunWereadGatewayPreflight(
+            args.agentConfig,
+            args.tools,
+            args.userInput,
+            args.messages,
+        )
+    ) {
+        return { ran: false, elapsedMs: 0 };
+    }
+
+    const toolCall: AssistantToolCall = {
+        id: `call_weread_preflight_${Date.now()}`,
+        type: "function",
+        function: {
+            name: "wereadGateway",
+            arguments: JSON.stringify({ api_name: "/shelf/sync", params: {} }),
+        },
+    };
+    args.messages.push({
+        role: "assistant",
+        content: null,
+        tool_calls: [toolCall],
+    });
+    args.send?.({
+        type: "assistant_tool_calls",
+        content: null,
+        tool_calls: [toolCall],
+    });
+    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 completedAt = Date.now();
+    args.messages.push({
+        role: "tool",
+        tool_call_id: toolCall.id,
+        content: toolResult,
+    });
+    args.messages.push({
+        role: "system",
+        content:
+            "上面的 wereadGateway 是本轮服务端预检得到的真实结果。请基于该结果回答用户；不要声称 wereadGateway 未挂载、不可用或无法调用。若结果包含 MISSING_WEREAD_API_KEY 或缺少 WEREAD_API_KEY，请提示用户去密钥管理保存 WEREAD_API_KEY。",
+    });
+    args.send?.({
+        type: "tool_result",
+        toolCallId: toolCall.id,
+        toolName: "wereadGateway",
+        content: toolResult,
+    });
+    args.send?.({ type: "tool_end" });
+
+    return {
+        ran: true,
+        elapsedMs: Math.max(0, completedAt - startedAt),
+        completedAt,
+    };
+}
+
+function buildLoopRequestBody(
+    agentConfig: any,
+    messages: ChatMessage[],
+    tools: any[] | undefined,
+    stream: boolean,
+): Record<string, any> {
+    const upstreamMessages = sanitizeLoopMessagesForUpstream(messages);
+    // Keep agent-run aligned with the foreground chat path so image-output agents
+    // inherit the same modalities/image_config contract instead of silently
+    // degrading to plain text.
+    const body: Record<string, any> = generateRequestBody({
+        agentConfig,
+        messages: upstreamMessages as any,
+        prependSystemPrompt: !agentConfig?.runtimePromptAlreadyInMessages,
+    });
+    applyLoopStreamMode(body, stream);
+    if (isResponseAPIModel(agentConfig)) {
+        const responseTools = [
+            ...(toResponsesTools(tools) ?? []),
+            ...(
+                String(agentConfig?.provider || "").toLowerCase() === "openai" &&
+                !getModelInfo(String(agentConfig?.model || ""))?.hasImageOutput &&
+                !!agentConfig?.imageConfig?.enabled
+                    ? [{ type: "image_generation" as const }]
+                    : []
+            ),
+        ];
+        if (responseTools.length) {
+            body.tools = responseTools;
+            body.tool_choice = "auto";
+        }
+        return body;
+    }
+    if (tools) {
+        body.tools = tools;
+        body.tool_choice = "auto";
+    }
+    if (agentConfig.enableThinking) {
+        const provider = (agentConfig.provider || "").toLowerCase();
+        if (provider === "anthropic") {
+            body.thinking = { type: "enabled", budget_tokens: agentConfig.thinkingBudget ?? 8000 };
+        }
+    } else if (
+        /xiaomimimo\.com/i.test(agentConfig.customProviderUrl ?? "") ||
+        String(agentConfig?.provider || "").toLowerCase() === "mimo"
+    ) {
+        body.thinking = { type: "disabled" };
+    }
+    return body;
+}
+
+export function applyLoopStreamMode(body: Record<string, any>, stream: boolean) {
+    body.stream = stream;
+    if (!stream) {
+        delete body.stream_options;
+    }
+    return body;
+}
+
+function buildAssistantMessageFromResponse(data: any): ChatMessage | null {
+    const toolCalls = extractToolCallsFromResponseOutput(data);
+    const contentText = extractTextFromResponseOutput(data);
+    const contentImages = extractImagePartsFromResponseOutput(data);
+    const content =
+        contentImages.length > 0
+            ? [
+                ...(contentText ? [{ type: "text", text: contentText }] : []),
+                ...contentImages,
+            ]
+            : contentText;
+    if (!content && toolCalls.length === 0) return null;
+
+    return {
+        role: "assistant",
+        content: content || null,
+        ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
+    };
+}
+
+function extractTextFromResponseOutputItem(item: any): string {
+    if (item?.type !== "message" || !Array.isArray(item.content)) return "";
+    return item.content
+        .filter((content: any) => content?.type === "output_text" && typeof content.text === "string")
+        .map((content: any) => content.text)
+        .join("");
+}
+
+function buildLatencyProfile(args: {
+    startedAt: number;
+    llmRequestCount: number;
+    llmWaitMs: number;
+    llmJsonParseMs: number;
+    toolExecutionMs: number;
+    firstAssistantAt?: number;
+    firstToolResultAt?: number;
+}) {
+    const endedAt = Date.now();
+    return {
+        totalMs: Math.max(0, endedAt - args.startedAt),
+        llmRequestCount: args.llmRequestCount,
+        llmWaitMs: args.llmWaitMs,
+        llmJsonParseMs: args.llmJsonParseMs,
+        toolExecutionMs: args.toolExecutionMs,
+        ...(typeof args.firstAssistantAt === "number"
+            ? { timeToFirstAssistantMs: Math.max(0, args.firstAssistantAt - args.startedAt) }
+            : {}),
+        ...(typeof args.firstToolResultAt === "number"
+            ? { timeToFirstToolResultMs: Math.max(0, args.firstToolResultAt - args.startedAt) }
+            : {}),
+        endedAt,
+    };
+}
+
+// ── 非流式 ────────────────────────────────────────────────────────────────────
+
+export async function runAgentLoop(
+    agentConfig: any,
+    initialMessages: ChatMessage[],
+    _maxRounds: number,
+    serverBase: string,
+    authToken: string,
+    runtimePolicy?: ResolvedRuntimePolicy,
+    userId?: string | null,
+    dialogId?: string | null,
+    currentSpaceId?: string | null,
+    userInput?: string | null,
+    runtimeContext?: AgentRunRuntimeContext | null,
+): Promise<LoopResult> {
+    const startTime = Date.now();
+    agentConfig = await hydrateApiKeyReferenceIfNeeded(agentConfig, serverBase, authToken);
+    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;
+    }
+
+    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;
+
+        if (!res.ok) throw new Error(`LLM API error (${res.status}): ${await res.text()}`);
+
+        const parseStartedAt = Date.now();
+        const data = await res.json() as any;
+        llmJsonParseMs += Math.max(0, Date.now() - parseStartedAt);
+        const choice = data.choices?.[0];
+        const assistantMsg: ChatMessage | null = isResponseAPIModel(agentConfig)
+            ? buildAssistantMessageFromResponse(data)
+            : choice?.message;
+        if (!assistantMsg) break;
+        if (firstAssistantAt === undefined) {
+            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;
+            finalParallelSummaryRepairUsed = true;
+            continue;
+        }
+        if (
+            !assistantMsg.tool_calls?.length &&
+            !assistantText &&
+            !emptyAssistantRepairUsed
+        ) {
+            emptyAssistantRepairPending = true;
+            emptyAssistantRepairUsed = true;
+            continue;
+        }
+        messages.push(assistantMsg);
+
+        if (!assistantMsg.tool_calls?.length || (!isResponseAPIModel(agentConfig) && choice.finish_reason === "stop")) {
+            finalContent = assistantText;
+            break;
+        }
+
+        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),
+            });
+            toolExecutionMs += Math.max(0, Date.now() - toolStartedAt);
+            if (firstToolResultAt === undefined) {
+                firstToolResultAt = Date.now();
+            }
+            messages.push({
+                role: "tool",
+                tool_call_id: tc.id,
+                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 (["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"
+                                ? 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,
+        }),
+    };
+}
+
+// ── 流式（SSE）────────────────────────────────────────────────────────────────
+
+type Send = (data: object) => void;
+
+export function buildSseStream(
+    agentConfig: any,
+    initialMessages: ChatMessage[],
+    _maxRounds: number,
+    serverBase: string,
+    authToken: string,
+    runtimePolicy?: ResolvedRuntimePolicy,
+    userId?: string | null,
+    dialogId?: string | null,
+    currentSpaceId?: string | null,
+    userInput?: string | null,
+    runtimeContext?: AgentRunRuntimeContext | null,
+): 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,
+                });
+
+                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);
+                    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;
+                    }
+                    if (!res.ok || !res.body) {
+                        send({ type: "error", message: `LLM API error (${res.status}): ${await res.text()}` });
+                        break;
+                    }
+
+                    const streamResult = isResponseAPIModel(agentConfig)
+                        ? await consumeResponsesSseStream(res.body, send)
+                        : await consumeSseStream(res.body, send, {
+                            suppressPreToolText: shouldSuppressPreToolText(agentConfig),
+                        });
+                    const {
+                        toolCalls,
+                        hasToolCalls,
+                        assistantContent,
+                        reasoningContent,
+                    } = streamResult;
+                    lastUsage = streamResult.lastUsage ?? lastUsage;
+
+                    const assistantMsg: ChatMessage = {
+                        role: "assistant",
+                        content: assistantContent || null,
+                        ...(reasoningContent ? { reasoning_content: reasoningContent } : {}),
+                        ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
+                    };
+                    if (
+                        !hasToolCalls &&
+                        !extractAssistantText(assistantMsg).trim() &&
+                        !finalParallelSummaryRepairUsed &&
+                        hasParallelBranchMessages(messages)
+                    ) {
+                        finalParallelSummaryRepairPending = true;
+                        finalParallelSummaryRepairUsed = true;
+                        continue;
+                    }
+                    if (
+                        !hasToolCalls &&
+                        !extractAssistantText(assistantMsg).trim() &&
+                        !emptyAssistantRepairUsed
+                    ) {
+                        emptyAssistantRepairPending = true;
+                        emptyAssistantRepairUsed = true;
+                        continue;
+                    }
+                    messages.push(assistantMsg);
+
+                    if (!hasToolCalls) {
+                        send({
+                            type: "done",
+                            usage: lastUsage,
+                            provider: lastResolvedProvider,
+                            model: lastResolvedModel,
+                            inputPrice: lastResolvedInputPrice,
+                            outputPrice: lastResolvedOutputPrice,
+                        });
+                        break;
+                    }
+
+                    send({
+                        type: "assistant_tool_calls",
+                        content: assistantMsg.content ?? null,
+                        tool_calls: toolCalls,
+                    });
+                    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),
+                        });
+                        messages.push({
+                            role: "tool",
+                            tool_call_id: tc.id,
+                            content: toolResult,
+                        });
+                        send({
+                            type: "tool_result",
+                            toolCallId: tc.id,
+                            toolName: canonicalizeToolName(tc.function.name),
+                            content: toolResult,
+                        });
+                        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;
+                        }
+                        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;
+                            }
+                        }
+                        // 如果是创建文档类工具，解析结果并推送 doc_created 事件让前端感知
+                        if (["createDoc", "createSkillDoc", "importSkill"].includes(canonicalizeToolName(tc.function.name))) {
+                            try {
+                                const parsed = JSON.parse(toolResult);
+                                if (parsed?.dbKey) {
+                                    send({ type: "doc_created", dbKey: parsed.dbKey, title: parsed.title, spaceId: parsed.spaceId });
+                                }
+                            } catch { /* 忽略解析失败 */ }
+                        }
+                    }
+                    send({ type: "tool_end" });
+                }
+            } catch (e: any) {
+                controller.enqueue(
+                    encoder.encode(`data: ${JSON.stringify({ type: "error", message: e.message ?? "Unexpected error" })}\n\n`)
+                );
+            }
+            controller.close();
+        },
+    });
+}
+
+interface SseConsumeResult {
+    toolCalls: AssistantToolCall[];
+    hasToolCalls: boolean;
+    assistantContent: ChatMessage["content"];
+    reasoningContent: string;
+    lastUsage: any;
+}
+
+function shouldSuppressPreToolText(agentConfig: any): boolean {
+    return (
+        agentConfig?.dbKey === BUILTIN_NOLO_AGENT_KEY ||
+        agentConfig?.agentKey === BUILTIN_NOLO_AGENT_KEY ||
+        agentConfig?.id === BUILTIN_NOLO_AGENT_KEY ||
+        agentConfig?.id === "01NOLOAPPBLD000000019KCKT0"
+    );
+}
+
+async function consumeSseStream(
+    body: ReadableStream<Uint8Array>,
+    send: Send,
+    options?: { suppressPreToolText?: boolean },
+): Promise<SseConsumeResult> {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buf = "";
+    const acc: Record<number, AssistantToolCall> = {};
+    let hasToolCalls = false;
+    const assistantContentParts: Array<
+        { type: "text"; text: string } | { type: "image_url"; image_url: { url: string } }
+    > = [];
+    let reasoningContent = "";
+    let lastUsage: any = null;
+    let suppressedText = "";
+
+    outer: while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buf += decoder.decode(value, { stream: true });
+        const lines = buf.split("\n");
+        buf = lines.pop() ?? "";
+
+        for (const line of lines) {
+            if (!line.startsWith("data: ")) continue;
+            const raw = line.slice(6).trim();
+            if (raw === "[DONE]") break outer;
+
+            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; }
+
+            if (typeof delta.content === "string" && delta.content) {
+                appendTextPart(assistantContentParts, delta.content);
+                if (options?.suppressPreToolText) {
+                    suppressedText += delta.content;
+                } else {
+                    send({ type: "text", content: delta.content });
+                }
+            }
+
+            if (Array.isArray(delta.images) && delta.images.length > 0) {
+                assistantContentParts.push(...delta.images);
+            }
+
+            // 思考内容：Ollama/Qwen3 用 delta.reasoning，DeepSeek 用 delta.reasoning_content
+            const thinkChunk: string = delta.reasoning ?? delta.reasoning_content ?? "";
+            if (thinkChunk) {
+                reasoningContent += thinkChunk;
+                send({ type: "thinking", content: thinkChunk });
+            }
+
+            if (Array.isArray(delta.tool_calls)) {
+                hasToolCalls = true;
+                for (const tc of delta.tool_calls) {
+                    const idx: number = tc.index ?? 0;
+                    if (!acc[idx]) {
+                        acc[idx] = { id: tc.id ?? "", type: "function", function: { name: tc.function?.name ?? "", arguments: "" } };
+                    }
+                    acc[idx].function.arguments += tc.function?.arguments ?? "";
+                    if (tc.id) acc[idx].id = tc.id;
+                    if (tc.function?.name) acc[idx].function.name = tc.function.name;
+                }
+            }
+
+            if (chunk.usage) lastUsage = chunk.usage;
+        }
+    }
+
+    const assistantContent = finalizeAssistantContent(assistantContentParts);
+    if (options?.suppressPreToolText && !hasToolCalls && suppressedText) {
+        send({ type: "text", content: suppressedText });
+    }
+
+    return {
+        toolCalls: Object.values(acc),
+        hasToolCalls,
+        assistantContent,
+        reasoningContent,
+        lastUsage,
+    };
+}
+
+async function consumeResponsesSseStream(
+    body: ReadableStream<Uint8Array>,
+    send: Send
+): Promise<SseConsumeResult> {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buf = "";
+    const acc = new Map<string, AssistantToolCall>();
+    let hasToolCalls = false;
+    let assistantContent = "";
+    let reasoningContent = "";
+    let lastUsage: any = null;
+    let completedResponse: any = null;
+
+    outer: while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buf += decoder.decode(value, { stream: true });
+        const lines = buf.split("\n");
+        buf = lines.pop() ?? "";
+
+        for (const line of lines) {
+            if (!line.startsWith("data: ")) continue;
+            const raw = line.slice(6).trim();
+            if (raw === "[DONE]") break outer;
+
+            let event: any;
+            try {
+                event = JSON.parse(raw);
+            } catch {
+                continue;
+            }
+
+            if (event?.usage) lastUsage = event.usage;
+
+            switch (event?.type) {
+                case "response.output_text.delta":
+                    if (event.delta) {
+                        assistantContent += event.delta;
+                        send({ type: "text", content: event.delta });
+                    }
+                    break;
+                case "response.reasoning.delta":
+                    if (event.delta?.text) {
+                        reasoningContent += event.delta.text;
+                        send({ type: "thinking", content: event.delta.text });
+                    }
+                    break;
+                case "response.output_item.added":
+                case "response.output_item.done": {
+                    const item = event.item;
+                    if (!assistantContent) {
+                        const itemText = extractTextFromResponseOutputItem(item);
+                        if (itemText) {
+                            assistantContent = itemText;
+                            send({ type: "text", content: itemText });
+                        }
+                    }
+                    if (item?.type !== "function_call") break;
+                    hasToolCalls = true;
+                    const key = item.call_id || item.id;
+                    if (!key) break;
+                    acc.set(key, {
+                        id: item.call_id || item.id,
+                        type: "function",
+                        function: {
+                            name: item.name ?? "",
+                            arguments:
+                                typeof item.arguments === "string" ? item.arguments : "",
+                        },
+                    });
+                    break;
+                }
+                case "response.function_call_arguments.delta": {
+                    hasToolCalls = true;
+                    const key = event.call_id || event.item_id || `${event.output_index ?? 0}`;
+                    const current = acc.get(key) ?? {
+                        id: event.call_id || key,
+                        type: "function" as const,
+                        function: { name: event.name ?? "", arguments: "" },
+                    };
+                    current.function.arguments += event.delta ?? "";
+                    if (event.name) current.function.name = event.name;
+                    acc.set(key, current);
+                    break;
+                }
+                case "response.function_call_arguments.done": {
+                    hasToolCalls = true;
+                    const key = event.call_id || event.item_id || `${event.output_index ?? 0}`;
+                    const current = acc.get(key) ?? {
+                        id: event.call_id || key,
+                        type: "function" as const,
+                        function: { name: event.name ?? "", arguments: "" },
+                    };
+                    if (event.name) current.function.name = event.name;
+                    if (typeof event.arguments === "string") {
+                        current.function.arguments = event.arguments;
+                    }
+                    acc.set(key, current);
+                    break;
+                }
+                case "response.completed":
+                    completedResponse = event.response ?? null;
+                    if (event.response?.usage) lastUsage = event.response.usage;
+                    break;
+                default:
+                    break;
+            }
+        }
+    }
+
+    if (!assistantContent && completedResponse) {
+        assistantContent = extractTextFromResponseOutput(completedResponse);
+        if (assistantContent) {
+            send({ type: "text", content: assistantContent });
+        }
+    }
+
+    return {
+        toolCalls: Array.from(acc.values()),
+        hasToolCalls,
+        assistantContent,
+        reasoningContent,
+        lastUsage,
+    };
+}