nolo-cli 0.1.30 → 0.1.32

package/server/handlers/agentRun/index.ts

@@ -1,1630 +0,0 @@
-// 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);
-    }
-}