nolo-cli 0.1.26 → 0.1.29

package/server/handlers/agentRun/saveDialog.ts

@@ -0,0 +1,1373 @@
+// packages/server/handlers/agentRun/saveDialog.ts
+// 将 agentRun 执行结果持久化为真实 Dialog（含完整消息轨迹），所有调用方含 localhost。
+
+import { formatISO } from "date-fns";
+import { monotonicFactory } from "ulid";
+import serverDb from "../../../database/server/db";
+import { createKey, createDialogKey, createDialogMessageKeyAndId } from "../../../database/keys";
+import { extractCustomId } from "../../../core/prefix";
+import { DataType } from "../../../create/types";
+import { createSpaceKey } from "../../../create/space/spaceKeys";
+import { fetchMessages } from "../../../chat/messages/fetchMessages";
+import { pushEvent } from "../eventBus";
+import { emitDialogStatusNotification } from "../notificationEmitter";
+import type { LoopResult } from "./types";
+import { extractDialogUserId } from "./dialogLookup";
+import { summarizeMessagesForDebug } from "../../../chat/messages/messageContract";
+import {
+    captureExplicitMemoryEpisode,
+    scheduleExplicitMemoryConsolidation,
+} from "../../../ai/memory/capture";
+import { rememberMemory } from "../../../ai/memory/remember";
+import { captureUnderstandingMemoryFromDialog } from "../../../ai/memory/understanding";
+import { buildDialogFallbackTitleFromUserInput } from "../../../chat/dialog/dialogTitle";
+import type {
+    DialogRuntimeBinding,
+    DialogRuntimeController,
+    DialogRuntimeProfile,
+    DialogSubjectRef,
+} from "../../../app/types";
+import { buildDialogRuntimeBinding } from "./runtimeBinding";
+import type { AgentRunRuntimeContext } from "./types";
+
+/**
+ * 将 Dialog 注册到 Space 的 contents 中，使其在侧边栏可见。
+ * 如果 spaceId 不存在或 space 记录读不到，静默跳过。
+ */
+async function addDialogToSpace(
+    spaceId: string,
+    dialogKey: string,
+    title: string,
+    categoryId?: string
+): Promise<void> {
+    const spaceKey = createSpaceKey.space(spaceId);
+    let spaceData: any;
+    try {
+        spaceData = await serverDb.get(spaceKey);
+    } catch (_) {
+        return; // space 不存在，跳过
+    }
+    if (!spaceData) return;
+    const existingContent = spaceData?.contents?.[dialogKey];
+    if (
+        existingContent &&
+        existingContent.title === title &&
+        (categoryId
+            ? existingContent.categoryId === categoryId
+            : !("categoryId" in existingContent))
+    ) {
+        return;
+    }
+
+    const now = Date.now();
+    const nextContent = {
+        ...(existingContent ?? {}),
+        title: title.trim(),
+        type: DataType.DIALOG,
+        contentKey: dialogKey,
+        pinned: existingContent?.pinned ?? false,
+        createdAt: existingContent?.createdAt ?? now,
+        updatedAt: now,
+    } as Record<string, any>;
+    delete nextContent.categoryId;
+    if (categoryId) {
+        nextContent.categoryId = categoryId;
+    }
+    await serverDb.put(spaceKey, {
+        ...spaceData,
+        updatedAt: now,
+        contents: {
+            ...(spaceData.contents ?? {}),
+            [dialogKey]: nextContent,
+        },
+    });
+}
+
+async function resolveSpaceName(spaceId?: string): Promise<string | undefined> {
+    if (!spaceId) return undefined;
+    try {
+        const space = await serverDb.get(createSpaceKey.space(spaceId));
+        if (typeof space?.name === "string" && space.name.trim()) {
+            return space.name;
+        }
+    } catch (_) { }
+    return undefined;
+}
+
+function summarizeTraceMessages(messages: Array<{ role?: string; content?: any }> | null | undefined) {
+    const safeMessages = Array.isArray(messages) ? messages : [];
+    return {
+        count: safeMessages.length,
+        roles: safeMessages.map((message) => message?.role ?? "unknown"),
+        imageMessageCount: safeMessages.filter((message) =>
+            Array.isArray(message?.content) &&
+            message.content.some((part: any) => part?.type === "image_url"),
+        ).length,
+    };
+}
+
+function buildPersistedTraceMessage(opts: {
+    info: { key: string; messageId: string };
+    msg: any;
+    nowIso: string;
+    defaultAgentKey: string;
+    toolName?: string;
+    parentMessageId?: string;
+}) {
+    const { info, msg, nowIso, defaultAgentKey, toolName, parentMessageId } = opts;
+    const messageAgentKey =
+        typeof msg?.agentKey === "string" && msg.agentKey.trim()
+            ? msg.agentKey.trim()
+            : typeof msg?.cybotKey === "string" && msg.cybotKey.trim()
+                ? msg.cybotKey.trim()
+                : defaultAgentKey;
+
+    return {
+        id: info.messageId,
+        dbKey: info.key,
+        role: msg.role,
+        content: msg.content ?? null,
+        cybotKey: messageAgentKey,
+        ...(messageAgentKey ? { agentKey: messageAgentKey } : {}),
+        ...(typeof msg?.agentName === "string" && msg.agentName.trim()
+            ? { agentName: msg.agentName.trim() }
+            : {}),
+        createdAt: nowIso,
+        ...(msg.role === "tool" && toolName ? { toolName } : {}),
+        ...(msg.role === "tool" && parentMessageId ? { parentMessageId } : {}),
+        ...((msg as any).tool_calls ? { tool_calls: (msg as any).tool_calls } : {}),
+        ...((msg as any).tool_call_id ? { toolCallId: (msg as any).tool_call_id } : {}),
+        ...(typeof msg?.parallelSessionId === "string"
+            ? { parallelSessionId: msg.parallelSessionId }
+            : {}),
+        ...(typeof msg?.parallelBranchId === "string"
+            ? { parallelBranchId: msg.parallelBranchId }
+            : {}),
+        ...(typeof msg?.parallelLabel === "string"
+            ? { parallelLabel: msg.parallelLabel }
+            : {}),
+        ...(typeof msg?.parallelIndex === "number"
+            ? { parallelIndex: msg.parallelIndex }
+            : {}),
+    };
+}
+
+function contentToPlainText(content: any): string | null {
+    if (typeof content === "string") {
+        const normalized = content.trim();
+        return normalized || null;
+    }
+    if (Array.isArray(content)) {
+        const text = content
+            .filter((part: any) => part?.type === "text" && typeof part.text === "string")
+            .map((part: any) => part.text)
+            .join("")
+            .trim();
+        return text || null;
+    }
+    return null;
+}
+
+function normalizeDialogTaskLabel(value: unknown): string | undefined {
+    if (typeof value !== "string") return undefined;
+    const trimmed = value.trim();
+    if (!trimmed) return undefined;
+    return trimmed.length > 120 ? `${trimmed.slice(0, 117)}...` : trimmed;
+}
+
+function mergeDialogTags(existing: unknown, additions: Array<string | null | undefined>): string[] | undefined {
+    const normalized = new Set<string>();
+    if (Array.isArray(existing)) {
+        for (const tag of existing) {
+            if (typeof tag !== "string") continue;
+            const trimmed = tag.trim();
+            if (trimmed) normalized.add(trimmed);
+        }
+    }
+    for (const tag of additions) {
+        if (typeof tag !== "string") continue;
+        const trimmed = tag.trim();
+        if (trimmed) normalized.add(trimmed);
+    }
+    return normalized.size > 0 ? [...normalized] : undefined;
+}
+
+function asRecord(value: unknown): Record<string, any> {
+    return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, any> : {};
+}
+
+function mergeCheckpointToolNames(...values: unknown[]) {
+    const names: 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 (!names.includes(name)) names.push(name);
+        }
+    }
+    return names;
+}
+
+function stringArray(value: unknown): string[] {
+    return Array.isArray(value)
+        ? value.filter((item): item is string => typeof item === "string" && !!item.trim())
+        : [];
+}
+
+function extractArtifactRecord(value: unknown): Record<string, any> | null {
+    if (value && typeof value === "object" && !Array.isArray(value)) return value as Record<string, any>;
+    if (Array.isArray(value)) {
+        const record = value.find((item) => item && typeof item === "object" && !Array.isArray(item));
+        return record ? record as Record<string, any> : null;
+    }
+    return null;
+}
+
+function pickWorkspaceToolName(runtimeBinding?: DialogRuntimeBinding | null) {
+    const policy = asRecord(runtimeBinding?.runtimeToolPolicySnapshot);
+    const runtimeTools = stringArray(policy.runtimeTools);
+    if (runtimeTools.includes("execShell")) return "execShell";
+    return "workspaceArtifact";
+}
+
+function buildArtifactCheckpointFacts(opts: {
+    result: LoopResult;
+    runtimeBinding?: DialogRuntimeBinding | null;
+}) {
+    const artifact = extractArtifactRecord(opts.result.artifacts);
+    const changedFiles = stringArray(artifact?.changedFiles);
+    const statusShort = typeof artifact?.statusShort === "string" && artifact.statusShort.trim()
+        ? artifact.statusShort.trim()
+        : "";
+    if (changedFiles.length === 0 && !statusShort) {
+        return {
+            toolCallCount: 0,
+            toolCount: 0,
+            lastToolNames: [] as string[],
+            workspaceProgress: {},
+        };
+    }
+
+    const workspaceLease = asRecord(opts.runtimeBinding?.workspaceLease);
+    const workspaceRoot =
+        typeof workspaceLease.workspaceRoot === "string" && workspaceLease.workspaceRoot.trim()
+            ? workspaceLease.workspaceRoot.trim()
+            : typeof artifact?.cwd === "string" && artifact.cwd.trim()
+                ? artifact.cwd.trim()
+                : undefined;
+    const policy = asRecord(opts.runtimeBinding?.runtimeToolPolicySnapshot);
+    const workspace = asRecord(policy.workspace);
+    const workspaceMode = typeof workspace.mode === "string" && workspace.mode.trim()
+        ? workspace.mode.trim()
+        : undefined;
+
+    return {
+        toolCallCount: 1,
+        toolCount: 1,
+        lastToolNames: [pickWorkspaceToolName(opts.runtimeBinding)],
+        workspaceProgress: {
+            ...(workspaceRoot ? { workspaceRoot } : {}),
+            ...(workspaceMode ? { workspaceKind: workspaceMode } : {}),
+            ...(changedFiles.length > 0 ? { changedFiles } : {}),
+            ...(statusShort ? { statusShort } : {}),
+        },
+    };
+}
+
+function buildRuntimeCheckpoint(opts: {
+    dialogId: string;
+    status: "done" | "failed";
+    userInput: string;
+    result: LoopResult;
+    lastAssistantMessageId?: string;
+    toolCallIdToName?: Map<string, string>;
+    runtimeBinding?: DialogRuntimeBinding | null;
+    previousRuntimeCheckpoint?: unknown;
+}): Record<string, any> {
+    const trace = Array.isArray(opts.result.trace) ? opts.result.trace : [];
+    const assistantMessages = trace.filter((msg) => msg?.role === "assistant");
+    const toolMessages = trace.filter((msg) => msg?.role === "tool");
+    const previous = asRecord(opts.previousRuntimeCheckpoint);
+    const previousTraceSummary = asRecord(previous.traceSummary);
+    const lastAssistantText =
+        contentToPlainText(assistantMessages.at(-1)?.content) ??
+        contentToPlainText(opts.result.content) ??
+        null;
+    const lastToolNames = Array.from(
+        new Set(
+            toolMessages
+                .map((msg: any) =>
+                    typeof msg?.tool_call_id === "string"
+                        ? opts.toolCallIdToName?.get(msg.tool_call_id) ?? null
+                        : null
+                )
+                .filter((name): name is string => typeof name === "string" && !!name.trim())
+        )
+    );
+    const previousToolCallCount =
+        typeof previous.toolCallCount === "number" && Number.isFinite(previous.toolCallCount)
+            ? previous.toolCallCount
+            : 0;
+    const resultToolCallCount =
+        typeof opts.result.toolCallCount === "number" && Number.isFinite(opts.result.toolCallCount)
+            ? opts.result.toolCallCount
+            : 0;
+    const previousToolMessageCount =
+        typeof previousTraceSummary.toolCount === "number" && Number.isFinite(previousTraceSummary.toolCount)
+            ? previousTraceSummary.toolCount
+            : 0;
+    const artifactFacts = buildArtifactCheckpointFacts({
+        result: opts.result,
+        runtimeBinding: opts.runtimeBinding,
+    });
+    const workspaceProgress = {
+        ...asRecord(previous.workspaceProgress),
+        ...artifactFacts.workspaceProgress,
+    };
+
+    return {
+        ...previous,
+        version: 1,
+        status: opts.status,
+        dialogId: opts.dialogId,
+        updatedAt: Date.now(),
+        lastUserInput: opts.userInput,
+        lastAssistantText,
+        ...(opts.lastAssistantMessageId ? { lastAssistantMessageId: opts.lastAssistantMessageId } : {}),
+        toolCallCount: Math.max(resultToolCallCount, previousToolCallCount, artifactFacts.toolCallCount),
+        traceSummary: {
+            assistantCount: assistantMessages.length,
+            toolCount: Math.max(toolMessages.length, previousToolMessageCount, artifactFacts.toolCount),
+        },
+        lastToolNames: mergeCheckpointToolNames(previous.lastToolNames, lastToolNames, artifactFacts.lastToolNames),
+        availableToolNames: Array.isArray(opts.result.runtimeToolNames)
+            ? opts.result.runtimeToolNames
+            : [],
+        ...(Object.keys(workspaceProgress).length > 0 ? { workspaceProgress } : {}),
+        ...(opts.runtimeBinding ? { runtimeBinding: opts.runtimeBinding } : {}),
+        ...(opts.result.latencyProfile ? { latencyProfile: opts.result.latencyProfile } : {}),
+        ...(opts.result.policyState ? { policyState: opts.result.policyState } : {}),
+    };
+}
+
+function parseJsonObject(raw: unknown): Record<string, any> | null {
+    if (typeof raw !== "string" || !raw.trim()) return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : null;
+    } catch {
+        return null;
+    }
+}
+
+function normalizeNonEmptyString(value: unknown): string | undefined {
+    if (typeof value !== "string") return undefined;
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+
+function uniqueStrings(values: Array<string | null | undefined>): string[] {
+    return [
+        ...new Set(
+            values.filter((value): value is string => typeof value === "string" && !!value.trim())
+        ),
+    ];
+}
+
+function normalizeSubjectRef(ref: unknown): DialogSubjectRef | null {
+    if (!ref || typeof ref !== "object") return null;
+    const raw = ref as Record<string, unknown>;
+    const kind = normalizeNonEmptyString(raw.kind);
+    const id = normalizeNonEmptyString(raw.id);
+    if (!kind || !id) return null;
+    const role = normalizeNonEmptyString(raw.role);
+    return {
+        kind,
+        id,
+        ...(role ? { role } : {}),
+    };
+}
+
+function mergeSubjectRefs(...groups: unknown[]): DialogSubjectRef[] | undefined {
+    const refs: DialogSubjectRef[] = [];
+    const seen = new Set<string>();
+    for (const group of groups) {
+        if (!Array.isArray(group)) continue;
+        for (const item of group) {
+            const ref = normalizeSubjectRef(item);
+            if (!ref) continue;
+            const key = `${ref.kind}:${ref.id}:${ref.role ?? ""}`;
+            if (seen.has(key)) continue;
+            seen.add(key);
+            refs.push(ref);
+        }
+    }
+    return refs.length ? refs : undefined;
+}
+
+function buildRuntimeSubjectRefs(runtimeContext?: AgentRunRuntimeContext | null): DialogSubjectRef[] | undefined {
+    const taskRun = runtimeContext?.taskRun;
+    const taskRefs: DialogSubjectRef[] = [];
+    if (taskRun?.rowDbKey) {
+        taskRefs.push({ kind: "table-row", id: taskRun.rowDbKey, role: "subject" });
+    }
+    if (taskRun?.workItemId) {
+        taskRefs.push({ kind: "table-row", id: taskRun.workItemId, role: "work-item" });
+    }
+    for (const artifactId of taskRun?.artifactIds ?? []) {
+        taskRefs.push({ kind: "external", id: artifactId, role: "artifact" });
+    }
+    return mergeSubjectRefs(runtimeContext?.subjectRefs, taskRefs);
+}
+
+function buildToolTraceFacts(args: {
+    trace: any[];
+    toolCallIdToName: Map<string, string>;
+}): {
+    toolsUsed?: string[];
+    writtenFiles?: string[];
+    toolErrors?: string[];
+    artifacts?: Record<string, any>;
+} {
+    const writeToolNames = new Set([
+        "applyEdit",
+        "applyLineEdits",
+        "writeFile",
+        "createDoc",
+        "updateDoc",
+    ]);
+    const toolCallIdToArgs = new Map<string, Record<string, any>>();
+    const toolsUsed: string[] = [];
+    const writtenFiles: string[] = [];
+    const toolErrors: string[] = [];
+
+    for (const msg of args.trace) {
+        if (msg?.role !== "assistant" || !Array.isArray(msg?.tool_calls)) continue;
+        for (const call of msg.tool_calls) {
+            const callId = normalizeNonEmptyString(call?.id);
+            const toolName = normalizeNonEmptyString(call?.function?.name);
+            if (toolName) toolsUsed.push(toolName);
+            if (!callId) continue;
+            const parsedArgs = parseJsonObject(call?.function?.arguments);
+            if (parsedArgs) toolCallIdToArgs.set(callId, parsedArgs);
+        }
+    }
+
+    for (const msg of args.trace) {
+        if (msg?.role !== "tool") continue;
+        const callId = normalizeNonEmptyString(msg?.tool_call_id);
+        const toolName = callId ? args.toolCallIdToName.get(callId) : undefined;
+        if (toolName) toolsUsed.push(toolName);
+        const callArgs = callId ? toolCallIdToArgs.get(callId) : undefined;
+        const content = parseJsonObject(msg?.content);
+
+        if (toolName && writeToolNames.has(toolName)) {
+            writtenFiles.push(
+                normalizeNonEmptyString(callArgs?.filePath) ??
+                normalizeNonEmptyString(content?.filePath) ??
+                ""
+            );
+        }
+        if (content?.ok === false || content?.success === false || content?.applied === false || content?.error) {
+            toolErrors.push(toolName ?? callId ?? "unknown-tool");
+        }
+    }
+
+    const normalizedWrittenFiles = uniqueStrings(writtenFiles);
+    const normalizedToolsUsed = uniqueStrings(toolsUsed);
+    const normalizedToolErrors = uniqueStrings(toolErrors);
+    return {
+        ...(normalizedToolsUsed.length ? { toolsUsed: normalizedToolsUsed } : {}),
+        ...(normalizedWrittenFiles.length ? { writtenFiles: normalizedWrittenFiles } : {}),
+        ...(normalizedToolErrors.length ? { toolErrors: normalizedToolErrors } : {}),
+        ...(normalizedWrittenFiles.length
+            ? {
+                artifacts: {
+                    source: "platform-tool-trace",
+                    type: "workspace-write",
+                    changedFiles: normalizedWrittenFiles,
+                    writtenFiles: normalizedWrittenFiles,
+                    toolsUsed: normalizedToolsUsed.filter((tool) => writeToolNames.has(tool)),
+                },
+            }
+            : {}),
+    };
+}
+
+function mergeResultArtifactFacts(result: LoopResult, derived: ReturnType<typeof buildToolTraceFacts>) {
+    return {
+        ...(result.artifacts
+            ? { artifacts: result.artifacts }
+            : derived.artifacts
+                ? { artifacts: derived.artifacts }
+                : {}),
+        ...(derived.writtenFiles ? { writtenFiles: derived.writtenFiles } : {}),
+        ...(derived.toolsUsed ? { toolsUsed: derived.toolsUsed } : {}),
+        ...(derived.toolErrors ? { toolErrors: derived.toolErrors } : {}),
+    };
+}
+
+type UiAskChoiceSelection = {
+    question: string;
+    choiceLabel: string;
+    userMessage: string;
+};
+
+function parseUiAskChoiceContent(rawContent: unknown): {
+    type: "ui_ask_choice";
+    question?: string;
+    choices?: Array<{ label?: string; userMessage?: string }>;
+} | null {
+    const parsed =
+        typeof rawContent === "string"
+            ? (() => {
+                try {
+                    return JSON.parse(rawContent);
+                } catch {
+                    return null;
+                }
+            })()
+            : rawContent;
+
+    if (!parsed || typeof parsed !== "object") return null;
+    if ((parsed as any).type !== "ui_ask_choice") return null;
+    return parsed as {
+        type: "ui_ask_choice";
+        question?: string;
+        choices?: Array<{ label?: string; userMessage?: string }>;
+    };
+}
+
+async function findRecentUiAskChoiceSelection(opts: {
+    dialogId: string;
+    userInput: string;
+}): Promise<UiAskChoiceSelection | null> {
+    const normalizedUserInput = opts.userInput.trim();
+    if (!normalizedUserInput) return null;
+
+    const previousMessages = await fetchMessages(serverDb, opts.dialogId, {
+        limit: 12,
+        throwOnError: true,
+    });
+
+    for (const message of previousMessages) {
+        if (message.role !== "tool") continue;
+        const parsed = parseUiAskChoiceContent(message.content);
+        if (!parsed) continue;
+
+        const matchedChoice = (parsed.choices ?? []).find((choice) => {
+            const candidate = String(choice.userMessage ?? choice.label ?? "").trim();
+            return candidate === normalizedUserInput;
+        });
+        if (!matchedChoice) return null;
+
+        return {
+            question: String(parsed.question ?? "").trim(),
+            choiceLabel: String(matchedChoice.label ?? matchedChoice.userMessage ?? "").trim(),
+            userMessage: normalizedUserInput,
+        };
+    }
+
+    return null;
+}
+
+function buildUiAskChoiceMemoryContent(selection: UiAskChoiceSelection): string {
+    const questionPart = selection.question
+        ? `在选项问题「${selection.question}」中，`
+        : "在一次选项选择中，";
+
+    if (
+        selection.choiceLabel &&
+        selection.choiceLabel !== selection.userMessage
+    ) {
+        return `${questionPart}用户选择了「${selection.choiceLabel}」，对应表达是「${selection.userMessage}」。`;
+    }
+
+    return `${questionPart}用户选择了「${selection.userMessage}」。`;
+}
+
+export interface SavedDialog {
+    dialogId: string;
+    dialogKey: string;
+}
+
+async function buildDialogLineageFields(opts: {
+    inheritedFromDialogKey?: string;
+    parentDialogId?: string;
+}): Promise<{
+    inheritedFromDialogKey?: string;
+    inheritedFromDialogTitle?: string;
+    parentDialogId?: string;
+    rootDialogId?: string;
+}> {
+    const inheritedFromDialogKey = opts.inheritedFromDialogKey?.trim();
+    const explicitParentDialogId = opts.parentDialogId?.trim();
+
+    if (!inheritedFromDialogKey) {
+        return explicitParentDialogId
+            ? { parentDialogId: explicitParentDialogId, rootDialogId: explicitParentDialogId }
+            : {};
+    }
+
+    let inheritedFromDialogTitle: string | undefined;
+    let parentDialog: any;
+    try {
+        parentDialog = await serverDb.get(inheritedFromDialogKey);
+        if (typeof parentDialog?.title === "string" && parentDialog.title.trim()) {
+            inheritedFromDialogTitle = parentDialog.title.trim();
+        }
+    } catch (_) { }
+
+    const derivedParentDialogId =
+        inheritedFromDialogKey.split("-").at(-1) || extractCustomId(inheritedFromDialogKey);
+    const parentDialogId = explicitParentDialogId || derivedParentDialogId;
+    const rootDialogId =
+        normalizeNonEmptyString(parentDialog?.rootDialogId) ??
+        normalizeNonEmptyString(parentDialog?.parentDialogId) ??
+        parentDialogId;
+
+    return {
+        inheritedFromDialogKey,
+        ...(inheritedFromDialogTitle ? { inheritedFromDialogTitle } : {}),
+        parentDialogId,
+        rootDialogId,
+    };
+}
+
+/**
+ * 立即写入 status=pending 的 Dialog 骨架，供 background 模式先返回 dialogId。
+ */
+export async function createPendingDialog(opts: {
+    agentKey: string;
+    userId: string | null;
+    callerType: "jwt" | "localhost";
+    userInput: string;
+    spaceId?: string;
+    category?: string;
+    inheritedFromDialogKey?: string;
+    parentDialogId?: string;
+    runtimeController?: DialogRuntimeController;
+    runtimeProfile?: DialogRuntimeProfile;
+    runtimeContext?: AgentRunRuntimeContext | null;
+    runtimeToolPolicySnapshot?: Record<string, unknown> | null;
+    workspaceLease?: Record<string, unknown> | null;
+}): Promise<SavedDialog> {
+    const { agentKey, userId, callerType, userInput, spaceId, category } = opts;
+    const effectiveUserId = userId ?? "server";
+    const now = Date.now();
+    const nowIso = formatISO(new Date(now));
+    const dialogTitle = buildDialogFallbackTitleFromUserInput(userInput);
+    const taskLabel = normalizeDialogTaskLabel(dialogTitle);
+
+    const dialogKey = createDialogKey(effectiveUserId);
+    const dialogId = extractCustomId(dialogKey);
+    const triggerType = callerType === "localhost" ? "localhost" : "api";
+    const lineageFields = await buildDialogLineageFields({
+        inheritedFromDialogKey: opts.inheritedFromDialogKey,
+        parentDialogId: opts.parentDialogId,
+    });
+    const subjectRefs = buildRuntimeSubjectRefs(opts.runtimeContext);
+    const runtimeBinding = buildDialogRuntimeBinding({
+        dialogId,
+        agentKey,
+        tenantUserId: userId,
+        controller: opts.runtimeController ?? "request",
+        triggerType,
+        executionMode: "background",
+        runtimeProfile: opts.runtimeProfile,
+        spaceId,
+        category,
+        runtimeToolPolicySnapshot: opts.runtimeToolPolicySnapshot,
+        workspaceLease: opts.workspaceLease,
+    });
+    const dialogTags = mergeDialogTags(undefined, [
+        `trigger:${triggerType}`,
+        "mode:background",
+    ]);
+
+    await serverDb.put(dialogKey, {
+        id: dialogId,
+        dbKey: dialogKey,
+        type: DataType.DIALOG,
+        cybots: [agentKey],
+        primaryAgentKey: agentKey,
+        title: dialogTitle,
+        ...(taskLabel ? { taskLabel } : {}),
+        createdAt: nowIso,
+        updatedAt: nowIso,
+        ...(spaceId ? { spaceId } : {}),
+        ...(category ? { category } : {}),
+        ...lineageFields,
+        ...(subjectRefs ? { subjectRefs } : {}),
+        triggerType,
+        executionMode: "background",
+        status: "pending",
+        startedAt: now,
+        runtimeBinding,
+        ...(dialogTags ? { tags: dialogTags } : {}),
+    });
+
+    // 先写用户消息（在执行前就可见）
+    const userMsgInfo = createDialogMessageKeyAndId(dialogId);
+    await serverDb.put(userMsgInfo.key, {
+        id: userMsgInfo.messageId,
+        dbKey: userMsgInfo.key,
+        role: "user",
+        content: userInput,
+        userId: effectiveUserId,
+        createdAt: nowIso,
+    });
+
+    // 绑定到 Space（使 Dialog 在侧边栏可见）并广播创建事件
+    if (spaceId) {
+        await addDialogToSpace(spaceId, dialogKey, dialogTitle, category);
+        pushEvent(`space-${spaceId}`, {
+            type: "dialog.created",
+            dialogId,
+            dialogKey,
+            title: dialogTitle,
+        });
+    }
+
+    return { dialogId, dialogKey };
+}
+
+/**
+ * 执行完成后，更新 Dialog 状态并写入 trace 消息。
+ */
+export async function finalizeDialog(opts: {
+    dialogId: string;
+    dialogKey: string;
+    agentKey: string;
+    traceAgentKey?: string;
+    result: LoopResult;
+    startedAt: number;
+    status?: "done" | "failed";
+    userInput?: string;
+    userId?: string | null;
+    spaceId?: string;
+    runtimeContext?: AgentRunRuntimeContext | null;
+    runtimeToolPolicySnapshot?: Record<string, unknown> | null;
+    workspaceLease?: Record<string, unknown> | null;
+}): Promise<void> {
+    const { dialogId, dialogKey, agentKey, result, startedAt, status = "done" } = opts;
+    const defaultTraceAgentKey = opts.traceAgentKey ?? agentKey;
+    const now = Date.now();
+    const nowIso = formatISO(new Date(now));
+    const durationMs = now - startedAt;
+
+    // 更新 Dialog 元信息
+    let existing: any = {};
+    try { existing = await serverDb.get(dialogKey); } catch (_) { }
+    const effectiveUserId = extractDialogUserId(dialogKey, dialogId) ?? existing.userId ?? null;
+    const effectiveSpaceId = existing.spaceId;
+    const runtimeBinding = buildDialogRuntimeBinding({
+        existing: existing.runtimeBinding,
+        dialogId,
+        agentKey,
+        tenantUserId: effectiveUserId,
+        triggerType: existing.triggerType,
+        executionMode: existing.executionMode,
+        spaceId: effectiveSpaceId,
+        category: existing.category,
+        runtimeToolPolicySnapshot: opts.runtimeToolPolicySnapshot,
+        workspaceLease: opts.workspaceLease,
+    });
+    const triggerType =
+        existing.triggerType ??
+        existing.runtimeBinding?.triggerType;
+    const executionMode =
+        existing.executionMode ??
+        existing.runtimeBinding?.executionMode;
+    const taskLabel =
+        normalizeDialogTaskLabel(existing.taskLabel) ??
+        normalizeDialogTaskLabel(existing.title) ??
+        normalizeDialogTaskLabel(opts.userInput);
+    const tags = mergeDialogTags(existing.tags, [
+        triggerType ? `trigger:${triggerType}` : null,
+        executionMode ? `mode:${executionMode}` : null,
+    ]);
+    const subjectRefs = mergeSubjectRefs(
+        existing.subjectRefs,
+        buildRuntimeSubjectRefs(opts.runtimeContext),
+    );
+
+    // 写入 trace 消息（assistant + tool calls/results，跳过 system 和 user）
+    // 注意：user 消息已在 createPendingDialog 中写入，这里不应重复写入
+    const trace = result.trace ?? [];
+
+    // 建立 tool_call_id -> function.name 的映射，用于写 toolName
+    const toolCallIdToName = new Map<string, string>();
+    for (const msg of trace) {
+        if (msg.role === "assistant" && Array.isArray((msg as any).tool_calls)) {
+            for (const tc of (msg as any).tool_calls) {
+                if (tc?.id && tc?.function?.name) {
+                    toolCallIdToName.set(tc.id, tc.function.name);
+                }
+            }
+        }
+    }
+    const toolTraceFacts = buildToolTraceFacts({ trace, toolCallIdToName });
+
+    await serverDb.put(dialogKey, {
+        ...existing,
+        primaryAgentKey: existing.primaryAgentKey ?? agentKey,
+        ...(taskLabel ? { taskLabel } : {}),
+        updatedAt: nowIso,
+        status,
+        finishedAt: now,
+        durationMs,
+        toolCallCount: result.toolCallCount ?? 0,
+        runtimeBinding,
+        ...(tags ? { tags } : {}),
+        ...(subjectRefs ? { subjectRefs } : {}),
+        ...mergeResultArtifactFacts(result, toolTraceFacts),
+        ...(result.policyState ? { policyState: result.policyState } : {}),
+    });
+
+    // 使用单调递增 ULID 工厂保证写入顺序 == key 顺序
+    const mono = monotonicFactory();
+    let lastAssistantMsgId: string | undefined;
+
+    for (const msg of trace) {
+        if (msg.role === "system" || msg.role === "user") continue;
+        const info = createDialogMessageKeyAndId(dialogId, mono);
+
+        const toolName = msg.role === "tool" && (msg as any).tool_call_id
+            ? toolCallIdToName.get((msg as any).tool_call_id)
+            : undefined;
+
+        await serverDb.put(info.key, buildPersistedTraceMessage({
+            info,
+            msg,
+            nowIso,
+            defaultAgentKey: defaultTraceAgentKey,
+            toolName,
+            parentMessageId: lastAssistantMsgId,
+        }));
+
+        if (msg.role === "assistant") {
+            lastAssistantMsgId = info.messageId;
+        }
+    }
+
+    const runtimeCheckpoint =
+        status === "done" && opts.userInput
+            ? buildRuntimeCheckpoint({
+                dialogId,
+                status,
+                userInput: opts.userInput,
+                result,
+                lastAssistantMessageId: lastAssistantMsgId,
+                toolCallIdToName,
+                runtimeBinding,
+                previousRuntimeCheckpoint: existing.runtimeCheckpoint,
+            })
+            : undefined;
+    if (runtimeCheckpoint) {
+        await serverDb.put(dialogKey, {
+            ...(await serverDb.get(dialogKey).catch(() => ({}))),
+            toolCallCount: runtimeCheckpoint.toolCallCount,
+            runtimeCheckpoint,
+        });
+    }
+
+    await emitDialogStatusNotification({
+        userId: effectiveUserId,
+        dialogId,
+        dialogKey,
+        dialogTitle: existing?.title,
+        spaceId: effectiveSpaceId,
+        spaceName: await resolveSpaceName(effectiveSpaceId),
+        status,
+        createdAt: now,
+    });
+
+    if (status === "done" && opts.userInput) {
+        await captureExplicitMemoryEpisode({
+            userId: opts.userId ?? null,
+            spaceId: opts.spaceId ?? effectiveSpaceId,
+            agentKey,
+            dialogId,
+            userInput: opts.userInput,
+        });
+        await captureUnderstandingMemoryFromDialog({
+            db: serverDb,
+            userId: opts.userId ?? null,
+            spaceId: opts.spaceId ?? effectiveSpaceId,
+            agentKey,
+            dialogId,
+            userInput: opts.userInput,
+            trace: result.trace,
+        });
+        scheduleExplicitMemoryConsolidation({
+            userId: opts.userId ?? null,
+            spaceId: opts.spaceId ?? effectiveSpaceId,
+            agentKey,
+            dialogId,
+            userInput: opts.userInput,
+        });
+    }
+}
+
+/**
+ * 同步（前台）模式：执行完毕后一次性写入 Dialog + 所有消息。
+ */
+export async function saveRunAsDialog(opts: {
+    agentKey: string;
+    traceAgentKey?: string;
+    userId: string | null;
+    callerType: "jwt" | "localhost";
+    userInput: string;
+    result: LoopResult;
+    durationMs: number;
+    spaceId?: string;
+    category?: string;
+    inheritedFromDialogKey?: string;
+    parentDialogId?: string;
+    runtimeController?: DialogRuntimeController;
+    runtimeProfile?: DialogRuntimeProfile;
+    runtimeContext?: AgentRunRuntimeContext | null;
+    runtimeToolPolicySnapshot?: Record<string, unknown> | null;
+    workspaceLease?: Record<string, unknown> | null;
+}): Promise<SavedDialog> {
+    const { agentKey, userId, callerType, userInput, result, durationMs, spaceId, category } = opts;
+    const defaultTraceAgentKey = opts.traceAgentKey ?? agentKey;
+    const effectiveUserId = userId ?? "server";
+    const now = Date.now();
+    const nowIso = formatISO(new Date(now));
+    const dialogTitle = buildDialogFallbackTitleFromUserInput(userInput);
+    const taskLabel = normalizeDialogTaskLabel(dialogTitle);
+
+    const dialogKey = createDialogKey(effectiveUserId);
+    const dialogId = extractCustomId(dialogKey);
+    const triggerType = callerType === "localhost" ? "localhost" : "api";
+    const lineageFields = await buildDialogLineageFields({
+        inheritedFromDialogKey: opts.inheritedFromDialogKey,
+        parentDialogId: opts.parentDialogId,
+    });
+    const subjectRefs = buildRuntimeSubjectRefs(opts.runtimeContext);
+    const runtimeBinding = buildDialogRuntimeBinding({
+        dialogId,
+        agentKey,
+        tenantUserId: userId,
+        controller: opts.runtimeController ?? "request",
+        triggerType,
+        executionMode: "foreground",
+        runtimeProfile: opts.runtimeProfile,
+        spaceId,
+        category,
+        runtimeToolPolicySnapshot: opts.runtimeToolPolicySnapshot,
+        workspaceLease: opts.workspaceLease,
+    });
+    const dialogTags = mergeDialogTags(undefined, [
+        `trigger:${triggerType}`,
+        "mode:foreground",
+    ]);
+
+    // 使用单调递增 ULID 工厂保证 user + trace 消息的 key 顺序 == 写入/逻辑顺序
+    const mono = monotonicFactory();
+
+    const userMsgInfo = createDialogMessageKeyAndId(dialogId, mono);
+
+    const trace = result.trace ?? [];
+
+    // 建立 tool_call_id -> function.name 的映射，用于写 toolName
+    const toolCallIdToName = new Map<string, string>();
+    for (const msg of trace) {
+        if (msg.role === "assistant" && Array.isArray((msg as any).tool_calls)) {
+            for (const tc of (msg as any).tool_calls) {
+                if (tc?.id && tc?.function?.name) {
+                    toolCallIdToName.set(tc.id, tc.function.name);
+                }
+            }
+        }
+    }
+    const toolTraceFacts = buildToolTraceFacts({ trace, toolCallIdToName });
+
+    // 收集所有写入操作为 batch
+    const ops: { type: "put"; key: string; value: any }[] = [];
+
+    ops.push({
+        type: "put", key: dialogKey, value: {
+            id: dialogId,
+            dbKey: dialogKey,
+            type: DataType.DIALOG,
+            cybots: [agentKey],
+            primaryAgentKey: agentKey,
+            title: dialogTitle,
+            ...(taskLabel ? { taskLabel } : {}),
+            createdAt: nowIso,
+            updatedAt: nowIso,
+            ...(spaceId ? { spaceId } : {}),
+            ...(category ? { category } : {}),
+            ...lineageFields,
+            ...(subjectRefs ? { subjectRefs } : {}),
+            triggerType,
+            executionMode: "foreground",
+            status: "done",
+            startedAt: now - durationMs,
+            finishedAt: now,
+            durationMs,
+            toolCallCount: result.toolCallCount ?? 0,
+            runtimeBinding,
+            ...(dialogTags ? { tags: dialogTags } : {}),
+            ...mergeResultArtifactFacts(result, toolTraceFacts),
+            ...(result.policyState ? { policyState: result.policyState } : {}),
+        },
+    });
+
+    ops.push({
+        type: "put", key: userMsgInfo.key, value: {
+            id: userMsgInfo.messageId,
+            dbKey: userMsgInfo.key,
+            role: "user",
+            content: userInput,
+            userId: effectiveUserId,
+            createdAt: formatISO(new Date(now - durationMs)),
+        },
+    });
+
+    let lastAssistantMsgId: string | undefined;
+    for (const msg of trace) {
+        if (msg.role === "system" || msg.role === "user") continue;
+        const info = createDialogMessageKeyAndId(dialogId, mono);
+
+        const toolName = msg.role === "tool" && (msg as any).tool_call_id
+            ? toolCallIdToName.get((msg as any).tool_call_id)
+            : undefined;
+
+        ops.push({
+            type: "put",
+            key: info.key,
+            value: buildPersistedTraceMessage({
+                info,
+                msg,
+                nowIso,
+                defaultAgentKey: defaultTraceAgentKey,
+                toolName,
+                parentMessageId: lastAssistantMsgId,
+            }),
+        });
+
+        if (msg.role === "assistant") {
+            lastAssistantMsgId = info.messageId;
+        }
+    }
+
+    ops[0]!.value.runtimeCheckpoint = buildRuntimeCheckpoint({
+        dialogId,
+        status: "done",
+        userInput,
+        result,
+        lastAssistantMessageId: lastAssistantMsgId,
+        toolCallIdToName,
+        runtimeBinding,
+        previousRuntimeCheckpoint: undefined,
+    });
+
+    await serverDb.batch(ops);
+
+    // 绑定到 Space（使 Dialog 在侧边栏可见）
+    // 同步模式直接推 dialog.done，让前端直接跳过 running 状态
+    if (spaceId) {
+        await addDialogToSpace(spaceId, dialogKey, dialogTitle, category);
+        pushEvent(`space-${spaceId}`, {
+            type: "dialog.created",
+            dialogId,
+            dialogKey,
+            title: dialogTitle,
+        });
+        pushEvent(`space-${spaceId}`, { type: "dialog.done", dialogId });
+    }
+
+    await emitDialogStatusNotification({
+        userId: effectiveUserId,
+        dialogId,
+        dialogKey,
+        dialogTitle: dialogTitle,
+        spaceId,
+        spaceName: await resolveSpaceName(spaceId),
+        status: "done",
+        createdAt: now,
+    });
+
+    await captureExplicitMemoryEpisode({
+        userId,
+        spaceId,
+        agentKey,
+        dialogId,
+        userInput,
+    });
+    await captureUnderstandingMemoryFromDialog({
+        db: serverDb,
+        userId,
+        spaceId,
+        agentKey,
+        dialogId,
+        userInput,
+        trace: result.trace,
+    });
+    scheduleExplicitMemoryConsolidation({
+        userId,
+        spaceId,
+        agentKey,
+        dialogId,
+        userInput,
+    });
+
+    return { dialogId, dialogKey };
+}
+
+/**
+ * 追加模式：将新的 user + trace 消息追加到已有对话，更新 dialog 元数据。
+ * 适用于 continueDialogId 场景：在同一个 dialog 里追加新一轮对话。
+ */
+export async function appendToExistingDialog(opts: {
+    dialogId: string;
+    dialogKey?: string;
+    agentKey: string;
+    traceAgentKey?: string;
+    userId: string | null;
+    userInput: string;
+    result: LoopResult;
+    durationMs: number;
+    spaceId?: string;
+    runtimeController?: DialogRuntimeController;
+    runtimeProfile?: DialogRuntimeProfile;
+    runtimeContext?: AgentRunRuntimeContext | null;
+}): Promise<SavedDialog> {
+    const {
+        dialogId,
+        dialogKey: providedDialogKey,
+        agentKey,
+        traceAgentKey,
+        userId,
+        userInput,
+        result,
+        durationMs,
+        spaceId,
+    } = opts;
+    const now = Date.now();
+    const nowIso = formatISO(new Date(now));
+    const defaultTraceAgentKey = traceAgentKey ?? agentKey;
+    const fallbackDialogTitle = buildDialogFallbackTitleFromUserInput(userInput);
+
+    // 重建 dialogKey（结构：DIALOG-{userId}-{dialogId}）
+    const dialogKey =
+        providedDialogKey ??
+        createKey(DataType.DIALOG, userId ?? "server", dialogId);
+    const effectiveUserId =
+        userId ??
+        extractDialogUserId(dialogKey, dialogId) ??
+        "server";
+
+    // 更新 dialog 元数据（累加 toolCallCount / durationMs）
+    let existing: any = null;
+    try { existing = await serverDb.get(dialogKey); } catch (_) { }
+    const existingDialog =
+        existing && typeof existing === "object" ? existing : {};
+    const effectiveSpaceId = existingDialog.spaceId ?? spaceId;
+    const runtimeBinding = buildDialogRuntimeBinding({
+        existing: existingDialog.runtimeBinding,
+        dialogId,
+        agentKey,
+        tenantUserId: userId ?? extractDialogUserId(dialogKey, dialogId),
+        controller: opts.runtimeController,
+        triggerType: existingDialog.triggerType,
+        executionMode: existingDialog.executionMode,
+        runtimeProfile: opts.runtimeProfile,
+        spaceId: effectiveSpaceId,
+        category: existingDialog.category,
+        runtimeToolPolicySnapshot: opts.runtimeToolPolicySnapshot,
+        workspaceLease: opts.workspaceLease,
+    });
+    const triggerType =
+        existingDialog.triggerType ??
+        existingDialog.runtimeBinding?.triggerType;
+    const executionMode =
+        existingDialog.executionMode ??
+        existingDialog.runtimeBinding?.executionMode;
+    const taskLabel =
+        normalizeDialogTaskLabel(existingDialog.taskLabel) ??
+        normalizeDialogTaskLabel(existingDialog.title) ??
+        normalizeDialogTaskLabel(fallbackDialogTitle);
+    const tags = mergeDialogTags(existingDialog.tags, [
+        triggerType ? `trigger:${triggerType}` : null,
+        executionMode ? `mode:${executionMode}` : null,
+    ]);
+    const subjectRefs = mergeSubjectRefs(
+        existingDialog.subjectRefs,
+        buildRuntimeSubjectRefs(opts.runtimeContext),
+    );
+
+    // 使用 monotonicFactory 保证 key 顺序 == 写入/逻辑顺序
+    const mono = monotonicFactory();
+    const uiAskChoiceSelection = await findRecentUiAskChoiceSelection({
+        dialogId,
+        userInput,
+    }).catch(() => null);
+
+    // 写新 user 消息
+    const userMsgInfo = createDialogMessageKeyAndId(dialogId, mono);
+
+    const trace = result.trace ?? [];
+    console.log("[agentRun] append-dialog", {
+        dialogId,
+        dialogKey,
+        trace: summarizeMessagesForDebug(trace as any[]),
+    });
+
+    // tool_call_id -> function.name 映射，用于写 toolName
+    const toolCallIdToName = new Map<string, string>();
+    for (const msg of trace) {
+        if (msg.role === "assistant" && Array.isArray((msg as any).tool_calls)) {
+            for (const tc of (msg as any).tool_calls) {
+                if (tc?.id && tc?.function?.name) {
+                    toolCallIdToName.set(tc.id, tc.function.name);
+                }
+            }
+        }
+    }
+    const toolTraceFacts = buildToolTraceFacts({ trace, toolCallIdToName });
+
+    // 收集所有写入操作为 batch
+    const ops: { type: "put"; key: string; value: any }[] = [];
+
+    ops.push({
+        type: "put", key: dialogKey, value: {
+            ...existingDialog,
+            primaryAgentKey: existingDialog.primaryAgentKey ?? agentKey,
+            ...(taskLabel ? { taskLabel } : {}),
+            ...(effectiveSpaceId ? { spaceId: effectiveSpaceId } : {}),
+            updatedAt: nowIso,
+            status: "done",
+            finishedAt: now,
+            durationMs: (existingDialog.durationMs ?? 0) + durationMs,
+            toolCallCount: (existingDialog.toolCallCount ?? 0) + (result.toolCallCount ?? 0),
+            runtimeBinding,
+            ...(tags ? { tags } : {}),
+            ...(subjectRefs ? { subjectRefs } : {}),
+            ...mergeResultArtifactFacts(result, toolTraceFacts),
+            ...(result.policyState
+                ? {
+                    policyState: {
+                        ...(existingDialog.policyState ?? {}),
+                        ...result.policyState,
+                    },
+                }
+                : {}),
+        },
+    });
+
+    ops.push({
+        type: "put", key: userMsgInfo.key, value: {
+            id: userMsgInfo.messageId,
+            dbKey: userMsgInfo.key,
+            role: "user",
+            content: userInput,
+            userId: effectiveUserId,
+            createdAt: formatISO(new Date(now - durationMs)),
+        },
+    });
+
+    let lastAssistantMsgId: string | undefined;
+    for (const msg of trace) {
+        if (msg.role === "system" || msg.role === "user") continue;
+        const info = createDialogMessageKeyAndId(dialogId, mono);
+        const toolName = msg.role === "tool" && (msg as any).tool_call_id
+            ? toolCallIdToName.get((msg as any).tool_call_id)
+            : undefined;
+
+        ops.push({
+            type: "put",
+            key: info.key,
+            value: buildPersistedTraceMessage({
+                info,
+                msg,
+                nowIso,
+                defaultAgentKey: defaultTraceAgentKey,
+                toolName,
+                parentMessageId: lastAssistantMsgId,
+            }),
+        });
+
+        if (msg.role === "assistant") {
+            lastAssistantMsgId = info.messageId;
+        }
+    }
+
+    ops[0]!.value.runtimeCheckpoint = buildRuntimeCheckpoint({
+        dialogId,
+        status: "done",
+        userInput,
+        result,
+        lastAssistantMessageId: lastAssistantMsgId,
+        toolCallIdToName,
+        runtimeBinding,
+        previousRuntimeCheckpoint: existingDialog.runtimeCheckpoint,
+    });
+    ops[0]!.value.toolCallCount = Math.max(
+        ops[0]!.value.toolCallCount ?? 0,
+        ops[0]!.value.runtimeCheckpoint?.toolCallCount ?? 0,
+    );
+
+    await serverDb.batch(ops);
+
+    if (effectiveSpaceId) {
+        pushEvent(`space-${effectiveSpaceId}`, { type: "dialog.done", dialogId });
+    }
+
+    await emitDialogStatusNotification({
+        userId: effectiveUserId,
+        dialogId,
+        dialogKey,
+        dialogTitle: existing?.title ?? fallbackDialogTitle,
+        spaceId: effectiveSpaceId,
+        spaceName: await resolveSpaceName(effectiveSpaceId),
+        status: "done",
+        createdAt: now,
+    });
+
+    await captureExplicitMemoryEpisode({
+        userId,
+        spaceId: effectiveSpaceId,
+        agentKey,
+        dialogId,
+        userInput,
+    });
+    await captureUnderstandingMemoryFromDialog({
+        db: serverDb,
+        userId,
+        spaceId: effectiveSpaceId,
+        agentKey,
+        dialogId,
+        userInput,
+        trace: result.trace,
+    });
+    scheduleExplicitMemoryConsolidation({
+        userId,
+        spaceId: effectiveSpaceId,
+        agentKey,
+        dialogId,
+        userInput,
+    });
+    if (uiAskChoiceSelection) {
+        void rememberMemory({
+            userId: effectiveUserId,
+            spaceId: effectiveSpaceId,
+            dialogId,
+            content: buildUiAskChoiceMemoryContent(uiAskChoiceSelection),
+        }).catch((error) => {
+            console.warn("[memory] ui_ask_choice selection capture failed", {
+                dialogId,
+                userId: effectiveUserId,
+                spaceId: effectiveSpaceId ?? null,
+                error,
+            });
+        });
+    }
+
+    return { dialogId, dialogKey };
+}