nolo-cli 0.1.26 → 0.1.29

package/server/handlers/agentRun/index.ts

@@ -0,0 +1,1630 @@
+// packages/server/handlers/agentRun/index.ts
+//
+// POST /api/agent/run
+//
+// 鉴权模式：
+//   1. Authorization: Bearer <jwt>   ← 登录用户（计费 + 审计）
+//
+// 持久化说明：
+//   ✅ 持久化  — Agent 配置（LevelDB）、Dialog 记录 + 全量消息轨迹（LevelDB）、Token 记录（LevelDB）
+//
+// Request:
+//   { agentKey, userInput, messages?, stream?, maxRounds?, background? }
+//   说明：maxRounds 仅为兼容旧客户端保留，服务端已不再按工具轮次截断。
+//
+// Response (非流式):
+//   { content, model, usage, dialogId }
+//
+// Response (background=true, 202):
+//   { dialogId, status: "pending" }
+//
+// Response (流式 SSE):
+//   data: {"type":"dialog","dialogId":"...","dialogKey":"...","status":"running"}
+//   data: {"type":"text","content":"..."}
+//   data: {"type":"tool_start","calls":["fetchWebpage"]}
+//   data: {"type":"tool_end"}
+//   data: {"type":"done","usage":{...},"dialogId":"..."}
+//   data: {"type":"error","message":"..."}
+
+import { createHash } from "node:crypto";
+import { ulid } from "ulid";
+import { authenticateRequest } from "../../../auth/utils";
+import { WEB_AUTH_TOKEN_COOKIE } from "../../../auth/tokenCookie";
+import { getUser } from "../../../auth/server/getUser";
+import { checkBasicBalance } from "../../../auth/billing";
+import { chargeTokenUsageWithLedger } from "../../../auth/server/tokenUsageBilling";
+import { writeServerTokenRecord } from "../../../ai/token/serverTokenWriter";
+import serverDb, { ensureServerDbOpen } from "../../../database/server/db";
+import { runAgentLoop, buildSseStream } from "./loop";
+import { incActiveStream, decActiveStream } from "../../serverDrain";
+import { saveRunAsDialog, createPendingDialog, finalizeDialog, appendToExistingDialog } from "./saveDialog";
+import { fetchConvMsgs } from "../../api/methods";
+import { pushEvent } from "../eventBus";
+import { createUserKey } from "../../../database/keys";
+import { emitDialogStatusNotification } from "../notificationEmitter";
+import { summarizeMessagesForDebug } from "../../../chat/messages/messageContract";
+import {
+    buildUserPolicyContext,
+    resolveRuntimePolicy,
+} from "../../../ai/policy/runtimePolicy";
+import { resolveMemoryRuntime } from "../../../ai/memory/runtime";
+import type { AgentRunRequest, ChatMessage, LoopResult } from "./types";
+import { resolveExistingDialogRef } from "./dialogLookup";
+import { resolveContinueDialogContext } from "./continueDialogContext";
+import { prepareAgentRunExecutionContext } from "./runtimeExecutionContext";
+import { resolveEffectiveRuntimeToolPolicy } from "../../../agent-runtime";
+import { prepareForegroundStreamDialog } from "./foregroundStreamDialog";
+import { isBackgroundRunDialogError, prepareBackgroundRunDialog } from "./backgroundRunDialog";
+import { canonicalizeToolNames, prioritizeToolNames } from "../../../ai/tools/toolNameAliases";
+import { resolveServerReferenceRuntime } from "./referenceRuntime";
+import { buildDialogFallbackTitleFromUserInput } from "../../../chat/dialog/dialogTitle";
+import { buildRuntimeSystemMessageContext } from "./runtimeSystemMessages";
+import { resolveAutonomousRuntimeContext } from "./autonomousRuntime";
+import {
+    ensureLocalModelRuntimeIfNeeded,
+    isLocalRuntimeUnavailableError,
+} from "./localRuntimeBootstrap";
+import { isLocalEndpoint } from "./localRuntimeBootstrap";
+import {
+    BUILTIN_ECOMMERCE_AGENT_KEY,
+    BUILTIN_NOLO_AGENT_KEY,
+} from "./builtinAgents";
+import { resolveAgentRunAgentConfig } from "./agentLookup";
+import {
+    resolveAgentRunDelegation,
+    resolveMachineBindingPreflight,
+} from "./runtimeRouting";
+import {
+    prepareAgentRunRuntimeConfig,
+    resolveTaskRunPreflightContext,
+} from "./runtimePreparation";
+import {
+    parseAgentRunRequestBody,
+} from "./requestContext";
+import { buildAgentRunDebugContext } from "./debugContext";
+import { resolveAgentRunBilledUsage } from "./runBilling";
+import { buildInheritedDialogPromptBlock } from "./inheritedDialogPrompt";
+import { completeSyncAgentRunDialog } from "./syncRunDialog";
+import {
+    AGENT_RUN_CORS_HEADERS as CORS,
+    agentRunError,
+    agentRunJson,
+    agentRunSse,
+} from "./response";
+import { machineRegistry } from "../machines/machineRegistry";
+import {
+    ConnectorOfflineError,
+    type MachineConnectorRunProgress,
+    resolveAgentRuntimeMachineId,
+    runViaMachineConnector,
+    shouldUseMachineConnector,
+} from "./machineConnector";
+import type { ConnectorAgentRunResult } from "../connector/connectorConnectionRegistry";
+import { projectDialogActivityToSubjectRows } from "./tableActivityProjection";
+import { buildWorkspaceLeaseFromConnectorResult } from "./workspaceLease";
+import { resolveCoreDataProxyTarget } from "../../../database/server/coreDataProxy";
+
+type AgentRunTokenWrite = Awaited<ReturnType<typeof writeServerTokenRecord>>;
+type AgentRunBillingInput = Parameters<typeof resolveAgentRunBilledUsage>[0] & {
+    agentKey: string;
+};
+
+const DEFAULT_BACKGROUND_RUN_TIMEOUT_MS = 10 * 60_000;
+const DEFAULT_RUNTIME_PROMPT_PAGE_THRESHOLD_BYTES = 32_000;
+
+function byteLength(value: string) {
+    return Buffer.byteLength(value, "utf8");
+}
+
+function shortHash(value: string) {
+    return createHash("sha256").update(value).digest("hex").slice(0, 12);
+}
+
+function resolveRuntimePromptPageThresholdBytes() {
+    const raw = Number(process.env.NOLO_RUNTIME_PROMPT_PAGE_THRESHOLD_BYTES);
+    return Number.isFinite(raw) && raw >= 1024
+        ? raw
+        : DEFAULT_RUNTIME_PROMPT_PAGE_THRESHOLD_BYTES;
+}
+
+function textToSlate(text: string) {
+    return text.split("\n").map((line) => ({
+        type: "paragraph",
+        children: [{ text: line }],
+    }));
+}
+
+async function createRuntimePromptPageIfLarge(args: {
+    agentConfig: any;
+    agentKey: string;
+    dialogId: string;
+    runtimeContext: unknown;
+    spaceId?: string;
+    userId: string;
+    userInputText: string;
+}) {
+    const content = [
+        "# Nolo Runtime Prompt Context",
+        "",
+        "This page is generated for a single agent run. It is shared cloud context for audit, handoff, and recovery.",
+        "Local repository changes, diffs, tests, and commits remain authoritative for local execution facts.",
+        "",
+        `dialogId: ${args.dialogId}`,
+        `agentKey: ${args.agentKey}`,
+        "",
+        "## Agent Prompt",
+        typeof args.agentConfig?.prompt === "string" ? args.agentConfig.prompt.trim() : "",
+        "",
+        "## Runtime Context",
+        JSON.stringify(args.runtimeContext ?? null, null, 2),
+        "",
+        "## User Task",
+        args.userInputText,
+    ].join("\n");
+    const contentBytes = byteLength(content);
+    if (contentBytes <= resolveRuntimePromptPageThresholdBytes()) return null;
+
+    const pageId = ulid();
+    const dbKey = `page-${args.userId}-${pageId}`;
+    const now = Date.now();
+    const promptHash = shortHash(content);
+    const title = `Runtime Prompt ${args.dialogId}`;
+    await serverDb.put(dbKey, {
+        id: pageId,
+        dbKey,
+        type: "page",
+        title,
+        spaceId: args.spaceId ?? null,
+        content,
+        slateData: textToSlate(content),
+        createdAt: now,
+        updatedAt: now,
+        created: new Date(now).toISOString(),
+        meta: {
+            kind: "nolo_runtime_prompt",
+            ephemeral: true,
+            dialogId: args.dialogId,
+            agentKey: args.agentKey,
+            promptHash,
+            contentBytes,
+        },
+    });
+    return { dbKey, title, promptHash, contentBytes };
+}
+
+async function withBackgroundRunTimeout<T>(
+    run: Promise<T>,
+    timeoutMs: number,
+): Promise<T> {
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    const timeoutPromise = new Promise<never>((_, reject) => {
+        timeout = setTimeout(() => {
+            reject(new Error(`background agent run timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([run, timeoutPromise]);
+    } finally {
+        if (timeout) clearTimeout(timeout);
+    }
+}
+
+async function chargeAgentRunTokenCost(userId: string, tokenWrite: AgentRunTokenWrite) {
+    return chargeTokenUsageWithLedger({
+        store: serverDb,
+        userId,
+        tokenKey: tokenWrite.recordKey,
+        tokenRecord: tokenWrite.tokenRecord,
+        reason: "agent_run",
+        txId: `token-${tokenWrite.recordKey}`,
+    });
+}
+
+async function projectBackgroundDialogActivity(args: {
+    dialogId: string;
+    dialogKey: string;
+    agentKey: string;
+    parentDialogId?: string | null;
+    runtimeContext?: AgentRunRequest["runtimeContext"];
+    status: "done" | "failed" | string;
+}) {
+    const subjectRefs = Array.isArray(args.runtimeContext?.subjectRefs)
+        ? args.runtimeContext.subjectRefs
+        : [];
+    if (subjectRefs.length === 0) return;
+
+    try {
+        await projectDialogActivityToSubjectRows({
+            db: serverDb,
+            subjectRefs,
+            activityRef: {
+                type: "dialog",
+                dialogId: args.dialogId,
+                dialogKey: args.dialogKey,
+                role:
+                    args.runtimeContext?.entrypoint === "agent-tool:startAgentDialog"
+                        ? "child-dialog"
+                        : "background-dialog",
+                agentKey: args.agentKey,
+                ...(args.parentDialogId ? { parentDialogId: args.parentDialogId } : {}),
+                status: args.status,
+                updatedAt: new Date().toISOString(),
+            },
+        });
+    } catch (error) {
+        console.error(`[background] dialog=${args.dialogId} activity projection failed:`, error);
+    }
+}
+
+function buildRunningRuntimeCheckpoint(args: {
+    dialogId: string;
+    userInputText: string;
+    updatedAt: number;
+    runtimeBinding?: unknown;
+}) {
+    return {
+        version: 1,
+        status: "running",
+        dialogId: args.dialogId,
+        updatedAt: args.updatedAt,
+        lastUserInput: args.userInputText,
+        lastAssistantText: null,
+        toolCallCount: 0,
+        traceSummary: { assistantCount: 0, toolCount: 0 },
+        lastToolNames: [],
+        ...(args.runtimeBinding ? { runtimeBinding: args.runtimeBinding } : {}),
+    };
+}
+
+function asRecord(value: unknown): Record<string, any> {
+    return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, any> : {};
+}
+
+function mergeUniqueStrings(...values: unknown[]) {
+    const merged: string[] = [];
+    for (const value of values) {
+        if (!Array.isArray(value)) continue;
+        for (const item of value) {
+            if (typeof item !== "string" || !item.trim()) continue;
+            const name = item.trim();
+            if (!merged.includes(name)) merged.push(name);
+        }
+    }
+    return merged.slice(-12);
+}
+
+function buildProgressRuntimeCheckpoint(args: {
+    existingDialog: any;
+    dialogId: string;
+    userInputText: string;
+    progress: MachineConnectorRunProgress;
+    updatedAt: number;
+}) {
+    const previous = asRecord(args.existingDialog?.runtimeCheckpoint);
+    const previousTrace = asRecord(previous.traceSummary);
+    const toolCallCount =
+        typeof args.progress.toolCallCount === "number"
+            ? args.progress.toolCallCount
+            : typeof previous.toolCallCount === "number"
+                ? previous.toolCallCount
+                : 0;
+    const toolResultCount =
+        typeof args.progress.toolResultCount === "number"
+            ? args.progress.toolResultCount
+            : typeof previousTrace.toolCount === "number"
+                ? previousTrace.toolCount
+                : 0;
+    const workspaceProgress = {
+        ...asRecord(previous.workspaceProgress),
+        ...(args.progress.workspaceRoot ? { workspaceRoot: args.progress.workspaceRoot } : {}),
+        ...(args.progress.workspaceKind ? { workspaceKind: args.progress.workspaceKind } : {}),
+    };
+    return {
+        ...previous,
+        version: 1,
+        status: "running",
+        dialogId: args.dialogId,
+        updatedAt: args.updatedAt,
+        lastUserInput: previous.lastUserInput ?? args.userInputText,
+        lastAssistantText: previous.lastAssistantText ?? null,
+        toolCallCount,
+        traceSummary: {
+            assistantCount: typeof previousTrace.assistantCount === "number" ? previousTrace.assistantCount : 0,
+            toolCount: toolResultCount,
+        },
+        lastToolNames: mergeUniqueStrings(previous.lastToolNames, args.progress.lastToolNames),
+        ...(Object.keys(workspaceProgress).length > 0 ? { workspaceProgress } : {}),
+        ...(args.existingDialog?.runtimeBinding ? { runtimeBinding: args.existingDialog.runtimeBinding } : {}),
+        lastProgressEventType: args.progress.eventType ?? previous.lastProgressEventType,
+        ...(args.progress.message ? { lastProgressMessage: args.progress.message } : {}),
+    };
+}
+
+function buildFailedRuntimeCheckpoint(args: {
+    existingDialog: any;
+    dialogId: string;
+    userInputText: string;
+    updatedAt: number;
+    errorMessage: string;
+}) {
+    const previous = asRecord(args.existingDialog?.runtimeCheckpoint);
+    const previousTrace = asRecord(previous.traceSummary);
+    return {
+        ...previous,
+        version: 1,
+        status: "failed",
+        dialogId: args.dialogId,
+        updatedAt: args.updatedAt,
+        lastUserInput: previous.lastUserInput ?? args.userInputText,
+        lastAssistantText: previous.lastAssistantText ?? null,
+        toolCallCount:
+            typeof previous.toolCallCount === "number"
+                ? previous.toolCallCount
+                : typeof args.existingDialog?.toolCallCount === "number"
+                    ? args.existingDialog.toolCallCount
+                    : 0,
+        traceSummary: {
+            assistantCount: typeof previousTrace.assistantCount === "number" ? previousTrace.assistantCount : 0,
+            toolCount: typeof previousTrace.toolCount === "number" ? previousTrace.toolCount : 0,
+        },
+        lastToolNames: mergeUniqueStrings(previous.lastToolNames),
+        ...(args.existingDialog?.runtimeBinding ? { runtimeBinding: args.existingDialog.runtimeBinding } : {}),
+        errorMessage: args.errorMessage,
+    };
+}
+
+async function writeAgentRunBillingIfNeeded(args: AgentRunBillingInput) {
+    try {
+        const { billingAgentConfig, billedUsage } = resolveAgentRunBilledUsage({
+            agentConfig: args.agentConfig,
+            result: args.result,
+            dialogId: args.dialogId,
+            mode: args.mode,
+            userId: args.userId,
+        });
+        if (!args.userId || !billedUsage) return;
+
+        const tokenWrite = await writeServerTokenRecord({
+            userId: args.userId,
+            agentKey: args.agentKey,
+            agentConfig: billingAgentConfig,
+            runId: args.dialogId,
+            rawUsage: billedUsage as any,
+        });
+        if (tokenWrite.cost > 0) await chargeAgentRunTokenCost(args.userId, tokenWrite);
+    } catch (error) {
+        console.warn("[billing] Agent run billing write failed; preserving dialog result", {
+            dialogId: args.dialogId,
+            mode: args.mode,
+            userId: args.userId,
+            agentKey: args.agentKey,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+
+let runAgentLoopImpl = runAgentLoop;
+let buildSseStreamImpl = buildSseStream;
+
+type StreamBillingContext = {
+    agentConfig: any;
+    agentKey: string;
+    dialogAgentKey?: string;
+    traceAgentKey?: string;
+    userId: string | null;
+    dialogId: string;
+    dialogKey: string;
+    userInputText: string;
+    startedAt: number;
+    isContinue: boolean;
+    spaceId?: string;
+    runtimeProfile?: any;
+    runtimeToolPolicySnapshot?: Record<string, unknown>;
+    workspaceLease?: Record<string, unknown>;
+    persistDialog?: boolean;
+};
+
+const normalizeAgentRunUserParts = (
+    userInput: AgentRunRequest["userInput"],
+): Array<Exclude<ChatMessage["content"], string | null>[number]> => {
+    if (!Array.isArray(userInput)) return [];
+    return userInput.filter((part): part is Exclude<ChatMessage["content"], string | null>[number] => {
+        if (!part || typeof part !== "object") return false;
+        if (part.type === "text") {
+            return typeof part.text === "string" && !!part.text.trim();
+        }
+        return (
+            part.type === "image_url" &&
+            typeof part.image_url?.url === "string" &&
+            !!part.image_url.url.trim()
+        );
+    });
+};
+
+const extractAgentRunUserText = (userInput: AgentRunRequest["userInput"]): string => {
+    if (typeof userInput === "string") {
+        return userInput.trim();
+    }
+    return normalizeAgentRunUserParts(userInput)
+        .filter((part): part is { type: "text"; text: string } => part.type === "text")
+        .map((part) => part.text)
+        .join("\n")
+        .trim();
+};
+
+const buildAgentRunUserMessageContent = (
+    userInput: AgentRunRequest["userInput"],
+    turnInstruction?: string | null,
+    prelude?: string | null,
+): ChatMessage["content"] => {
+    const normalizedTurnInstruction =
+        typeof turnInstruction === "string" && turnInstruction.trim()
+            ? turnInstruction.trim()
+            : "";
+    const normalizedPrelude =
+        typeof prelude === "string" && prelude.trim()
+            ? prelude.trim()
+            : "";
+    const normalizedParts = normalizeAgentRunUserParts(userInput);
+    if (normalizedParts.length > 0) {
+        // Inject URL hints so the model uses original HTTPS URLs in tool calls
+        // rather than reconstructing/hallucinating base64 from its vision input.
+        const imageUrlParts = normalizedParts.filter(
+            (p): p is { type: "image_url"; image_url: { url: string } } =>
+                p.type === "image_url"
+        );
+        const urlHintText =
+            imageUrlParts.length > 0
+                ? imageUrlParts
+                      .map(
+                          (p, i) =>
+                              `[附件图片${i + 1} URL（工具调用时请直接将此 URL 填入 images[${i}].data，不要重编码）: ${p.image_url.url}]`
+                      )
+                      .join("\n")
+                : null;
+
+        return [
+            ...(normalizedPrelude
+                ? [{ type: "text" as const, text: `${normalizedPrelude}\n\n--- User task ---` }]
+                : []),
+            ...(normalizedTurnInstruction
+                ? [{ type: "text" as const, text: `${normalizedTurnInstruction}\n\n--- User task ---` }]
+                : []),
+            ...(urlHintText
+                ? [{ type: "text" as const, text: urlHintText }]
+                : []),
+            // Only include text parts in the coordinator LLM message.
+            // image_url parts are intentionally excluded: high-capability models like
+            // gpt-5.4 charge ~857k tokens per image even at detail:low, exceeding the
+            // 400k TPM limit. The URL hint text above already provides the URL for tool
+            // calls; the actual image analysis is done by gpt-image-2, not the coordinator.
+            ...normalizedParts.filter((p) => p.type === "text"),
+        ];
+    }
+
+    const userText = extractAgentRunUserText(userInput);
+    const prefix = [normalizedPrelude, normalizedTurnInstruction].filter(Boolean).join("\n\n");
+    if (!prefix) {
+        return userText;
+    }
+    if (!userText) {
+        return prefix;
+    }
+    return [prefix, "--- User task ---", userText].join("\n\n");
+};
+
+function resolveDirectSpecialistAgentKey(args: {
+    agentKey: string;
+    userInputText: string;
+    stream: boolean;
+    background: boolean;
+    continueDialogId?: string;
+}): string | null {
+    if (args.agentKey !== BUILTIN_NOLO_AGENT_KEY) return null;
+    if (!args.stream || args.background || args.continueDialogId) return null;
+
+    const text = args.userInputText.trim();
+    if (!text) return null;
+    const ecommerceUrlMatches =
+        text.match(/https?:\/\/\S*(?:item\.jd\.com|item\.m\.jd\.com|jd\.com|taobao\.com|tmall\.com)\S*/gi) ?? [];
+    if (ecommerceUrlMatches.length > 1) return null;
+
+    const hasEcommerceTarget =
+        /(?:item\.jd\.com|item\.m\.jd\.com|jd\.com|taobao\.com|tmall\.com)/i.test(text) ||
+        /(?:京东|淘宝|天猫|SKU|商品链接|商品ID|itemId)/i.test(text);
+    const asksForProductData =
+        /(?:参数|型号|价格|规格|尺寸|重量|质保|库存|店铺|sku|商品详情|真实)/i.test(text);
+    if (!hasEcommerceTarget || !asksForProductData) return null;
+
+    const asksForParentFollowup =
+        /(?:对比表|表格|建表|记录|写入|保存|分析|总结|推荐|方案|继续|然后|再帮我|顺便|做成|生成|整理成)/i.test(text);
+    if (asksForParentFollowup) return null;
+    return BUILTIN_ECOMMERCE_AGENT_KEY;
+}
+
+export function __setAgentRunLoopForTest(overrides: {
+    runAgentLoop?: typeof runAgentLoop;
+    buildSseStream?: typeof buildSseStream;
+}) {
+    if (overrides.runAgentLoop) {
+        runAgentLoopImpl = overrides.runAgentLoop;
+    }
+    if (overrides.buildSseStream) {
+        buildSseStreamImpl = overrides.buildSseStream;
+    }
+}
+
+function buildMachineConnectorSseStream(result: ConnectorAgentRunResult): ReadableStream<Uint8Array> {
+    return new ReadableStream({
+        start(controller) {
+            const encoder = new TextEncoder();
+            const send = (payload: unknown) => {
+                controller.enqueue(encoder.encode(`data: ${JSON.stringify(payload)}\n\n`));
+            };
+            if (result.content) {
+                send({ type: "text", content: result.content });
+            }
+            send({ type: "done", usage: result.usage, artifacts: result.artifacts });
+            controller.close();
+        },
+    });
+}
+
+const serializeSseEvent = (payload: unknown) =>
+    `data: ${JSON.stringify(payload)}\n\n`;
+
+const parseSseEventPayload = (eventText: string): any | null => {
+    const data = eventText
+        .split(/\r?\n/)
+        .filter((line) => line.startsWith("data:"))
+        .map((line) => line.slice(5).trim())
+        .join("\n")
+        .trim();
+    if (!data || data === "[DONE]") return null;
+    try {
+        return JSON.parse(data);
+    } catch {
+        return null;
+    }
+};
+
+async function persistAndBillForegroundStreamRun(
+    context: StreamBillingContext,
+    result: LoopResult
+) {
+    const durationMs = Math.max(0, Date.now() - context.startedAt);
+    if (context.persistDialog !== false) {
+        if (context.isContinue) {
+            await appendToExistingDialog({
+                dialogId: context.dialogId,
+                dialogKey: context.dialogKey,
+                agentKey: context.dialogAgentKey ?? context.agentKey,
+                traceAgentKey: context.traceAgentKey,
+                userId: context.userId,
+                userInput: context.userInputText,
+                result,
+                durationMs,
+                spaceId: context.spaceId,
+                runtimeProfile: context.runtimeProfile,
+                runtimeToolPolicySnapshot: context.runtimeToolPolicySnapshot,
+                workspaceLease: context.workspaceLease,
+            });
+        } else {
+            await finalizeDialog({
+                dialogId: context.dialogId,
+                dialogKey: context.dialogKey,
+                agentKey: context.dialogAgentKey ?? context.agentKey,
+                traceAgentKey: context.traceAgentKey,
+                result,
+                startedAt: context.startedAt,
+                status: "done",
+                userInput: context.userInputText,
+                userId: context.userId,
+                spaceId: context.spaceId,
+                runtimeToolPolicySnapshot: context.runtimeToolPolicySnapshot,
+                workspaceLease: context.workspaceLease,
+            });
+        }
+    }
+
+    await writeAgentRunBillingIfNeeded({
+        agentConfig: context.agentConfig,
+        agentKey: context.agentKey,
+        result,
+        dialogId: context.dialogId,
+        mode: "sync",
+        userId: context.userId,
+    });
+}
+
+function buildBillableForegroundSseStream(
+    source: ReadableStream,
+    context: StreamBillingContext
+): ReadableStream<Uint8Array> {
+    const encoder = new TextEncoder();
+    const decoder = new TextDecoder();
+
+    return new ReadableStream({
+        async start(controller) {
+            const reader = source.getReader();
+            let buffer = "";
+            let assistantText = "";
+            let lastUsage: Record<string, any> | undefined;
+            let lastProvider = context.agentConfig.provider ?? undefined;
+            let lastModel = context.agentConfig.model ?? "unknown";
+            let lastInputPrice = context.agentConfig.inputPrice;
+            let lastOutputPrice = context.agentConfig.outputPrice;
+            let lastArtifacts: unknown;
+            let toolCallCount = 0;
+            let sawDone = false;
+            const trace: ChatMessage[] = [];
+
+            controller.enqueue(
+                encoder.encode(serializeSseEvent({
+                    type: "dialog",
+                    dialogId: context.dialogId,
+                    dialogKey: context.dialogKey,
+                    status: "running",
+                }))
+            );
+
+            const enqueueEvent = (eventText: string) => {
+                const payload = parseSseEventPayload(eventText);
+                if (!payload || typeof payload !== "object") {
+                    controller.enqueue(encoder.encode(eventText));
+                    return;
+                }
+
+                if (payload.type === "text" && typeof payload.content === "string") {
+                    assistantText += payload.content;
+                }
+                if (payload.type === "assistant_tool_calls") {
+                    const toolCalls = Array.isArray(payload.tool_calls)
+                        ? payload.tool_calls
+                        : [];
+                    toolCallCount += toolCalls.length;
+                    assistantText = "";
+                    trace.push({
+                        role: "assistant",
+                        content: payload.content ?? null,
+                        ...(toolCalls.length ? { tool_calls: toolCalls } : {}),
+                    } as ChatMessage);
+                }
+                if (payload.type === "tool_result") {
+                    trace.push({
+                        role: "tool",
+                        content: payload.content ?? null,
+                        ...(payload.toolCallId ? { tool_call_id: payload.toolCallId } : {}),
+                    } as ChatMessage);
+                }
+                if (payload.type === "done") {
+                    sawDone = true;
+                    lastUsage = payload.usage ?? lastUsage;
+                    lastProvider = payload.provider ?? lastProvider;
+                    lastModel = payload.model ?? lastModel;
+                    lastInputPrice =
+                        typeof payload.inputPrice === "number"
+                            ? payload.inputPrice
+                            : lastInputPrice;
+                    lastOutputPrice =
+                        typeof payload.outputPrice === "number"
+                            ? payload.outputPrice
+                            : lastOutputPrice;
+                    lastArtifacts = payload.artifacts ?? lastArtifacts;
+                    if (assistantText) {
+                        trace.push({ role: "assistant", content: assistantText });
+                    }
+                    controller.enqueue(
+                        encoder.encode(serializeSseEvent({
+                            ...payload,
+                            dialogId: context.dialogId,
+                        }))
+                    );
+                    return;
+                }
+
+                controller.enqueue(encoder.encode(eventText));
+            };
+
+            try {
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done) break;
+                    buffer += decoder.decode(value, { stream: true });
+                    const events = buffer.split(/\n\n/);
+                    buffer = events.pop() ?? "";
+                    for (const eventText of events) {
+                        if (!eventText) continue;
+                        enqueueEvent(`${eventText}\n\n`);
+                    }
+                }
+                if (buffer.trim()) {
+                    enqueueEvent(buffer.endsWith("\n\n") ? buffer : `${buffer}\n\n`);
+                }
+
+                if (sawDone) {
+                    await persistAndBillForegroundStreamRun(context, {
+                        content: assistantText,
+                        model: lastModel,
+                        provider: lastProvider,
+                        inputPrice: lastInputPrice,
+                        outputPrice: lastOutputPrice,
+                        usage: lastUsage,
+                        ...(lastArtifacts ? { artifacts: lastArtifacts } : {}),
+                        trace,
+                        runtimeToolNames: [],
+                        toolCallCount,
+                    });
+                }
+            } catch (error) {
+                console.error("[agentRun] foreground stream billing failed", {
+                    dialogId: context.dialogId,
+                    error,
+                });
+            } finally {
+                controller.close();
+            }
+        },
+    });
+}
+
+async function proxyAgentRunToRemote(options: {
+    targetBase: string;
+    body: AgentRunRequest;
+    authToken: string;
+    stream: boolean;
+}): Promise<Response> {
+    const { targetBase, body, authToken, stream } = options;
+
+    let remoteResponse: Response;
+    try {
+        remoteResponse = await fetch(`${targetBase}/api/agent/run`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                ...(authToken ? { Authorization: `Bearer ${authToken}` } : {}),
+            },
+            body: JSON.stringify(body),
+        });
+    } catch (error: any) {
+        return agentRunError(
+            `Runtime server unavailable: ${targetBase} (${error?.message ?? "request failed"})`,
+            502,
+        );
+    }
+
+    if (stream) {
+        return new Response(remoteResponse.body, {
+            status: remoteResponse.status,
+            headers: {
+                ...CORS,
+                "Content-Type":
+                    remoteResponse.headers.get("Content-Type") ?? "text/event-stream",
+                "Cache-Control":
+                    remoteResponse.headers.get("Cache-Control") ?? "no-cache",
+                Connection: remoteResponse.headers.get("Connection") ?? "keep-alive",
+            },
+        });
+    }
+
+    const responseText = await remoteResponse.text();
+    let responseBodyText = responseText;
+    const contentType =
+        remoteResponse.headers.get("Content-Type") ?? "application/json";
+    if (options.body.background && contentType.includes("application/json")) {
+        try {
+            const parsed = JSON.parse(responseText);
+            if (parsed && typeof parsed === "object" && !("serverBase" in parsed)) {
+                responseBodyText = JSON.stringify({
+                    ...parsed,
+                    serverBase: targetBase,
+                });
+            }
+        } catch {
+            // fall back to original body
+        }
+    }
+    return new Response(responseBodyText, {
+        status: remoteResponse.status,
+        headers: {
+            ...CORS,
+            "Content-Type": contentType,
+        },
+    });
+}
+
+const LOCAL_SMOKE_AGENT_KEYS = new Set([
+    "agent-0e95801d90-01KJZ79FDW84G5VG2050KBJM70",
+]);
+function shouldBypassBalanceForLocalSmokeAgent(
+    agentKey: string,
+    agentConfig: any,
+    serverBase: string,
+): boolean {
+    const isCustomSource =
+        agentConfig?.apiSource === "custom" || !!agentConfig?.customProviderUrl;
+    if (LOCAL_SMOKE_AGENT_KEYS.has(agentKey)) return isCustomSource;
+    return isCustomSource &&
+        isLocalEndpoint(serverBase) &&
+        isLocalEndpoint(agentConfig?.customProviderUrl ?? "");
+}
+
+function resolveConnectorFailureResponse(error: any, agentConfig: any): Response | null {
+    if (error instanceof ConnectorOfflineError) {
+        return agentRunJson({
+            error: "Connector offline",
+            reason: "connector_offline",
+            message: error.message,
+        }, 409);
+    }
+    if (shouldUseMachineConnector(agentConfig)) {
+        return agentRunJson({
+            error: "Connector execution failed",
+            reason: "connector_execution_failed",
+            message: error.message ?? "Connector execution failed",
+        }, 502);
+    }
+    return null;
+}
+
+// ── 鉴权：JWT Bearer Token ────────────────────────────────────────────────────
+
+interface AuthInfo { authToken: string; userId: string; callerType: "jwt"; }
+
+function extractAuthToken(req: Request): string {
+    const authHeaderToken = req.headers.get("authorization")?.split(" ")[1]?.trim();
+    if (authHeaderToken) return authHeaderToken;
+
+    const cookieHeader = req.headers.get("cookie") ?? req.headers.get("Cookie") ?? "";
+    const cookieToken = cookieHeader
+        .split(";")
+        .map((part) => part.trim())
+        .find((part) => part.startsWith(`${WEB_AUTH_TOKEN_COOKIE}=`))
+        ?.slice(`${WEB_AUTH_TOKEN_COOKIE}=`.length);
+    return cookieToken ? decodeURIComponent(cookieToken) : "";
+}
+
+async function authorize(req: Request): Promise<AuthInfo | Response> {
+    // 标准 JWT Bearer Token（登录用户，计费 + 审计）
+    const result = await authenticateRequest(req);
+    if (result instanceof Response) return result; // 401
+    return {
+        authToken: result.authToken ?? extractAuthToken(req),
+        userId: result.userId,
+        callerType: "jwt",
+    };
+}
+
+// ── Handler ────────────────────────────────────────────────────────────────────
+
+export async function handleAgentRun(req: Request): Promise<Response> {
+    if (req.method === "OPTIONS") {
+        return new Response(null, { status: 204, headers: CORS });
+    }
+
+    const authResult = await authorize(req);
+    if (authResult instanceof Response) return authResult;
+    const { authToken, userId, callerType } = authResult;
+
+    const serverBase = (() => {
+        const u = new URL(req.url);
+        return `${u.protocol}//${u.host}`;
+    })();
+
+    let body: AgentRunRequest;
+    try {
+        body = await req.json() as AgentRunRequest;
+    } catch {
+        return agentRunError("Invalid JSON body", 400);
+    }
+
+    const parsedRequest = parseAgentRunRequestBody(body);
+    if (!parsedRequest.ok) {
+        return agentRunError(parsedRequest.error.message, parsedRequest.error.status);
+    }
+    const {
+        requestedAgentKey,
+        userInput,
+        history,
+        stream,
+        runtimeContext,
+        effectiveMaxRounds,
+        background,
+        spaceId,
+        category,
+        inheritedFromDialogKey,
+        parentDialogId,
+        runtimeProfile,
+        runtimeOptions,
+        debugContextLayers,
+        continueDialogId,
+        effectiveAgentRunTimeoutMs,
+    } = parsedRequest.value;
+    const { persistDialog = true, clientDialogId } = body;
+    const shouldPersistDialog = persistDialog !== false;
+    const normalizedClientDialogId =
+        typeof clientDialogId === "string" && clientDialogId.trim()
+            ? clientDialogId.trim()
+            : null;
+    if (!shouldPersistDialog && (!stream || !normalizedClientDialogId)) {
+        return agentRunError("persistDialog=false requires stream=true and clientDialogId", 400);
+    }
+    const userInputText = extractAgentRunUserText(userInput);
+    const directSpecialistAgentKey = resolveDirectSpecialistAgentKey({
+        agentKey: requestedAgentKey,
+        userInputText,
+        stream,
+        background,
+        continueDialogId,
+    });
+    const agentKey = directSpecialistAgentKey ?? requestedAgentKey;
+    const dialogAgentKey = requestedAgentKey;
+    const traceAgentKey = directSpecialistAgentKey ?? undefined;
+    const coreProxyTarget = resolveCoreDataProxyTarget({
+        dbKey: agentKey,
+        requestUrl: req.url,
+        coreBaseUrl: process.env.NOLO_SERVER_CORE_BASE_URL,
+    });
+    if (coreProxyTarget) {
+        return proxyAgentRunToRemote({
+            targetBase: coreProxyTarget,
+            body,
+            authToken,
+            stream,
+        });
+    }
+
+    // 读取 Agent 配置（已持久化在 LevelDB）
+    try { await ensureServerDbOpen(); } catch (e: any) { return agentRunError(e.message, 500); }
+    const agentLookup = await resolveAgentRunAgentConfig({
+        agentKey,
+        getAgentRecord: (key) => serverDb.get(key),
+    });
+    if (!agentLookup.ok) {
+        return agentRunError(agentLookup.message, agentLookup.status);
+    }
+    let agentConfig: any = agentLookup.agentConfig;
+    agentConfig = {
+        ...agentConfig,
+        dbKey: agentConfig.dbKey ?? agentKey,
+    };
+
+    const runtimeDelegation = resolveAgentRunDelegation({ agentConfig, serverBase });
+    if (!runtimeDelegation.ok) {
+        return agentRunError(runtimeDelegation.message, runtimeDelegation.status);
+    }
+    if (runtimeDelegation.route === "remote") {
+        return proxyAgentRunToRemote({
+            targetBase: runtimeDelegation.targetBase,
+            body,
+            authToken,
+            stream,
+        });
+    }
+
+    const machineBinding = resolveMachineBindingPreflight({
+        agentConfig,
+        userId,
+        listMachines: (ownerUserId) => machineRegistry.listMachines(ownerUserId),
+    });
+    if (!machineBinding.ok) {
+        return agentRunJson(machineBinding.body, machineBinding.status);
+    }
+
+    const taskRunPreflight = await resolveTaskRunPreflightContext({
+        runtimeContext,
+        authToken,
+    });
+    const taskRunPreflightPrompt = taskRunPreflight.prompt;
+    agentConfig = await prepareAgentRunRuntimeConfig({
+        agentConfig,
+        runtimeContext,
+        taskRunPreflightPrompt,
+        runtimeOptions,
+        parentDialogId,
+        inheritedFromDialogKey,
+        resolveReferenceRuntime: (references) =>
+            resolveServerReferenceRuntime({
+                references,
+                loadPage: async (identifier: string) => {
+                    try {
+                        return await serverDb.get(identifier);
+                    } catch {
+                        return null;
+                    }
+                },
+            }),
+        buildInheritedDialogPromptBlock: (args) =>
+            buildInheritedDialogPromptBlock({
+                ...args,
+                getDialogRecord: async (dialogKey) => {
+                    try {
+                        return await serverDb.get(dialogKey);
+                    } catch {
+                        return null;
+                    }
+                },
+                fetchConversationMessages: fetchConvMsgs,
+            }),
+    });
+    const runtimeToolPolicySnapshot = resolveEffectiveRuntimeToolPolicy({
+        agentConfig,
+        taskRunControl: taskRunPreflight.control,
+        host: "web",
+    });
+
+    // 余额检查（仅 JWT 登录用户）
+    const bypassBalanceCheck = shouldBypassBalanceForLocalSmokeAgent(agentKey, agentConfig, serverBase);
+    if (userId && !bypassBalanceCheck) {
+        const user = await getUser(userId);
+        const balanceCheck = checkBasicBalance(user?.balance ?? 0);
+        if (!balanceCheck.allowed) {
+            return agentRunJson({ error: balanceCheck.error }, 402);
+        }
+    }
+
+    const {
+        contextHistory,
+        existingDialogRecord,
+        existingDialogKey,
+        continueDialogUserId,
+    } = await resolveContinueDialogContext({
+        continueDialogId,
+        history,
+        userId,
+        resolveExistingDialogRef,
+        fetchConvMsgs,
+        summarizeMessagesForDebug,
+    });
+
+    const executionContext = await prepareAgentRunExecutionContext({
+        agentConfig,
+        agentKey,
+        userId,
+        userInput,
+        userInputText,
+        contextHistory,
+        spaceId,
+        runtimeProfile,
+        existingDialogRecord,
+        taskRunPreflightPrompt,
+        loadUserSettings: (settingsUserId) =>
+            serverDb.get(createUserKey.settings(settingsUserId)),
+        resolveRuntimePolicy,
+        buildUserPolicyContext,
+        resolveMemoryRuntime,
+        resolveAutonomousRuntimeContext,
+        buildRuntimeSystemMessageContext,
+        buildAgentRunUserMessageContent,
+        canonicalizeToolNames,
+        prioritizeToolNames,
+    });
+    agentConfig = executionContext.agentConfig;
+    const runtimePolicy = executionContext.runtimePolicy;
+    const effectiveRuntimeProfile = executionContext.effectiveRuntimeProfile;
+    const memoryRuntime = executionContext.memoryRuntime;
+    const autonomousRuntime = executionContext.autonomousRuntime;
+    const runtimeSystemMessageContext = executionContext.runtimeSystemMessageContext;
+    const messages = executionContext.messages;
+
+    try {
+        await ensureLocalModelRuntimeIfNeeded(agentConfig);
+    } catch (e: any) {
+        if (isLocalRuntimeUnavailableError(e)) {
+            return agentRunJson({
+                error: "Local provider unavailable",
+                reason: e.reason,
+                message: e.message,
+            }, e.status);
+        }
+        return agentRunError(e.message ?? "Local provider runtime check failed", 500);
+    }
+
+    const prepareCurrentForegroundStreamDialog = async (): Promise<
+        Awaited<ReturnType<typeof prepareForegroundStreamDialog>> & { persistDialog: boolean }
+    > => {
+        if (!shouldPersistDialog) {
+            return {
+                dialogId: normalizedClientDialogId!,
+                dialogKey: "",
+                effectiveUserId: userId,
+                effectiveSpaceId: spaceId,
+                persistDialog: false,
+            };
+        }
+        const prepared = await prepareForegroundStreamDialog({
+            continueDialogId,
+            existingDialogKey,
+            existingDialogRecord,
+            continueDialogUserId,
+            fallbackSpaceId: spaceId,
+            createPendingDialog,
+            pendingDialogInput: {
+                agentKey: dialogAgentKey,
+                userId,
+                callerType,
+                userInput: userInputText,
+                spaceId,
+                category,
+                inheritedFromDialogKey,
+                parentDialogId,
+                runtimeProfile: effectiveRuntimeProfile,
+                runtimeContext,
+                runtimeToolPolicySnapshot,
+            },
+        });
+        return {
+            ...prepared,
+            persistDialog: true,
+        };
+    };
+
+    if (stream) {
+        try {
+            const connectorResult = await runViaMachineConnector({
+                agentConfig,
+                agentKey,
+                category,
+                continueDialogId: continueDialogId ?? undefined,
+                messages,
+                runtimeContext,
+                spaceId,
+                userId,
+                userInput: userInputText,
+                requestTimeoutMs: effectiveAgentRunTimeoutMs,
+                runtimeToolPolicySnapshot,
+            });
+            if (connectorResult) {
+                const workspaceLease = buildWorkspaceLeaseFromConnectorResult({
+                    result: connectorResult,
+                    agentKey,
+                    machineId: resolveAgentRuntimeMachineId(agentConfig),
+                    runtimeToolPolicySnapshot,
+                });
+                const streamDialog = await prepareCurrentForegroundStreamDialog();
+                const startedAt = Date.now();
+                return agentRunSse(buildBillableForegroundSseStream(
+                    buildMachineConnectorSseStream(connectorResult),
+                    {
+                        agentConfig,
+                        agentKey,
+                        dialogAgentKey,
+                        traceAgentKey,
+                        userId: streamDialog.effectiveUserId,
+                        dialogId: streamDialog.dialogId,
+                        dialogKey: streamDialog.dialogKey,
+                        userInputText,
+                        startedAt,
+                        isContinue: Boolean(continueDialogId),
+                        spaceId: streamDialog.effectiveSpaceId,
+                        runtimeProfile: effectiveRuntimeProfile,
+                        runtimeToolPolicySnapshot,
+                        workspaceLease,
+                        persistDialog: streamDialog.persistDialog,
+                    }
+                ));
+            }
+        } catch (e: any) {
+            const connectorFailureResponse = resolveConnectorFailureResponse(e, agentConfig);
+            if (connectorFailureResponse) return connectorFailureResponse;
+            throw e;
+        }
+        let streamDialog: Awaited<ReturnType<typeof prepareForegroundStreamDialog>>;
+        try {
+            streamDialog = await prepareCurrentForegroundStreamDialog();
+        } catch (e: any) {
+            return agentRunError(e.message ?? "Failed to create dialog", e.status ?? 500);
+        }
+        const startedAt = Date.now();
+        const sourceStream = buildSseStreamImpl(
+            agentConfig,
+            messages,
+            effectiveMaxRounds,
+            serverBase,
+            authToken,
+            runtimePolicy,
+            streamDialog.effectiveUserId,
+            streamDialog.dialogId,
+            streamDialog.effectiveSpaceId,
+            userInputText,
+            runtimeContext,
+        );
+        return agentRunSse(buildBillableForegroundSseStream(sourceStream, {
+            agentConfig,
+            agentKey,
+            dialogAgentKey,
+            traceAgentKey,
+            userId: streamDialog.effectiveUserId,
+            dialogId: streamDialog.dialogId,
+            dialogKey: streamDialog.dialogKey,
+            userInputText,
+            startedAt,
+            isContinue: Boolean(continueDialogId),
+            spaceId: streamDialog.effectiveSpaceId,
+            runtimeProfile: effectiveRuntimeProfile,
+            runtimeToolPolicySnapshot,
+            persistDialog: streamDialog.persistDialog,
+        }));
+    }
+
+    // ── background 模式：立即返回 dialogId，后台执行 ───────────────────────────
+    if (background) {
+        const backgroundDialog = await prepareBackgroundRunDialog({
+            continueDialogId,
+            existingDialogKey,
+            existingDialogRecord,
+            continueDialogUserId,
+            fallbackSpaceId: spaceId,
+            createPendingDialog,
+            pendingDialogInput: {
+                agentKey,
+                userId,
+                callerType,
+                userInput: userInputText,
+                spaceId,
+                category,
+                inheritedFromDialogKey,
+                parentDialogId,
+                runtimeProfile: effectiveRuntimeProfile,
+                runtimeContext,
+                runtimeToolPolicySnapshot,
+            },
+        });
+        if (isBackgroundRunDialogError(backgroundDialog)) {
+            return agentRunError(backgroundDialog.error, backgroundDialog.status);
+        }
+        const {
+            dialogId,
+            dialogKey,
+            effectiveUserId: effectiveBackgroundUserId,
+            effectiveSpaceId: effectiveBackgroundSpaceId,
+        } = backgroundDialog;
+        const startedAt = Date.now();
+
+        // 更新 status=running
+        try {
+            const existingDialog = await serverDb.get(dialogKey);
+            const runningAt = Date.now();
+            await serverDb.put(dialogKey, {
+                ...existingDialog,
+                status: "running",
+                startedAt,
+                updatedAt: new Date(runningAt).toISOString(),
+                runtimeCheckpoint: buildRunningRuntimeCheckpoint({
+                    dialogId,
+                    userInputText,
+                    updatedAt: runningAt,
+                    runtimeBinding: existingDialog?.runtimeBinding,
+                }),
+            });
+            await projectBackgroundDialogActivity({
+                dialogId,
+                dialogKey,
+                agentKey,
+                parentDialogId,
+                runtimeContext,
+                status: "running",
+            });
+        } catch (e) {
+            console.error(`[background] dialog=${dialogId} status update failed:`, e);
+        }
+        pushEvent(`dialog-${dialogId}`, { type: "status", status: "running" });
+
+        // 后台执行（不阻塞响应）
+        incActiveStream();
+        (async () => {
+            try {
+                const backgroundTimeoutMs =
+                    effectiveAgentRunTimeoutMs ?? DEFAULT_BACKGROUND_RUN_TIMEOUT_MS;
+                let workspaceLease: Record<string, unknown> | undefined;
+                const persistConnectorProgress = async (progress: MachineConnectorRunProgress) => {
+                    const progressAt = Date.now();
+                    try {
+                        const existingDialog = await serverDb.get(dialogKey);
+                        await serverDb.put(dialogKey, {
+                            ...existingDialog,
+                            status: "running",
+                            updatedAt: new Date(progressAt).toISOString(),
+                            runtimeCheckpoint: buildProgressRuntimeCheckpoint({
+                                existingDialog,
+                                dialogId,
+                                userInputText,
+                                progress,
+                                updatedAt: progressAt,
+                            }),
+                        });
+                        await projectBackgroundDialogActivity({
+                            dialogId,
+                            dialogKey,
+                            agentKey,
+                            parentDialogId,
+                            runtimeContext,
+                            status: "running",
+                        });
+                        pushEvent(`dialog-${dialogId}`, {
+                            type: "runtime.progress",
+                            progress,
+                        });
+                    } catch (progressError) {
+                        console.error(`[background] dialog=${dialogId} progress persist failed:`, progressError);
+                    }
+                };
+                const runtimePromptPage = await createRuntimePromptPageIfLarge({
+                    agentConfig,
+                    agentKey,
+                    dialogId,
+                    runtimeContext,
+                    spaceId: effectiveBackgroundSpaceId,
+                    userId: effectiveBackgroundUserId,
+                    userInputText,
+                }).catch((error) => {
+                    console.warn("[agentRun.background] runtime prompt page create failed", {
+                        dialogId,
+                        agentKey,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    return null;
+                });
+                if (runtimePromptPage) {
+                    await persistConnectorProgress({
+                        message: "runtime-prompt-page-created",
+                        promptPageKey: runtimePromptPage.dbKey,
+                        promptPageHash: runtimePromptPage.promptHash,
+                        promptBytes: runtimePromptPage.contentBytes,
+                        updatedAt: Date.now(),
+                    });
+                }
+                const result = await withBackgroundRunTimeout((async () => {
+                    console.log("[agentRun.background] dispatch", {
+                        dialogId,
+                        agentKey,
+                        backgroundTimeoutMs,
+                        userInputBytes: byteLength(userInputText),
+                        runtimePromptPageKey: runtimePromptPage?.dbKey,
+                    });
+                    const connectorResult = await runViaMachineConnector({
+                        agentConfig,
+                        agentKey,
+                        category,
+                        continueDialogId: continueDialogId ?? undefined,
+                        messages,
+                        runtimeContext,
+                        spaceId,
+                        userId: effectiveBackgroundUserId,
+                        userInput: userInputText,
+                        requestTimeoutMs: backgroundTimeoutMs,
+                        runtimeToolPolicySnapshot,
+                        runtimePromptPage,
+                        onProgress: persistConnectorProgress,
+                    });
+                    console.log("[agentRun.background] connector-result", {
+                        dialogId,
+                        agentKey,
+                        usedMachineConnector: Boolean(connectorResult),
+                        contentBytes: byteLength(String(connectorResult?.content ?? "")),
+                    });
+                    workspaceLease = buildWorkspaceLeaseFromConnectorResult({
+                        result: connectorResult,
+                        agentKey,
+                        machineId: resolveAgentRuntimeMachineId(agentConfig),
+                        runtimeToolPolicySnapshot,
+                    });
+                    return (connectorResult ?? await runAgentLoopImpl(
+                        agentConfig,
+                        messages,
+                        effectiveMaxRounds,
+                        serverBase,
+                        authToken,
+                        runtimePolicy,
+                        effectiveBackgroundUserId,
+                        dialogId,
+                        effectiveBackgroundSpaceId,
+                        userInputText,
+                        runtimeContext,
+                    )) as LoopResult;
+                })(), backgroundTimeoutMs);
+                if (continueDialogId) {
+                    await appendToExistingDialog({
+                        dialogId,
+                        dialogKey,
+                        agentKey,
+                        userId: effectiveBackgroundUserId,
+                        userInput: userInputText,
+                        result,
+                        durationMs: Date.now() - startedAt,
+                        spaceId: effectiveBackgroundSpaceId,
+                        runtimeProfile: effectiveRuntimeProfile,
+                        runtimeContext,
+                        runtimeToolPolicySnapshot,
+                        workspaceLease,
+                    });
+                } else {
+                    await finalizeDialog({
+                        dialogId,
+                        dialogKey,
+                        agentKey,
+                        result,
+                        startedAt,
+                        status: "done",
+                        userInput: userInputText,
+                        userId,
+                        spaceId,
+                        runtimeContext,
+                        runtimeToolPolicySnapshot,
+                        workspaceLease,
+                    });
+                }
+                await projectBackgroundDialogActivity({
+                    dialogId,
+                    dialogKey,
+                    agentKey,
+                    parentDialogId,
+                    runtimeContext,
+                    status: "done",
+                });
+                pushEvent(`dialog-${dialogId}`, {
+                    type: "done",
+                    content: result.content,
+                    usage: result.usage,
+                });
+                if (effectiveBackgroundSpaceId) {
+                    pushEvent(`space-${effectiveBackgroundSpaceId}`, { type: "dialog.done", dialogId });
+                }
+                await writeAgentRunBillingIfNeeded({
+                    agentConfig,
+                    agentKey,
+                    result,
+                    dialogId,
+                    mode: "background",
+                    userId: effectiveBackgroundUserId,
+                });
+            } catch (e) {
+                console.error(`[background] dialog=${dialogId} failed:`, e);
+                const failedAt = Date.now();
+                const errorMessage = e instanceof Error ? e.message : String(e);
+                await serverDb.get(dialogKey).then((d: any) =>
+                    serverDb.put(dialogKey, {
+                        ...d,
+                        status: "failed",
+                        updatedAt: new Date(failedAt).toISOString(),
+                        finishedAt: failedAt,
+                        durationMs: Math.max(0, failedAt - startedAt),
+                        runtimeCheckpoint: {
+                            ...buildFailedRuntimeCheckpoint({
+                                existingDialog: d,
+                                dialogId,
+                                userInputText,
+                                updatedAt: failedAt,
+                                errorMessage,
+                            }),
+                            errorMessage,
+                        },
+                        errorMessage,
+                    })
+                ).catch((putErr) => { console.error(`[background] dialog=${dialogId} status persist failed:`, putErr); });
+                await projectBackgroundDialogActivity({
+                    dialogId,
+                    dialogKey,
+                    agentKey,
+                    parentDialogId,
+                    runtimeContext,
+                    status: "failed",
+                });
+                pushEvent(`dialog-${dialogId}`, {
+                    type: "failed",
+                    error: errorMessage,
+                });
+                if (effectiveBackgroundSpaceId) {
+                    pushEvent(`space-${effectiveBackgroundSpaceId}`, { type: "dialog.failed", dialogId });
+                }
+                const dialogTitle =
+                    existingDialogRecord?.title ??
+                    buildDialogFallbackTitleFromUserInput(userInputText);
+                await emitDialogStatusNotification({
+                    userId: effectiveBackgroundUserId,
+                    dialogId,
+                    dialogKey,
+                    dialogTitle,
+                    spaceId: effectiveBackgroundSpaceId,
+                    status: "failed",
+                    createdAt: failedAt,
+                    errorMessage,
+                });
+            } finally {
+                decActiveStream();
+            }
+        })().catch((e) => { console.error(`[background] unhandled rejection dialog=${dialogId}:`, e); });
+
+        return agentRunJson({ dialogId, status: "pending" }, 202);
+    }
+
+    // ── 前台同步模式 ───────────────────────────────────────────────────────────
+    try {
+        const startTime = Date.now();
+        // 注意：sync 新建 dialog 的首轮执行在 saveRunAsDialog 之前，runAgentLoop 此时还拿不到最终 dialogId。
+        // 这意味着首轮 server-side external tool charge 还无法稳定投影进 dialog.totalCost；
+        // continue/background 场景已有 dialogId，可正常回写。后续若要补齐这里，需要先拿稳定 dialogId 再执行工具链。
+        const connectorResult = await runViaMachineConnector({
+            agentConfig,
+            agentKey,
+            category,
+            continueDialogId: continueDialogId ?? undefined,
+            messages,
+            runtimeContext,
+            spaceId,
+            userId,
+            userInput: userInputText,
+            requestTimeoutMs: effectiveAgentRunTimeoutMs,
+            runtimeToolPolicySnapshot,
+        });
+        const workspaceLease = buildWorkspaceLeaseFromConnectorResult({
+            result: connectorResult,
+            agentKey,
+            machineId: resolveAgentRuntimeMachineId(agentConfig),
+            runtimeToolPolicySnapshot,
+        });
+        const result = (connectorResult ?? await runAgentLoopImpl(
+            agentConfig,
+            messages,
+            effectiveMaxRounds,
+            serverBase,
+            authToken,
+            runtimePolicy,
+            userId,
+            continueDialogId ?? undefined,
+            spaceId,
+            userInputText,
+            runtimeContext,
+        )) as LoopResult;
+        const durationMs = Date.now() - startTime;
+
+        const { dialogId, dialogKey } = await completeSyncAgentRunDialog({
+            continueDialogId,
+            existingDialogKey,
+            dialogAgentKey,
+            traceAgentKey,
+            userId,
+            continueDialogUserId,
+            callerType,
+            userInput: userInputText,
+            result,
+            durationMs,
+            spaceId,
+            category,
+            inheritedFromDialogKey,
+            parentDialogId,
+            runtimeProfile: effectiveRuntimeProfile,
+            runtimeContext,
+            runtimeToolPolicySnapshot,
+            workspaceLease,
+            appendToExistingDialog,
+            saveRunAsDialog,
+            summarizeMessagesForDebug,
+        });
+        await writeAgentRunBillingIfNeeded({
+            agentConfig,
+            agentKey,
+            result,
+            dialogId,
+            mode: "sync",
+            userId,
+        });
+
+        const debugContext = buildAgentRunDebugContext({
+            enabled: debugContextLayers,
+            runtimeSystemMessageContext,
+            selectedMemoryItems: memoryRuntime.selectedItems,
+        });
+
+        return agentRunJson({
+            ...result,
+            dialogId,
+            dialogKey,
+            ...(debugContext ? { debug: debugContext } : {}),
+        });
+    } catch (e: any) {
+        const connectorFailureResponse = resolveConnectorFailureResponse(e, agentConfig);
+        if (connectorFailureResponse) return connectorFailureResponse;
+        return agentRunError(e.message ?? "Internal server error", 500);
+    }
+}