@elizaos/agent 0.25.9 → 2.0.0-alpha.144

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

@@ -0,0 +1,367 @@
+import { ModelType } from "@elizaos/core";
+function replaceCharacterNameTokens(value, nextName) {
+    return value
+        .replaceAll("{{agentName}}", nextName)
+        .replaceAll("{{name}}", nextName);
+}
+function shouldRewriteExampleSpeakerName(speakerName, previousName) {
+    const normalized = speakerName.trim().toLowerCase();
+    if (!normalized)
+        return false;
+    if (normalized === "{{agentname}}" ||
+        normalized === "{{name}}" ||
+        normalized === "assistant" ||
+        normalized === "agent" ||
+        normalized === "ai" ||
+        normalized === "model") {
+        return true;
+    }
+    if (previousName?.trim()) {
+        return normalized === previousName.trim().toLowerCase();
+    }
+    return false;
+}
+function normalizeCharacterMessageExamplesForName(messageExamples, nextName, previousName) {
+    if (!Array.isArray(messageExamples)) {
+        return undefined;
+    }
+    return messageExamples.map((group) => {
+        const examples = Array.isArray(group?.examples)
+            ? group.examples
+            : [];
+        return {
+            examples: examples.map((example) => ({
+                ...example,
+                name: shouldRewriteExampleSpeakerName(example.name, previousName)
+                    ? nextName
+                    : replaceCharacterNameTokens(example.name, nextName),
+                content: {
+                    ...example.content,
+                    text: replaceCharacterNameTokens(example.content.text, nextName),
+                },
+            })),
+        };
+    });
+}
+function syncRuntimeCharacterToConfig(state, saveConfig) {
+    const runtime = state.runtime;
+    const config = state.config;
+    if (!runtime || !config)
+        return;
+    if (!config.agents)
+        config.agents = {};
+    const existingList = config.agents.list ?? [];
+    const primaryAgent = existingList[0] ?? {
+        id: "main",
+        default: true,
+    };
+    const character = runtime.character;
+    const nextAgent = {
+        ...primaryAgent,
+        ...(character.name ? { name: character.name } : {}),
+        ...(Array.isArray(character.bio) ? { bio: [...character.bio] } : {}),
+        ...(typeof character.system === "string"
+            ? { system: character.system }
+            : {}),
+        ...(Array.isArray(character.adjectives)
+            ? { adjectives: [...character.adjectives] }
+            : {}),
+        ...(Array.isArray(character.topics)
+            ? { topics: [...(character.topics ?? [])] }
+            : {}),
+        ...(character.style
+            ? {
+                style: {
+                    ...(Array.isArray(character.style.all)
+                        ? { all: [...character.style.all] }
+                        : {}),
+                    ...(Array.isArray(character.style.chat)
+                        ? { chat: [...character.style.chat] }
+                        : {}),
+                    ...(Array.isArray(character.style.post)
+                        ? { post: [...character.style.post] }
+                        : {}),
+                },
+            }
+            : {}),
+        ...(Array.isArray(character.postExamples)
+            ? { postExamples: [...character.postExamples] }
+            : {}),
+        ...(Array.isArray(character.messageExamples)
+            ? {
+                messageExamples: JSON.parse(JSON.stringify(character.messageExamples)),
+            }
+            : {}),
+    };
+    config.agents.list = [nextAgent, ...existingList.slice(1)];
+    saveConfig?.(config);
+}
+function buildCharacterSummary(ctx) {
+    return [
+        ctx.name ? `Name: ${ctx.name}` : "",
+        ctx.system ? `System prompt: ${ctx.system}` : "",
+        ctx.bio ? `Bio: ${ctx.bio}` : "",
+        ctx.topics?.length ? `Topics: ${ctx.topics.join(", ")}` : "",
+        ctx.style?.all?.length ? `Style rules: ${ctx.style.all.join("; ")}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+function buildGeneratePrompt(field, context, mode) {
+    const charSummary = buildCharacterSummary(context);
+    if (field === "bio") {
+        return `Given this character:\n${charSummary}\n\nWrite a concise, compelling bio for this character (3-4 short paragraphs, one per line). Use their current interests and info to expand the bio into something more interesting and unique. Just output the bio lines, nothing else. Match the character's voice and personality.`;
+    }
+    if (field === "system") {
+        return `Given this character:\n${charSummary}\n\nWrite a system prompt that defines how this AI agent should behave. The system prompt should be written in first person, describing the agent's personality, communication style, and core behaviors. Include specific guidelines about tone, language style (formal/casual), and any unique quirks. Keep it concise but comprehensive (2-4 paragraphs). Just output the system prompt text, nothing else.`;
+    }
+    if (field === "style") {
+        const existing = mode === "append" && context.style?.all?.length
+            ? `\nExisting style rules (add to these, don't repeat):\n${context.style.all.join("\n")}`
+            : "";
+        return `Given this character:\n${charSummary}${existing}\n\nGenerate 4-6 communication style rules for this character. Output a JSON object with keys "all", "chat", "post", each containing an array of short rule strings. Just output the JSON, nothing else.`;
+    }
+    if (field === "chatExamples") {
+        return `Given this character:\n${charSummary}\n\nGenerate 3 example chat conversations showing how this character responds. Output strict JSON only, with no markdown fences and no explanation. The JSON must be an array of conversation groups using this exact schema:\n[\n  {\n    "examples": [\n      { "name": "{{user1}}", "content": { "text": "..." } },\n      { "name": "{{agentName}}", "content": { "text": "..." } }\n    ]\n  }\n]\n\nEach conversation should contain 2-4 turns. Use the "name" field, not "user" or "role". Use content.text strings only.`;
+    }
+    const existing = mode === "append" && context.postExamples?.length
+        ? `\nExisting posts (add new ones, don't repeat):\n${context.postExamples.join("\n")}`
+        : "";
+    return `Given this character:\n${charSummary}${existing}\n\nGenerate 3-5 example social media posts this character would write. Output a JSON array of strings. Just output the JSON array, nothing else.`;
+}
+const CHARACTER_SCHEMA_FIELDS = [
+    {
+        key: "name",
+        type: "string",
+        label: "Name",
+        description: "Agent display name",
+        maxLength: 100,
+    },
+    {
+        key: "username",
+        type: "string",
+        label: "Username",
+        description: "Agent username for platforms",
+        maxLength: 50,
+    },
+    {
+        key: "bio",
+        type: "string | string[]",
+        label: "Bio",
+        description: "Biography — single string or array of points",
+    },
+    {
+        key: "system",
+        type: "string",
+        label: "System Prompt",
+        description: "System prompt defining core behavior",
+        maxLength: 10000,
+    },
+    {
+        key: "adjectives",
+        type: "string[]",
+        label: "Adjectives",
+        description: "Personality adjectives (e.g. curious, witty)",
+    },
+    {
+        key: "topics",
+        type: "string[]",
+        label: "Topics",
+        description: "Conversation topics the agent is knowledgeable about",
+    },
+    {
+        key: "style",
+        type: "object",
+        label: "Style",
+        description: "Communication style guides",
+        children: [
+            {
+                key: "all",
+                type: "string[]",
+                label: "All",
+                description: "Style guidelines for all responses",
+            },
+            {
+                key: "chat",
+                type: "string[]",
+                label: "Chat",
+                description: "Style guidelines for chat responses",
+            },
+            {
+                key: "post",
+                type: "string[]",
+                label: "Post",
+                description: "Style guidelines for social media posts",
+            },
+        ],
+    },
+    {
+        key: "messageExamples",
+        type: "array",
+        label: "Message Examples",
+        description: "Example conversations demonstrating the agent's voice",
+    },
+    {
+        key: "postExamples",
+        type: "string[]",
+        label: "Post Examples",
+        description: "Example social media posts",
+    },
+];
+export async function handleCharacterRoutes(ctx) {
+    const { req, res, method, pathname, state, saveConfig, readJsonBody, json, error, pickRandomNames, validateCharacter, } = ctx;
+    if (method === "GET" && pathname === "/api/character") {
+        const runtime = state.runtime;
+        const merged = {};
+        if (runtime) {
+            const character = runtime.character;
+            if (character.name)
+                merged.name = character.name;
+            if (character.username)
+                merged.username = character.username;
+            if (character.bio)
+                merged.bio = character.bio;
+            if (character.system)
+                merged.system = character.system;
+            if (character.adjectives)
+                merged.adjectives = character.adjectives;
+            if (Array.isArray(character.topics)) {
+                merged.topics = character.topics;
+            }
+            if (character.style)
+                merged.style = character.style;
+            if (character.messageExamples) {
+                merged.messageExamples = character.messageExamples;
+            }
+            if (character.postExamples) {
+                merged.postExamples = character.postExamples;
+            }
+        }
+        json(res, { character: merged, agentName: state.agentName });
+        return true;
+    }
+    if (method === "PUT" && pathname === "/api/character") {
+        const body = await readJsonBody(req, res);
+        if (!body)
+            return true;
+        const result = validateCharacter(body);
+        if (!result.success && "error" in result) {
+            const issues = result.error.issues.map((issue) => ({
+                path: issue.path.join("."),
+                message: issue.message,
+            }));
+            json(res, { ok: false, validationErrors: issues }, 422);
+            return true;
+        }
+        if (state.runtime) {
+            const character = state.runtime.character;
+            const previousCharacterName = typeof character.name === "string" ? character.name : undefined;
+            const nextCharacterName = typeof body.name === "string" && body.name.trim()
+                ? body.name.trim()
+                : typeof character.name === "string" && character.name.trim()
+                    ? character.name.trim()
+                    : state.agentName;
+            if (body.name != null)
+                character.name = String(body.name);
+            if (body.username != null)
+                character.username = String(body.username);
+            if (body.bio != null) {
+                character.bio = Array.isArray(body.bio)
+                    ? body.bio
+                    : [String(body.bio)];
+            }
+            if (body.system != null)
+                character.system = String(body.system);
+            if (body.adjectives != null) {
+                character.adjectives = body.adjectives;
+            }
+            if (body.topics != null) {
+                character.topics = body.topics;
+            }
+            if (body.style != null) {
+                character.style = body.style;
+            }
+            if (body.messageExamples != null) {
+                character.messageExamples = normalizeCharacterMessageExamplesForName(body.messageExamples, nextCharacterName, previousCharacterName);
+            }
+            else if (body.name != null) {
+                const normalizedExamples = normalizeCharacterMessageExamplesForName(character.messageExamples, nextCharacterName, previousCharacterName);
+                if (normalizedExamples) {
+                    character.messageExamples = normalizedExamples;
+                }
+            }
+            if (body.postExamples != null) {
+                character.postExamples = body.postExamples;
+            }
+            // Persist character fields to DB so edits survive restarts
+            const charData = {
+                name: character.name,
+                username: character.username,
+                bio: character.bio,
+                system: character.system,
+                adjectives: character.adjectives,
+                topics: character.topics,
+                style: character.style,
+                messageExamples: character.messageExamples,
+                postExamples: character.postExamples,
+            };
+            await state.runtime.updateAgent(state.runtime.agentId, {
+                name: character.name,
+                metadata: {
+                    ...state.runtime.character
+                        .metadata,
+                    character: charData,
+                },
+            });
+        }
+        syncRuntimeCharacterToConfig(state, saveConfig);
+        if (body.name)
+            state.agentName = String(body.name);
+        json(res, {
+            ok: true,
+            character: state.runtime?.character ?? body,
+            agentName: state.agentName,
+        });
+        return true;
+    }
+    if (method === "GET" && pathname === "/api/character/random-name") {
+        const names = pickRandomNames(1);
+        json(res, { name: names[0] ?? "Reimu" });
+        return true;
+    }
+    if (method === "POST" && pathname === "/api/character/generate") {
+        const body = await readJsonBody(req, res);
+        if (!body)
+            return true;
+        if (!body.field || !body.context) {
+            error(res, "field and context are required", 400);
+            return true;
+        }
+        const runtime = state.runtime;
+        if (!runtime) {
+            error(res, "Agent runtime not available. Start the agent first.", 503);
+            return true;
+        }
+        if (body.field !== "bio" &&
+            body.field !== "system" &&
+            body.field !== "style" &&
+            body.field !== "chatExamples" &&
+            body.field !== "postExamples") {
+            error(res, `Unknown field: ${body.field}`, 400);
+            return true;
+        }
+        const prompt = buildGeneratePrompt(body.field, body.context, body.mode);
+        const result = await runtime.useModel(ModelType.TEXT_SMALL, {
+            prompt,
+            temperature: 0.8,
+            maxTokens: 1500,
+        });
+        json(res, { generated: String(result) });
+        return true;
+    }
+    if (method === "GET" && pathname === "/api/character/schema") {
+        json(res, { fields: CHARACTER_SCHEMA_FIELDS });
+        return true;
+    }
+    return false;
+}

package/packages/agent/src/api/chat-augmentation.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Chat message enhancement helpers extracted from server.ts.
+ *
+ * Functions for augmenting chat messages with language instructions,
+ * knowledge context, wallet context, image attachments, and user message building.
+ */
+import { type AgentRuntime, type ChannelType, createMessageMemory, type Media, type UUID } from "@elizaos/core";
+export declare function maybeAugmentChatMessageWithLanguage(message: ReturnType<typeof createMessageMemory>, preferredLanguage?: string): ReturnType<typeof createMessageMemory>;
+export declare function getErrorMessage(err: unknown, fallback?: string): string;
+export declare function getChatKnowledgeTimeoutMs(): number;
+export declare function shouldAugmentChatMessageWithKnowledge(userPrompt: string): boolean;
+export declare function getChatKnowledgeMatchesWithTimeout(lookup: Promise<Array<{
+    id: UUID;
+    content: {
+        text?: string;
+    };
+    similarity?: number;
+    metadata?: Record<string, unknown>;
+}>>): Promise<Array<{
+    id: UUID;
+    content: {
+        text?: string;
+    };
+    similarity?: number;
+    metadata?: Record<string, unknown>;
+}>>;
+export declare function normalizeChatKnowledgeSnippet(text: string): string;
+export declare function buildChatKnowledgePrompt(userPrompt: string, snippets: string[]): string;
+export declare function buildAgentAwarenessContextPrompt(runtime: AgentRuntime, userPrompt: string): Promise<string>;
+export declare function maybeAugmentChatMessageWithAgentAwareness(runtime: AgentRuntime, message: ReturnType<typeof createMessageMemory>): Promise<ReturnType<typeof createMessageMemory>>;
+export declare function maybeAugmentChatMessageWithKnowledge(runtime: AgentRuntime, message: ReturnType<typeof createMessageMemory>): Promise<ReturnType<typeof createMessageMemory>>;
+export interface ChatImageAttachment {
+    /** Base64-encoded image data (no data URL prefix). */
+    data: string;
+    mimeType: string;
+    name: string;
+}
+export declare const IMAGE_ONLY_CHAT_FALLBACK_PROMPT = "Please describe the attached image.";
+/** Returns an error message string, or null if valid. Exported for unit tests. */
+export declare function validateChatImages(images: unknown): string | null;
+/**
+ * Extension of the core Media attachment shape that carries raw image bytes for
+ * action handlers (e.g. POST_TWEET) while the message is in-memory. The
+ * extra fields are intentionally stripped before the message is persisted.
+ *
+ * Note: `_data`/`_mimeType` survive only because elizaOS passes the
+ * `userMessage` object reference directly to action handlers without
+ * deep-cloning or serializing it. If that ever changes, action handlers
+ * that read these fields will silently receive `undefined`.
+ */
+export interface ChatAttachmentWithData extends Media {
+    /** Raw base64 image data — never written to the database. */
+    _data: string;
+    /** MIME type corresponding to `_data`. */
+    _mimeType: string;
+}
+/**
+ * Builds in-memory and compact (DB-persisted) attachment arrays from
+ * validated images. Exported so it can be unit-tested independently.
+ */
+export declare function buildChatAttachments(images: ChatImageAttachment[] | undefined): {
+    /** In-memory attachments that include `_data`/`_mimeType` for action handlers. */
+    attachments: ChatAttachmentWithData[] | undefined;
+    /** Persistence-safe attachments with `_data`/`_mimeType` stripped. */
+    compactAttachments: Media[] | undefined;
+};
+export declare function normalizeIncomingChatPrompt(text: string | null | undefined, images: ChatImageAttachment[] | null | undefined): string | null;
+type MessageMemory = ReturnType<typeof createMessageMemory>;
+/**
+ * Constructs the in-memory user message (with image data for action handlers)
+ * and the persistence-safe counterpart (image data stripped). Extracted to
+ * avoid duplicating this logic across the stream and non-stream chat endpoints.
+ */
+export declare function buildUserMessages(params: {
+    images: ChatImageAttachment[] | undefined;
+    prompt: string;
+    userId: UUID;
+    agentId: UUID;
+    roomId: UUID;
+    channelType: ChannelType;
+    conversationMode?: "simple" | "power";
+    messageSource?: string;
+    metadata?: Record<string, unknown>;
+}): {
+    userMessage: MessageMemory;
+    messageToStore: MessageMemory;
+};
+export {};
+//# sourceMappingURL=chat-augmentation.d.ts.map

package/packages/agent/src/api/chat-augmentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-augmentation.d.ts","sourceRoot":"","sources":["../../../../../src/api/chat-augmentation.ts"],"names":[],"mappings":"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"}