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

package/api/chat-routes.js

@@ -0,0 +1,2495 @@
+/**
+ * Chat route handlers extracted from server.ts.
+ *
+ * Handles:
+ *   POST /v1/chat/completions   – OpenAI-compatible
+ *   POST /v1/messages           – Anthropic-compatible
+ *   GET  /v1/models             – OpenAI model listing
+ *   GET  /v1/models/:id         – OpenAI single model
+ *
+ * Also exports generateChatResponse() and supporting helpers so that
+ * conversation-routes.ts (and server.ts itself) can reuse them.
+ */
+import crypto from "node:crypto";
+import { ChannelType, createMessageMemory, logger, ModelType, runWithTrajectoryContext, stringToUuid, } from "@elizaos/core";
+import { asRecord, extractAssistantReplyText, normalizeCharacterLanguage, resolveStreamingUpdate, } from "@elizaos/shared";
+import { estimateTokenCount, withModelUsageCapture, } from "../runtime/prompt-optimization.js";
+import { resolveTrajectoryGrouping } from "../runtime/trajectory-internals.js";
+import { startTrajectoryStepInDatabase } from "../runtime/trajectory-storage.js";
+import { syncCharacterIntoConfig } from "../services/character-persistence.js";
+import { detectRuntimeModel } from "./agent-model.js";
+import { executeFallbackParsedActions, maybeHandleDirectBinanceSkillRequest, parseFallbackActionBlocks, } from "./binance-skill-helpers.js";
+import { maybeAugmentChatMessageWithDocuments, maybeAugmentChatMessageWithLanguage, } from "./chat-augmentation.js";
+import { isClientVisibleNoResponse, isNoResponsePlaceholder, } from "./chat-text-helpers.js";
+import { resolveClientChatAdminEntityId } from "./client-chat-admin.js";
+import { extractAnthropicSystemAndLastUser, extractCompatTextContent, extractOpenAiSystemAndLastUser, resolveCompatRoomKey, } from "./compat-utils.js";
+import { isInsufficientCreditsError, isInsufficientCreditsMessage, } from "./credit-detection.js";
+import { buildWalletActionNotExecutedReply, cloneWithoutBlockedObjectKeys, decodePathComponent, getErrorMessage, hasBlockedObjectKeyDeep, isWalletActionRequiredIntent, maybeAugmentChatMessageWithWalletContext, normalizeIncomingChatPrompt, resolveAppUserName, trimWalletProgressPrefix, validateChatImages, } from "./server-helpers.js";
+const DEFAULT_CONVERSATION_TITLE_TIMEOUT_MS = 5_000;
+let localInferenceChatApiPromise = null;
+function getLocalInferenceChatApi() {
+    localInferenceChatApiPromise ??= import("@elizaos/plugin-local-inference");
+    return localInferenceChatApiPromise;
+}
+const CHAT_MAX_BODY_BYTES = 20 * 1024 * 1024; // 20 MB (image-capable)
+/** Max accepted client-supplied idempotency key length. Anything longer is a
+ *  malformed/abusive client and is treated as absent (no dedupe). */
+const CLIENT_MESSAGE_ID_MAX_LENGTH = 128;
+/**
+ * Short-window idempotency cache for the HTTP chat path, the analogue of the
+ * WebSocket `isDuplicateWsMessage` cache in server.ts. Chat sends go over HTTP
+ * SSE (not WS), so the WS cache does not cover them. The client stamps a stable
+ * `clientMessageId` on every send (`ui/src/api/client-base.ts`); a retried or
+ * double-submitted POST carries the same id, and without this guard would start
+ * a second LLM turn and persist a duplicate assistant memory (report 05,
+ * Finding 1 / W3.1).
+ *
+ * Keyed by `${conversationOrUserScope}:${clientMessageId}` so a legitimately
+ * identical message in a different conversation, or the same text re-sent after
+ * the TTL, is NOT suppressed. Entries expire after `CHAT_DEDUPE_TTL_MS`; the map
+ * stays bounded via an amortized sweep (at most once per TTL window) — the same
+ * O(1)-check / amortized-eviction shape as the WS cache.
+ */
+const chatSeenMessageIds = new Map();
+const CHAT_DEDUPE_TTL_MS = 30_000;
+let chatSeenLastSweepAt = 0;
+/** Normalize a raw body value into a usable idempotency key, or `null` when
+ *  absent/invalid. Exported for unit testing the dedupe decision in isolation. */
+export function normalizeClientMessageId(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    if (trimmed.length === 0 || trimmed.length > CLIENT_MESSAGE_ID_MAX_LENGTH) {
+        return null;
+    }
+    return trimmed;
+}
+/**
+ * TTL-aware O(1) duplicate check for an HTTP chat send. Returns `true` when this
+ * `(scope, clientMessageId)` pair was already seen within the TTL window. When
+ * `clientMessageId` is absent/invalid the result is ALWAYS `false`, so requests
+ * without an idempotency key behave exactly as before (no dedupe). The first
+ * sighting records the timestamp and returns `false`; a repeat within the window
+ * returns `true`. After the TTL elapses the id is treated as new again.
+ *
+ * `scope` is the conversation room id (dashboard chat) or the per-user room key
+ * (agent-message API) so the key cannot collide across conversations/users.
+ */
+export function isDuplicateChatMessage(scope, clientMessageId, now = Date.now()) {
+    if (!clientMessageId)
+        return false;
+    const key = `${scope}:${clientMessageId}`;
+    const seenAt = chatSeenMessageIds.get(key);
+    if (seenAt !== undefined && now - seenAt <= CHAT_DEDUPE_TTL_MS)
+        return true;
+    chatSeenMessageIds.set(key, now);
+    // Amortized eviction: sweep expired entries at most once per TTL window
+    // rather than on every request, keeping the map bounded without a per-request
+    // O(n) scan.
+    if (now - chatSeenLastSweepAt > CHAT_DEDUPE_TTL_MS) {
+        chatSeenLastSweepAt = now;
+        for (const [seenKey, ts] of chatSeenMessageIds) {
+            if (now - ts > CHAT_DEDUPE_TTL_MS)
+                chatSeenMessageIds.delete(seenKey);
+        }
+    }
+    return false;
+}
+/** Test-only: clear the HTTP chat idempotency cache between cases. */
+export function __resetChatDedupeForTests() {
+    chatSeenMessageIds.clear();
+    chatSeenLastSweepAt = 0;
+}
+const ANDROID_LOCAL_DIRECT_CHAT_DENY_PATTERN = /\b(check|search|find|fetch|get|look\s+up|browse|open|click|call|email|send|create|update|delete|save|remember|schedule|remind|set|run|execute|install|download|upload|read|inspect|build|deploy|commit|push|pull|merge|rebase|book|pay|buy|order)\b/i;
+const ANDROID_LOCAL_CURRENT_DATA_PATTERN = /\b(latest|current|today|tomorrow|yesterday|weather|price|calendar|email|file|repo|repository|log|logs|issue|issues|pr|pull\s+request|wallet|transaction|account|contact|contacts)\b/i;
+const ANDROID_LOCAL_CONTEXTUAL_MEMORY_PATTERN = /\b(what\s+did\s+i\s+just\s+say|what\s+(?:is|'s)\s+my\s+name|who\s+am\s+i|do\s+you\s+remember|remember\s+(?:me|my|that)|what\s+was\s+my|what\s+did\s+we|previous(?:ly)?|earlier|last\s+(?:message|thing|question|conversation)|recent\s+(?:message|conversation)|my\s+(?:name|email|address|phone|preference|preferences))\b/i;
+function readRuntimeStringSetting(runtime, key) {
+    const setting = typeof runtime.getSetting === "function" ? runtime.getSetting(key) : null;
+    if (typeof setting === "string" && setting.trim().length > 0) {
+        return setting.trim();
+    }
+    if (typeof setting === "number" || typeof setting === "boolean") {
+        return String(setting);
+    }
+    const env = process.env[key];
+    return typeof env === "string" && env.trim().length > 0 ? env.trim() : null;
+}
+function readPositiveIntegerSetting(runtime, key, fallback) {
+    const raw = readRuntimeStringSetting(runtime, key);
+    const parsed = raw ? Number.parseInt(raw, 10) : Number.NaN;
+    return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+function isAndroidLocalDirectChatRuntime(runtime) {
+    const optOut = readRuntimeStringSetting(runtime, "ELIZA_MOBILE_LOCAL_DIRECT_REPLY");
+    if (/^(0|false|no|off)$/i.test(optOut ?? "")) {
+        return false;
+    }
+    const platform = readRuntimeStringSetting(runtime, "ELIZA_MOBILE_PLATFORM") ??
+        readRuntimeStringSetting(runtime, "ELIZA_PLATFORM");
+    const normalizedPlatform = platform?.toLowerCase();
+    const localLlama = readRuntimeStringSetting(runtime, "ELIZA_LOCAL_LLAMA") === "1" ||
+        readRuntimeStringSetting(runtime, "ELIZA_DEVICE_BRIDGE_ENABLED") === "1" ||
+        readRuntimeStringSetting(runtime, "ELIZA_IOS_LOCAL_BACKEND") === "1";
+    return ((normalizedPlatform === "android" || normalizedPlatform === "ios") &&
+        localLlama);
+}
+function hasAndroidLocalDirectChatBlockingContent(content) {
+    if (Array.isArray(content.attachments) && content.attachments.length > 0) {
+        return true;
+    }
+    if (Array.isArray(content.media) && content.media.length > 0) {
+        return true;
+    }
+    if (Array.isArray(content.files) && content.files.length > 0) {
+        return true;
+    }
+    if (content.documentIds || content.documents || content.localInference) {
+        return true;
+    }
+    const metadata = content.metadata && typeof content.metadata === "object"
+        ? content.metadata
+        : {};
+    return Boolean(metadata.benchmark || metadata.localInference || metadata.contextRouting);
+}
+function isAndroidLocalDirectChatChannel(content) {
+    const channelType = content.channelType;
+    return (channelType === ChannelType.API ||
+        channelType === ChannelType.DM ||
+        channelType === ChannelType.SELF ||
+        channelType === ChannelType.VOICE_DM ||
+        channelType === undefined);
+}
+function shouldUseAndroidLocalDirectChat(runtime, message) {
+    if (!isAndroidLocalDirectChatRuntime(runtime)) {
+        return false;
+    }
+    const text = normalizeAndroidLocalDirectUserText(extractCompatTextContent(message.content));
+    if (!text || text.length > 700) {
+        return false;
+    }
+    if (!isAndroidLocalDirectChatChannel(message.content)) {
+        return false;
+    }
+    if (hasAndroidLocalDirectChatBlockingContent(message.content)) {
+        return false;
+    }
+    if (ANDROID_LOCAL_DIRECT_CHAT_DENY_PATTERN.test(text)) {
+        return false;
+    }
+    if (ANDROID_LOCAL_CONTEXTUAL_MEMORY_PATTERN.test(text)) {
+        return false;
+    }
+    if (ANDROID_LOCAL_CURRENT_DATA_PATTERN.test(text)) {
+        return /\b(local|locally|on[-\s]?device|device|pixel|eliza[-\s]?1|llama)\b/i.test(text);
+    }
+    return true;
+}
+function escapeAndroidLocalChatTemplateTokens(text) {
+    return text
+        .replaceAll("<|im_start|>", "<| im_start |>")
+        .replaceAll("<|im_end|>", "<| im_end |>")
+        .replaceAll("<think>", "< think >")
+        .replaceAll("</think>", "</ think >");
+}
+function normalizeAndroidLocalDirectUserText(text) {
+    return text
+        .replace(/(^|\s)\/(?:no_)?think\b/gi, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function buildAndroidLocalDirectChatPrompt(args) {
+    const systemText = [
+        "Eliza-1 on device.",
+        "One natural sentence under 10 words. Stop after it.",
+        "If asked local/on-device: yes, local Eliza-1.",
+        "No markdown, labels, tools, logs, or hidden reasoning.",
+    ].join("\n");
+    return [
+        "<|im_start|>system",
+        systemText,
+        "<|im_end|>",
+        "<|im_start|>user",
+        escapeAndroidLocalChatTemplateTokens(args.userText),
+        "<|im_end|>",
+        "<|im_start|>assistant",
+        // Match llama.cpp's Qwen3 `enable_thinking=false` chat-template shape.
+        // The direct mobile path is for short voice/chat replies; pre-filling an
+        // empty think block prevents the model from spending its first tokens on
+        // hidden `<think>...</think>` scaffolding before any speakable text.
+        "<think>",
+        "",
+        "</think>",
+        "",
+    ].join("\n");
+}
+function extractAndroidLocalModelText(raw) {
+    if (typeof raw === "string") {
+        return raw;
+    }
+    if (!raw || typeof raw !== "object") {
+        return "";
+    }
+    const record = raw;
+    if (typeof record.text === "string") {
+        return record.text;
+    }
+    if (typeof record.content === "string") {
+        return record.content;
+    }
+    if (Array.isArray(record.content)) {
+        return record.content
+            .map((part) => {
+            if (typeof part === "string")
+                return part;
+            if (part && typeof part === "object") {
+                const partRecord = part;
+                return typeof partRecord.text === "string" ? partRecord.text : "";
+            }
+            return "";
+        })
+            .join("");
+    }
+    return "";
+}
+function truncateAndroidLocalReplyToFirstSentence(text) {
+    const compact = text.replace(/\s+/g, " ").trim();
+    if (!compact)
+        return "";
+    const firstSentence = compact.match(/^(.{12,280}?[.!?])(?:\s|$)/u)?.[1];
+    return (firstSentence ?? compact).trim();
+}
+function stripAndroidLocalReasoning(text) {
+    let next = text.replace(/<think>[\s\S]*?<\/think>/gi, "");
+    const danglingClose = next.lastIndexOf("</think>");
+    if (danglingClose >= 0) {
+        next = next.slice(danglingClose + "</think>".length);
+    }
+    const danglingOpen = next.indexOf("<think>");
+    if (danglingOpen >= 0) {
+        next = next.slice(0, danglingOpen);
+    }
+    return next;
+}
+function cleanAndroidLocalDirectChatReply(raw) {
+    let text = stripAndroidLocalReasoning(extractAndroidLocalModelText(raw));
+    text = text
+        .split("<|im_end|>")[0]
+        .split("<|im_start|>")[0]
+        .replace(/^\s*(assistant|eliza)\s*:\s*/i, "")
+        .replace(/\bEliza-1\b/gi, "Eliza-1")
+        .trim();
+    text = truncateAndroidLocalReplyToFirstSentence(text);
+    if (text.length <= 700) {
+        return text;
+    }
+    const truncated = text.slice(0, 700);
+    const sentenceEnd = Math.max(truncated.lastIndexOf("."), truncated.lastIndexOf("!"), truncated.lastIndexOf("?"));
+    return (sentenceEnd >= 80 ? truncated.slice(0, sentenceEnd + 1) : truncated).trim();
+}
+async function rewriteDirectActionCallbackText(args) {
+    const text = args.text.trim();
+    if (!text)
+        return args.text;
+    const fallback = () => {
+        const error = typeof args.content?.error === "string" && args.content.error.trim()
+            ? ` It reported: ${args.content.error.trim()}`
+            : "";
+        return `I ran ${args.actionName} and got a result, but I couldn't format the details cleanly here.${error}`;
+    };
+    try {
+        const raw = await args.runtime.useModel(ModelType.TEXT_SMALL, {
+            prompt: [
+                "Rewrite this direct action callback in the assistant character's user-facing voice.",
+                'Return strict JSON only: {"response":"..."}.',
+                "",
+                "Rules:",
+                "- Preserve status, IDs, names, URLs, counts, errors, and next steps.",
+                "- Do not expose raw JSON, shell output, schema names, stack traces, or internal action plumbing unless an exact value is necessary.",
+                "- Do not claim success if the payload says failed or pending.",
+                "- Keep it brief and natural.",
+                "",
+                `Character: ${JSON.stringify({
+                    name: args.runtime.character?.name,
+                    system: args.runtime.character?.system,
+                    bio: args.runtime.character?.bio,
+                    style: args.runtime.character?.style,
+                })}`,
+                `Action: ${JSON.stringify(args.actionName)}`,
+                `Payload: ${JSON.stringify(text)}`,
+                `Metadata: ${JSON.stringify({
+                    source: args.content?.source,
+                    actions: args.content?.actions,
+                    actionStatus: args.content?.actionStatus,
+                    error: args.content?.error,
+                })}`,
+            ].join("\n"),
+            maxTokens: 260,
+            providerOptions: { eliza: { thinking: "off" } },
+        });
+        const parsed = JSON.parse(String(raw).trim());
+        return typeof parsed.response === "string" && parsed.response.trim()
+            ? parsed.response.trim()
+            : fallback();
+    }
+    catch (err) {
+        args.runtime.logger.debug({
+            src: "eliza-api",
+            action: args.actionName,
+            err: err instanceof Error ? err.message : String(err),
+        }, "[eliza-api] Direct action callback voice rewrite failed");
+        return fallback();
+    }
+}
+async function maybeGenerateAndroidLocalDirectChatResponse(args) {
+    if (!shouldUseAndroidLocalDirectChat(args.runtime, args.message)) {
+        return null;
+    }
+    const userText = normalizeAndroidLocalDirectUserText(extractCompatTextContent(args.message.content));
+    if (!userText)
+        return null;
+    const prompt = buildAndroidLocalDirectChatPrompt({
+        runtime: args.runtime,
+        userText,
+    });
+    const maxTokens = readPositiveIntegerSetting(args.runtime, "ELIZA_MOBILE_LOCAL_DIRECT_REPLY_MAX_TOKENS", 20);
+    const startedAt = Date.now();
+    args.runtime.logger.info({
+        src: "eliza-api",
+        promptChars: prompt.length,
+        maxTokens,
+        messageId: args.message.id,
+    }, "[eliza-api] Android local direct chat fast path start");
+    let streamedRaw = "";
+    let lastStreamedSnapshot = "";
+    let streamedChunks = 0;
+    const emitCleanStreamingSnapshot = (snapshot) => {
+        if (!snapshot || snapshot === lastStreamedSnapshot)
+            return;
+        const update = resolveStreamingUpdate(lastStreamedSnapshot, snapshot);
+        if (update.kind === "append") {
+            args.opts?.onChunk?.(update.emittedText);
+        }
+        else if (update.kind === "replace" && !args.opts?.onSnapshot) {
+            // OpenAI-compatible SSE cannot rewrite already-sent text. In the rare
+            // case cleaning turns a partial local reply into a non-append snapshot,
+            // hold the rewrite for the final response body instead of duplicating
+            // content on the token stream.
+            args.runtime.logger.debug({
+                src: "eliza-api",
+                previousChars: lastStreamedSnapshot.length,
+                nextChars: snapshot.length,
+                messageId: args.message.id,
+            }, "[eliza-api] Android local direct chat fast path held non-append streaming snapshot");
+        }
+        args.opts?.onSnapshot?.(snapshot);
+        lastStreamedSnapshot = snapshot;
+    };
+    const raw = await args.runtime.useModel(ModelType.TEXT_SMALL, {
+        prompt,
+        maxTokens,
+        stopSequences: ["<|im_end|>", "<|im_start|>"],
+        temperature: 0,
+        providerOptions: {
+            eliza: {
+                thinking: "off",
+            },
+            androidLocal: {
+                stopOnFirstSentence: true,
+                minFirstSentenceChars: 12,
+            },
+        },
+        signal: args.signal,
+        stream: true,
+        onStreamChunk: (chunk) => {
+            streamedRaw += chunk;
+            streamedChunks += 1;
+            const snapshot = cleanAndroidLocalDirectChatReply(streamedRaw);
+            emitCleanStreamingSnapshot(snapshot);
+        },
+    });
+    const text = cleanAndroidLocalDirectChatReply(raw);
+    if (!text) {
+        args.runtime.logger.warn({ src: "eliza-api", messageId: args.message.id }, "[eliza-api] Android local direct chat fast path returned empty text");
+        return null;
+    }
+    const latencyMs = Date.now() - startedAt;
+    emitCleanStreamingSnapshot(text);
+    const localInference = {
+        provider: "mobile-local-direct-reply",
+        mode: "api_fast_path",
+        latencyMs,
+        promptChars: prompt.length,
+        maxTokens,
+        streamedChunks,
+    };
+    const responseContent = {
+        text,
+        source: "client_chat",
+        actions: ["REPLY"],
+        localInference,
+    };
+    args.runtime.logger.info({
+        src: "eliza-api",
+        latencyMs,
+        textChars: text.length,
+        messageId: args.message.id,
+    }, "[eliza-api] Android local direct chat fast path done");
+    return {
+        text,
+        agentName: args.agentName,
+        localInference,
+        responseContent,
+        usage: {
+            promptTokens: estimateTokenCount(prompt),
+            completionTokens: estimateTokenCount(text),
+            totalTokens: estimateTokenCount(prompt) + estimateTokenCount(text),
+            model: detectRuntimeModel(args.runtime, undefined) ?? undefined,
+            provider: "mobile-local-direct-reply",
+            isEstimated: true,
+            llmCalls: 1,
+        },
+    };
+}
+function resolveCallbackMergeMode(content, fallback = "replace") {
+    return content.merge === "append" || content.merge === "replace"
+        ? content.merge
+        : fallback;
+}
+function normalizeActionCallbackText(text) {
+    return text.trim();
+}
+function getLatestVisibleResponseMessageText(responseMessages) {
+    if (!Array.isArray(responseMessages) || responseMessages.length === 0) {
+        return "";
+    }
+    for (let index = responseMessages.length - 1; index >= 0; index -= 1) {
+        const content = responseMessages[index]?.content;
+        const text = typeof extractCompatTextContent(content) === "string"
+            ? extractCompatTextContent(content).trim()
+            : "";
+        if (!text || isNoResponsePlaceholder(text)) {
+            continue;
+        }
+        return text;
+    }
+    return "";
+}
+const EXACT_GROUNDED_VALUE_REQUEST = /\b(?:exact|verbatim|copy|quoted?|identifier|codeword|return only|only the)\b/i;
+const DOCUMENT_VALUE_CAPTURE = /\b(?:codeword|identifier|token|value)\s*(?:is|=|:)\s*([A-Za-z0-9][A-Za-z0-9._-]{1,127})\b/gi;
+const UPPERCASE_IDENTIFIER_CAPTURE = /\b[A-Z0-9]+(?:[-_][A-Z0-9]+)+\b/g;
+const UUID_IDENTIFIER_CAPTURE = /\b[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}\b/gi;
+function uniqueMatches(matches) {
+    return Array.from(new Set(Array.from(matches).map((value) => value.trim()))).filter((value) => value.length > 0);
+}
+function collectRegexMatches(text, pattern, groupIndex) {
+    const regex = new RegExp(pattern.source, pattern.flags);
+    return Array.from(text.matchAll(regex), (match) => String(groupIndex === undefined ? match[0] : (match[groupIndex] ?? "")));
+}
+function extractExactGroundedValueFromText(messageText, documentText) {
+    if (!messageText || !EXACT_GROUNDED_VALUE_REQUEST.test(messageText)) {
+        return null;
+    }
+    if (!documentText) {
+        return null;
+    }
+    const capturedDocumentValues = uniqueMatches(collectRegexMatches(documentText, DOCUMENT_VALUE_CAPTURE, 1));
+    if (capturedDocumentValues.length === 1) {
+        return capturedDocumentValues[0];
+    }
+    const uppercaseCandidates = uniqueMatches(collectRegexMatches(documentText, UPPERCASE_IDENTIFIER_CAPTURE));
+    if (uppercaseCandidates.length === 1) {
+        return uppercaseCandidates[0];
+    }
+    const uuidCandidates = uniqueMatches(collectRegexMatches(documentText, UUID_IDENTIFIER_CAPTURE));
+    if (uuidCandidates.length === 1) {
+        return uuidCandidates[0];
+    }
+    return null;
+}
+async function resolveExactDocumentValueForChat(runtime, message) {
+    const messageText = typeof extractCompatTextContent(message.content) === "string"
+        ? extractCompatTextContent(message.content).trim()
+        : "";
+    if (!messageText || !EXACT_GROUNDED_VALUE_REQUEST.test(messageText)) {
+        return null;
+    }
+    const documentsService = runtime.getService("documents");
+    if (!documentsService ||
+        typeof documentsService.searchDocuments !== "function") {
+        return null;
+    }
+    try {
+        const matches = await documentsService.searchDocuments(message);
+        if (!Array.isArray(matches) || matches.length === 0) {
+            return null;
+        }
+        const uploadedMatches = matches.filter((match) => {
+            const metadata = match.metadata && typeof match.metadata === "object"
+                ? match.metadata
+                : null;
+            return metadata?.source === "upload";
+        });
+        const preferredMatches = uploadedMatches.length > 0 ? uploadedMatches : matches;
+        const exactMatchCandidates = uniqueMatches(preferredMatches
+            .map((match) => typeof match.content?.text === "string"
+            ? extractExactGroundedValueFromText(messageText, match.content.text.trim())
+            : null)
+            .filter((value) => typeof value === "string"));
+        if (exactMatchCandidates.length === 1) {
+            return exactMatchCandidates[0];
+        }
+        const documentsText = preferredMatches
+            .map((match) => typeof match.content?.text === "string"
+            ? match.content.text.trim()
+            : "")
+            .filter((text) => text.length > 0)
+            .join("\n\n");
+        return extractExactGroundedValueFromText(messageText, documentsText);
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Chat failure / no-response helpers
+// ---------------------------------------------------------------------------
+// Reserved for path #4 — actual generation throw caught by getChatFailureReply.
+// Do NOT use as the generic empty-response fallback; that mislabels every
+// IGNORE / empty-action / empty-normalized-text path as a provider failure.
+const PROVIDER_ISSUE_CHAT_REPLY = "Sorry, I'm having a provider issue";
+const INSUFFICIENT_CREDITS_CHAT_REPLY = "Eliza Cloud credits are depleted. Top up the cloud balance and try again.";
+// Used by paths #1-#3: planner picked IGNORE/NONE/empty REPLY, action ran but
+// emitted no text callback, or normalized text became empty. None of these are
+// provider failures, so the message must not blame the provider.
+const NO_RESPONSE_FALLBACK_REPLY = "I don't have a reply for that — try rephrasing?";
+// Routed-model errors raised by the model router when no provider plugin is
+// loaded for a requested model class (e.g. TEXT_SMALL). Identifies the OOB
+// "no provider configured" case so chat routes can return a structured 503
+// instead of a generic 500 — UI clients gate on `error.type === "no_provider"`
+// to render a "Connect a provider" CTA instead of an opaque error toast.
+const NO_PROVIDER_ERROR_FRAGMENTS = [
+    "No provider registered for",
+    "No model registered for",
+];
+function isNoProviderError(err) {
+    const msg = err instanceof Error ? err.message : typeof err === "string" ? err : "";
+    return NO_PROVIDER_ERROR_FRAGMENTS.some((frag) => msg.includes(frag));
+}
+const NO_PROVIDER_CHAT_MESSAGE = "Connect an LLM provider to start chatting. Open Settings → Providers, " +
+    "or choose Eliza Cloud during first-run setup.";
+const DEFAULT_CHAT_GENERATION_TIMEOUT_MS = 180_000;
+const NON_EXECUTABLE_FALLBACK_ACTIONS = new Set(["REPLY", "NONE", "IGNORE"]);
+function isExecutableFallbackAction(action) {
+    return !NON_EXECUTABLE_FALLBACK_ACTIONS.has(action.name);
+}
+function classifySyntheticChatFailureText(text) {
+    const normalized = text
+        .trim()
+        .toLowerCase()
+        .replace(/[’]/g, "'")
+        .replace(/\s+/g, " ");
+    if (!normalized)
+        return null;
+    if (normalized === PROVIDER_ISSUE_CHAT_REPLY.toLowerCase()) {
+        return "provider_issue";
+    }
+    if (/\bprovider issue\b/.test(normalized)) {
+        return "provider_issue";
+    }
+    if (normalized === NO_RESPONSE_FALLBACK_REPLY.toLowerCase()) {
+        return "no_response";
+    }
+    if (normalized === INSUFFICIENT_CREDITS_CHAT_REPLY.toLowerCase()) {
+        return "insufficient_credits";
+    }
+    if (normalized === NO_PROVIDER_CHAT_MESSAGE.toLowerCase()) {
+        return "no_provider";
+    }
+    if (normalized === "something went wrong on my end. please try again.") {
+        return "transient_failure";
+    }
+    return null;
+}
+export function markSyntheticChatFailureContent(content) {
+    const text = extractCompatTextContent(content);
+    const failureKind = typeof content.failureKind === "string"
+        ? content.failureKind
+        : classifySyntheticChatFailureText(text);
+    if (!failureKind)
+        return content;
+    const metadata = asRecord(content.metadata) ?? {};
+    return {
+        ...content,
+        metadata: {
+            ...metadata,
+            elizaSyntheticFailure: true,
+            chatFailureKind: failureKind,
+        },
+    };
+}
+function normalizeActionName(value) {
+    return typeof value === "string" ? value.trim().toUpperCase() : "";
+}
+function ensureMessageMemoryContent(content) {
+    return typeof content.text === "string"
+        ? { ...content, text: content.text }
+        : { ...content, text: "" };
+}
+function buildRuntimeActionNameLookup(runtime) {
+    const lookup = new Map();
+    const runtimeActions = Array.isArray(runtime.actions)
+        ? runtime.actions
+        : [];
+    for (const action of runtimeActions) {
+        const canonicalName = normalizeActionName(action.name);
+        if (!canonicalName) {
+            continue;
+        }
+        lookup.set(canonicalName, canonicalName);
+        if (!Array.isArray(action.similes)) {
+            continue;
+        }
+        for (const alias of action.similes) {
+            const normalizedAlias = normalizeActionName(alias);
+            if (normalizedAlias) {
+                lookup.set(normalizedAlias, canonicalName);
+            }
+        }
+    }
+    return lookup;
+}
+function listExecutedRuntimeActions(runtime, messageId) {
+    if (!messageId) {
+        return new Set();
+    }
+    const getActionResults = runtime.getActionResults;
+    if (typeof getActionResults !== "function") {
+        return new Set();
+    }
+    try {
+        return new Set(getActionResults(messageId)
+            .map((result) => {
+            if (typeof result === "string") {
+                return normalizeActionName(result);
+            }
+            if (!result || typeof result !== "object") {
+                return "";
+            }
+            const record = result;
+            if (typeof record.actionName === "string") {
+                return normalizeActionName(record.actionName);
+            }
+            const data = record.data && typeof record.data === "object"
+                ? record.data
+                : null;
+            return normalizeActionName(data?.actionName);
+        })
+            .filter((name) => name.length > 0));
+    }
+    catch {
+        return new Set();
+    }
+}
+function pickInsufficientCreditsChatReply() {
+    return INSUFFICIENT_CREDITS_CHAT_REPLY;
+}
+function findRecentInsufficientCreditsLog(logBuffer, lookbackMs = 60_000) {
+    const now = Date.now();
+    for (let i = logBuffer.length - 1; i >= 0; i--) {
+        const entry = logBuffer[i];
+        if (now - entry.timestamp > lookbackMs)
+            break;
+        if (isInsufficientCreditsMessage(entry.message)) {
+            return entry;
+        }
+    }
+    return null;
+}
+export function resolveNoResponseFallback(logBuffer, _runtime, _lang = "en") {
+    if (findRecentInsufficientCreditsLog(logBuffer)) {
+        return pickInsufficientCreditsChatReply();
+    }
+    return NO_RESPONSE_FALLBACK_REPLY;
+}
+function getProviderIssueChatReply() {
+    return PROVIDER_ISSUE_CHAT_REPLY;
+}
+function resolveChatGenerationTimeoutMs(explicit) {
+    if (typeof explicit === "number" &&
+        Number.isFinite(explicit) &&
+        explicit > 0) {
+        return Math.max(1, Math.floor(explicit));
+    }
+    const fromEnv = process.env.ELIZA_CHAT_GENERATION_TIMEOUT_MS?.trim();
+    if (!fromEnv)
+        return DEFAULT_CHAT_GENERATION_TIMEOUT_MS;
+    const parsed = Number.parseInt(fromEnv, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return DEFAULT_CHAT_GENERATION_TIMEOUT_MS;
+    }
+    return Math.max(1_000, parsed);
+}
+function createChatGenerationTimeoutError(timeoutMs) {
+    return new Error(`Chat generation timed out after ${timeoutMs}ms`);
+}
+async function withTimeout(promise, timeoutMs, createError, onTimeout) {
+    let timeoutHandle;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_resolve, reject) => {
+                timeoutHandle = setTimeout(() => {
+                    onTimeout?.();
+                    reject(createError());
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeoutHandle) {
+            clearTimeout(timeoutHandle);
+        }
+    }
+}
+export function getChatFailureReply(err, logBuffer) {
+    if (isInsufficientCreditsError(err) ||
+        findRecentInsufficientCreditsLog(logBuffer)) {
+        return pickInsufficientCreditsChatReply();
+    }
+    if (isNoProviderError(err)) {
+        return NO_PROVIDER_CHAT_MESSAGE;
+    }
+    return getProviderIssueChatReply();
+}
+export function classifyChatFailure(err, logBuffer) {
+    if (isInsufficientCreditsError(err) ||
+        findRecentInsufficientCreditsLog(logBuffer)) {
+        return "insufficient_credits";
+    }
+    if (isNoProviderError(err)) {
+        return "no_provider";
+    }
+    if (isLocalInferenceError(err)) {
+        return "local_inference";
+    }
+    return "provider_issue";
+}
+function normalizeIntentText(text) {
+    return text
+        .toLowerCase()
+        .replace(/[`"'“”‘’]/g, "")
+        .replace(/[_-]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function hasLocalInferenceMetadata(message) {
+    const contentMetadata = asRecord(message.content.metadata) ?? {};
+    const messageMetadata = asRecord(message.metadata) ?? {};
+    const metadata = { ...contentMetadata, ...messageMetadata };
+    const localValue = metadata.localInference ??
+        metadata.localInferenceContext ??
+        metadata.localModel ??
+        metadata.modelHub;
+    if (localValue === true)
+        return true;
+    if (typeof localValue === "string") {
+        return /^(1|true|yes|local|local-inference|model-hub)$/i.test(localValue.trim());
+    }
+    const context = typeof metadata.context === "string"
+        ? metadata.context
+        : typeof metadata.scope === "string"
+            ? metadata.scope
+            : "";
+    return /\blocal[-_\s]?inference\b|\bmodel[-_\s]?hub\b/i.test(context);
+}
+function hasLocalInferenceTopic(text) {
+    return (/\b(local|locally|on device|on-device|device model|local model|local inference|model hub|gguf|llama|inference|provider|runtime)\b/i.test(text) || /\bmodel\s+(?:download|install|load|setup)\b/i.test(text));
+}
+function isImperativeCloudOrLocalRouting(text) {
+    return /^(?:please\s+)?(?:use|switch|prefer|route|go|move)\s+(?:me\s+)?(?:to\s+)?(?:the\s+)?(?:cloud|local|on device|on-device)\b/i.test(text);
+}
+export function detectLocalInferenceCommandIntent(text, options = {}) {
+    const normalized = normalizeIntentText(text);
+    if (!normalized)
+        return null;
+    const explicitContext = options.localInferenceContext === true ||
+        hasLocalInferenceTopic(normalized) ||
+        isImperativeCloudOrLocalRouting(normalized);
+    if (!explicitContext)
+        return null;
+    if (/\b(?:use|switch|prefer|route|go|move)\s+(?:to\s+)?(?:the\s+)?cloud\b/.test(normalized) ||
+        /\bcloud\s+(?:mode|provider|inference|model|routing)\b/.test(normalized)) {
+        return "use_cloud";
+    }
+    if (/\b(?:status|progress|state|ready|loaded|loading|how far|what model)\b/.test(normalized) &&
+        (options.localInferenceContext === true ||
+            /\b(?:download|model|local|inference|gguf|eliza-1|provider|runtime)\b/.test(normalized))) {
+        return "status";
+    }
+    if (/\b(?:use|switch|prefer|route|go|move)\s+(?:to\s+)?(?:the\s+)?(?:local|on device|on device model)\b/.test(normalized) ||
+        /\b(?:local|on device)\s+(?:mode|provider|inference|model|routing)\b/.test(normalized)) {
+        return "use_local";
+    }
+    if (/\b(?:smaller|smallest|tiny|lighter|lightweight|less memory|low ram|low memory)\b/.test(normalized) &&
+        /\b(?:switch|use|load|pick|select|change|model)\b/.test(normalized)) {
+        return "switch_smaller";
+    }
+    if (/\b(?:cancel|stop|abort|halt)\b/.test(normalized) &&
+        /\b(?:download|model|local|inference)\b/.test(normalized)) {
+        return "cancel";
+    }
+    if (/\b(?:re download|redownload|download again|fresh download)\b/.test(normalized)) {
+        return "redownload";
+    }
+    if (/\b(?:retry|try again|resume|continue|restart)\b/.test(normalized) &&
+        /\b(?:download|model|local|inference)\b/.test(normalized)) {
+        return normalized.includes("resume") || normalized.includes("continue")
+            ? "resume"
+            : "retry";
+    }
+    if (/\b(?:download|install|get|fetch|pull)\b/.test(normalized) &&
+        (options.localInferenceContext === true ||
+            /\b(?:model|local|inference|gguf|eliza-1)\b/.test(normalized))) {
+        return "download";
+    }
+    return null;
+}
+export function isLocalInferenceError(err) {
+    const message = err instanceof Error ? err.message : typeof err === "string" ? err : "";
+    return /\b(?:local inference|local model|on-device|device bridge|llama|gguf|capacitor-llama|no local model|model download|enospc|no space left|disk full)\b/i.test(message);
+}
+export function normalizeChatResponseText(text, logBuffer, runtime) {
+    // Both fallback strings can hit this path; either should be re-routed to
+    // the insufficient-credits reply when a recent credits log explains why
+    // generation produced nothing.
+    const visibleText = extractAssistantReplyText(text) ?? text;
+    const trimmed = visibleText.trim();
+    if ((trimmed === PROVIDER_ISSUE_CHAT_REPLY ||
+        trimmed === NO_RESPONSE_FALLBACK_REPLY) &&
+        findRecentInsufficientCreditsLog(logBuffer)) {
+        return pickInsufficientCreditsChatReply();
+    }
+    if (!isClientVisibleNoResponse(visibleText))
+        return visibleText;
+    return resolveNoResponseFallback(logBuffer, runtime);
+}
+function listResponseActions(responseContent) {
+    if (!Array.isArray(responseContent?.actions)) {
+        return [];
+    }
+    return responseContent.actions
+        .map((action) => typeof action === "string" ? action.trim().toUpperCase() : "")
+        .filter((action) => action.length > 0);
+}
+function isIntentionalNoResponseResult(result, candidateText) {
+    if (!result)
+        return false;
+    const actions = listResponseActions(result.responseContent);
+    const hasSilentTerminalAction = actions.length === 1 && (actions[0] === "IGNORE" || actions[0] === "STOP");
+    const hasNoVisibleText = candidateText.trim().length === 0 ||
+        isClientVisibleNoResponse(candidateText);
+    return (hasNoVisibleText && (result.didRespond === false || hasSilentTerminalAction));
+}
+function buildUnexecutedActionPayloadReply(actionNames) {
+    const uniqueNames = [
+        ...new Set(actionNames.map((name) => normalizeActionName(name)).filter(Boolean)),
+    ];
+    const actionsLabel = uniqueNames.length > 0 ? uniqueNames.join(", ") : "unknown";
+    return [
+        "I could not complete that request because the model returned actions that were not executed.",
+        `Unexecuted actions: ${actionsLabel}.`,
+        "No side effects were applied.",
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// SSE helpers
+// ---------------------------------------------------------------------------
+export function initSse(res) {
+    res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache, no-transform",
+        Connection: "keep-alive",
+        "X-Accel-Buffering": "no",
+    });
+}
+export function writeSse(res, payload) {
+    if (res.writableEnded || res.destroyed)
+        return;
+    res.write(`data: ${JSON.stringify(payload)}\n\n`);
+}
+export function writeChatTokenSse(res, text, fullText) {
+    writeSse(res, { type: "token", text, fullText });
+}
+export function writeSseData(res, data, event) {
+    if (res.writableEnded || res.destroyed)
+        return;
+    const safeEvent = typeof event === "string" && /^[A-Za-z0-9_.-]+$/.test(event) ? event : null;
+    if (safeEvent)
+        res.write(`event: ${safeEvent}\n`);
+    for (const line of data.split(/\r\n|\r|\n/)) {
+        res.write(`data: ${line}\n`);
+    }
+    res.write("\n");
+}
+export function writeSseJson(res, payload, event) {
+    writeSseData(res, JSON.stringify(payload), event);
+}
+// ---------------------------------------------------------------------------
+// Persistence helpers
+// ---------------------------------------------------------------------------
+function isDuplicateMemoryError(err) {
+    if (!(err instanceof Error))
+        return false;
+    const msg = err.message.toLowerCase();
+    return (msg.includes("duplicate") ||
+        msg.includes("already exists") ||
+        msg.includes("unique constraint"));
+}
+export async function persistConversationMemory(runtime, memory) {
+    try {
+        await runtime.createMemory(memory, "messages");
+    }
+    catch (err) {
+        if (isDuplicateMemoryError(err))
+            return;
+        throw err;
+    }
+}
+async function hasRecentAssistantMemory(runtime, roomId, text, sinceMs) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return false;
+    try {
+        const recent = await runtime.getMemories({
+            roomId,
+            tableName: "messages",
+            limit: 12,
+        });
+        return recent.some((memory) => {
+            const contentText = memory.content?.text?.trim();
+            const createdAt = memory.createdAt ?? 0;
+            return (memory.entityId === runtime.agentId &&
+                contentText === trimmed &&
+                createdAt >= sinceMs - 2000);
+        });
+    }
+    catch {
+        return false;
+    }
+}
+export async function hasRecentVisibleAssistantMemorySince(runtime, roomId, sinceMs) {
+    return Boolean(await getRecentVisibleAssistantMemoryTextSince(runtime, roomId, sinceMs));
+}
+export async function getRecentVisibleAssistantMemoryTextSince(runtime, roomId, sinceMs) {
+    try {
+        const recent = await runtime.getMemories({
+            roomId,
+            tableName: "messages",
+            limit: 12,
+        });
+        const persistedAssistantTurn = recent
+            .filter((memory) => {
+            const contentText = memory.content?.text?.trim();
+            const createdAt = memory.createdAt ?? 0;
+            return (memory.entityId === runtime.agentId &&
+                Boolean(contentText) &&
+                createdAt >= sinceMs - 2000);
+        })
+            .sort((a, b) => (b.createdAt ?? 0) - (a.createdAt ?? 0))[0];
+        return (persistedAssistantTurn?.content?.text?.trim() ?? null);
+    }
+    catch {
+        return null;
+    }
+}
+export async function persistAssistantConversationMemory(runtime, roomId, content, channelType, dedupeSinceMs) {
+    const persistedContent = markSyntheticChatFailureContent(typeof content === "string"
+        ? {
+            text: content,
+            source: "client_chat",
+            channelType,
+        }
+        : {
+            ...content,
+            text: extractCompatTextContent(content),
+            source: typeof content.source === "string" ? content.source : "client_chat",
+            channelType: typeof content.channelType === "string"
+                ? content.channelType
+                : channelType,
+        });
+    const trimmed = persistedContent.text.trim();
+    if (!trimmed)
+        return;
+    if (typeof dedupeSinceMs === "number") {
+        const alreadyPersisted = await hasRecentAssistantMemory(runtime, roomId, trimmed, dedupeSinceMs);
+        if (alreadyPersisted)
+            return;
+    }
+    await persistConversationMemory(runtime, createMessageMemory({
+        id: crypto.randomUUID(),
+        entityId: runtime.agentId,
+        agentId: runtime.agentId,
+        roomId,
+        content: persistedContent,
+    }));
+}
+// ---------------------------------------------------------------------------
+// Chat request parsing
+// ---------------------------------------------------------------------------
+const VALID_CHANNEL_TYPES = new Set(Object.values(ChannelType));
+function parseRequestChannelType(value, fallback = ChannelType.DM) {
+    if (value === undefined || value === null) {
+        return fallback;
+    }
+    if (typeof value !== "string") {
+        return null;
+    }
+    const normalized = value.trim().toUpperCase();
+    if (!VALID_CHANNEL_TYPES.has(normalized)) {
+        return null;
+    }
+    return normalized;
+}
+function readUiLanguageHeader(req) {
+    if (!req) {
+        return undefined;
+    }
+    const header = req.headers["x-eliza-ui-language"];
+    if (Array.isArray(header)) {
+        return header.find((value) => value.trim())?.trim();
+    }
+    return typeof header === "string" && header.trim()
+        ? header.trim()
+        : undefined;
+}
+export async function readChatRequestPayload(req, res, helpers, 
+/** Body size limit. Image-capable endpoints pass CHAT_MAX_BODY_BYTES (20 MB);
+ *  legacy/cloud-proxy endpoints that don't process images pass MAX_BODY_BYTES (1 MB). */
+maxBytes = CHAT_MAX_BODY_BYTES) {
+    const body = await helpers.readJsonBody(req, res, { maxBytes });
+    if (!body)
+        return null;
+    const normalizedPrompt = normalizeIncomingChatPrompt(body.text, body.images);
+    if (!normalizedPrompt) {
+        helpers.error(res, "text is required");
+        return null;
+    }
+    const channelType = parseRequestChannelType(body.channelType, ChannelType.DM);
+    if (!channelType) {
+        helpers.error(res, "channelType is invalid", 400);
+        return null;
+    }
+    const imageValidationError = validateChatImages(body.images);
+    if (imageValidationError) {
+        helpers.error(res, imageValidationError, 400);
+        return null;
+    }
+    const images = Array.isArray(body.images)
+        ? body.images.map((img) => ({
+            ...img,
+            mimeType: img.mimeType.toLowerCase(),
+        }))
+        : undefined;
+    const rawPreferredLanguage = (typeof body.language === "string" && body.language.trim()
+        ? body.language
+        : undefined) ?? readUiLanguageHeader(req);
+    const preferredLanguage = rawPreferredLanguage
+        ? normalizeCharacterLanguage(rawPreferredLanguage)
+        : undefined;
+    const source = typeof body.source === "string" && body.source.trim().length > 0
+        ? body.source.trim()
+        : undefined;
+    const metadata = body.metadata &&
+        typeof body.metadata === "object" &&
+        !Array.isArray(body.metadata)
+        ? body.metadata
+        : undefined;
+    const clientMessageId = normalizeClientMessageId(body.clientMessageId);
+    return {
+        prompt: normalizedPrompt,
+        channelType,
+        images,
+        ...(preferredLanguage ? { preferredLanguage } : {}),
+        ...(source ? { source } : {}),
+        ...(metadata ? { metadata } : {}),
+        ...(clientMessageId ? { clientMessageId } : {}),
+    };
+}
+function readMessageTrajectoryStepId(message) {
+    const metadata = message.metadata;
+    if (!metadata || typeof metadata !== "object")
+        return null;
+    const stepId = metadata.trajectoryStepId;
+    return typeof stepId === "string" && stepId.trim().length > 0
+        ? stepId.trim()
+        : null;
+}
+function readMessageTrajectoryGrouping(message) {
+    const contentMetadata = asRecord(message.content.metadata) ?? {};
+    const evalMetadata = asRecord(contentMetadata.eval) ?? {};
+    const messageMetadata = asRecord(message.metadata) ?? {};
+    return resolveTrajectoryGrouping({
+        ...contentMetadata,
+        ...evalMetadata,
+        ...messageMetadata,
+    });
+}
+async function persistMessageTrajectoryGrouping(runtime, message) {
+    const stepId = readMessageTrajectoryStepId(message);
+    if (!stepId)
+        return;
+    const grouping = readMessageTrajectoryGrouping(message);
+    if (!grouping.scenarioId && !grouping.batchId)
+        return;
+    await startTrajectoryStepInDatabase({
+        runtime,
+        stepId,
+        source: typeof message.content.source === "string" &&
+            message.content.source.trim().length > 0
+            ? message.content.source
+            : undefined,
+        metadata: {
+            ...(grouping.scenarioId ? { scenarioId: grouping.scenarioId } : {}),
+            ...(grouping.batchId ? { batchId: grouping.batchId } : {}),
+        },
+    });
+}
+function buildChatUsage(runtime, message, finalText, capturedUsage) {
+    const model = capturedUsage?.model ?? detectRuntimeModel(runtime, undefined) ?? undefined;
+    if (capturedUsage) {
+        return {
+            promptTokens: capturedUsage.promptTokens,
+            completionTokens: capturedUsage.completionTokens,
+            totalTokens: capturedUsage.totalTokens,
+            ...(model ? { model } : {}),
+            ...(capturedUsage.provider ? { provider: capturedUsage.provider } : {}),
+            isEstimated: capturedUsage.isEstimated,
+            llmCalls: capturedUsage.llmCalls,
+        };
+    }
+    const promptText = extractCompatTextContent(message.content);
+    const promptTokens = estimateTokenCount(promptText);
+    const completionTokens = estimateTokenCount(finalText);
+    return {
+        promptTokens,
+        completionTokens,
+        totalTokens: promptTokens + completionTokens,
+        ...(model ? { model } : {}),
+        isEstimated: true,
+        llmCalls: 0,
+    };
+}
+// ---------------------------------------------------------------------------
+// generateChatResponse
+// ---------------------------------------------------------------------------
+export async function generateChatResponse(runtime, message, agentName, opts) {
+    const generationTimeoutMs = resolveChatGenerationTimeoutMs(opts?.timeoutDuration);
+    let generationTimedOut = false;
+    if (generationTimeoutMs <= 1) {
+        generationTimedOut = true;
+        throw createChatGenerationTimeoutError(generationTimeoutMs);
+    }
+    const generationAbortController = new AbortController();
+    const abortGeneration = (reason) => {
+        if (!generationAbortController.signal.aborted) {
+            generationAbortController.abort(reason);
+        }
+    };
+    const onExternalAbort = () => {
+        abortGeneration(opts?.abortSignal?.reason);
+    };
+    if (opts?.abortSignal?.aborted) {
+        onExternalAbort();
+    }
+    else {
+        opts?.abortSignal?.addEventListener("abort", onExternalAbort, {
+            once: true,
+        });
+    }
+    try {
+        const originalUserText = String(extractCompatTextContent(message.content));
+        let responseText = "";
+        let forcedWalletExecutionText = false;
+        let blockedUnexecutedActionPayload = false;
+        let activeStreamSource = "unset";
+        const actionCallbackHistory = [];
+        // Snapshot of `responseText` at the moment the first action callback runs.
+        // WHY: LLM streaming genuinely appends token deltas. Action handlers that
+        // call HandlerCallback multiple times (Discord "progressive message" pattern)
+        // send unrelated status strings — merging them with mergeStreamingText would
+        // concatenate ("🔍…" + "✨…" + "Now playing…"). We preserve the streamed
+        // prefix and replace only the callback suffix so the dashboard SSE client
+        // gets snapshot fullText updates (same UX as editing one chat bubble).
+        let preCallbackText = null;
+        const messageSource = typeof message.content.source === "string" &&
+            message.content.source.trim().length > 0
+            ? message.content.source
+            : "api";
+        const emitChunk = (chunk) => {
+            if (!chunk)
+                return;
+            responseText += chunk;
+            opts?.onChunk?.(chunk);
+        };
+        const emitSnapshot = (text) => {
+            if (!text)
+                return;
+            // Skip when the snapshot matches the current responseText exactly:
+            // re-emitting the same fullText forces clients to re-render an identical
+            // bubble (and on-the-wire bytes for nothing).
+            if (text === responseText)
+                return;
+            responseText = text;
+            opts?.onSnapshot?.(text);
+        };
+        const claimStreamSource = (source) => {
+            if (activeStreamSource === "unset") {
+                activeStreamSource = source;
+                return true;
+            }
+            return activeStreamSource === source;
+        };
+        const appendIncomingText = (incoming) => {
+            const update = resolveStreamingUpdate(responseText, incoming);
+            if (update.kind === "unchanged")
+                return;
+            if (update.kind === "append") {
+                emitChunk(update.emittedText);
+                return;
+            }
+            emitSnapshot(update.nextText);
+        };
+        const captureCallbackBaseline = () => {
+            if (preCallbackText === null) {
+                preCallbackText = responseText;
+            }
+        };
+        const recordActionCallbackText = (incoming) => {
+            const normalized = normalizeActionCallbackText(incoming);
+            if (!normalized)
+                return;
+            if (actionCallbackHistory.at(-1) === normalized)
+                return;
+            actionCallbackHistory.push(normalized);
+        };
+        /** Latest action callback wins: replaces prior callback text, keeps LLM prefix. */
+        const replaceCallbackText = (incoming) => {
+            recordActionCallbackText(incoming);
+            captureCallbackBaseline();
+            const baseline = preCallbackText ?? "";
+            const separator = baseline.length > 0 ? "\n\n" : "";
+            const nextText = `${baseline}${separator}${incoming}`;
+            // Heuristic: if the new callback text is a true append on top of the
+            // currently streamed responseText, emit a delta chunk (cheap on the wire,
+            // lets modern SSE clients append without re-rendering the whole bubble)
+            // AND a snapshot for legacy clients that only consume `fullText`.
+            // Otherwise (structural rewrite — Discord-style "🔍 searching" → "✨ done"
+            // or planner restart), snapshot only.
+            if (nextText === responseText)
+                return;
+            if (nextText.startsWith(responseText) && responseText.length > 0) {
+                const delta = nextText.slice(responseText.length);
+                emitChunk(delta);
+                // emitChunk already advanced responseText; re-emit snapshot for
+                // legacy clients that only handle fullText updates.
+                opts?.onSnapshot?.(nextText);
+                return;
+            }
+            emitSnapshot(nextText);
+        };
+        const applyCallbackTextUpdate = (content, incoming) => {
+            captureCallbackBaseline();
+            if (resolveCallbackMergeMode(content) === "append") {
+                recordActionCallbackText(incoming);
+                appendIncomingText(incoming);
+                return;
+            }
+            replaceCallbackText(incoming);
+        };
+        // Emit inbound events so trajectory/session hooks run for API chat.
+        try {
+            if (typeof runtime.emitEvent === "function") {
+                await runtime.emitEvent("MESSAGE_RECEIVED", {
+                    message,
+                    source: messageSource,
+                });
+            }
+        }
+        catch (err) {
+            runtime.logger.warn({
+                err,
+                src: "eliza-api",
+                messageId: message.id,
+                roomId: message.roomId,
+            }, "Failed to emit MESSAGE_RECEIVED event");
+        }
+        const trajectoryStepId = readMessageTrajectoryStepId(message);
+        const trajectoryContext = typeof trajectoryStepId === "string" && trajectoryStepId.trim().length > 0
+            ? { trajectoryStepId: trajectoryStepId.trim() }
+            : undefined;
+        const androidDirectResult = await runWithTrajectoryContext(trajectoryContext, () => maybeGenerateAndroidLocalDirectChatResponse({
+            runtime,
+            message,
+            agentName,
+            signal: generationAbortController.signal,
+            opts,
+        }));
+        if (androidDirectResult) {
+            try {
+                if (androidDirectResult.responseContent &&
+                    typeof runtime.emitEvent === "function") {
+                    const memoryLike = createMessageMemory({
+                        id: crypto.randomUUID(),
+                        roomId: message.roomId,
+                        entityId: runtime.agentId,
+                        content: ensureMessageMemoryContent(androidDirectResult.responseContent),
+                    });
+                    memoryLike.metadata = message.metadata;
+                    await runtime.emitEvent("MESSAGE_SENT", {
+                        message: memoryLike,
+                        source: messageSource,
+                    });
+                }
+            }
+            catch (err) {
+                runtime.logger.warn({
+                    err,
+                    src: "eliza-api",
+                    messageId: message.id,
+                    roomId: message.roomId,
+                }, "Failed to emit MESSAGE_SENT event");
+            }
+            return androidDirectResult;
+        }
+        let result;
+        let capturedUsage = null;
+        let actionCallbacksSeen = 0;
+        const seenActionTags = new Set();
+        const recordActionCallback = (actionTag, hasText) => {
+            actionCallbacksSeen += 1;
+            const normalizedActionTag = normalizeActionName(actionTag);
+            if (normalizedActionTag) {
+                seenActionTags.add(normalizedActionTag);
+            }
+            runtime.logger.info({
+                src: "eliza-api",
+                action: normalizedActionTag || actionTag,
+                hasText,
+            }, `[eliza-api] Action callback fired: ${normalizedActionTag || actionTag}`);
+        };
+        const extractCallbackActionTag = (content) => {
+            const record = content;
+            if (typeof record.action === "string" && record.action.length > 0) {
+                return record.action;
+            }
+            if (Array.isArray(record.actions)) {
+                const firstAction = record.actions.find((action) => typeof action === "string" && action.trim().length > 0);
+                if (firstAction)
+                    return firstAction;
+            }
+            return "VISIBLE_CALLBACK";
+        };
+        const generationCapture = await withModelUsageCapture(runtime, () => withTimeout(Promise.resolve(runWithTrajectoryContext(trajectoryContext, async () => {
+            // Binance skill direct dispatch
+            const directSkillText = await maybeHandleDirectBinanceSkillRequest(runtime, message, replaceCallbackText, emitSnapshot);
+            if (directSkillText) {
+                const finalText = isClientVisibleNoResponse(directSkillText)
+                    ? directSkillText || "(no response)"
+                    : directSkillText;
+                result = {
+                    didRespond: true,
+                    responseContent: { text: finalText },
+                    responseMessages: [],
+                };
+                responseText = finalText;
+                forcedWalletExecutionText =
+                    isClientVisibleNoResponse(directSkillText);
+                return;
+            }
+            // Direct dispatch for explicit task creation intent from UI
+            const contentMetadata = message.content.metadata;
+            if (contentMetadata?.intent === "create_task") {
+                const coordinator = runtime.getService("SWARM_COORDINATOR");
+                if (coordinator) {
+                    const createTaskAction = runtime.actions.find((a) => a.name.toUpperCase() === "START_CODING_TASK") ??
+                        runtime.actions.find((a) => a.name.toUpperCase() === "CREATE_TASK");
+                    if (createTaskAction) {
+                        runtime.logger.info({
+                            src: "eliza-api",
+                            agentType: contentMetadata.agentType,
+                            intent: "create_task",
+                        }, "[eliza-api] Direct dispatch START_CODING_TASK from UI intent");
+                        let actionResponseText = "";
+                        await createTaskAction.handler(runtime, message, undefined, {}, async (content) => {
+                            if (generationTimedOut || opts?.isAborted?.()) {
+                                throw createChatGenerationTimeoutError(generationTimeoutMs);
+                            }
+                            const chunk = extractCompatTextContent(content);
+                            if (chunk) {
+                                const voicedChunk = await rewriteDirectActionCallbackText({
+                                    runtime,
+                                    actionName: createTaskAction.name,
+                                    text: chunk,
+                                    content,
+                                });
+                                applyCallbackTextUpdate(content, voicedChunk);
+                                actionResponseText = responseText;
+                            }
+                            return [];
+                        });
+                        const finalText = actionResponseText || responseText || "Task created.";
+                        result = {
+                            didRespond: true,
+                            responseContent: { text: finalText },
+                            responseMessages: [],
+                        };
+                        responseText = finalText;
+                        return;
+                    }
+                }
+                // Fall through to normal LLM-based routing if coordinator not available
+            }
+            const localInferenceIntent = detectLocalInferenceCommandIntent(originalUserText, {
+                localInferenceContext: hasLocalInferenceMetadata(message),
+            });
+            if (localInferenceIntent) {
+                const { handleLocalInferenceChatCommand } = await getLocalInferenceChatApi();
+                const localResult = await handleLocalInferenceChatCommand(localInferenceIntent, originalUserText);
+                emitSnapshot(localResult.text);
+                result = {
+                    didRespond: true,
+                    responseContent: {
+                        text: localResult.text,
+                        source: "client_chat",
+                        actions: ["REPLY"],
+                        localInference: localResult.localInference,
+                        failureKind: localResult.localInference.status === "failed" ||
+                            localResult.localInference.status === "no_space"
+                            ? "local_inference"
+                            : undefined,
+                    },
+                    responseMessages: [],
+                };
+                responseText = localResult.text;
+                return;
+            }
+            const languageAugmentedMessage = maybeAugmentChatMessageWithLanguage(message, opts?.preferredLanguage);
+            const walletAugmentedMessage = maybeAugmentChatMessageWithWalletContext(runtime, languageAugmentedMessage);
+            const generationMessage = await maybeAugmentChatMessageWithDocuments(runtime, walletAugmentedMessage);
+            result = await runtime.messageService?.handleMessage(runtime, generationMessage, async (content) => {
+                if (generationTimedOut || opts?.isAborted?.()) {
+                    throw createChatGenerationTimeoutError(generationTimeoutMs);
+                }
+                const chunk = extractCompatTextContent(content);
+                recordActionCallback(extractCallbackActionTag(content), Boolean(chunk));
+                if (!chunk)
+                    return [];
+                if (!claimStreamSource("callback"))
+                    return [];
+                applyCallbackTextUpdate(content, chunk);
+                return [];
+            }, {
+                timeoutDuration: generationTimeoutMs,
+                abortSignal: generationAbortController.signal,
+                keepExistingResponses: true,
+                onStreamChunk: opts?.onChunk
+                    ? async (chunk) => {
+                        if (generationTimedOut || opts?.isAborted?.()) {
+                            throw createChatGenerationTimeoutError(generationTimeoutMs);
+                        }
+                        if (!chunk)
+                            return;
+                        if (!claimStreamSource("onStreamChunk"))
+                            return;
+                        appendIncomingText(chunk);
+                    }
+                    : undefined,
+            });
+            // Ensure MESSAGE_SENT hooks run for API chat flows.
+            try {
+                const responseMessages = Array.isArray(result?.responseMessages)
+                    ? result.responseMessages
+                    : [];
+                const fallbackResponseContent = result?.responseContent &&
+                    typeof result.responseContent === "object"
+                    ? result.responseContent
+                    : responseText
+                        ? { text: responseText }
+                        : null;
+                const messagesToEmit = responseMessages.length > 0
+                    ? responseMessages
+                    : fallbackResponseContent
+                        ? [
+                            {
+                                id: crypto.randomUUID(),
+                                content: fallbackResponseContent,
+                            },
+                        ]
+                        : [];
+                if (messagesToEmit.length > 0 &&
+                    typeof runtime.emitEvent === "function") {
+                    for (const responseMessage of messagesToEmit) {
+                        const memoryLike = createMessageMemory({
+                            id: responseMessage.id ??
+                                crypto.randomUUID(),
+                            roomId: message.roomId,
+                            entityId: runtime.agentId,
+                            content: markSyntheticChatFailureContent(ensureMessageMemoryContent(responseMessage.content ?? { text: "" })),
+                        });
+                        memoryLike.metadata = message.metadata;
+                        await runtime.emitEvent("MESSAGE_SENT", {
+                            message: memoryLike,
+                            source: messageSource,
+                        });
+                    }
+                }
+            }
+            catch (err) {
+                runtime.logger.warn({
+                    err,
+                    src: "eliza-api",
+                    messageId: message.id,
+                    roomId: message.roomId,
+                }, "Failed to emit MESSAGE_SENT event");
+            }
+            // Post-process fallback actions
+            if (result) {
+                const rc = result.responseContent;
+                const resultRecord = asRecord(result);
+                runtime.logger.info({
+                    src: "eliza-api",
+                    mode: resultRecord?.mode,
+                    actions: rc?.actions,
+                    hasText: Boolean(rc?.text),
+                }, "[eliza-api] Chat response metadata");
+                const rawActionsPayload = rc?.actions ?? resultRecord?.actions;
+                const modelText = String(extractCompatTextContent(result.responseContent));
+                const parsedFallbackActions = parseFallbackActionBlocks(rawActionsPayload, modelText);
+                const actionNameLookup = buildRuntimeActionNameLookup(runtime);
+                const executedRuntimeActions = listExecutedRuntimeActions(runtime, typeof message.id === "string" ? message.id : undefined);
+                const executedActionNames = new Set([...executedRuntimeActions, ...seenActionTags]
+                    .map((name) => actionNameLookup.get(name) ?? name)
+                    .filter((name) => name.length > 0));
+                // Only run fallback execution when the core did NOT dispatch actions itself.
+                const coreHandledActions = resultRecord?.mode === "actions";
+                const executableFallbackActions = parsedFallbackActions.filter((action) => {
+                    if (!isExecutableFallbackAction(action)) {
+                        return false;
+                    }
+                    const canonicalName = actionNameLookup.get(normalizeActionName(action.name)) ??
+                        normalizeActionName(action.name);
+                    return !executedActionNames.has(canonicalName);
+                });
+                if (!coreHandledActions && executableFallbackActions.length > 0) {
+                    const selfControlFallbackActions = executableFallbackActions.filter((action) => {
+                        const canonicalName = actionNameLookup.get(normalizeActionName(action.name)) ??
+                            normalizeActionName(action.name);
+                        return canonicalName === "BLOCK";
+                    });
+                    const callbacksBeforeFallback = actionCallbacksSeen;
+                    if (selfControlFallbackActions.length > 0) {
+                        await executeFallbackParsedActions(runtime, message, selfControlFallbackActions, appendIncomingText, recordActionCallback, {
+                            getCurrentText: () => responseText || modelText,
+                        });
+                    }
+                    const selfControlFallbackExecuted = actionCallbacksSeen > callbacksBeforeFallback;
+                    const remainingExecutableFallbackActions = executableFallbackActions.filter((action) => {
+                        const canonicalName = actionNameLookup.get(normalizeActionName(action.name)) ??
+                            normalizeActionName(action.name);
+                        if (canonicalName === "BLOCK") {
+                            return !selfControlFallbackExecuted;
+                        }
+                        return true;
+                    });
+                    if (remainingExecutableFallbackActions.length > 0) {
+                        runtime.logger.error({
+                            src: "eliza-api",
+                            parsedActions: remainingExecutableFallbackActions.map((a) => a.name),
+                        }, "[eliza-api] Unexecuted action payload detected; failing closed");
+                        const failureText = buildUnexecutedActionPayloadReply(remainingExecutableFallbackActions.map((action) => action.name));
+                        if (opts?.onSnapshot) {
+                            emitSnapshot(failureText);
+                        }
+                        else {
+                            responseText = failureText;
+                        }
+                        blockedUnexecutedActionPayload = true;
+                    }
+                    if (remainingExecutableFallbackActions.some((action) => normalizeActionName(action.name) === "CHECK_BALANCE")) {
+                        forcedWalletExecutionText = true;
+                    }
+                }
+            }
+        })), generationTimeoutMs, () => createChatGenerationTimeoutError(generationTimeoutMs), () => {
+            generationTimedOut = true;
+            abortGeneration(createChatGenerationTimeoutError(generationTimeoutMs));
+        }));
+        capturedUsage = generationCapture.usage;
+        const responseMessageText = getLatestVisibleResponseMessageText(result?.responseMessages);
+        const resultText = responseMessageText ||
+            extractCompatTextContent(result?.responseContent) ||
+            "";
+        // Fallback: if callbacks weren't used for text, stream + return final text.
+        if (!responseText && resultText) {
+            if (opts?.onSnapshot) {
+                emitSnapshot(resultText);
+            }
+            else {
+                emitChunk(resultText);
+            }
+        }
+        else if (actionCallbacksSeen === 0 &&
+            resultText &&
+            resultText !== responseText &&
+            resultText.startsWith(responseText)) {
+            emitChunk(resultText.slice(responseText.length));
+        }
+        else if (actionCallbacksSeen === 0 &&
+            resultText &&
+            resultText !== responseText &&
+            !forcedWalletExecutionText &&
+            !blockedUnexecutedActionPayload) {
+            if (opts?.onSnapshot) {
+                emitSnapshot(resultText);
+            }
+            else {
+                responseText = resultText;
+            }
+        }
+        if (actionCallbacksSeen === 0 &&
+            isWalletActionRequiredIntent(originalUserText)) {
+            const failureText = buildWalletActionNotExecutedReply(runtime, originalUserText.trim());
+            if (opts?.onSnapshot) {
+                emitSnapshot(failureText);
+            }
+            else {
+                responseText = failureText;
+            }
+        }
+        const noResponseFallback = opts?.resolveNoResponseText?.();
+        const exactDocumentValue = await resolveExactDocumentValueForChat(runtime, message);
+        const normalizedResponseText = trimWalletProgressPrefix(exactDocumentValue || responseText || resultText || "");
+        const intentionalNoResponse = isIntentionalNoResponseResult(result, normalizedResponseText);
+        const finalText = intentionalNoResponse
+            ? ""
+            : isClientVisibleNoResponse(normalizedResponseText)
+                ? (noResponseFallback ??
+                    (normalizedResponseText || responseText || "(no response)"))
+                : normalizedResponseText;
+        const responseMessages = Array.isArray(result?.responseMessages)
+            ? result.responseMessages.map((entry) => ({
+                ...(entry.id ? { id: entry.id } : {}),
+                ...(entry.content ? { content: entry.content } : {}),
+            }))
+            : [];
+        const responseContent = result?.responseContent && typeof result.responseContent === "object"
+            ? {
+                ...result.responseContent,
+                text: finalText,
+            }
+            : finalText
+                ? { text: finalText }
+                : null;
+        const responseRecord = responseContent;
+        const localInference = responseRecord?.localInference &&
+            typeof responseRecord.localInference === "object"
+            ? responseRecord.localInference
+            : undefined;
+        const responseMetadata = asRecord(responseRecord?.metadata);
+        const rawFailureKind = typeof responseRecord?.failureKind === "string"
+            ? responseRecord.failureKind
+            : typeof responseMetadata?.chatFailureKind === "string"
+                ? responseMetadata.chatFailureKind
+                : undefined;
+        const failureKind = rawFailureKind === "insufficient_credits" ||
+            rawFailureKind === "local_inference" ||
+            rawFailureKind === "no_provider" ||
+            rawFailureKind === "provider_issue"
+            ? rawFailureKind
+            : undefined;
+        const thought = typeof responseContent?.thought === "string" &&
+            responseContent.thought.trim()
+            ? responseContent.thought
+            : undefined;
+        return {
+            text: finalText,
+            agentName,
+            ...(thought ? { thought } : {}),
+            ...(intentionalNoResponse
+                ? { noResponseReason: "ignored" }
+                : {}),
+            ...(failureKind ? { failureKind } : {}),
+            ...(localInference ? { localInference } : {}),
+            ...(actionCallbacksSeen > 0 ? { usedActionCallbacks: true } : {}),
+            ...(actionCallbackHistory.length > 0
+                ? { actionCallbackHistory: [...actionCallbackHistory] }
+                : {}),
+            ...(responseContent ? { responseContent } : {}),
+            ...(responseMessages.length > 0 ? { responseMessages } : {}),
+            usage: buildChatUsage(runtime, message, finalText, capturedUsage),
+        };
+    }
+    finally {
+        opts?.abortSignal?.removeEventListener("abort", onExternalAbort);
+        try {
+            await persistMessageTrajectoryGrouping(runtime, message);
+        }
+        catch (err) {
+            runtime.logger.warn({
+                err,
+                src: "eliza-api",
+                messageId: message.id,
+                roomId: message.roomId,
+            }, "Failed to persist trajectory grouping metadata");
+        }
+    }
+}
+function createConversationTitleAbortSignal(options = {}) {
+    const controller = new AbortController();
+    const abortFromCaller = () => {
+        controller.abort(options.signal?.reason ?? new Error("Request aborted"));
+    };
+    if (options.signal?.aborted) {
+        abortFromCaller();
+    }
+    else {
+        options.signal?.addEventListener("abort", abortFromCaller, { once: true });
+    }
+    const timeoutMs = typeof options.timeoutMs === "number" &&
+        Number.isFinite(options.timeoutMs) &&
+        options.timeoutMs > 0
+        ? Math.floor(options.timeoutMs)
+        : DEFAULT_CONVERSATION_TITLE_TIMEOUT_MS;
+    const timer = setTimeout(() => {
+        controller.abort(new DOMException(`Conversation title generation timed out after ${timeoutMs}ms`, "TimeoutError"));
+    }, timeoutMs);
+    timer.unref?.();
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            clearTimeout(timer);
+            options.signal?.removeEventListener("abort", abortFromCaller);
+        },
+    };
+}
+function isAbortLikeError(err) {
+    if (!(err instanceof Error))
+        return false;
+    return (err.name === "AbortError" ||
+        err.name === "TimeoutError" ||
+        err.message.toLowerCase().includes("aborted"));
+}
+export async function generateConversationTitle(runtime, userMessage, agentName, options) {
+    const modelClass = ModelType.TEXT_SMALL;
+    const prompt = `Based on the user's first message in a new chat, generate a very short, concise title (max 4-5 words) for the conversation.
+The agent's name is "${agentName}". The title should reflect the topic or intent of the user.
+Ideally, the title should fit the persona/vibe of the agent if possible, but clarity is more important.
+Do not use quotes. Do not include "Title:" prefix.
+
+User message: "${userMessage}"
+
+Title:`;
+    const abort = createConversationTitleAbortSignal(options);
+    try {
+        const title = await runtime.useModel(modelClass, {
+            prompt,
+            maxTokens: 20,
+            temperature: 0.7,
+            signal: abort.signal,
+        });
+        if (!title)
+            return null;
+        let cleanTitle = title.trim();
+        if ((cleanTitle.startsWith('"') && cleanTitle.endsWith('"')) ||
+            (cleanTitle.startsWith("'") && cleanTitle.endsWith("'"))) {
+            cleanTitle = cleanTitle.slice(1, -1);
+        }
+        if (!cleanTitle || cleanTitle.length > 50)
+            return null;
+        return cleanTitle;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (isAbortLikeError(err)) {
+            logger.info(`[eliza] Conversation title generation cancelled: ${message}`);
+        }
+        else {
+            logger.warn(`[eliza] Failed to generate conversation title: ${message}`);
+        }
+        return null;
+    }
+    finally {
+        abort.cleanup();
+    }
+}
+export function resolveChatAdminEntityId(state) {
+    return resolveClientChatAdminEntityId(state);
+}
+async function ensureCompatChatConnection(state, runtime, agentName, channelIdPrefix, roomKey) {
+    const userId = ensureAdminEntityIdForChat(state);
+    const roomId = stringToUuid(`${agentName}-${channelIdPrefix}-room-${roomKey}`);
+    const worldId = stringToUuid(`${agentName}-web-chat-world`);
+    const messageServerId = stringToUuid(`${agentName}-web-server`);
+    await runtime.ensureConnection({
+        entityId: userId,
+        roomId,
+        worldId,
+        userName: resolveAppUserName(state.config),
+        source: "client_chat",
+        channelId: `${channelIdPrefix}-${roomKey}`,
+        type: ChannelType.DM,
+        messageServerId,
+        metadata: { ownership: { ownerId: userId } },
+    });
+    // Ensure world ownership
+    const world = await runtime.getWorld(worldId);
+    if (world) {
+        let needsUpdate = false;
+        if (!world.metadata) {
+            world.metadata = {};
+            needsUpdate = true;
+        }
+        if (!world.metadata.ownership ||
+            typeof world.metadata.ownership !== "object" ||
+            world.metadata.ownership.ownerId !== userId) {
+            world.metadata.ownership = { ownerId: userId };
+            needsUpdate = true;
+        }
+        const metadataWithRoles = world.metadata;
+        const roles = metadataWithRoles.roles ?? {};
+        if (roles[userId] !== "OWNER") {
+            roles[userId] = "OWNER";
+            metadataWithRoles.roles = roles;
+            needsUpdate = true;
+        }
+        if (needsUpdate) {
+            await runtime.updateWorld(world);
+        }
+    }
+    return { userId, roomId, worldId };
+}
+function ensureAdminEntityIdForChat(state) {
+    return resolveChatAdminEntityId(state);
+}
+function syncRuntimeCharacterToChatStateConfig(state) {
+    if (!state.runtime || !state.config) {
+        return;
+    }
+    syncCharacterIntoConfig(state.config, state.runtime.character);
+}
+// ---------------------------------------------------------------------------
+// Main route handler
+// ---------------------------------------------------------------------------
+export async function handleChatRoutes(ctx) {
+    const { req, res, method, pathname, readJsonBody, json, state } = ctx;
+    // ── GET /v1/models (OpenAI compatible) ─────────────────────────────────
+    if (method === "GET" && pathname === "/v1/models") {
+        const created = Math.floor(Date.now() / 1000);
+        const ids = new Set();
+        ids.add("eliza");
+        if (state.agentName.trim())
+            ids.add(state.agentName.trim());
+        if (state.runtime?.character.name?.trim())
+            ids.add(state.runtime.character.name.trim());
+        json(res, {
+            object: "list",
+            data: Array.from(ids).map((id) => ({
+                id,
+                object: "model",
+                created,
+                owned_by: "eliza",
+            })),
+        });
+        return true;
+    }
+    // ── GET /v1/models/:id (OpenAI compatible) ─────────────────────────────
+    if (method === "GET" && /^\/v1\/models\/[^/]+$/.test(pathname)) {
+        const created = Math.floor(Date.now() / 1000);
+        const raw = pathname.split("/")[3] ?? "";
+        const decoded = decodePathComponent(raw, res, "model id");
+        if (!decoded)
+            return true;
+        const id = decoded.trim();
+        if (!id) {
+            json(res, {
+                error: {
+                    message: "Model id is required",
+                    type: "invalid_request_error",
+                },
+            }, 400);
+            return true;
+        }
+        json(res, { id, object: "model", created, owned_by: "eliza" });
+        return true;
+    }
+    // ── POST /v1/chat/completions (OpenAI compatible) ──────────────────────
+    if (method === "POST" && pathname === "/v1/chat/completions") {
+        const body = await readJsonBody(req, res);
+        if (!body)
+            return true;
+        if (hasBlockedObjectKeyDeep(body)) {
+            json(res, {
+                error: {
+                    message: "Request body contains a blocked object key",
+                    type: "invalid_request_error",
+                },
+            }, 400);
+            return true;
+        }
+        const safeBody = cloneWithoutBlockedObjectKeys(body);
+        const extracted = extractOpenAiSystemAndLastUser(safeBody.messages);
+        if (!extracted) {
+            json(res, {
+                error: {
+                    message: "messages must be an array containing at least one user message",
+                    type: "invalid_request_error",
+                },
+            }, 400);
+            return true;
+        }
+        const roomKey = resolveCompatRoomKey(safeBody).slice(0, 120);
+        const wantsStream = safeBody.stream === true ||
+            (req.headers.accept ?? "").includes("text/event-stream");
+        const requestedModel = typeof safeBody.model === "string" && safeBody.model.trim()
+            ? safeBody.model.trim()
+            : null;
+        const prompt = extracted.system
+            ? `${extracted.system}\n\n${extracted.user}`.trim()
+            : extracted.user;
+        const created = Math.floor(Date.now() / 1000);
+        const id = `chatcmpl-${crypto.randomUUID()}`;
+        const model = requestedModel ?? state.agentName;
+        if (wantsStream) {
+            initSse(res);
+            let aborted = false;
+            req.on("close", () => {
+                aborted = true;
+            });
+            const sendChunk = (delta, finishReason) => {
+                writeSseData(res, JSON.stringify({
+                    id,
+                    object: "chat.completion.chunk",
+                    created,
+                    model,
+                    choices: [
+                        {
+                            index: 0,
+                            delta,
+                            finish_reason: finishReason,
+                        },
+                    ],
+                }));
+            };
+            try {
+                if (!state.runtime) {
+                    writeSseData(res, JSON.stringify({
+                        error: {
+                            message: "Agent is not running",
+                            type: "service_unavailable",
+                        },
+                    }));
+                    writeSseData(res, "[DONE]");
+                    return true;
+                }
+                sendChunk({ role: "assistant" }, null);
+                let fullText = "";
+                {
+                    const runtime = state.runtime;
+                    if (!runtime)
+                        throw new Error("Agent is not running");
+                    const agentName = runtime.character.name ?? "Eliza";
+                    const { userId, roomId } = await ensureCompatChatConnection(state, runtime, agentName, "openai-compat", roomKey);
+                    const message = createMessageMemory({
+                        id: crypto.randomUUID(),
+                        entityId: userId,
+                        agentId: runtime.agentId,
+                        roomId,
+                        content: {
+                            text: prompt,
+                            source: "compat_openai",
+                            channelType: ChannelType.API,
+                        },
+                    });
+                    const result = await generateChatResponse(runtime, message, state.agentName, {
+                        isAborted: () => aborted,
+                        onChunk: (chunk) => {
+                            fullText += chunk;
+                            if (chunk)
+                                sendChunk({ content: chunk }, null);
+                        },
+                        resolveNoResponseText: () => resolveNoResponseFallback(state.logBuffer, runtime),
+                    });
+                    if (result.localInference && !fullText) {
+                        fullText = result.text;
+                        sendChunk({ content: result.text }, null);
+                    }
+                    syncRuntimeCharacterToChatStateConfig(state);
+                }
+                const resolved = normalizeChatResponseText(fullText, state.logBuffer, state.runtime);
+                if ((fullText.trim().length === 0 || isNoResponsePlaceholder(fullText)) &&
+                    resolved.trim()) {
+                    sendChunk({ content: resolved }, null);
+                }
+                sendChunk({}, "stop");
+                writeSseData(res, "[DONE]");
+            }
+            catch (err) {
+                if (!aborted) {
+                    if (isLocalInferenceError(err)) {
+                        const { getLocalInferenceChatStatus } = await getLocalInferenceChatApi();
+                        const localFailure = await getLocalInferenceChatStatus("status", err);
+                        writeSseData(res, JSON.stringify({
+                            error: {
+                                message: localFailure.text,
+                                type: "local_inference",
+                                localInference: localFailure.localInference,
+                            },
+                        }));
+                    }
+                    else if (isNoProviderError(err)) {
+                        writeSseData(res, JSON.stringify({
+                            error: {
+                                message: NO_PROVIDER_CHAT_MESSAGE,
+                                type: "no_provider",
+                                code: "NO_PROVIDER_REGISTERED",
+                            },
+                        }));
+                    }
+                    else {
+                        writeSseData(res, JSON.stringify({
+                            error: {
+                                message: getErrorMessage(err),
+                                type: "server_error",
+                            },
+                        }));
+                    }
+                    writeSseData(res, "[DONE]");
+                }
+            }
+            finally {
+                res.end();
+            }
+            return true;
+        }
+        // Non-streaming
+        try {
+            let responseText;
+            let localInference;
+            let failureKind;
+            {
+                if (!state.runtime) {
+                    json(res, {
+                        error: {
+                            message: "Agent is not running",
+                            type: "service_unavailable",
+                        },
+                    }, 503);
+                    return true;
+                }
+                const runtime = state.runtime;
+                const agentName = runtime.character.name ?? "Eliza";
+                const { userId, roomId } = await ensureCompatChatConnection(state, runtime, agentName, "openai-compat", roomKey);
+                const message = createMessageMemory({
+                    id: crypto.randomUUID(),
+                    entityId: userId,
+                    roomId,
+                    content: {
+                        text: prompt,
+                        source: "compat_openai",
+                        channelType: ChannelType.API,
+                    },
+                });
+                const result = await generateChatResponse(runtime, message, state.agentName, {
+                    resolveNoResponseText: () => resolveNoResponseFallback(state.logBuffer, runtime),
+                });
+                syncRuntimeCharacterToChatStateConfig(state);
+                responseText = result.text;
+                localInference = result.localInference;
+                failureKind = result.failureKind;
+            }
+            if (failureKind === "no_provider") {
+                json(res, {
+                    error: {
+                        message: NO_PROVIDER_CHAT_MESSAGE,
+                        type: "no_provider",
+                        code: "NO_PROVIDER_REGISTERED",
+                    },
+                }, 503);
+                return true;
+            }
+            const resolvedText = normalizeChatResponseText(responseText, state.logBuffer, state.runtime);
+            json(res, {
+                id,
+                object: "chat.completion",
+                created,
+                model,
+                choices: [
+                    {
+                        index: 0,
+                        message: { role: "assistant", content: resolvedText },
+                        finish_reason: "stop",
+                    },
+                ],
+                ...(failureKind ? { failureKind } : {}),
+                ...(localInference ? { localInference } : {}),
+            });
+        }
+        catch (err) {
+            if (isLocalInferenceError(err)) {
+                const { getLocalInferenceChatStatus } = await getLocalInferenceChatApi();
+                const localFailure = await getLocalInferenceChatStatus("status", err);
+                json(res, {
+                    error: {
+                        message: localFailure.text,
+                        type: "local_inference",
+                        localInference: localFailure.localInference,
+                    },
+                }, 503);
+            }
+            else if (isNoProviderError(err)) {
+                json(res, {
+                    error: {
+                        message: NO_PROVIDER_CHAT_MESSAGE,
+                        type: "no_provider",
+                        code: "NO_PROVIDER_REGISTERED",
+                    },
+                }, 503);
+            }
+            else {
+                json(res, { error: { message: getErrorMessage(err), type: "server_error" } }, 500);
+            }
+        }
+        return true;
+    }
+    // ── POST /v1/messages (Anthropic compatible) ───────────────────────────
+    if (method === "POST" && pathname === "/v1/messages") {
+        const body = await readJsonBody(req, res);
+        if (!body)
+            return true;
+        if (hasBlockedObjectKeyDeep(body)) {
+            json(res, {
+                error: {
+                    type: "invalid_request_error",
+                    message: "Request body contains a blocked object key",
+                },
+            }, 400);
+            return true;
+        }
+        const safeBody = cloneWithoutBlockedObjectKeys(body);
+        const extracted = extractAnthropicSystemAndLastUser({
+            system: safeBody.system,
+            messages: safeBody.messages,
+        });
+        if (!extracted) {
+            json(res, {
+                error: {
+                    type: "invalid_request_error",
+                    message: "messages must be an array containing at least one user message",
+                },
+            }, 400);
+            return true;
+        }
+        const roomKey = resolveCompatRoomKey(safeBody).slice(0, 120);
+        const wantsStream = safeBody.stream === true ||
+            (req.headers.accept ?? "").includes("text/event-stream");
+        const requestedModel = typeof safeBody.model === "string" && safeBody.model.trim()
+            ? safeBody.model.trim()
+            : null;
+        const prompt = extracted.system
+            ? `${extracted.system}\n\n${extracted.user}`.trim()
+            : extracted.user;
+        const id = `msg_${crypto.randomUUID().replace(/-/g, "")}`;
+        const model = requestedModel ?? state.agentName;
+        if (wantsStream) {
+            initSse(res);
+            let aborted = false;
+            req.on("close", () => {
+                aborted = true;
+            });
+            try {
+                if (!state.runtime) {
+                    writeSseJson(res, {
+                        type: "error",
+                        error: {
+                            type: "service_unavailable",
+                            message: "Agent is not running",
+                        },
+                    }, "error");
+                    return true;
+                }
+                // Anthropic's wire format reports input_tokens on message_start (the
+                // prompt is fully known here) and accumulates output_tokens on the
+                // closing message_delta. We don't have a real model-side prompt count
+                // before generation, so input_tokens is the same heuristic estimate the
+                // rest of this file uses (estimateTokenCount); output_tokens is filled
+                // from the real generation result below.
+                const inputTokens = estimateTokenCount(prompt);
+                writeSseJson(res, {
+                    type: "message_start",
+                    message: {
+                        id,
+                        type: "message",
+                        role: "assistant",
+                        model,
+                        content: [],
+                        stop_reason: null,
+                        stop_sequence: null,
+                        usage: { input_tokens: inputTokens, output_tokens: 0 },
+                    },
+                }, "message_start");
+                writeSseJson(res, {
+                    type: "content_block_start",
+                    index: 0,
+                    content_block: { type: "text", text: "" },
+                }, "content_block_start");
+                let fullText = "";
+                let outputTokens = 0;
+                const onDelta = (chunk) => {
+                    if (!chunk)
+                        return;
+                    fullText += chunk;
+                    writeSseJson(res, {
+                        type: "content_block_delta",
+                        index: 0,
+                        delta: { type: "text_delta", text: chunk },
+                    }, "content_block_delta");
+                };
+                {
+                    const runtime = state.runtime;
+                    if (!runtime)
+                        throw new Error("Agent is not running");
+                    const agentName = runtime.character.name ?? "Eliza";
+                    const { userId, roomId } = await ensureCompatChatConnection(state, runtime, agentName, "anthropic-compat", roomKey);
+                    const message = createMessageMemory({
+                        id: crypto.randomUUID(),
+                        entityId: userId,
+                        roomId,
+                        content: {
+                            text: prompt,
+                            source: "compat_anthropic",
+                            channelType: ChannelType.API,
+                        },
+                    });
+                    const generation = await generateChatResponse(runtime, message, state.agentName, {
+                        isAborted: () => aborted,
+                        onChunk: onDelta,
+                        resolveNoResponseText: () => resolveNoResponseFallback(state.logBuffer, runtime),
+                    });
+                    outputTokens = generation.usage?.completionTokens ?? outputTokens;
+                    syncRuntimeCharacterToChatStateConfig(state);
+                }
+                const resolved = normalizeChatResponseText(fullText, state.logBuffer, state.runtime);
+                if ((fullText.trim().length === 0 || isNoResponsePlaceholder(fullText)) &&
+                    resolved.trim()) {
+                    onDelta(resolved);
+                }
+                writeSseJson(res, { type: "content_block_stop", index: 0 }, "content_block_stop");
+                writeSseJson(res, {
+                    type: "message_delta",
+                    delta: { stop_reason: "end_turn", stop_sequence: null },
+                    usage: {
+                        output_tokens: outputTokens > 0 ? outputTokens : estimateTokenCount(fullText),
+                    },
+                }, "message_delta");
+                writeSseJson(res, { type: "message_stop" }, "message_stop");
+            }
+            catch (err) {
+                if (!aborted) {
+                    if (isNoProviderError(err)) {
+                        writeSseJson(res, {
+                            type: "error",
+                            error: {
+                                type: "no_provider",
+                                code: "NO_PROVIDER_REGISTERED",
+                                message: NO_PROVIDER_CHAT_MESSAGE,
+                            },
+                        }, "error");
+                    }
+                    else {
+                        writeSseJson(res, {
+                            type: "error",
+                            error: { type: "server_error", message: getErrorMessage(err) },
+                        }, "error");
+                    }
+                }
+            }
+            finally {
+                res.end();
+            }
+            return true;
+        }
+        // Non-streaming
+        try {
+            let responseText;
+            let inputTokens = estimateTokenCount(prompt);
+            let outputTokens = 0;
+            {
+                if (!state.runtime) {
+                    json(res, {
+                        error: {
+                            type: "service_unavailable",
+                            message: "Agent is not running",
+                        },
+                    }, 503);
+                    return true;
+                }
+                const runtime = state.runtime;
+                const agentName = runtime.character.name ?? "Eliza";
+                const { userId, roomId } = await ensureCompatChatConnection(state, runtime, agentName, "anthropic-compat", roomKey);
+                const message = createMessageMemory({
+                    id: crypto.randomUUID(),
+                    entityId: userId,
+                    roomId,
+                    content: {
+                        text: prompt,
+                        source: "compat_anthropic",
+                        channelType: ChannelType.API,
+                    },
+                });
+                const result = await generateChatResponse(runtime, message, state.agentName, {
+                    resolveNoResponseText: () => resolveNoResponseFallback(state.logBuffer, runtime),
+                });
+                syncRuntimeCharacterToChatStateConfig(state);
+                responseText = result.text;
+                if (result.usage) {
+                    inputTokens = result.usage.promptTokens;
+                    outputTokens = result.usage.completionTokens;
+                }
+            }
+            const resolvedText = normalizeChatResponseText(responseText, state.logBuffer, state.runtime);
+            json(res, {
+                id,
+                type: "message",
+                role: "assistant",
+                model,
+                content: [{ type: "text", text: resolvedText }],
+                stop_reason: "end_turn",
+                stop_sequence: null,
+                usage: {
+                    input_tokens: inputTokens,
+                    output_tokens: outputTokens > 0 ? outputTokens : estimateTokenCount(resolvedText),
+                },
+            });
+        }
+        catch (err) {
+            if (isNoProviderError(err)) {
+                json(res, {
+                    error: {
+                        type: "no_provider",
+                        code: "NO_PROVIDER_REGISTERED",
+                        message: NO_PROVIDER_CHAT_MESSAGE,
+                    },
+                }, 503);
+            }
+            else {
+                json(res, { error: { type: "server_error", message: getErrorMessage(err) } }, 500);
+            }
+        }
+        return true;
+    }
+    // ── POST /api/agents/:id/message ───────────────────────────────────────
+    // Local-mode mirror of the cloud agent-server's per-agent message
+    // endpoint (`packages/cloud-services/agent-server/src/routes.ts`). Shares the
+    // same `generateChatResponse` path as `/v1/chat/completions` so model
+    // routing (incl. local-inference TEXT_LARGE handlers) is identical.
+    if (method === "POST" && /^\/api\/agents\/[^/]+\/message$/.test(pathname)) {
+        const rawId = pathname.split("/")[3] ?? "";
+        const decoded = decodePathComponent(rawId, res, "agent id");
+        if (!decoded)
+            return true;
+        const agentIdParam = decoded.trim();
+        if (!agentIdParam) {
+            json(res, { error: "agent id is required" }, 400);
+            return true;
+        }
+        if (!state.runtime) {
+            json(res, { error: "Agent is not running" }, 503);
+            return true;
+        }
+        // Surface a 404 only when the caller targeted an agent that this
+        // process doesn't actually run — distinct from "route missing", which
+        // is what the original issue (#7680) was reporting.
+        if (state.runtime.agentId !== agentIdParam) {
+            json(res, { error: "Agent not found" }, 404);
+            return true;
+        }
+        const body = await readJsonBody(req, res);
+        if (!body)
+            return true;
+        if (hasBlockedObjectKeyDeep(body)) {
+            json(res, { error: "Request body contains a blocked object key" }, 400);
+            return true;
+        }
+        const safeBody = cloneWithoutBlockedObjectKeys(body);
+        const userId = typeof safeBody.userId === "string" && safeBody.userId.trim().length > 0
+            ? safeBody.userId.trim()
+            : null;
+        const text = typeof safeBody.text === "string" && safeBody.text.trim().length > 0
+            ? safeBody.text
+            : null;
+        if (!userId || !text) {
+            json(res, { error: "userId and text are required" }, 400);
+            return true;
+        }
+        const platformName = typeof safeBody.platformName === "string" ? safeBody.platformName : null;
+        const channelType = typeof safeBody.channelType === "string"
+            ? safeBody.channelType
+            : ChannelType.API;
+        const source = platformName || "agent_message_api";
+        try {
+            const runtime = state.runtime;
+            const agentName = runtime.character.name ?? "Eliza";
+            // Per-user room key — matches cloud `handleMessage`'s
+            // `stringToUuid(\`${agentId}:${userId}\`)` shape closely enough that
+            // both surfaces produce stable, user-scoped conversation rooms.
+            const { roomId, userId: connUserId } = await ensureCompatChatConnection(state, runtime, agentName, "agent-message", `${agentIdParam}:${userId}`.slice(0, 120));
+            const message = createMessageMemory({
+                id: crypto.randomUUID(),
+                entityId: connUserId,
+                agentId: runtime.agentId,
+                roomId,
+                content: {
+                    text,
+                    source,
+                    channelType,
+                },
+            });
+            const result = await generateChatResponse(runtime, message, state.agentName, {
+                resolveNoResponseText: () => resolveNoResponseFallback(state.logBuffer, runtime),
+            });
+            syncRuntimeCharacterToChatStateConfig(state);
+            const resolvedText = normalizeChatResponseText(result.text, state.logBuffer, state.runtime);
+            json(res, {
+                response: resolvedText,
+                agentName: result.agentName,
+                ...(result.failureKind ? { failureKind: result.failureKind } : {}),
+                ...(result.localInference
+                    ? { localInference: result.localInference }
+                    : {}),
+            });
+        }
+        catch (err) {
+            if (isLocalInferenceError(err)) {
+                const { getLocalInferenceChatStatus } = await getLocalInferenceChatApi();
+                const localFailure = await getLocalInferenceChatStatus("status", err);
+                json(res, {
+                    error: localFailure.text,
+                    type: "local_inference",
+                    localInference: localFailure.localInference,
+                }, 503);
+            }
+            else if (isNoProviderError(err)) {
+                json(res, {
+                    error: NO_PROVIDER_CHAT_MESSAGE,
+                    type: "no_provider",
+                    code: "NO_PROVIDER_REGISTERED",
+                }, 503);
+            }
+            else {
+                json(res, { error: getErrorMessage(err) }, 500);
+            }
+        }
+        return true;
+    }
+    return false;
+}