@elizaos/agent 0.25.9 → 2.0.0-alpha.151

package/packages/agent/src/api/conversation-routes.js

@@ -0,0 +1,1128 @@
+/**
+ * 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 { resolveStateDir } from "../config/paths.js";
+import { generateChatResponse, generateConversationTitle, getChatFailureReply, hasRecentVisibleAssistantMemorySince, initSse, normalizeChatResponseText, persistAssistantConversationMemory, persistConversationMemory, readChatRequestPayload, resolveNoResponseFallback, writeChatTokenSse, writeSse, writeSseJson, } from "./chat-routes.js";
+import { cacheDiscordAvatarForRuntime, isCanonicalDiscordSource, resolveDiscordMessageAuthorProfile, resolveDiscordUserProfile, resolveStoredDiscordEntityProfile, } from "./discord-profiles.js";
+import { evictOldestConversation } from "./memory-bounds.js";
+import { buildUserMessages, getErrorMessage, isUuidLike, persistConversationRoomTitle, resolveAppUserName, resolveConversationGreetingText, resolveWalletModeGuidanceReply, } from "./server-helpers.js";
+// ---------------------------------------------------------------------------
+// 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 });
+}
+// ---------------------------------------------------------------------------
+// Closure-lifted helpers
+// ---------------------------------------------------------------------------
+function ensureAdminEntityId(state) {
+    if (state.adminEntityId) {
+        return state.adminEntityId;
+    }
+    const configuredValue = state.config.agents?.defaults?.adminEntityId;
+    const configured = typeof configuredValue === "string" ? configuredValue.trim() : undefined;
+    const nextAdminEntityId = configured && isUuidLike(configured)
+        ? configured
+        : stringToUuid(`${state.agentName}-admin-entity`);
+    if (configured && !isUuidLike(configured)) {
+        logger.warn(`[eliza-api] Invalid agents.defaults.adminEntityId "${configured}", using deterministic fallback`);
+    }
+    state.adminEntityId = nextAdminEntityId;
+    state.chatUserId = state.adminEntityId;
+    return nextAdminEntityId;
+}
+async function ensureWorldOwnershipAndRoles(runtime, worldId, ownerId) {
+    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 (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) {
+    if (!state.runtime)
+        return;
+    const runtime = state.runtime;
+    const agentName = runtime.character.name ?? "Eliza";
+    const userId = ensureAdminEntityId(state);
+    const worldId = stringToUuid(`${agentName}-web-chat-world`);
+    const messageServerId = stringToUuid(`${agentName}-web-server`);
+    await runtime.ensureConnection({
+        entityId: userId,
+        roomId: conv.roomId,
+        worldId,
+        userName: resolveAppUserName(state.config),
+        source: "client_chat",
+        channelId: `web-conv-${conv.id}`,
+        type: ChannelType.DM,
+        messageServerId,
+        metadata: { ownership: { ownerId: userId } },
+    });
+    await ensureWorldOwnershipAndRoles(runtime, worldId, userId);
+}
+async function syncConversationRoomTitle(state, conv) {
+    try {
+        await persistConversationRoomTitle(state.runtime, conv);
+    }
+    catch (err) {
+        logger.debug(`[conversations] Failed to persist room title for ${conv.id}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+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();
+    const visibleHistory = trimmedText.length > 0 && history.at(-1) === trimmedText
+        ? history.slice(0, -1)
+        : history;
+    if (visibleHistory.length === 0) {
+        return text;
+    }
+    return trimmedText.length > 0
+        ? `${visibleHistory.join("\n")}\n\n${text}`
+        : visibleHistory.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;
+}
+async function ensureConversationGreetingStored(state, conv, lang) {
+    const runtime = state.runtime;
+    const agentName = runtime?.character.name ?? state.agentName ?? "Eliza";
+    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 convos = Array.from(state.conversations.values())
+            .filter((c) => !state.deletedConversationIds.has(c.id))
+            .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 body = await readJsonBody(req, res);
+        if (!body)
+            return true;
+        await waitForConversationRestore(state);
+        const id = crypto.randomUUID();
+        const now = new Date().toISOString();
+        const roomId = stringToUuid(`web-conv-${id}`);
+        const conv = {
+            id,
+            title: body.title?.trim() || "New Chat",
+            roomId,
+            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);
+                await syncConversationRoomTitle(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 (!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 actionCallbackHistory = normalizeActionCallbackHistory(content.actionCallbackHistory);
+                return {
+                    id: m.id ?? "",
+                    role: m.entityId === agentId ? "assistant" : "user",
+                    text: formatConversationMessageText(m.content?.text ?? "", actionCallbackHistory),
+                    timestamp: m.createdAt ?? 0,
+                    source: normalizedSource,
+                    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.
+                .filter((m) => m.text.trim().length > 0);
+            await Promise.all(messages.map(async (message) => {
+                if (!isCanonicalDiscordSource(message.source)) {
+                    return;
+                }
+                const storedSenderProfile = await 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 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 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 cacheDiscordAvatarForRuntime(runtime, message.avatarUrl, rawSenderId);
+            }));
+            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/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;
+        }
+        const body = await readJsonBody(req, res);
+        if (!body)
+            return true;
+        const messageId = typeof body.messageId === "string" ? body.messageId.trim() : "";
+        if (!messageId) {
+            error(res, "messageId is required", 400);
+            return true;
+        }
+        const runtime = state.runtime;
+        if (!runtime) {
+            error(res, "Agent is not running", 503);
+            return true;
+        }
+        try {
+            const result = await truncateConversationMessages(runtime, conv, messageId, {
+                inclusive: body.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;
+        }
+        const chatPayload = await readChatRequestPayload(req, res, {
+            readJsonBody,
+            error,
+        });
+        if (!chatPayload)
+            return true;
+        const { prompt, channelType, images, conversationMode, preferredLanguage, source, metadata: chatMetadata, } = chatPayload;
+        const runtime = state.runtime;
+        if (!runtime) {
+            error(res, "Agent is not running", 503);
+            return true;
+        }
+        const userId = ensureAdminEntityId(state);
+        const turnStartedAt = Date.now();
+        try {
+            await ensureConversationRoom(state, conv);
+        }
+        catch (err) {
+            error(res, `Failed to initialize conversation room: ${getErrorMessage(err)}`, 500);
+            return true;
+        }
+        const { userMessage, messageToStore } = buildUserMessages({
+            images,
+            prompt,
+            userId,
+            agentId: runtime.agentId,
+            roomId: conv.roomId,
+            channelType,
+            conversationMode,
+            messageSource: source,
+            metadata: chatMetadata,
+        });
+        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) {
+            initSse(res);
+            let aborted = false;
+            req.on("close", () => {
+                aborted = true;
+            });
+            if (!aborted) {
+                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),
+                    });
+                    res.end();
+                    return true;
+                }
+                writeSseJson(res, {
+                    type: "done",
+                    fullText: walletModeGuidance,
+                    agentName: state.agentName,
+                });
+            }
+            res.end();
+            return true;
+        }
+        // ── Local runtime path (streaming) ───────────────────────
+        initSse(res);
+        let aborted = false;
+        req.on("close", () => {
+            aborted = true;
+        });
+        // SSE heartbeat to keep connection alive during long generation
+        const heartbeatInterval = setInterval(() => {
+            if (!aborted && !res.writableEnded) {
+                res.write(": heartbeat\n\n");
+            }
+        }, 5000);
+        let streamedText = "";
+        try {
+            const result = await generateChatResponse(runtime, userMessage, state.agentName, {
+                isAborted: () => aborted,
+                onChunk: (chunk) => {
+                    if (!chunk)
+                        return;
+                    streamedText += chunk;
+                    writeChatTokenSse(res, chunk, streamedText);
+                },
+                onSnapshot: (text) => {
+                    if (!text)
+                        return;
+                    streamedText = text;
+                    writeChatTokenSse(res, text, streamedText);
+                },
+                resolveNoResponseText: () => resolveNoResponseFallback(state.logBuffer, runtime),
+                preferredLanguage,
+            });
+            if (!aborted) {
+                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);
+                    }
+                    writeSseJson(res, {
+                        type: "done",
+                        fullText: resolvedText,
+                        agentName: result.agentName,
+                        ...(result.usage ? { estimatedUsage: result.usage } : {}),
+                    });
+                }
+                else {
+                    writeSseJson(res, {
+                        type: "done",
+                        fullText: "",
+                        agentName: result.agentName,
+                        noResponseReason: "ignored",
+                        ...(result.usage ? { estimatedUsage: result.usage } : {}),
+                    });
+                }
+            }
+        }
+        catch (err) {
+            if (!aborted) {
+                // If text was already streamed to the client (e.g. the initial
+                // response succeeded but a post-action continuation 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) }, "Chat generation failed with no streamed text");
+                    const providerIssueReply = getChatFailureReply(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,
+                        });
+                    }
+                    catch (persistErr) {
+                        writeSse(res, {
+                            type: "error",
+                            message: getErrorMessage(persistErr),
+                        });
+                    }
+                }
+            }
+        }
+        finally {
+            clearInterval(heartbeatInterval);
+            res.end();
+        }
+        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;
+        }
+        const chatPayload = await readChatRequestPayload(req, res, {
+            readJsonBody,
+            error,
+        });
+        if (!chatPayload)
+            return true;
+        const { prompt, channelType, images, conversationMode, preferredLanguage, source, metadata: restMetadata, } = chatPayload;
+        const runtime = state.runtime;
+        if (!runtime) {
+            error(res, "Agent is not running", 503);
+            return true;
+        }
+        const userId = ensureAdminEntityId(state);
+        const turnStartedAt = Date.now();
+        try {
+            await ensureConversationRoom(state, conv);
+        }
+        catch (err) {
+            error(res, `Failed to initialize conversation room: ${getErrorMessage(err)}`, 500);
+            return true;
+        }
+        const { userMessage, messageToStore } = buildUserMessages({
+            images,
+            prompt,
+            userId,
+            agentId: runtime.agentId,
+            roomId: conv.roomId,
+            channelType,
+            conversationMode,
+            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);
+            try {
+                await persistAssistantConversationMemory(runtime, conv.roomId, providerIssueReply, channelType);
+                conv.updatedAt = new Date().toISOString();
+                json(res, {
+                    text: providerIssueReply,
+                    agentName: state.agentName,
+                });
+            }
+            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;
+        }
+        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);
+        }
+        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;
+        }
+        const body = await readJsonBody(req, res);
+        if (!body)
+            return true;
+        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 newTitle = await generateConversationTitle(state.runtime, prompt, state.agentName);
+            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 syncConversationRoomTitle(state, conv);
+            }
+        }
+        else if (body.title?.trim()) {
+            conv.title = body.title.trim();
+            conv.updatedAt = new Date().toISOString();
+            await syncConversationRoomTitle(state, conv);
+        }
+        json(res, { conversation: conv });
+        return true;
+    }
+    // ── DELETE /api/conversations/:id ───────────────────────────────────
+    if (method === "DELETE" &&
+        /^\/api\/conversations\/[^/]+$/.test(pathname) &&
+        !pathname.endsWith("/messages")) {
+        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;
+}