@elizaos/ui 2.0.0-alpha.25 → 2.0.0-alpha.334

package/packages/typescript/src/connection.js

@@ -0,0 +1,149 @@
+/**
+ * Standalone connection management: ensure entity/world/room/participants.
+ * Batch-first: ensureConnections does 4 batch operations (upsertEntities, upsertWorlds,
+ * upsertRooms, createRoomParticipants per room); ensureConnection is a single-connection wrapper.
+ * Use these directly with adapter, or via runtime.ensureConnection() which delegates here.
+ *
+ * WHY standalone + batch: Callers can ensure many connections in one go without going through
+ * the runtime; batch APIs reduce DB round-trips. Safe to use from both Node and edge entry points.
+ */
+import { ChannelType } from "./types";
+import { stringToUuid } from "./utils";
+/** WHY: World is required for room hierarchy; derive a stable worldId from messageServerId when not provided. */
+function resolveWorldId(worldId, messageServerId, agentId) {
+    if (worldId)
+        return worldId;
+    if (messageServerId)
+        return stringToUuid(`${messageServerId}:${agentId}`);
+    throw new Error("worldId or messageServerId is required");
+}
+/**
+ * Batch: upsert entities, worlds, rooms; then add participants per room.
+ * Uses 4 batch operations (upsertEntities, upsertWorlds, upsertRooms, createRoomParticipants per room).
+ * WHY batch: Minimizes round-trips when syncing many connections (e.g. many users/rooms at once).
+ */
+export async function ensureConnections(adapter, params) {
+    const { agentId, connections } = params;
+    if (!connections.length)
+        return;
+    const entityMap = new Map();
+    const worldMap = new Map();
+    const roomMap = new Map();
+    const roomParticipants = new Map();
+    for (const c of connections) {
+        const worldId = resolveWorldId(c.worldId, c.messageServerId, agentId);
+        const names = [c.name, c.userName].filter(Boolean);
+        const source = c.source || "default";
+        const entityKey = c.entityId;
+        if (!entityMap.has(entityKey)) {
+            entityMap.set(entityKey, {
+                entityId: c.entityId,
+                names: [],
+                metadata: {},
+                agentId,
+            });
+        }
+        const ent = entityMap.get(entityKey);
+        if (!ent) {
+            continue;
+        }
+        ent.names = [...new Set([...ent.names, ...names])].filter(Boolean);
+        ent.metadata[source] = {
+            id: c.userId,
+            name: c.name,
+            userName: c.userName,
+        };
+        const world = {
+            id: worldId,
+            name: c.worldName
+                ? c.worldName
+                : c.messageServerId
+                    ? `World for server ${c.messageServerId}`
+                    : `World for room ${c.roomId}`,
+            agentId,
+            messageServerId: c.messageServerId,
+            metadata: c.metadata,
+        };
+        worldMap.set(worldId, world);
+        const roomType = typeof c.type === "string" &&
+            Object.values(ChannelType).includes(c.type)
+            ? c.type
+            : ChannelType.DM;
+        const room = {
+            id: c.roomId,
+            name: c.roomName || c.name || "default",
+            source,
+            type: roomType,
+            channelId: c.channelId ?? c.roomId,
+            messageServerId: c.messageServerId,
+            worldId,
+        };
+        roomMap.set(c.roomId, room);
+        if (!roomParticipants.has(c.roomId)) {
+            roomParticipants.set(c.roomId, new Set());
+        }
+        const participants = roomParticipants.get(c.roomId);
+        if (!participants) {
+            continue;
+        }
+        participants.add(c.entityId);
+        participants.add(agentId);
+    }
+    const entityIds = [...entityMap.keys()];
+    const existingEntities = entityIds.length > 0
+        ? await adapter.getEntitiesByIds(entityIds)
+        : [];
+    const existingByKey = new Map(existingEntities.map((e) => [e.id, e]));
+    const entities = [];
+    for (const [, v] of entityMap) {
+        const existing = existingByKey.get(v.entityId) ?? null;
+        const names = existing
+            ? [...new Set([...(existing.names || []), ...v.names])].filter(Boolean)
+            : v.names;
+        const metadata = (existing ? { ...existing.metadata, ...v.metadata } : v.metadata);
+        entities.push({
+            id: v.entityId,
+            names,
+            metadata,
+            agentId: v.agentId,
+        });
+    }
+    if (entities.length)
+        await adapter.upsertEntities(entities);
+    const worlds = [...worldMap.values()].map((w) => ({
+        ...w,
+        agentId,
+    }));
+    if (worlds.length)
+        await adapter.upsertWorlds(worlds);
+    const rooms = [...roomMap.values()].map((r) => ({
+        ...r,
+        agentId,
+    }));
+    if (rooms.length)
+        await adapter.upsertRooms(rooms);
+    for (const [roomId, entityIdsSet] of roomParticipants) {
+        const currentResult = await adapter.getParticipantsForRooms([
+            roomId,
+        ]);
+        const current = currentResult[0]?.entityIds ?? [];
+        const missing = [...entityIdsSet].filter((id) => !current.includes(id));
+        if (missing.length) {
+            await adapter.createRoomParticipants(missing, roomId);
+        }
+    }
+}
+/**
+ * Single-connection wrapper around ensureConnections.
+ * WHY: Convenience for the common case of ensuring one entity/room; runtime.ensureConnection() uses this.
+ */
+export async function ensureConnection(adapter, params) {
+    if (!params.source) {
+        throw new Error("Source is required for ensureConnection");
+    }
+    const worldId = resolveWorldId(params.worldId, params.messageServerId, params.agentId);
+    await ensureConnections(adapter, {
+        agentId: params.agentId,
+        connections: [{ ...params, worldId }],
+    });
+}

package/packages/typescript/src/constants/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Constants Module
+ *
+ * Re-exports all constants from submodules.
+ */
+export * from "./secrets";
+//# sourceMappingURL=index.d.ts.map

package/packages/typescript/src/constants/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/constants/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,WAAW,CAAC"}

package/packages/typescript/src/constants/index.js

@@ -0,0 +1,6 @@
+/**
+ * Constants Module
+ *
+ * Re-exports all constants from submodules.
+ */
+export * from "./secrets";

package/packages/typescript/src/constants/secrets.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Secret Key Constants and Aliases
+ *
+ * This module provides canonical secret key names, aliases for backward compatibility,
+ * and mappings for model providers. All secret key naming should reference this module
+ * to ensure consistency across the codebase.
+ *
+ * @module constants/secrets
+ */
+/**
+ * Maps legacy/alternative secret key names to their canonical names.
+ * When looking up a secret, check if it's an alias first and resolve to canonical name.
+ *
+ * Key: Legacy/alternative name
+ * Value: Canonical name
+ */
+export declare const SECRET_KEY_ALIASES: Record<string, string>;
+/**
+ * List of all canonical secret key names.
+ * These are the "official" key names that should be used throughout the codebase.
+ */
+export declare const CANONICAL_SECRET_KEYS: readonly ["OPENAI_API_KEY", "ANTHROPIC_API_KEY", "GOOGLE_API_KEY", "GROQ_API_KEY", "XAI_API_KEY", "OPENROUTER_API_KEY", "MISTRAL_API_KEY", "COHERE_API_KEY", "TOGETHER_API_KEY", "FIREWORKS_API_KEY", "PERPLEXITY_API_KEY", "DEEPSEEK_API_KEY", "DISCORD_BOT_TOKEN", "DISCORD_APPLICATION_ID", "TELEGRAM_BOT_TOKEN", "SLACK_BOT_TOKEN", "SLACK_APP_TOKEN", "WHATSAPP_TOKEN", "SIGNAL_CLI_PATH", "TWITTER_USERNAME", "TWITTER_PASSWORD", "TWITTER_EMAIL", "TWITTER_2FA_SECRET", "ELEVENLABS_API_KEY", "ELEVENLABS_VOICE_ID", "ENCRYPTION_SALT", "DATABASE_URL", "OLLAMA_BASE_URL"];
+/**
+ * Type for canonical secret keys
+ */
+export type CanonicalSecretKey = (typeof CANONICAL_SECRET_KEYS)[number];
+/**
+ * Comprehensive mapping of model provider names to their API key environment variables.
+ * Used for detecting which AI provider is configured and for auto-enabling provider plugins.
+ */
+export declare const MODEL_PROVIDER_SECRETS: Record<string, string>;
+/**
+ * Model providers that don't require API keys (local inference).
+ * These are validated differently (check for URL availability).
+ */
+export declare const LOCAL_MODEL_PROVIDERS: readonly ["ollama"];
+/**
+ * Required secrets for each communication channel.
+ * Used to determine if a channel can be enabled.
+ */
+export declare const CHANNEL_SECRETS: Record<string, string[]>;
+/**
+ * Optional secrets for channels (enhance functionality but not required).
+ */
+export declare const CHANNEL_OPTIONAL_SECRETS: Record<string, string[]>;
+/**
+ * Resolve a secret key alias to its canonical name.
+ * If the key is not an alias, returns the original key.
+ *
+ * @param key - The secret key to resolve
+ * @returns The canonical key name
+ */
+export declare function resolveSecretKeyAlias(key: string): string;
+/**
+ * Check if a key is a known alias.
+ *
+ * @param key - The key to check
+ * @returns true if the key is an alias
+ */
+export declare function isSecretKeyAlias(key: string): boolean;
+/**
+ * Get all aliases for a canonical key.
+ *
+ * @param canonicalKey - The canonical key name
+ * @returns Array of alias names that map to this canonical key
+ */
+export declare function getAliasesForKey(canonicalKey: string): string[];
+/**
+ * Check if a key is a canonical secret key.
+ *
+ * @param key - The key to check
+ * @returns true if the key is in the canonical keys list
+ */
+export declare function isCanonicalSecretKey(key: string): key is CanonicalSecretKey;
+/**
+ * Get the model provider name for a given API key.
+ *
+ * @param apiKey - The API key environment variable name
+ * @returns The provider name, or null if not found
+ */
+export declare function getProviderForApiKey(apiKey: string): string | null;
+/**
+ * Get required secrets for a channel.
+ *
+ * @param channel - The channel name
+ * @returns Array of required secret key names
+ */
+export declare function getRequiredSecretsForChannel(channel: string): string[];
+/**
+ * Get all secrets (required + optional) for a channel.
+ *
+ * @param channel - The channel name
+ * @returns Object with required and optional secret arrays
+ */
+export declare function getAllSecretsForChannel(channel: string): {
+    required: string[];
+    optional: string[];
+};
+//# sourceMappingURL=secrets.d.ts.map

package/packages/typescript/src/constants/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/constants/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA4DrD,CAAC;AAMF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,mjBAwCxB,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAMxE;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAmBzD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,qBAAsB,CAAC;AAMzD;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAOpD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAG7D,CAAC;AAMF;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CAI/D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,kBAAkB,CAE3E;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOlE;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAEtE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG;IACzD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB,CAKA"}

package/packages/typescript/src/constants/secrets.js

@@ -0,0 +1,239 @@
+/**
+ * Secret Key Constants and Aliases
+ *
+ * This module provides canonical secret key names, aliases for backward compatibility,
+ * and mappings for model providers. All secret key naming should reference this module
+ * to ensure consistency across the codebase.
+ *
+ * @module constants/secrets
+ */
+// ═══════════════════════════════════════════════════════════════════════════════
+// SECRET KEY ALIASES (Backward Compatibility)
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Maps legacy/alternative secret key names to their canonical names.
+ * When looking up a secret, check if it's an alias first and resolve to canonical name.
+ *
+ * Key: Legacy/alternative name
+ * Value: Canonical name
+ */
+export const SECRET_KEY_ALIASES = {
+    // Discord aliases
+    DISCORD_TOKEN: "DISCORD_BOT_TOKEN",
+    DISCORD_API_TOKEN: "DISCORD_BOT_TOKEN",
+    // Telegram aliases
+    TELEGRAM_TOKEN: "TELEGRAM_BOT_TOKEN",
+    TELEGRAM_API_TOKEN: "TELEGRAM_BOT_TOKEN",
+    TG_BOT_TOKEN: "TELEGRAM_BOT_TOKEN",
+    // Slack aliases
+    SLACK_TOKEN: "SLACK_BOT_TOKEN",
+    SLACK_API_TOKEN: "SLACK_BOT_TOKEN",
+    // OpenAI aliases
+    OPENAI_KEY: "OPENAI_API_KEY",
+    OPENAI_TOKEN: "OPENAI_API_KEY",
+    // Anthropic aliases
+    ANTHROPIC_KEY: "ANTHROPIC_API_KEY",
+    ANTHROPIC_TOKEN: "ANTHROPIC_API_KEY",
+    CLAUDE_API_KEY: "ANTHROPIC_API_KEY",
+    // Google aliases
+    GOOGLE_KEY: "GOOGLE_API_KEY",
+    GOOGLE_AI_KEY: "GOOGLE_API_KEY",
+    GEMINI_API_KEY: "GOOGLE_API_KEY",
+    GOOGLE_GENERATIVE_AI_API_KEY: "GOOGLE_API_KEY",
+    // Groq aliases
+    GROQ_KEY: "GROQ_API_KEY",
+    GROQ_TOKEN: "GROQ_API_KEY",
+    // XAI aliases
+    XAI_KEY: "XAI_API_KEY",
+    GROK_API_KEY: "XAI_API_KEY",
+    // OpenRouter aliases
+    OPENROUTER_KEY: "OPENROUTER_API_KEY",
+    OPENROUTER_TOKEN: "OPENROUTER_API_KEY",
+    // Mistral aliases
+    MISTRAL_KEY: "MISTRAL_API_KEY",
+    MISTRAL_TOKEN: "MISTRAL_API_KEY",
+    // Cohere aliases
+    COHERE_KEY: "COHERE_API_KEY",
+    COHERE_TOKEN: "COHERE_API_KEY",
+    // Together aliases
+    TOGETHER_KEY: "TOGETHER_API_KEY",
+    TOGETHER_TOKEN: "TOGETHER_API_KEY",
+    // ElevenLabs aliases
+    ELEVENLABS_KEY: "ELEVENLABS_API_KEY",
+    ELEVEN_LABS_API_KEY: "ELEVENLABS_API_KEY",
+    // WhatsApp aliases
+    WHATSAPP_BOT_TOKEN: "WHATSAPP_TOKEN",
+    WHATSAPP_API_TOKEN: "WHATSAPP_TOKEN",
+};
+// ═══════════════════════════════════════════════════════════════════════════════
+// CANONICAL SECRET KEYS
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * List of all canonical secret key names.
+ * These are the "official" key names that should be used throughout the codebase.
+ */
+export const CANONICAL_SECRET_KEYS = [
+    // Model Provider API Keys
+    "OPENAI_API_KEY",
+    "ANTHROPIC_API_KEY",
+    "GOOGLE_API_KEY",
+    "GROQ_API_KEY",
+    "XAI_API_KEY",
+    "OPENROUTER_API_KEY",
+    "MISTRAL_API_KEY",
+    "COHERE_API_KEY",
+    "TOGETHER_API_KEY",
+    "FIREWORKS_API_KEY",
+    "PERPLEXITY_API_KEY",
+    "DEEPSEEK_API_KEY",
+    // Channel/Platform Tokens
+    "DISCORD_BOT_TOKEN",
+    "DISCORD_APPLICATION_ID",
+    "TELEGRAM_BOT_TOKEN",
+    "SLACK_BOT_TOKEN",
+    "SLACK_APP_TOKEN",
+    "WHATSAPP_TOKEN",
+    "SIGNAL_CLI_PATH",
+    // Twitter/X credentials
+    "TWITTER_USERNAME",
+    "TWITTER_PASSWORD",
+    "TWITTER_EMAIL",
+    "TWITTER_2FA_SECRET",
+    // Media/Voice Services
+    "ELEVENLABS_API_KEY",
+    "ELEVENLABS_VOICE_ID",
+    // Infrastructure
+    "ENCRYPTION_SALT",
+    "DATABASE_URL",
+    // Ollama (local inference)
+    "OLLAMA_BASE_URL",
+];
+// ═══════════════════════════════════════════════════════════════════════════════
+// MODEL PROVIDER SECRETS
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Comprehensive mapping of model provider names to their API key environment variables.
+ * Used for detecting which AI provider is configured and for auto-enabling provider plugins.
+ */
+export const MODEL_PROVIDER_SECRETS = {
+    // Primary providers
+    anthropic: "ANTHROPIC_API_KEY",
+    openai: "OPENAI_API_KEY",
+    google: "GOOGLE_API_KEY",
+    groq: "GROQ_API_KEY",
+    xai: "XAI_API_KEY",
+    openrouter: "OPENROUTER_API_KEY",
+    // Additional providers
+    mistral: "MISTRAL_API_KEY",
+    cohere: "COHERE_API_KEY",
+    together: "TOGETHER_API_KEY",
+    fireworks: "FIREWORKS_API_KEY",
+    perplexity: "PERPLEXITY_API_KEY",
+    deepseek: "DEEPSEEK_API_KEY",
+    // Local inference (checks for URL instead of API key)
+    ollama: "OLLAMA_BASE_URL",
+};
+/**
+ * Model providers that don't require API keys (local inference).
+ * These are validated differently (check for URL availability).
+ */
+export const LOCAL_MODEL_PROVIDERS = ["ollama"];
+// ═══════════════════════════════════════════════════════════════════════════════
+// CHANNEL SECRETS
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Required secrets for each communication channel.
+ * Used to determine if a channel can be enabled.
+ */
+export const CHANNEL_SECRETS = {
+    discord: ["DISCORD_BOT_TOKEN"],
+    telegram: ["TELEGRAM_BOT_TOKEN"],
+    slack: ["SLACK_BOT_TOKEN", "SLACK_APP_TOKEN"],
+    whatsapp: ["WHATSAPP_TOKEN"],
+    signal: ["SIGNAL_CLI_PATH"],
+    twitter: ["TWITTER_USERNAME", "TWITTER_PASSWORD"],
+};
+/**
+ * Optional secrets for channels (enhance functionality but not required).
+ */
+export const CHANNEL_OPTIONAL_SECRETS = {
+    discord: ["DISCORD_APPLICATION_ID"],
+    twitter: ["TWITTER_EMAIL", "TWITTER_2FA_SECRET"],
+};
+// ═══════════════════════════════════════════════════════════════════════════════
+// HELPER FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Resolve a secret key alias to its canonical name.
+ * If the key is not an alias, returns the original key.
+ *
+ * @param key - The secret key to resolve
+ * @returns The canonical key name
+ */
+export function resolveSecretKeyAlias(key) {
+    return SECRET_KEY_ALIASES[key] ?? key;
+}
+/**
+ * Check if a key is a known alias.
+ *
+ * @param key - The key to check
+ * @returns true if the key is an alias
+ */
+export function isSecretKeyAlias(key) {
+    return key in SECRET_KEY_ALIASES;
+}
+/**
+ * Get all aliases for a canonical key.
+ *
+ * @param canonicalKey - The canonical key name
+ * @returns Array of alias names that map to this canonical key
+ */
+export function getAliasesForKey(canonicalKey) {
+    return Object.entries(SECRET_KEY_ALIASES)
+        .filter(([_, canonical]) => canonical === canonicalKey)
+        .map(([alias]) => alias);
+}
+/**
+ * Check if a key is a canonical secret key.
+ *
+ * @param key - The key to check
+ * @returns true if the key is in the canonical keys list
+ */
+export function isCanonicalSecretKey(key) {
+    return CANONICAL_SECRET_KEYS.includes(key);
+}
+/**
+ * Get the model provider name for a given API key.
+ *
+ * @param apiKey - The API key environment variable name
+ * @returns The provider name, or null if not found
+ */
+export function getProviderForApiKey(apiKey) {
+    for (const [provider, key] of Object.entries(MODEL_PROVIDER_SECRETS)) {
+        if (key === apiKey) {
+            return provider;
+        }
+    }
+    return null;
+}
+/**
+ * Get required secrets for a channel.
+ *
+ * @param channel - The channel name
+ * @returns Array of required secret key names
+ */
+export function getRequiredSecretsForChannel(channel) {
+    return CHANNEL_SECRETS[channel] ?? [];
+}
+/**
+ * Get all secrets (required + optional) for a channel.
+ *
+ * @param channel - The channel name
+ * @returns Object with required and optional secret arrays
+ */
+export function getAllSecretsForChannel(channel) {
+    return {
+        required: CHANNEL_SECRETS[channel] ?? [],
+        optional: CHANNEL_OPTIONAL_SECRETS[channel] ?? [],
+    };
+}