@elizaos/agent 2.0.0-beta.1 → 2.0.11-beta.5

package/api/conversation-routes.js

@@ -0,0 +1,1783 @@
+/**
+ * Conversation CRUD routes extracted from server.ts.
+ *
+ * Handles:
+ *   POST   /api/conversations            – create
+ *   GET    /api/conversations             – list
+ *   GET    /api/conversations/:id/messages – get messages
+ *   POST   /api/conversations/:id/messages/truncate – truncate
+ *   POST   /api/conversations/:id/messages/stream   – stream message
+ *   POST   /api/conversations/:id/messages           – send message
+ *   POST   /api/conversations/:id/greeting            – get/store greeting
+ *   PATCH  /api/conversations/:id         – update/rename
+ *   DELETE /api/conversations/:id         – delete
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { ChannelType, createMessageMemory, logger, stringToUuid, } from "@elizaos/core";
+import { PatchConversationRequestSchema, PostConversationCleanupEmptyRequestSchema, PostConversationRequestSchema, PostConversationTruncateRequestSchema, } from "@elizaos/shared";
+import { resolveStateDir } from "../config/paths.js";
+import { classifyChatFailure, generateChatResponse, generateConversationTitle, getChatFailureReply, hasRecentVisibleAssistantMemorySince, initSse, normalizeChatResponseText, persistAssistantConversationMemory, persistConversationMemory, readChatRequestPayload, resolveNoResponseFallback, writeChatTokenSse, writeSse, writeSseJson, } from "./chat-routes.js";
+import { resolveClientChatAdminEntityId } from "./client-chat-admin.js";
+import { buildConversationRoomMetadata, sanitizeConversationMetadata, } from "./conversation-metadata.js";
+import { evictOldestConversation } from "./memory-bounds.js";
+import { buildUserMessages, getErrorMessage, resolveAppUserName, resolveConversationGreetingText, resolveWalletModeGuidanceReply, } from "./server-helpers.js";
+import { resolveWaifuChatAccess, waifuChatRoleToWorldRole, } from "./server-helpers-auth.js";
+let discordConversationPromise = null;
+function getDiscordConversationApi() {
+    discordConversationPromise ??= import("@elizaos/plugin-discord");
+    return discordConversationPromise;
+}
+function mayNeedDiscordMessageEnrichment(source) {
+    return typeof source === "string" && source.toLowerCase().includes("discord");
+}
+function chunkVisibleTextForSse(text) {
+    const chunks = [];
+    let cursor = 0;
+    const targetSize = 48;
+    while (cursor < text.length) {
+        const limit = Math.min(text.length, cursor + targetSize);
+        let end = limit;
+        if (limit < text.length) {
+            const boundary = text.lastIndexOf(" ", limit);
+            if (boundary > cursor + 12) {
+                end = boundary + 1;
+            }
+        }
+        chunks.push(text.slice(cursor, end));
+        cursor = end;
+    }
+    return chunks;
+}
+// ---------------------------------------------------------------------------
+// Deleted-conversations state persistence
+// ---------------------------------------------------------------------------
+const DELETED_CONVERSATIONS_FILENAME = "deleted-conversations.v1.json";
+const MAX_DELETED_CONVERSATION_IDS = 5000;
+function _readDeletedConversationIdsFromState() {
+    const filePath = path.join(resolveStateDir(), DELETED_CONVERSATIONS_FILENAME);
+    if (!fs.existsSync(filePath))
+        return new Set();
+    try {
+        const raw = fs.readFileSync(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        const ids = Array.isArray(parsed.ids) ? parsed.ids : [];
+        return new Set(ids
+            .map((id) => (typeof id === "string" ? id.trim() : ""))
+            .filter((id) => id.length > 0));
+    }
+    catch (err) {
+        logger.warn(`[eliza-api] Failed to read deleted conversations state: ${err instanceof Error ? err.message : String(err)}`);
+        return new Set();
+    }
+}
+function persistDeletedConversationIdsToState(ids) {
+    const dir = resolveStateDir();
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    const normalized = Array.from(ids)
+        .map((id) => id.trim())
+        .filter((id) => id.length > 0)
+        .slice(-MAX_DELETED_CONVERSATION_IDS);
+    const payload = {
+        version: 1,
+        updatedAt: new Date().toISOString(),
+        ids: normalized,
+    };
+    fs.writeFileSync(path.join(dir, DELETED_CONVERSATIONS_FILENAME), JSON.stringify(payload, null, 2), { encoding: "utf-8", mode: 0o600 });
+}
+/**
+ * How long a chat turn may HOLD waiting for first-turn capability during the
+ * warming window (early API bind → runtime ready). Normal boots resolve in ~2s;
+ * the cap bounds the hold so a genuinely-stuck boot still fails fast.
+ */
+const WARMING_TURN_HOLD_MS = 30_000;
+/**
+ * Resolve the runtime for a chat turn, HOLDING through the warming window
+ * instead of 503-dropping. Returns the live runtime immediately if present;
+ * otherwise, only while the agent is actively warming up (`starting`/
+ * `restarting`), waits up to WARMING_TURN_HOLD_MS for capability to come online.
+ * A genuinely stopped/errored agent (or one with no gate wired) returns null so
+ * the caller fails fast with the usual 503.
+ */
+async function resolveRuntimeForChatTurn(state) {
+    if (state.runtime) {
+        return state.runtime;
+    }
+    const warming = state.agentState === "starting" || state.agentState === "restarting";
+    if (!warming || !state.awaitRuntimeReady) {
+        return state.runtime ?? null;
+    }
+    return state.awaitRuntimeReady(WARMING_TURN_HOLD_MS);
+}
+// ---------------------------------------------------------------------------
+// Closure-lifted helpers
+// ---------------------------------------------------------------------------
+export function resolveConversationAdminEntityId(state) {
+    return resolveClientChatAdminEntityId(state);
+}
+function isStreamEventSource(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.on === "function");
+}
+function isStreamSocketLike(value) {
+    return typeof value === "object" && value !== null;
+}
+function createRequestDisconnectAbortTracker({ req, res, operation, }) {
+    const abortController = new AbortController();
+    const registrations = [];
+    let aborted = false;
+    let completed = false;
+    const abort = (reason) => {
+        if (completed || aborted)
+            return;
+        aborted = true;
+        abortController.abort(reason instanceof Error ? reason : new Error(`${operation} aborted`));
+    };
+    const register = (source, event, listener) => {
+        if (!isStreamEventSource(source))
+            return;
+        source.on?.(event, listener);
+        registrations.push({ source, event, listener });
+    };
+    const onClientGone = () => abort(new Error(`${operation} client disconnected`));
+    const onResponseClose = () => {
+        const ended = Boolean(res.writableEnded);
+        if (!ended)
+            onClientGone();
+    };
+    register(req, "aborted", onClientGone);
+    register(req, "error", onClientGone);
+    register(res, "close", onResponseClose);
+    register(res, "error", onClientGone);
+    return {
+        signal: abortController.signal,
+        dispose: () => {
+            for (const { source, event, listener } of registrations) {
+                source.off?.(event, listener);
+            }
+            registrations.length = 0;
+        },
+        isAborted: () => aborted,
+        markCompleted: () => {
+            completed = true;
+        },
+    };
+}
+function createConversationStreamDisconnectTracker({ req, res, conversationId, roomId, }) {
+    const abortController = new AbortController();
+    const registrations = [];
+    let aborted = false;
+    let completed = false;
+    const requestSocket = isStreamSocketLike(req.socket)
+        ? (req.socket ??
+            null)
+        : null;
+    const responseSocket = isStreamSocketLike(res.socket)
+        ? (res.socket ??
+            null)
+        : null;
+    const responseEnded = () => Boolean(res.writableEnded);
+    const abort = (reason) => {
+        if (completed || aborted)
+            return;
+        aborted = true;
+        logger.info({ conversationId, roomId }, "[ConversationStream] client disconnected; aborting generation");
+        abortController.abort(reason ?? new Error("Client disconnected"));
+    };
+    const checkConnectionClosed = () => {
+        const socketClosed = requestSocket?.destroyed === true ||
+            responseSocket?.destroyed === true ||
+            (requestSocket?.writable === false && !responseEnded()) ||
+            (responseSocket?.writable === false && !responseEnded());
+        const responseClosed = res.destroyed ===
+            true && !responseEnded();
+        if (socketClosed || responseClosed) {
+            abort(new Error("Client disconnected"));
+            return true;
+        }
+        return false;
+    };
+    const register = (source, event, listener) => {
+        if (!isStreamEventSource(source))
+            return;
+        source.on?.(event, listener);
+        registrations.push({ source, event, listener });
+    };
+    const onRequestClose = () => {
+        checkConnectionClosed();
+    };
+    const onClientGone = () => {
+        abort(new Error("Client disconnected"));
+    };
+    // Bun's node:http shim emits req.close when the POST body finishes, before
+    // the SSE response is complete. Socket events must be attached before that
+    // point; listeners added after body parsing can miss later client exits.
+    register(req, "aborted", onClientGone);
+    register(req, "close", onRequestClose);
+    register(req, "error", onClientGone);
+    register(res, "close", onClientGone);
+    register(res, "error", onClientGone);
+    register(requestSocket, "close", onClientGone);
+    register(requestSocket, "error", onClientGone);
+    if (responseSocket && responseSocket !== requestSocket) {
+        register(responseSocket, "close", onClientGone);
+        register(responseSocket, "error", onClientGone);
+    }
+    return {
+        signal: abortController.signal,
+        abort,
+        checkConnectionClosed,
+        dispose: () => {
+            for (const { source, event, listener } of registrations) {
+                source.off?.(event, listener);
+            }
+            registrations.length = 0;
+        },
+        isAborted: () => aborted,
+        markCompleted: () => {
+            completed = true;
+        },
+    };
+}
+function writeConversationStreamHeartbeat(res, disconnectTracker) {
+    if (disconnectTracker.isAborted() || res.writableEnded)
+        return;
+    try {
+        res.write(": heartbeat\n\n");
+    }
+    catch {
+        disconnectTracker.abort(new Error("Client disconnected"));
+    }
+}
+function isTurnAbortError(err) {
+    if (!(err instanceof Error))
+        return false;
+    const code = err.code;
+    return (code === "TURN_ABORTED" ||
+        err.name === "TurnAbortedError" ||
+        err.message.startsWith("Turn aborted:"));
+}
+function ensureAdminEntityId(state) {
+    return resolveConversationAdminEntityId(state);
+}
+function resolveConversationCaller(req, state) {
+    const access = resolveWaifuChatAccess(req);
+    if (!access) {
+        return {
+            entityId: ensureAdminEntityId(state),
+            role: "OWNER",
+            userName: resolveAppUserName(state.config),
+        };
+    }
+    return {
+        entityId: stringToUuid(`waifu-wallet:${access.walletAddress.toLowerCase()}`),
+        role: waifuChatRoleToWorldRole(access.role),
+        userName: access.walletAddress,
+    };
+}
+function normalizeWaifuWallet(address) {
+    if (!address || !/^0x[a-fA-F0-9]{40}$/.test(address))
+        return null;
+    return address.toLowerCase();
+}
+function getWaifuChatOwnerWallet(conv) {
+    return normalizeWaifuWallet(conv.metadata?.waifuChatOwnerWallet);
+}
+function addWaifuConversationOwnerMetadata(req, metadata) {
+    const access = resolveWaifuChatAccess(req);
+    if (!access)
+        return metadata;
+    return {
+        ...(metadata ?? {}),
+        waifuChatOwnerWallet: access.walletAddress.toLowerCase(),
+        waifuChatRole: access.role,
+    };
+}
+function canWaifuAccessConversation(access, conv) {
+    if (!access || access.role === "admin")
+        return true;
+    return getWaifuChatOwnerWallet(conv) === access.walletAddress.toLowerCase();
+}
+function rejectWaifuConversationAccessIfNeeded(req, conv, error, res) {
+    const access = resolveWaifuChatAccess(req);
+    if (canWaifuAccessConversation(access, conv))
+        return false;
+    error(res, "Conversation not found", 404);
+    return true;
+}
+function rejectWaifuNonAdminMutationIfNeeded(req, error, res) {
+    const access = resolveWaifuChatAccess(req);
+    if (!access || access.role === "admin")
+        return false;
+    error(res, "Forbidden", 403);
+    return true;
+}
+async function ensureWorldOwnershipAndRoles(runtime, worldId, ownerId, callerId, callerRole) {
+    const world = await runtime.getWorld(worldId);
+    if (!world)
+        return;
+    let needsUpdate = false;
+    if (!world.metadata) {
+        world.metadata = {};
+        needsUpdate = true;
+    }
+    if (!world.metadata.ownership ||
+        typeof world.metadata.ownership !== "object" ||
+        world.metadata.ownership.ownerId !== ownerId) {
+        world.metadata.ownership = { ownerId };
+        needsUpdate = true;
+    }
+    const metadataWithRoles = world.metadata;
+    const roles = metadataWithRoles.roles ?? {};
+    if (roles[ownerId] !== "OWNER") {
+        roles[ownerId] = "OWNER";
+        metadataWithRoles.roles = roles;
+        needsUpdate = true;
+    }
+    if (roles[callerId] !== callerRole) {
+        roles[callerId] = callerRole;
+        metadataWithRoles.roles = roles;
+        needsUpdate = true;
+    }
+    if (needsUpdate) {
+        await runtime.updateWorld(world);
+    }
+}
+async function shouldPersistFinalAssistantTurn(runtime, roomId, turnStartedAt, result) {
+    if (!result.usedActionCallbacks) {
+        return true;
+    }
+    const alreadyPersistedVisibleAssistantTurn = await hasRecentVisibleAssistantMemorySince(runtime, roomId, turnStartedAt);
+    return !alreadyPersistedVisibleAssistantTurn;
+}
+function markConversationDeleted(state, conversationId) {
+    const normalizedId = conversationId.trim();
+    if (!normalizedId)
+        return;
+    if (state.deletedConversationIds.has(normalizedId))
+        return;
+    state.deletedConversationIds.add(normalizedId);
+    while (state.deletedConversationIds.size > MAX_DELETED_CONVERSATION_IDS) {
+        const oldest = state.deletedConversationIds.values().next().value;
+        if (!oldest)
+            break;
+        state.deletedConversationIds.delete(oldest);
+    }
+    try {
+        persistDeletedConversationIdsToState(state.deletedConversationIds);
+    }
+    catch (err) {
+        logger.warn(`[conversations] Failed to persist deleted conversation tombstones: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+async function deleteConversationRoomData(runtime, roomId) {
+    const runtimeWithDelete = runtime;
+    if (typeof runtimeWithDelete.deleteRoom === "function") {
+        await runtimeWithDelete.deleteRoom(roomId);
+        return;
+    }
+    const dbDeleteRoom = runtimeWithDelete.adapter.db.deleteRoom;
+    if (typeof dbDeleteRoom === "function") {
+        await dbDeleteRoom.call(runtimeWithDelete.adapter.db, roomId);
+    }
+}
+async function deleteConversationMemories(runtime, memoryIds) {
+    if (memoryIds.length === 0)
+        return 0;
+    const runtimeWithDelete = runtime;
+    if (typeof runtimeWithDelete.deleteManyMemories === "function") {
+        await runtimeWithDelete.deleteManyMemories(memoryIds);
+        return memoryIds.length;
+    }
+    const dbDeleteMany = runtimeWithDelete.adapter.db.deleteManyMemories;
+    if (typeof dbDeleteMany === "function") {
+        await dbDeleteMany.call(runtimeWithDelete.adapter.db, memoryIds);
+        return memoryIds.length;
+    }
+    let deletedCount = 0;
+    for (const memoryId of memoryIds) {
+        if (typeof runtimeWithDelete.deleteMemory === "function") {
+            await runtimeWithDelete.deleteMemory(memoryId);
+        }
+        else if (typeof runtimeWithDelete.removeMemory === "function") {
+            await runtimeWithDelete.removeMemory(memoryId);
+        }
+        else if (typeof runtimeWithDelete.adapter.db.deleteMemory === "function") {
+            await runtimeWithDelete.adapter.db.deleteMemory.call(runtimeWithDelete.adapter.db, memoryId);
+        }
+        else if (typeof runtimeWithDelete.adapter.db.removeMemory === "function") {
+            await runtimeWithDelete.adapter.db.removeMemory.call(runtimeWithDelete.adapter.db, memoryId);
+        }
+        else {
+            const unsupportedError = new Error("Conversation message deletion is not supported by this runtime");
+            unsupportedError.status = 501;
+            throw unsupportedError;
+        }
+        deletedCount += 1;
+    }
+    return deletedCount;
+}
+async function ensureConversationRoom(state, conv, caller) {
+    if (!state.runtime)
+        return;
+    const runtime = state.runtime;
+    const agentName = runtime.character.name ?? "Eliza";
+    const ownerId = ensureAdminEntityId(state);
+    const worldId = stringToUuid(`${agentName}-web-chat-world`);
+    const messageServerId = stringToUuid(`${agentName}-web-server`);
+    await runtime.ensureConnection({
+        entityId: caller.entityId,
+        roomId: conv.roomId,
+        worldId,
+        userName: caller.userName,
+        source: "client_chat",
+        channelId: `web-conv-${conv.id}`,
+        type: ChannelType.DM,
+        messageServerId,
+        metadata: { ownership: { ownerId }, waifuRole: caller.role },
+    });
+    await ensureWorldOwnershipAndRoles(runtime, worldId, ownerId, caller.entityId, caller.role);
+}
+async function syncConversationRoomState(state, conv) {
+    if (!state.runtime)
+        return;
+    const runtime = state.runtime;
+    const room = await runtime.getRoom(conv.roomId);
+    if (!room)
+        return;
+    const ownerId = ensureAdminEntityId(state);
+    const nextMetadata = buildConversationRoomMetadata(conv, ownerId, room.metadata);
+    const nextName = conv.title;
+    const metadataChanged = JSON.stringify(room.metadata ?? null) !== JSON.stringify(nextMetadata);
+    if (room.name === nextName && !metadataChanged) {
+        return;
+    }
+    const adapter = runtime.adapter;
+    if (typeof adapter.updateRoom !== "function") {
+        return;
+    }
+    await adapter.updateRoom({
+        ...room,
+        name: nextName,
+        metadata: nextMetadata,
+    });
+}
+async function waitForConversationRestore(state) {
+    const pending = state.conversationRestorePromise;
+    if (!pending)
+        return;
+    try {
+        const timeout = new Promise((_, reject) => setTimeout(() => reject(new Error("Conversation restore timed out after 5000ms")), 5000));
+        await Promise.race([pending, timeout]);
+    }
+    catch {
+        // Restore failures are logged at the source.
+    }
+}
+export function normalizeActionCallbackHistory(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const history = [];
+    for (const entry of value) {
+        if (typeof entry !== "string") {
+            continue;
+        }
+        const normalized = entry.trim();
+        if (!normalized) {
+            continue;
+        }
+        if (history.at(-1) === normalized) {
+            continue;
+        }
+        history.push(normalized);
+    }
+    return history;
+}
+function mergeActionCallbackHistory(existing, incoming) {
+    return normalizeActionCallbackHistory([...existing, ...incoming]);
+}
+export function formatConversationMessageText(text, actionCallbackHistory = []) {
+    const history = normalizeActionCallbackHistory(actionCallbackHistory);
+    if (history.length === 0) {
+        return text;
+    }
+    const trimmedText = text.trim();
+    if (trimmedText.length > 0) {
+        return text;
+    }
+    return history.join("\n");
+}
+export function buildPersistedAssistantContent(text, result) {
+    const responseContent = result?.responseContent && typeof result.responseContent === "object"
+        ? result.responseContent
+        : null;
+    const responseMessageContent = Array.isArray(result?.responseMessages)
+        ? (result.responseMessages
+            .map((entry) => entry.content && typeof entry.content === "object"
+            ? entry.content
+            : null)
+            .filter((content) => content !== null)
+            .at(-1) ?? null)
+        : null;
+    const actionCallbackHistory = normalizeActionCallbackHistory(result?.actionCallbackHistory);
+    return responseContent || responseMessageContent
+        ? {
+            ...(responseMessageContent ?? {}),
+            ...(responseContent ?? {}),
+            text,
+            ...(actionCallbackHistory.length > 0 ? { actionCallbackHistory } : {}),
+        }
+        : {
+            text,
+            ...(actionCallbackHistory.length > 0 ? { actionCallbackHistory } : {}),
+        };
+}
+export async function persistRecentAssistantActionCallbackHistory(runtime, roomId, actionCallbackHistory, sinceMs) {
+    const normalizedHistory = normalizeActionCallbackHistory(actionCallbackHistory);
+    if (normalizedHistory.length === 0) {
+        return false;
+    }
+    try {
+        const recent = await runtime.getMemories({
+            roomId,
+            tableName: "messages",
+            limit: 12,
+        });
+        const target = recent
+            .filter((memory) => memory.entityId === runtime.agentId)
+            .filter((memory) => {
+            const content = memory.content;
+            const createdAt = memory.createdAt ?? 0;
+            return (typeof memory.id === "string" &&
+                typeof content?.text === "string" &&
+                content.text.trim().length > 0 &&
+                createdAt >= sinceMs - 2000);
+        })
+            .sort((left, right) => (left.createdAt ?? 0) - (right.createdAt ?? 0))
+            .at(-1);
+        if (!target || typeof target.id !== "string") {
+            return false;
+        }
+        const content = target.content && typeof target.content === "object"
+            ? target.content
+            : { text: "" };
+        const existingHistory = normalizeActionCallbackHistory(content.actionCallbackHistory);
+        const mergedHistory = mergeActionCallbackHistory(existingHistory, normalizedHistory);
+        if (mergedHistory.length === existingHistory.length &&
+            mergedHistory.every((entry, index) => entry === existingHistory[index])) {
+            return true;
+        }
+        await runtime.updateMemory({
+            id: target.id,
+            content: {
+                ...content,
+                actionCallbackHistory: mergedHistory,
+            },
+        });
+        return true;
+    }
+    catch (err) {
+        logger.debug(`[conversations] Failed to persist action callback history: ${getErrorMessage(err)}`);
+        return false;
+    }
+}
+async function getConversationWithRestore(state, convId) {
+    const existing = state.conversations.get(convId);
+    if (existing)
+        return existing;
+    await waitForConversationRestore(state);
+    return state.conversations.get(convId);
+}
+function extractConversationMetaString(memory, key) {
+    const meta = memory.metadata && typeof memory.metadata === "object"
+        ? memory.metadata
+        : undefined;
+    const value = meta?.[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/**
+ * Only URLs the browser can actually load are renderable. Inline-upload
+ * placeholders (e.g. `attachment:img-0`) whose bytes were never persisted are
+ * dropped here so the client never paints a broken image — real uploads and
+ * generated media carry a served `/api/media/...`, remote https, or inline
+ * `data:`/`blob:` URL.
+ */
+const RENDERABLE_ATTACHMENT_URL = /^(?:https?:|data:|blob:|\/)/i;
+export function serializeMessageAttachments(content) {
+    const raw = content?.attachments;
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    const out = [];
+    for (const item of raw) {
+        if (!item || typeof item !== "object")
+            continue;
+        const a = item;
+        const url = typeof a.url === "string" ? a.url : "";
+        if (!url || !RENDERABLE_ATTACHMENT_URL.test(url))
+            continue;
+        const str = (v) => typeof v === "string" && v.length > 0 ? v : undefined;
+        out.push({
+            id: str(a.id) ?? `att-${out.length}`,
+            url,
+            ...(str(a.contentType) ? { contentType: str(a.contentType) } : {}),
+            ...(str(a.title) ? { title: str(a.title) } : {}),
+            ...(str(a.description) ? { description: str(a.description) } : {}),
+            ...(str(a.source) ? { source: str(a.source) } : {}),
+            ...(str(a.text) ? { text: str(a.text) } : {}),
+            ...(str(a.mimeType) ? { mimeType: str(a.mimeType) } : {}),
+            ...(str(a.thumbnailUrl) ? { thumbnailUrl: str(a.thumbnailUrl) } : {}),
+        });
+    }
+    return out.length > 0 ? out : undefined;
+}
+async function ensureConversationGreetingStored(state, conv, lang) {
+    const runtime = state.runtime;
+    const agentName = runtime?.character.name ?? state.agentName;
+    if (!runtime) {
+        return {
+            text: "",
+            agentName,
+            generated: false,
+            persisted: false,
+        };
+    }
+    let memories;
+    try {
+        memories = await runtime.getMemories({
+            roomId: conv.roomId,
+            tableName: "messages",
+            limit: 12,
+        });
+    }
+    catch (err) {
+        throw new Error(`Failed to inspect existing conversation messages: ${getErrorMessage(err)}`);
+    }
+    memories.sort((a, b) => (a.createdAt ?? 0) - (b.createdAt ?? 0));
+    const existingGreeting = memories.find((memory) => {
+        const content = memory.content;
+        return (memory.entityId === runtime.agentId &&
+            content?.source === "agent_greeting" &&
+            typeof content.text === "string" &&
+            content.text.trim().length > 0);
+    });
+    if (existingGreeting) {
+        return {
+            text: String(existingGreeting.content
+                ?.text ?? ""),
+            agentName,
+            generated: true,
+            persisted: false,
+        };
+    }
+    if (memories.length > 0) {
+        return {
+            text: "",
+            agentName,
+            generated: false,
+            persisted: false,
+        };
+    }
+    const greeting = resolveConversationGreetingText(runtime, lang, state.config.ui).trim();
+    if (!greeting) {
+        return {
+            text: "",
+            agentName,
+            generated: false,
+            persisted: false,
+        };
+    }
+    try {
+        await persistConversationMemory(runtime, createMessageMemory({
+            id: crypto.randomUUID(),
+            entityId: runtime.agentId,
+            roomId: conv.roomId,
+            content: {
+                text: greeting,
+                source: "agent_greeting",
+                channelType: ChannelType.DM,
+            },
+        }));
+    }
+    catch (err) {
+        throw new Error(`Failed to store greeting message: ${getErrorMessage(err)}`);
+    }
+    conv.updatedAt = new Date().toISOString();
+    return {
+        text: greeting,
+        agentName,
+        generated: true,
+        persisted: true,
+    };
+}
+async function truncateConversationMessages(runtime, conv, messageId, options) {
+    const memories = await runtime.getMemories({
+        roomId: conv.roomId,
+        tableName: "messages",
+        limit: 1000,
+    });
+    memories.sort((a, b) => (a.createdAt ?? 0) - (b.createdAt ?? 0));
+    const targetIndex = memories.findIndex((memory) => memory.id === messageId);
+    if (targetIndex < 0) {
+        const notFoundError = new Error("Conversation message not found");
+        notFoundError.status = 404;
+        throw notFoundError;
+    }
+    const deleteStartIndex = options?.inclusive === true ? targetIndex : targetIndex + 1;
+    const memoryIds = memories
+        .slice(deleteStartIndex)
+        .map((memory) => memory.id)
+        .filter((memoryId) => typeof memoryId === "string" && memoryId.trim().length > 0);
+    const deletedCount = await deleteConversationMemories(runtime, memoryIds);
+    return { deletedCount };
+}
+// ---------------------------------------------------------------------------
+// Main handler
+// ---------------------------------------------------------------------------
+export async function handleConversationRoutes(ctx) {
+    const { req, res, method, pathname, readJsonBody, json, error, state } = ctx;
+    if (!pathname.startsWith("/api/conversations") ||
+        pathname.startsWith("/api/conversations/")
+        ? !/^\/api\/conversations\/[^/]/.test(pathname)
+        : pathname !== "/api/conversations") {
+        // Quick exit: not a conversation route
+        if (!pathname.startsWith("/api/conversations"))
+            return false;
+    }
+    // ── GET /api/conversations ──────────────────────────────────────────
+    if (method === "GET" && pathname === "/api/conversations") {
+        await waitForConversationRestore(state);
+        const waifuAccess = resolveWaifuChatAccess(req);
+        const convos = Array.from(state.conversations.values())
+            .filter((c) => !state.deletedConversationIds.has(c.id))
+            .filter((c) => canWaifuAccessConversation(waifuAccess, c))
+            .sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
+        json(res, { conversations: convos });
+        return true;
+    }
+    // ── POST /api/conversations ─────────────────────────────────────────
+    if (method === "POST" && pathname === "/api/conversations") {
+        const rawConv = await readJsonBody(req, res);
+        if (rawConv === null)
+            return true;
+        const parsedConv = PostConversationRequestSchema.safeParse(rawConv);
+        if (!parsedConv.success) {
+            error(res, parsedConv.error.issues[0]?.message ?? "Invalid request body", 400);
+            return true;
+        }
+        const body = parsedConv.data;
+        await waitForConversationRestore(state);
+        const id = crypto.randomUUID();
+        const now = new Date().toISOString();
+        const roomId = stringToUuid(`web-conv-${id}`);
+        const metadata = addWaifuConversationOwnerMetadata(req, sanitizeConversationMetadata(body.metadata));
+        const conv = {
+            id,
+            title: body.title?.trim() || "New Chat",
+            roomId,
+            ...(metadata ? { metadata } : {}),
+            createdAt: now,
+            updatedAt: now,
+        };
+        state.conversations.set(id, conv);
+        let greeting;
+        // Soft cap: evict the oldest conversation when the map exceeds 500
+        evictOldestConversation(state.conversations, 500);
+        if (state.runtime) {
+            try {
+                await ensureConversationRoom(state, conv, resolveConversationCaller(req, state));
+                await syncConversationRoomState(state, conv);
+                if (body.includeGreeting === true) {
+                    const storedGreeting = await ensureConversationGreetingStored(state, conv, typeof body.lang === "string" ? body.lang : "en");
+                    if (storedGreeting.text.trim()) {
+                        greeting = {
+                            text: storedGreeting.text,
+                            agentName: storedGreeting.agentName,
+                            generated: storedGreeting.generated,
+                            persisted: storedGreeting.persisted,
+                        };
+                    }
+                }
+            }
+            catch (err) {
+                error(res, `Failed to initialize conversation: ${getErrorMessage(err)}`, 500);
+                return true;
+            }
+        }
+        json(res, { conversation: conv, ...(greeting ? { greeting } : {}) });
+        return true;
+    }
+    // ── GET /api/conversations/:id/messages ─────────────────────────────
+    if (method === "GET" &&
+        /^\/api\/conversations\/[^/]+\/messages$/.test(pathname)) {
+        const convId = decodeURIComponent(pathname.split("/")[3]);
+        const conv = await getConversationWithRestore(state, convId);
+        if (!conv) {
+            error(res, "Conversation not found", 404);
+            return true;
+        }
+        if (rejectWaifuConversationAccessIfNeeded(req, conv, error, res)) {
+            return true;
+        }
+        if (!state.runtime) {
+            json(res, { messages: [] });
+            return true;
+        }
+        const runtime = state.runtime;
+        try {
+            const memories = await runtime.getMemories({
+                roomId: conv.roomId,
+                tableName: "messages",
+                limit: 200,
+            });
+            // Sort by createdAt ascending
+            memories.sort((a, b) => (a.createdAt ?? 0) - (b.createdAt ?? 0));
+            const agentId = runtime.agentId;
+            const messages = memories
+                .map((m) => {
+                const contentSource = m.content?.source;
+                const content = m.content;
+                const meta = m.metadata;
+                const entityName = meta?.entityName;
+                const replyToAuthor = meta?.replyToAuthor && typeof meta.replyToAuthor === "object"
+                    ? meta.replyToAuthor
+                    : null;
+                const normalizedSource = typeof contentSource === "string" &&
+                    contentSource.length > 0 &&
+                    contentSource !== "client_chat"
+                    ? contentSource
+                    : undefined;
+                const actionName = typeof content.action === "string" && content.action.length > 0
+                    ? content.action
+                    : undefined;
+                const actionCallbackHistory = normalizeActionCallbackHistory(content.actionCallbackHistory);
+                const role = m.entityId === agentId ? "assistant" : "user";
+                const rawText = formatConversationMessageText(m.content?.text ?? "", actionCallbackHistory);
+                const text = role === "assistant"
+                    ? normalizeChatResponseText(rawText, state.logBuffer, runtime)
+                    : rawText;
+                const attachments = serializeMessageAttachments(content);
+                return {
+                    id: m.id ?? "",
+                    role,
+                    text,
+                    timestamp: m.createdAt ?? 0,
+                    ...(attachments ? { attachments } : {}),
+                    source: normalizedSource,
+                    actionName,
+                    actionCallbackHistory: actionCallbackHistory.length > 0
+                        ? [...actionCallbackHistory]
+                        : undefined,
+                    from: typeof entityName === "string" && entityName.length > 0
+                        ? entityName
+                        : undefined,
+                    fromUserName: typeof meta?.entityUserName === "string" &&
+                        meta.entityUserName.length > 0
+                        ? meta.entityUserName
+                        : undefined,
+                    avatarUrl: typeof meta?.entityAvatarUrl === "string" &&
+                        meta.entityAvatarUrl.length > 0
+                        ? meta.entityAvatarUrl
+                        : undefined,
+                    replyToMessageId: typeof content.inReplyTo === "string" &&
+                        content.inReplyTo.length > 0
+                        ? content.inReplyTo
+                        : typeof meta?.replyToMessageId === "string" &&
+                            meta.replyToMessageId.length > 0
+                            ? meta.replyToMessageId
+                            : undefined,
+                    replyToSenderName: typeof meta?.replyToSenderName === "string" &&
+                        meta.replyToSenderName.length > 0
+                        ? meta.replyToSenderName
+                        : typeof replyToAuthor?.displayName === "string" &&
+                            replyToAuthor.displayName.length > 0
+                            ? replyToAuthor.displayName
+                            : typeof replyToAuthor?.username === "string" &&
+                                replyToAuthor.username.length > 0
+                                ? replyToAuthor.username
+                                : undefined,
+                    replyToSenderUserName: typeof meta?.replyToSenderUserName === "string" &&
+                        meta.replyToSenderUserName.length > 0
+                        ? meta.replyToSenderUserName
+                        : typeof replyToAuthor?.username === "string" &&
+                            replyToAuthor.username.length > 0
+                            ? replyToAuthor.username
+                            : undefined,
+                    rawDiscordChannelId: extractConversationMetaString(m, "discordChannelId"),
+                    rawDiscordMessageId: extractConversationMetaString(m, "discordMessageId"),
+                    rawSenderId: extractConversationMetaString(m, "fromId"),
+                    senderEntityId: typeof m.entityId === "string" ? m.entityId : undefined,
+                };
+            })
+                // Drop action-log memories that have no visible text (e.g.
+                // plugin action logs with only `thought` / `actions` fields).
+                // Without this filter they appear as blank chat bubbles. Image-only
+                // turns (uploaded or generated media with no caption) are kept.
+                .filter((m) => m.text.trim().length > 0 || (m.attachments?.length ?? 0) > 0);
+            const discordMessages = messages.filter((message) => mayNeedDiscordMessageEnrichment(message.source));
+            const discord = discordMessages.length > 0
+                ? await getDiscordConversationApi().catch((err) => {
+                    logger.debug(`[conversations] Discord metadata enrichment unavailable: ${getErrorMessage(err)}`);
+                    return null;
+                })
+                : null;
+            await Promise.all(discordMessages.map(async (message) => {
+                if (!discord) {
+                    return;
+                }
+                if (!discord.isCanonicalDiscordSource(message.source)) {
+                    return;
+                }
+                try {
+                    const storedSenderProfile = await discord.resolveStoredDiscordEntityProfile(runtime, message.senderEntityId);
+                    if (!message.from && storedSenderProfile?.displayName) {
+                        message.from = storedSenderProfile.displayName;
+                    }
+                    if (!message.fromUserName && storedSenderProfile?.username) {
+                        message.fromUserName = storedSenderProfile.username;
+                    }
+                    if (!message.avatarUrl && storedSenderProfile?.avatarUrl) {
+                        message.avatarUrl = storedSenderProfile.avatarUrl;
+                    }
+                    const messageAuthorProfile = message.rawDiscordChannelId && message.rawDiscordMessageId
+                        ? await discord.resolveDiscordMessageAuthorProfile(runtime, message.rawDiscordChannelId, message.rawDiscordMessageId)
+                        : null;
+                    if (!message.from && messageAuthorProfile?.displayName) {
+                        message.from = messageAuthorProfile.displayName;
+                    }
+                    if (!message.fromUserName && messageAuthorProfile?.username) {
+                        message.fromUserName = messageAuthorProfile.username;
+                    }
+                    if (!message.avatarUrl && messageAuthorProfile?.avatarUrl) {
+                        message.avatarUrl = messageAuthorProfile.avatarUrl;
+                    }
+                    const rawSenderId = message.rawSenderId ??
+                        storedSenderProfile?.rawUserId ??
+                        messageAuthorProfile?.rawUserId;
+                    if (rawSenderId) {
+                        const profile = await discord.resolveDiscordUserProfile(runtime, rawSenderId);
+                        if (profile) {
+                            if (profile.displayName) {
+                                message.from = profile.displayName;
+                            }
+                            if (profile.username) {
+                                message.fromUserName = profile.username;
+                            }
+                            if (profile.avatarUrl) {
+                                message.avatarUrl = profile.avatarUrl;
+                            }
+                        }
+                    }
+                    message.avatarUrl = await discord.cacheDiscordAvatarForRuntime(runtime, message.avatarUrl, rawSenderId);
+                }
+                catch (err) {
+                    logger.debug(`[conversations] Failed to enrich Discord message metadata: ${getErrorMessage(err)}`);
+                }
+            }));
+            json(res, {
+                messages: messages.map(({ rawDiscordChannelId: _rawDiscordChannelId, rawDiscordMessageId: _rawDiscordMessageId, rawSenderId: _rawSenderId, senderEntityId: _senderEntityId, ...message }) => message),
+            });
+        }
+        catch (err) {
+            logger.warn(`[conversations] Failed to fetch messages: ${err instanceof Error ? err.message : String(err)}`);
+            json(res, { messages: [], error: "Failed to fetch messages" }, 500);
+        }
+        return true;
+    }
+    // ── POST /api/conversations/:id/import ──────────────────────────────
+    // Silent bulk-insert of prior messages into a conversation WITHOUT running
+    // inference. Powers the shared→personal cloud handoff: the user's freshly
+    // provisioned personal container imports the conversation they already had
+    // on the shared agent so the switch is seamless. Keyed by the provided
+    // conversation id (so the client re-opens the same conversation after the
+    // switch) and idempotent per conversation — re-import onto an already
+    // populated room is a no-op, never a duplicate.
+    if (method === "POST" &&
+        /^\/api\/conversations\/[^/]+\/import$/.test(pathname)) {
+        const convId = decodeURIComponent(pathname.split("/")[3]);
+        const rawImport = await readJsonBody(req, res);
+        if (rawImport === null)
+            return true;
+        const rawMessages = rawImport.messages;
+        if (!Array.isArray(rawMessages)) {
+            error(res, "Body must include a `messages` array", 400);
+            return true;
+        }
+        const importMessages = rawMessages
+            .map((entry) => {
+            if (!entry || typeof entry !== "object")
+                return null;
+            const rec = entry;
+            const role = rec.role === "assistant"
+                ? "assistant"
+                : rec.role === "user"
+                    ? "user"
+                    : null;
+            const rawText = typeof rec.text === "string"
+                ? rec.text
+                : typeof rec.content === "string"
+                    ? rec.content
+                    : "";
+            const text = rawText.trim();
+            if (!role || !text)
+                return null;
+            const timestamp = typeof rec.timestamp === "number" && Number.isFinite(rec.timestamp)
+                ? rec.timestamp
+                : undefined;
+            return { role, text, timestamp };
+        })
+            .filter((m) => m !== null);
+        const runtime = await resolveRuntimeForChatTurn(state);
+        if (!runtime) {
+            error(res, "Agent is not running", 503);
+            return true;
+        }
+        await waitForConversationRestore(state);
+        let conv = state.conversations.get(convId);
+        if (!conv) {
+            const now = new Date().toISOString();
+            conv = {
+                id: convId,
+                title: typeof rawImport.title === "string" && rawImport.title.trim()
+                    ? rawImport.title.trim()
+                    : "New Chat",
+                roomId: stringToUuid(`web-conv-${convId}`),
+                createdAt: now,
+                updatedAt: now,
+            };
+            state.conversations.set(convId, conv);
+            evictOldestConversation(state.conversations, 500);
+        }
+        const caller = resolveConversationCaller(req, state);
+        try {
+            await ensureConversationRoom(state, conv, caller);
+        }
+        catch (err) {
+            error(res, `Failed to initialize conversation room: ${getErrorMessage(err)}`, 500);
+            return true;
+        }
+        // Idempotency: a populated room means the handoff already ran (or the user
+        // chatted here). Never double-import.
+        const existing = await runtime.getMemories({
+            roomId: conv.roomId,
+            tableName: "messages",
+            limit: 1,
+        });
+        if (existing.length > 0) {
+            json(res, {
+                conversationId: convId,
+                inserted: 0,
+                skipped: importMessages.length,
+                alreadyPopulated: true,
+            });
+            return true;
+        }
+        // Preserve original ordering: assign strictly increasing timestamps,
+        // anchored to the provided ones when present.
+        let inserted = 0;
+        const anchor = Date.now() - importMessages.length;
+        for (let i = 0; i < importMessages.length; i += 1) {
+            const m = importMessages[i];
+            const entityId = m.role === "assistant" ? runtime.agentId : caller.entityId;
+            const createdAt = m.timestamp ?? anchor + i;
+            try {
+                const memory = createMessageMemory({
+                    id: crypto.randomUUID(),
+                    entityId,
+                    roomId: conv.roomId,
+                    content: {
+                        text: m.text,
+                        channelType: ChannelType.DM,
+                        source: "handoff_import",
+                    },
+                });
+                memory.createdAt = createdAt;
+                if (memory.metadata && typeof memory.metadata === "object") {
+                    memory.metadata.timestamp = createdAt;
+                }
+                await persistConversationMemory(runtime, memory);
+                inserted += 1;
+            }
+            catch (err) {
+                logger.warn(`[conversations] import: failed to persist message ${i}: ${getErrorMessage(err)}`);
+            }
+        }
+        conv.updatedAt = new Date().toISOString();
+        state.broadcastWs?.({ type: "conversation-updated", conversation: conv });
+        json(res, {
+            conversationId: convId,
+            inserted,
+            skipped: importMessages.length - inserted,
+        });
+        return true;
+    }
+    // ── POST /api/conversations/:id/messages/truncate ──────────────────
+    if (method === "POST" &&
+        /^\/api\/conversations\/[^/]+\/messages\/truncate$/.test(pathname)) {
+        const convId = decodeURIComponent(pathname.split("/")[3]);
+        const conv = await getConversationWithRestore(state, convId);
+        if (!conv) {
+            error(res, "Conversation not found", 404);
+            return true;
+        }
+        if (rejectWaifuNonAdminMutationIfNeeded(req, error, res))
+            return true;
+        const rawTrunc = await readJsonBody(req, res);
+        if (rawTrunc === null)
+            return true;
+        const parsedTrunc = PostConversationTruncateRequestSchema.safeParse(rawTrunc);
+        if (!parsedTrunc.success) {
+            error(res, parsedTrunc.error.issues[0]?.message ?? "Invalid request body", 400);
+            return true;
+        }
+        const { messageId, inclusive } = parsedTrunc.data;
+        const runtime = state.runtime;
+        if (!runtime) {
+            error(res, "Agent is not running", 503);
+            return true;
+        }
+        try {
+            const result = await truncateConversationMessages(runtime, conv, messageId, {
+                inclusive: inclusive === true,
+            });
+            conv.updatedAt = new Date().toISOString();
+            state.broadcastWs?.({
+                type: "conversation-updated",
+                conversation: conv,
+            });
+            json(res, { ok: true, deletedCount: result.deletedCount });
+        }
+        catch (err) {
+            const status = typeof err.status === "number"
+                ? err.status
+                : 500;
+            error(res, getErrorMessage(err), status);
+        }
+        return true;
+    }
+    // ── POST /api/conversations/:id/messages/stream ─────────────────────
+    if (method === "POST" &&
+        /^\/api\/conversations\/[^/]+\/messages\/stream$/.test(pathname)) {
+        const convId = decodeURIComponent(pathname.split("/")[3]);
+        const conv = await getConversationWithRestore(state, convId);
+        if (!conv) {
+            error(res, "Conversation not found", 404);
+            return true;
+        }
+        if (rejectWaifuConversationAccessIfNeeded(req, conv, error, res)) {
+            return true;
+        }
+        const disconnectTracker = createConversationStreamDisconnectTracker({
+            req,
+            res,
+            conversationId: conv.id,
+            roomId: conv.roomId,
+        });
+        const finishStreamResponse = () => {
+            disconnectTracker.markCompleted();
+            disconnectTracker.dispose();
+            if (!res.writableEnded) {
+                res.end();
+            }
+        };
+        const chatPayload = await readChatRequestPayload(req, res, {
+            readJsonBody,
+            error,
+        });
+        if (!chatPayload) {
+            finishStreamResponse();
+            return true;
+        }
+        const { prompt, channelType, images, preferredLanguage, source, metadata: chatMetadata, } = chatPayload;
+        // Hold the streaming turn through the warming window instead of dropping it
+        // — the client already shows the optimistic bubble + typing indicator, and
+        // the response streams the instant first-turn capability comes online.
+        const runtime = await resolveRuntimeForChatTurn(state);
+        if (!runtime) {
+            disconnectTracker.markCompleted();
+            disconnectTracker.dispose();
+            error(res, "Agent is not running", 503);
+            return true;
+        }
+        const caller = resolveConversationCaller(req, state);
+        const userId = caller.entityId;
+        const turnStartedAt = Date.now();
+        try {
+            await ensureConversationRoom(state, conv, caller);
+        }
+        catch (err) {
+            error(res, `Failed to initialize conversation room: ${getErrorMessage(err)}`, 500);
+            disconnectTracker.markCompleted();
+            disconnectTracker.dispose();
+            return true;
+        }
+        const { userMessage, messageToStore } = await buildUserMessages({
+            images,
+            prompt,
+            userId,
+            agentId: runtime.agentId,
+            roomId: conv.roomId,
+            channelType,
+            messageSource: source,
+            metadata: chatMetadata,
+        });
+        try {
+            await persistConversationMemory(runtime, messageToStore);
+        }
+        catch (err) {
+            disconnectTracker.markCompleted();
+            disconnectTracker.dispose();
+            error(res, `Failed to store user message: ${getErrorMessage(err)}`, 500);
+            return true;
+        }
+        const walletModeGuidance = resolveWalletModeGuidanceReply(state, prompt);
+        if (walletModeGuidance) {
+            initSse(res);
+            try {
+                if (!disconnectTracker.isAborted()) {
+                    writeChatTokenSse(res, walletModeGuidance, walletModeGuidance);
+                    try {
+                        await persistAssistantConversationMemory(runtime, conv.roomId, walletModeGuidance, channelType, turnStartedAt);
+                        conv.updatedAt = new Date().toISOString();
+                    }
+                    catch (persistErr) {
+                        writeSse(res, {
+                            type: "error",
+                            message: getErrorMessage(persistErr),
+                        });
+                        return true;
+                    }
+                    writeSseJson(res, {
+                        type: "done",
+                        fullText: walletModeGuidance,
+                        agentName: state.agentName,
+                    });
+                }
+            }
+            finally {
+                finishStreamResponse();
+            }
+            return true;
+        }
+        // ── Local runtime path (streaming) ───────────────────────
+        initSse(res);
+        writeConversationStreamHeartbeat(res, disconnectTracker);
+        // SSE heartbeat to keep connection alive during long generation
+        const heartbeatInterval = setInterval(() => {
+            if (disconnectTracker.checkConnectionClosed()) {
+                return;
+            }
+            writeConversationStreamHeartbeat(res, disconnectTracker);
+        }, 5000);
+        let streamedText = "";
+        // When the success path emits `done` BEFORE running persistence (latency
+        // optimization), we hand off the persistence work as a detached promise so
+        // the `finally` block can `res.end()` immediately and still observe failures.
+        let deferredPersistence = null;
+        try {
+            const result = await generateChatResponse(runtime, userMessage, state.agentName, {
+                isAborted: () => disconnectTracker.isAborted(),
+                abortSignal: disconnectTracker.signal,
+                onChunk: (chunk) => {
+                    if (!chunk)
+                        return;
+                    if (disconnectTracker.isAborted() ||
+                        disconnectTracker.checkConnectionClosed()) {
+                        return;
+                    }
+                    streamedText += chunk;
+                    writeChatTokenSse(res, chunk, streamedText);
+                },
+                onSnapshot: (text) => {
+                    if (!text)
+                        return;
+                    if (!streamedText ||
+                        disconnectTracker.isAborted() ||
+                        disconnectTracker.checkConnectionClosed()) {
+                        return;
+                    }
+                    // Structured field extractors can briefly normalize whitespace or
+                    // closing punctuation while the same visible field is still
+                    // streaming. Do not shrink the user-visible token stream for
+                    // prefix-equivalent snapshots; later longer snapshots/deltas still
+                    // advance normally.
+                    if (text.length < streamedText.length &&
+                        streamedText.startsWith(text)) {
+                        return;
+                    }
+                    streamedText = text;
+                    writeChatTokenSse(res, text, streamedText);
+                },
+                resolveNoResponseText: () => resolveNoResponseFallback(state.logBuffer, runtime),
+                preferredLanguage,
+            });
+            if (!disconnectTracker.isAborted()) {
+                conv.updatedAt = new Date().toISOString();
+                if (result.noResponseReason !== "ignored") {
+                    const resolvedText = normalizeChatResponseText(result.text, state.logBuffer, runtime);
+                    if (!streamedText && resolvedText) {
+                        for (const chunk of chunkVisibleTextForSse(resolvedText)) {
+                            if (disconnectTracker.isAborted())
+                                break;
+                            streamedText += chunk;
+                            writeChatTokenSse(res, chunk, streamedText);
+                            await new Promise((resolve) => setTimeout(resolve, 60));
+                        }
+                    }
+                    // Emit `done` BEFORE persistence so user-perceived end-of-turn
+                    // latency excludes the ~100-500ms memory write. Persistence runs
+                    // after res.end() in the `finally` block as a detached promise.
+                    writeSseJson(res, {
+                        type: "done",
+                        fullText: resolvedText,
+                        agentName: result.agentName,
+                        ...(result.thought ? { thought: result.thought } : {}),
+                        ...(result.usage ? { usage: result.usage } : {}),
+                    });
+                    deferredPersistence = (async () => {
+                        if (result.actionCallbackHistory?.length) {
+                            await persistRecentAssistantActionCallbackHistory(runtime, conv.roomId, result.actionCallbackHistory, turnStartedAt);
+                        }
+                        if (await shouldPersistFinalAssistantTurn(runtime, conv.roomId, turnStartedAt, result)) {
+                            await persistAssistantConversationMemory(runtime, conv.roomId, buildPersistedAssistantContent(resolvedText, result), channelType, turnStartedAt);
+                        }
+                    })();
+                }
+                else {
+                    writeSseJson(res, {
+                        type: "done",
+                        fullText: "",
+                        agentName: result.agentName,
+                        noResponseReason: "ignored",
+                        ...(result.usage ? { usage: result.usage } : {}),
+                    });
+                }
+            }
+        }
+        catch (err) {
+            if (isTurnAbortError(err)) {
+                logger.info({ conversationId: conv.id, roomId: conv.roomId }, "[ConversationStream] generation aborted");
+            }
+            else if (!disconnectTracker.isAborted()) {
+                // If text was already streamed to the client (e.g. the initial
+                // response succeeded but planner follow-up failed), use the
+                // streamed text as the final reply instead of replacing it with a
+                // generic fallback.
+                if (streamedText) {
+                    logger.warn({
+                        err: getErrorMessage(err),
+                        streamedTextLength: streamedText.length,
+                    }, "Post-generation error after text was already streamed — using streamed text");
+                    try {
+                        await persistAssistantConversationMemory(runtime, conv.roomId, streamedText, channelType, turnStartedAt);
+                        conv.updatedAt = new Date().toISOString();
+                        writeSseJson(res, {
+                            type: "done",
+                            fullText: streamedText,
+                            agentName: state.agentName,
+                        });
+                    }
+                    catch (persistErr) {
+                        writeSse(res, {
+                            type: "error",
+                            message: getErrorMessage(persistErr),
+                        });
+                    }
+                }
+                else {
+                    logger.warn({
+                        err: getErrorMessage(err),
+                        stack: err instanceof Error ? err.stack : undefined,
+                    }, "Chat generation failed with no streamed text");
+                    const alreadyPersistedVisibleAssistantTurn = await hasRecentVisibleAssistantMemorySince(runtime, conv.roomId, turnStartedAt);
+                    if (alreadyPersistedVisibleAssistantTurn) {
+                        logger.warn({
+                            err: getErrorMessage(err),
+                            conversationId: conv.id,
+                            roomId: conv.roomId,
+                        }, "Chat generation failed after an assistant reply was already persisted — suppressing synthetic fallback");
+                        writeSseJson(res, {
+                            type: "done",
+                            fullText: "",
+                            agentName: state.agentName,
+                        });
+                        return true;
+                    }
+                    const providerIssueReply = getChatFailureReply(err, state.logBuffer);
+                    const failureKind = classifyChatFailure(err, state.logBuffer);
+                    try {
+                        await persistAssistantConversationMemory(runtime, conv.roomId, providerIssueReply, channelType);
+                        conv.updatedAt = new Date().toISOString();
+                        writeSse(res, {
+                            type: "done",
+                            fullText: providerIssueReply,
+                            agentName: state.agentName,
+                            // See non-streaming branch — renderer gates chat input on
+                            // failureKind === "no_provider".
+                            failureKind,
+                        });
+                    }
+                    catch (persistErr) {
+                        writeSse(res, {
+                            type: "error",
+                            message: getErrorMessage(persistErr),
+                        });
+                    }
+                }
+            }
+        }
+        finally {
+            clearInterval(heartbeatInterval);
+            finishStreamResponse();
+            // Persistence runs after the client has already received `done` + the
+            // socket is closed. Failures must still be observable — never swallow.
+            if (deferredPersistence !== null) {
+                deferredPersistence.catch((persistErr) => {
+                    logger.error({
+                        roomId: conv.roomId,
+                        err: getErrorMessage(persistErr),
+                    }, "[ConversationStream] persistence failed");
+                });
+            }
+        }
+        return true;
+    }
+    // ── POST /api/conversations/:id/messages ────────────────────────────
+    if (method === "POST" &&
+        /^\/api\/conversations\/[^/]+\/messages$/.test(pathname)) {
+        const convId = decodeURIComponent(pathname.split("/")[3]);
+        const conv = await getConversationWithRestore(state, convId);
+        if (!conv) {
+            error(res, "Conversation not found", 404);
+            return true;
+        }
+        if (rejectWaifuConversationAccessIfNeeded(req, conv, error, res)) {
+            return true;
+        }
+        const chatPayload = await readChatRequestPayload(req, res, {
+            readJsonBody,
+            error,
+        });
+        if (!chatPayload)
+            return true;
+        const { prompt, channelType, images, preferredLanguage, source, metadata: restMetadata, } = chatPayload;
+        // Hold the turn through the warming window (early API bind → runtime ready)
+        // instead of dropping it; the client already shows the optimistic bubble.
+        const runtime = await resolveRuntimeForChatTurn(state);
+        if (!runtime) {
+            error(res, "Agent is not running", 503);
+            return true;
+        }
+        const caller = resolveConversationCaller(req, state);
+        const userId = caller.entityId;
+        const turnStartedAt = Date.now();
+        try {
+            await ensureConversationRoom(state, conv, caller);
+        }
+        catch (err) {
+            error(res, `Failed to initialize conversation room: ${getErrorMessage(err)}`, 500);
+            return true;
+        }
+        const { userMessage, messageToStore } = await buildUserMessages({
+            images,
+            prompt,
+            userId,
+            agentId: runtime.agentId,
+            roomId: conv.roomId,
+            channelType,
+            messageSource: source,
+            metadata: restMetadata,
+        });
+        try {
+            await persistConversationMemory(runtime, messageToStore);
+        }
+        catch (err) {
+            error(res, `Failed to store user message: ${getErrorMessage(err)}`, 500);
+            return true;
+        }
+        const walletModeGuidance = resolveWalletModeGuidanceReply(state, prompt);
+        if (walletModeGuidance) {
+            try {
+                await persistAssistantConversationMemory(runtime, conv.roomId, walletModeGuidance, channelType, turnStartedAt);
+                conv.updatedAt = new Date().toISOString();
+                json(res, {
+                    text: walletModeGuidance,
+                    agentName: state.agentName,
+                });
+            }
+            catch (persistErr) {
+                error(res, getErrorMessage(persistErr), 500);
+            }
+            return true;
+        }
+        try {
+            const result = await generateChatResponse(runtime, userMessage, state.agentName, {
+                resolveNoResponseText: () => resolveNoResponseFallback(state.logBuffer, runtime),
+                preferredLanguage,
+            });
+            conv.updatedAt = new Date().toISOString();
+            if (result.noResponseReason !== "ignored") {
+                const resolvedText = normalizeChatResponseText(result.text, state.logBuffer, runtime);
+                if (result.actionCallbackHistory?.length) {
+                    await persistRecentAssistantActionCallbackHistory(runtime, conv.roomId, result.actionCallbackHistory, turnStartedAt);
+                }
+                if (await shouldPersistFinalAssistantTurn(runtime, conv.roomId, turnStartedAt, result)) {
+                    await persistAssistantConversationMemory(runtime, conv.roomId, buildPersistedAssistantContent(resolvedText, result), channelType, turnStartedAt);
+                }
+                json(res, {
+                    text: resolvedText,
+                    agentName: result.agentName,
+                });
+            }
+            else {
+                json(res, {
+                    text: "",
+                    agentName: result.agentName,
+                    noResponseReason: "ignored",
+                });
+            }
+        }
+        catch (err) {
+            logger.warn(`[conversations] POST /messages failed: ${err instanceof Error ? err.message : String(err)}`);
+            const providerIssueReply = getChatFailureReply(err, state.logBuffer);
+            const failureKind = classifyChatFailure(err, state.logBuffer);
+            try {
+                await persistAssistantConversationMemory(runtime, conv.roomId, providerIssueReply, channelType);
+                conv.updatedAt = new Date().toISOString();
+                json(res, {
+                    text: providerIssueReply,
+                    agentName: state.agentName,
+                    // Renderer keys off this discriminator. "no_provider" means the
+                    // chat input should be gated with a "Connect a provider" CTA
+                    // instead of treating the message text as a normal assistant
+                    // reply (the user can't make progress without taking action).
+                    failureKind,
+                });
+            }
+            catch (persistErr) {
+                error(res, getErrorMessage(persistErr), 500);
+            }
+        }
+        return true;
+    }
+    // ── POST /api/conversations/:id/greeting ───────────────────────────
+    if (method === "POST" &&
+        /^\/api\/conversations\/[^/]+\/greeting$/.test(pathname)) {
+        const convId = decodeURIComponent(pathname.split("/")[3]);
+        const conv = await getConversationWithRestore(state, convId);
+        if (!conv) {
+            error(res, "Conversation not found", 404);
+            return true;
+        }
+        if (rejectWaifuConversationAccessIfNeeded(req, conv, error, res)) {
+            return true;
+        }
+        const runtime = state.runtime;
+        if (!runtime) {
+            error(res, "Agent is not running", 503);
+            return true;
+        }
+        const url = new URL(req.url ?? "", `http://${req.headers.host}`);
+        const lang = url.searchParams.get("lang") ?? "en";
+        try {
+            await ensureConversationRoom(state, conv, resolveConversationCaller(req, state));
+        }
+        catch (err) {
+            error(res, `Failed to initialize conversation room: ${getErrorMessage(err)}`, 500);
+            return true;
+        }
+        try {
+            const greeting = await ensureConversationGreetingStored(state, conv, lang);
+            json(res, {
+                text: greeting.text,
+                agentName: greeting.agentName,
+                generated: greeting.generated,
+                persisted: greeting.persisted,
+            });
+        }
+        catch (err) {
+            error(res, getErrorMessage(err), 500);
+        }
+        return true;
+    }
+    // ── PATCH /api/conversations/:id ────────────────────────────────────
+    if (method === "PATCH" &&
+        /^\/api\/conversations\/[^/]+$/.test(pathname) &&
+        !pathname.endsWith("/messages")) {
+        const convId = decodeURIComponent(pathname.split("/")[3]);
+        const conv = await getConversationWithRestore(state, convId);
+        if (!conv) {
+            error(res, "Conversation not found", 404);
+            return true;
+        }
+        if (rejectWaifuNonAdminMutationIfNeeded(req, error, res))
+            return true;
+        const rawPatch = await readJsonBody(req, res);
+        if (rawPatch === null)
+            return true;
+        const parsedPatch = PatchConversationRequestSchema.safeParse(rawPatch);
+        if (!parsedPatch.success) {
+            error(res, parsedPatch.error.issues[0]?.message ?? "Invalid request body", 400);
+            return true;
+        }
+        const body = parsedPatch.data;
+        if (body.generate) {
+            if (!state.runtime) {
+                error(res, "Agent is not running", 503);
+                return true;
+            }
+            // Get the last user message to use as the prompt for generation
+            let prompt = "A generic conversation";
+            try {
+                const memories = await state.runtime.getMemories({
+                    roomId: conv.roomId,
+                    tableName: "messages",
+                    limit: 5,
+                });
+                const lastUserMemory = memories.find((m) => m.entityId !== state.runtime?.agentId);
+                if (lastUserMemory?.content?.text) {
+                    prompt = String(lastUserMemory.content.text);
+                }
+            }
+            catch (err) {
+                logger.warn(`[conversations] Failed to fetch context for title generation: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            const titleAbortTracker = createRequestDisconnectAbortTracker({
+                req,
+                res,
+                operation: "conversation title generation",
+            });
+            let newTitle = null;
+            try {
+                newTitle = await generateConversationTitle(state.runtime, prompt, state.agentName, { signal: titleAbortTracker.signal });
+            }
+            finally {
+                titleAbortTracker.markCompleted();
+                titleAbortTracker.dispose();
+            }
+            if (titleAbortTracker.isAborted())
+                return true;
+            const fallbackTitle = prompt
+                .replace(/\s+/g, " ")
+                .trim()
+                .split(" ")
+                .slice(0, 5)
+                .join(" ")
+                .trim();
+            const resolvedTitle = newTitle ?? fallbackTitle;
+            if (resolvedTitle) {
+                conv.title = resolvedTitle;
+                conv.updatedAt = new Date().toISOString();
+                await syncConversationRoomState(state, conv);
+            }
+        }
+        else if (body.title?.trim()) {
+            conv.title = body.title.trim();
+            conv.updatedAt = new Date().toISOString();
+            await syncConversationRoomState(state, conv);
+        }
+        if (body.metadata !== undefined) {
+            const nextMetadata = sanitizeConversationMetadata(body.metadata);
+            if (nextMetadata) {
+                conv.metadata = nextMetadata;
+            }
+            else {
+                delete conv.metadata;
+            }
+            conv.updatedAt = new Date().toISOString();
+            await syncConversationRoomState(state, conv);
+        }
+        json(res, { conversation: conv });
+        return true;
+    }
+    // ── POST /api/conversations/cleanup-empty ───────────────────────────
+    if (method === "POST" && pathname === "/api/conversations/cleanup-empty") {
+        if (rejectWaifuNonAdminMutationIfNeeded(req, error, res))
+            return true;
+        const rawCleanup = await readJsonBody(req, res);
+        if (rawCleanup === null)
+            return true;
+        const parsedCleanup = PostConversationCleanupEmptyRequestSchema.safeParse(rawCleanup);
+        if (!parsedCleanup.success) {
+            error(res, parsedCleanup.error.issues[0]?.message ?? "Invalid request body", 400);
+            return true;
+        }
+        await waitForConversationRestore(state);
+        const runtime = state.runtime;
+        if (!runtime) {
+            json(res, { deleted: [] });
+            return true;
+        }
+        const keepId = parsedCleanup.data.keepId;
+        const agentId = runtime.agentId;
+        const deleted = [];
+        for (const conv of Array.from(state.conversations.values())) {
+            if (keepId && conv.id === keepId)
+                continue;
+            if (state.deletedConversationIds.has(conv.id))
+                continue;
+            const memories = await runtime.getMemories({
+                roomId: conv.roomId,
+                tableName: "messages",
+                limit: 10,
+            });
+            const hasUserMessage = memories.some((m) => m.entityId !== agentId);
+            if (hasUserMessage)
+                continue;
+            const memoryIds = memories
+                .map((memory) => memory.id)
+                .filter((memoryId) => typeof memoryId === "string" && memoryId.trim().length > 0);
+            if (memoryIds.length > 0) {
+                await deleteConversationMemories(runtime, memoryIds);
+            }
+            await deleteConversationRoomData(runtime, conv.roomId);
+            state.conversations.delete(conv.id);
+            markConversationDeleted(state, conv.id);
+            deleted.push(conv.id);
+        }
+        json(res, { deleted });
+        return true;
+    }
+    // ── DELETE /api/conversations/:id ───────────────────────────────────
+    if (method === "DELETE" &&
+        /^\/api\/conversations\/[^/]+$/.test(pathname) &&
+        !pathname.endsWith("/messages")) {
+        if (rejectWaifuNonAdminMutationIfNeeded(req, error, res))
+            return true;
+        const convId = decodeURIComponent(pathname.split("/")[3]);
+        const conv = await getConversationWithRestore(state, convId);
+        if (conv?.roomId && state.runtime) {
+            try {
+                const memories = await state.runtime.getMemories({
+                    roomId: conv.roomId,
+                    tableName: "messages",
+                    limit: 1000,
+                });
+                const memoryIds = memories
+                    .map((memory) => memory.id)
+                    .filter((memoryId) => typeof memoryId === "string" && memoryId.trim().length > 0);
+                if (memoryIds.length > 0) {
+                    await deleteConversationMemories(state.runtime, memoryIds);
+                }
+            }
+            catch (err) {
+                logger.debug(`[conversations] Failed to delete messages for ${convId}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            try {
+                await deleteConversationRoomData(state.runtime, conv.roomId);
+            }
+            catch (err) {
+                logger.debug(`[conversations] Failed to delete room data for ${convId}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        state.conversations.delete(convId);
+        markConversationDeleted(state, convId);
+        json(res, { ok: true });
+        return true;
+    }
+    return false;
+}