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

package/packages/typescript/src/roles.js

@@ -0,0 +1,544 @@
+import { createUniqueUuid } from "./entities";
+import { logger } from "./logger";
+const DEFAULT_SERVER_ROLE = "NONE";
+export const ROLE_RANK = {
+    GUEST: 0,
+    USER: 1,
+    ADMIN: 2,
+    OWNER: 3,
+};
+const CONNECTOR_ADMINS_SETTING_KEY = "ELIZA_ROLES_CONNECTOR_ADMINS_JSON";
+const CANONICAL_OWNER_SETTING_KEY = "ELIZA_ADMIN_ENTITY_ID";
+const OWNER_CONTACTS_SETTING_KEY = "ELIZA_OWNER_CONTACTS_JSON";
+const CONNECTOR_ID_FIELDS = ["userId", "id", "username", "userName"];
+const CONNECTOR_STABLE_ID_FIELDS = ["userId", "id"];
+function asStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .filter((entry) => typeof entry === "string")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}
+function normalizeConnectorAdminWhitelist(whitelist) {
+    if (!whitelist || typeof whitelist !== "object")
+        return {};
+    return Object.fromEntries(Object.entries(whitelist)
+        .map(([connector, values]) => [connector, asStringArray(values)])
+        .filter(([, values]) => values.length > 0));
+}
+function normalizeRoleGrantSource(raw) {
+    if (raw === "owner" || raw === "manual" || raw === "connector_admin") {
+        return raw;
+    }
+    return null;
+}
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    return value;
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function getRuntimeSettingString(runtime, key) {
+    if (typeof runtime.getSetting !== "function") {
+        return undefined;
+    }
+    const value = runtime.getSetting(key);
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function parseOwnerContactEntityIds(raw) {
+    if (!raw) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return [];
+        }
+        return Object.values(parsed)
+            .map((entry) => entry && typeof entry.entityId === "string"
+            ? entry.entityId.trim()
+            : "")
+            .filter((entityId) => entityId.length > 0);
+    }
+    catch (error) {
+        logger.warn(`[roles] Failed to parse owner contacts from runtime settings: ${formatError(error)}`);
+        return [];
+    }
+}
+function getMemoryMetadata(message) {
+    return asRecord(message.metadata);
+}
+function getMessageSource(message) {
+    return typeof message.content?.source === "string"
+        ? message.content.source
+        : undefined;
+}
+function getConnectorMetadataFromMemory(message) {
+    const memoryMetadata = getMemoryMetadata(message);
+    const source = getMessageSource(message);
+    if (!source) {
+        return undefined;
+    }
+    const sourceMetadata = asRecord(memoryMetadata?.[source]);
+    if (sourceMetadata) {
+        return { [source]: sourceMetadata };
+    }
+    if (source === "discord") {
+        const fromId = memoryMetadata?.fromId;
+        if (typeof fromId !== "string" || fromId.trim().length === 0) {
+            return undefined;
+        }
+        const entityName = typeof memoryMetadata?.entityName === "string"
+            ? memoryMetadata.entityName
+            : undefined;
+        return {
+            discord: {
+                userId: fromId,
+                id: fromId,
+                ...(entityName ? { name: entityName, username: entityName } : {}),
+            },
+        };
+    }
+    return undefined;
+}
+async function getEntityMetadata(runtime, entityId) {
+    if (typeof runtime.getEntityById !== "function") {
+        return undefined;
+    }
+    try {
+        const entity = await runtime.getEntityById(entityId);
+        return asRecord(entity?.metadata);
+    }
+    catch (error) {
+        logger.warn(`[roles] Failed to look up entity ${entityId}: ${formatError(error)}`);
+        return undefined;
+    }
+}
+export async function getUserServerRole(runtime, entityId, serverId) {
+    const worldId = createUniqueUuid(runtime, serverId);
+    const world = await runtime.getWorld(worldId);
+    const worldMetadata = world?.metadata;
+    const roles = worldMetadata?.roles;
+    if (!roles) {
+        return DEFAULT_SERVER_ROLE;
+    }
+    const role = roles[entityId];
+    if (role) {
+        return role;
+    }
+    return DEFAULT_SERVER_ROLE;
+}
+export async function findWorldsForOwner(runtime, entityId) {
+    if (!entityId) {
+        logger.error({ src: "core:roles", agentId: runtime.agentId }, "User ID is required to find server");
+        return null;
+    }
+    const worlds = await runtime.getAllWorlds();
+    if (!worlds || worlds.length === 0) {
+        logger.debug({ src: "core:roles", agentId: runtime.agentId }, "No worlds found for agent");
+        return null;
+    }
+    const ownerWorlds = [];
+    for (const world of worlds) {
+        const worldMetadata = world.metadata;
+        const worldMetadataOwnership = worldMetadata?.ownership;
+        if (worldMetadataOwnership && worldMetadataOwnership.ownerId === entityId) {
+            ownerWorlds.push(world);
+        }
+    }
+    return ownerWorlds.length ? ownerWorlds : null;
+}
+export function getConfiguredOwnerEntityIds(runtime) {
+    const configuredAdminEntityId = getRuntimeSettingString(runtime, CANONICAL_OWNER_SETTING_KEY);
+    const ownerContactsRaw = getRuntimeSettingString(runtime, OWNER_CONTACTS_SETTING_KEY);
+    const ownerContactEntityIds = parseOwnerContactEntityIds(ownerContactsRaw);
+    const deduped = new Set();
+    if (configuredAdminEntityId) {
+        deduped.add(configuredAdminEntityId);
+    }
+    for (const entityId of ownerContactEntityIds) {
+        deduped.add(entityId);
+    }
+    return [...deduped];
+}
+export function hasConfiguredCanonicalOwner(runtime) {
+    return getConfiguredOwnerEntityIds(runtime).length > 0;
+}
+export function resolveCanonicalOwnerId(runtime, metadata) {
+    const configuredOwnerIds = getConfiguredOwnerEntityIds(runtime);
+    if (configuredOwnerIds.length > 0) {
+        return configuredOwnerIds[0] ?? null;
+    }
+    const worldOwnerId = metadata?.ownership?.ownerId;
+    return typeof worldOwnerId === "string" && worldOwnerId.length > 0
+        ? worldOwnerId
+        : null;
+}
+function resolveOwnershipCandidateIds(runtime, metadata) {
+    const configuredOwnerIds = getConfiguredOwnerEntityIds(runtime);
+    if (configuredOwnerIds.length > 0) {
+        return configuredOwnerIds;
+    }
+    const ownerId = resolveCanonicalOwnerId(runtime, metadata);
+    return ownerId ? [ownerId] : [];
+}
+function connectorIdentityMatches(left, right) {
+    if (!left || !right)
+        return false;
+    for (const [connector, leftRaw] of Object.entries(left)) {
+        const leftConnector = asRecord(leftRaw);
+        const rightConnector = asRecord(right[connector]);
+        if (!leftConnector || !rightConnector) {
+            continue;
+        }
+        for (const field of CONNECTOR_STABLE_ID_FIELDS) {
+            const leftValue = leftConnector[field];
+            const rightValue = rightConnector[field];
+            if (typeof leftValue === "string" &&
+                leftValue.length > 0 &&
+                leftValue === rightValue) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+async function hasConfirmedIdentityLink(runtime, entityId, ownerId) {
+    const linkedIds = await getConfirmedLinkedEntityIds(runtime, entityId);
+    return linkedIds.includes(ownerId);
+}
+async function getConfirmedLinkedEntityIds(runtime, entityId) {
+    if (typeof runtime.getRelationships !== "function") {
+        return [];
+    }
+    try {
+        const relationships = await runtime.getRelationships({
+            entityIds: [entityId],
+            tags: ["identity_link"],
+        });
+        const linkedIds = new Set();
+        for (const relationship of relationships) {
+            const metadata = asRecord(relationship.metadata);
+            if (metadata?.status !== "confirmed") {
+                continue;
+            }
+            if (relationship.sourceEntityId === entityId &&
+                typeof relationship.targetEntityId === "string") {
+                linkedIds.add(relationship.targetEntityId);
+            }
+            if (relationship.targetEntityId === entityId &&
+                typeof relationship.sourceEntityId === "string") {
+                linkedIds.add(relationship.sourceEntityId);
+            }
+        }
+        return [...linkedIds];
+    }
+    catch (error) {
+        logger.warn(`[roles] Failed to load identity links for ${entityId}: ${formatError(error)}`);
+        return [];
+    }
+}
+async function resolveOwnershipRole(runtime, metadata, entityId, options) {
+    const ownerIds = resolveOwnershipCandidateIds(runtime, metadata);
+    if (ownerIds.length === 0) {
+        return null;
+    }
+    const senderMetadata = options?.liveEntityMetadata ?? (await getEntityMetadata(runtime, entityId));
+    for (const ownerId of ownerIds) {
+        if (ownerId === entityId) {
+            return "OWNER";
+        }
+        if (await hasConfirmedIdentityLink(runtime, entityId, ownerId)) {
+            return "OWNER";
+        }
+        const ownerMetadata = await getEntityMetadata(runtime, ownerId);
+        if (!ownerMetadata) {
+            continue;
+        }
+        if (connectorIdentityMatches(senderMetadata, ownerMetadata)) {
+            return "OWNER";
+        }
+    }
+    return null;
+}
+function resolveWorldIdFromMessageMetadata(runtime, message) {
+    const source = getMessageSource(message);
+    const metadata = getMemoryMetadata(message);
+    if (source === "discord") {
+        const serverId = typeof metadata?.discordServerId === "string"
+            ? metadata.discordServerId
+            : typeof metadata?.discordChannelId === "string"
+                ? metadata.discordChannelId
+                : null;
+        if (!serverId) {
+            return null;
+        }
+        return createUniqueUuid(runtime, serverId);
+    }
+    return null;
+}
+export function setConnectorAdminWhitelist(runtime, whitelist) {
+    if (typeof runtime.setSetting !== "function") {
+        return;
+    }
+    const normalized = normalizeConnectorAdminWhitelist(whitelist);
+    if (Object.keys(normalized).length === 0) {
+        runtime.setSetting(CONNECTOR_ADMINS_SETTING_KEY, null);
+        return;
+    }
+    runtime.setSetting(CONNECTOR_ADMINS_SETTING_KEY, JSON.stringify(normalized));
+}
+export function getConnectorAdminWhitelist(runtime) {
+    const raw = getRuntimeSettingString(runtime, CONNECTOR_ADMINS_SETTING_KEY);
+    if (!raw) {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return normalizeConnectorAdminWhitelist(parsed);
+    }
+    catch (error) {
+        logger.warn(`[roles] Failed to parse ${CONNECTOR_ADMINS_SETTING_KEY}: ${formatError(error)}`);
+        return {};
+    }
+}
+export function matchEntityToConnectorAdminWhitelist(entityMetadata, whitelist) {
+    if (!entityMetadata || typeof entityMetadata !== "object")
+        return null;
+    const normalizedWhitelist = normalizeConnectorAdminWhitelist(whitelist);
+    for (const [connector, platformIds] of Object.entries(normalizedWhitelist)) {
+        const connectorMeta = asRecord(entityMetadata[connector]);
+        if (!connectorMeta) {
+            continue;
+        }
+        for (const field of CONNECTOR_ID_FIELDS) {
+            const value = connectorMeta[field];
+            if (typeof value === "string" && platformIds.includes(value)) {
+                return { connector, matchedValue: value, matchedField: field };
+            }
+        }
+    }
+    return null;
+}
+export function normalizeRole(raw) {
+    const upper = (raw ?? "").toUpperCase();
+    if (upper === "OWNER" || upper === "ADMIN" || upper === "USER")
+        return upper;
+    return "GUEST";
+}
+export function getEntityRole(metadata, entityId) {
+    if (!metadata?.roles)
+        return "GUEST";
+    return normalizeRole(metadata.roles[entityId]);
+}
+function getStoredRoleSource(metadata, entityId) {
+    return normalizeRoleGrantSource(metadata?.roleSources?.[entityId]);
+}
+async function resolveStoredRoleSource(runtime, metadata, entityId, options) {
+    const storedSource = getStoredRoleSource(metadata, entityId);
+    if (storedSource) {
+        return storedSource;
+    }
+    const storedRole = getEntityRole(metadata, entityId);
+    if (storedRole === "GUEST") {
+        return null;
+    }
+    if (storedRole === "OWNER") {
+        return "owner";
+    }
+    const entityMetadata = options?.liveEntityId === entityId
+        ? (options.liveEntityMetadata ?? undefined)
+        : undefined;
+    const matchedWhitelist = matchEntityToConnectorAdminWhitelist(entityMetadata ?? (await getEntityMetadata(runtime, entityId)), getConnectorAdminWhitelist(runtime));
+    if (storedRole === "ADMIN" && matchedWhitelist) {
+        return "connector_admin";
+    }
+    return "manual";
+}
+async function resolveExplicitGrantedRole(runtime, metadata, entityId, options) {
+    const directRole = getEntityRole(metadata, entityId);
+    const directSource = await resolveStoredRoleSource(runtime, metadata, entityId, options);
+    if (directRole !== "GUEST" && directSource === "manual") {
+        return { role: directRole, source: "manual" };
+    }
+    const linkedIds = await getConfirmedLinkedEntityIds(runtime, entityId);
+    let bestRole = null;
+    for (const linkedEntityId of linkedIds) {
+        const linkedRole = getEntityRole(metadata, linkedEntityId);
+        if (linkedRole === "GUEST") {
+            continue;
+        }
+        const linkedSource = await resolveStoredRoleSource(runtime, metadata, linkedEntityId);
+        if (linkedSource !== "manual") {
+            continue;
+        }
+        if (!bestRole || ROLE_RANK[linkedRole] > ROLE_RANK[bestRole]) {
+            bestRole = linkedRole;
+        }
+    }
+    return bestRole ? { role: bestRole, source: "linked_manual" } : null;
+}
+export function getLiveEntityMetadataFromMessage(message) {
+    // Only trust connector identity stamped into the Memory itself.
+    // content.metadata can come from untrusted chat clients, so it must not
+    // participate in role resolution.
+    return getConnectorMetadataFromMemory(message);
+}
+export async function resolveEntityRole(runtime, _world, metadata, entityId, options) {
+    const explicitRole = getEntityRole(metadata, entityId);
+    const explicitSource = await resolveStoredRoleSource(runtime, metadata, entityId, options);
+    const ownershipRole = await resolveOwnershipRole(runtime, metadata, entityId, options);
+    if (ownershipRole === "OWNER") {
+        return "OWNER";
+    }
+    const whitelist = getConnectorAdminWhitelist(runtime);
+    const liveMatched = matchEntityToConnectorAdminWhitelist(options?.liveEntityMetadata ?? undefined, whitelist);
+    if (explicitRole !== "GUEST") {
+        if (explicitRole === "OWNER") {
+            return hasConfiguredCanonicalOwner(runtime) ? "GUEST" : "OWNER";
+        }
+        if (explicitSource === "connector_admin") {
+            if (Object.keys(whitelist).length === 0) {
+                return "GUEST";
+            }
+            if (liveMatched) {
+                return "ADMIN";
+            }
+            const entityMetadata = await getEntityMetadata(runtime, entityId);
+            const matched = matchEntityToConnectorAdminWhitelist(entityMetadata, whitelist);
+            if (matched) {
+                return "ADMIN";
+            }
+            return "GUEST";
+        }
+        return explicitRole;
+    }
+    if (Object.keys(whitelist).length === 0) {
+        return explicitRole;
+    }
+    if (liveMatched) {
+        return "ADMIN";
+    }
+    const entityMetadata = await getEntityMetadata(runtime, entityId);
+    const matched = matchEntityToConnectorAdminWhitelist(entityMetadata, whitelist);
+    if (!matched) {
+        return explicitRole;
+    }
+    return "ADMIN";
+}
+export async function checkSenderPrivateAccess(runtime, message) {
+    const resolved = await resolveWorldForMessage(runtime, message);
+    if (!resolved)
+        return null;
+    const { world, metadata } = resolved;
+    const entityId = message.entityId;
+    const options = {
+        liveEntityMetadata: getLiveEntityMetadataFromMessage(message),
+        liveEntityId: entityId,
+    };
+    const role = await resolveEntityRole(runtime, world, metadata, entityId, options);
+    const ownershipRole = await resolveOwnershipRole(runtime, metadata, entityId, options);
+    if (ownershipRole === "OWNER") {
+        return {
+            entityId,
+            role,
+            isOwner: true,
+            isAdmin: true,
+            canManageRoles: true,
+            hasPrivateAccess: true,
+            accessRole: "OWNER",
+            accessSource: "owner",
+        };
+    }
+    const explicitAccess = await resolveExplicitGrantedRole(runtime, metadata, entityId, options);
+    return {
+        entityId,
+        role,
+        isOwner: false,
+        isAdmin: role === "OWNER" || role === "ADMIN",
+        canManageRoles: role === "OWNER" || role === "ADMIN",
+        hasPrivateAccess: explicitAccess !== null,
+        accessRole: explicitAccess?.role ?? null,
+        accessSource: explicitAccess?.source ?? null,
+    };
+}
+export function canModifyRole(actorRole, targetCurrentRole, newRole) {
+    if (targetCurrentRole === newRole)
+        return false;
+    const actorRank = ROLE_RANK[actorRole];
+    const targetRank = ROLE_RANK[targetCurrentRole];
+    if (actorRole === "OWNER")
+        return true;
+    if (actorRole === "ADMIN") {
+        if (targetRank >= actorRank)
+            return false;
+        if (newRole === "OWNER")
+            return false;
+        return true;
+    }
+    return false;
+}
+export async function resolveWorldForMessage(runtime, message) {
+    const room = await runtime.getRoom(message.roomId);
+    const worldId = room?.worldId ?? resolveWorldIdFromMessageMetadata(runtime, message);
+    if (!worldId)
+        return null;
+    const world = await runtime.getWorld(worldId);
+    if (!world)
+        return null;
+    const metadata = (world.metadata ?? {});
+    return { world, metadata };
+}
+export async function resolveCanonicalOwnerIdForMessage(runtime, message) {
+    const configuredOwnerId = resolveCanonicalOwnerId(runtime);
+    if (configuredOwnerId) {
+        return configuredOwnerId;
+    }
+    const resolved = await resolveWorldForMessage(runtime, message);
+    return resolveCanonicalOwnerId(runtime, resolved?.metadata);
+}
+export async function checkSenderRole(runtime, message) {
+    const resolved = await resolveWorldForMessage(runtime, message);
+    if (!resolved)
+        return null;
+    const { world, metadata } = resolved;
+    const entityId = message.entityId;
+    const role = await resolveEntityRole(runtime, world, metadata, entityId, {
+        liveEntityMetadata: getLiveEntityMetadataFromMessage(message),
+        liveEntityId: entityId,
+    });
+    return {
+        entityId,
+        role,
+        isOwner: role === "OWNER",
+        isAdmin: role === "OWNER" || role === "ADMIN",
+        canManageRoles: role === "OWNER" || role === "ADMIN",
+    };
+}
+export async function setEntityRole(runtime, message, targetEntityId, newRole, source = "manual") {
+    const resolved = await resolveWorldForMessage(runtime, message);
+    if (!resolved)
+        throw new Error("Cannot resolve world for role assignment");
+    const { world, metadata } = resolved;
+    if (!metadata.roles)
+        metadata.roles = {};
+    metadata.roleSources ??= {};
+    metadata.roles[targetEntityId] = newRole;
+    if (newRole === "GUEST") {
+        delete metadata.roleSources[targetEntityId];
+    }
+    else {
+        metadata.roleSources[targetEntityId] = source;
+    }
+    world.metadata = metadata;
+    await runtime.updateWorld(world);
+    return { ...metadata.roles };
+}

package/packages/typescript/src/runtime-composition.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Runtime composition: building blocks for creating elizaOS runtimes.
+ *
+ * This module provides a small, composable API so hosts (daemon, cloud, serverless,
+ * milaidy, etc.) can set up runtimes without duplicating adapter creation, plugin
+ * resolution, or settings merge logic.
+ *
+ * **WHY a composition layer:** Different hosts need different flows (e.g. cloud may
+ * use its own adapter pool and skip createRuntimes), but they share the need to
+ * load characters, resolve plugins, create adapters before the runtime, and merge
+ * DB-backed settings. This module composes existing helpers so each host can use
+ * the pieces it needs.
+ *
+ * **Exports:**
+ * - loadCharacters(sources, options?) – JSON file paths (strings) and/or inline CharacterInput; optional `cwd` for relative paths.
+ * - getBasicCapabilitiesSettings(character) – flatten character + env for adapter factories (basic-capabilities only).
+ * - mergeSettingsInto(character, agentRecord) – pure merge of DB agent into character (for custom pipelines).
+ * - createRuntimes(characters, options?) – full pipeline; options carry adapter override, provision, logLevel, etc.
+ *
+ * **Settings divide:** Adapter factories receive only *basic-capabilities* settings (character + env).
+ * Runtime settings from the DB are merged *after* the adapter is created and used when
+ * constructing the runtime. WHY: You cannot load settings from the DB until the adapter
+ * is connected; basic-capabilities settings (e.g. POSTGRES_URL, PGLITE_DATA_DIR) are what you
+ * need to create the adapter in the first place.
+ */
+import type { CharacterInput } from "./character";
+import type { Character, IAgentRuntime, IDatabaseAdapter } from "./types";
+import type { Plugin } from "./types/plugin";
+/**
+ * Flatten character.settings, character.secrets, and env into a single Record<string, string>.
+ * Used when calling adapter factories (Plugin.adapter(agentId, settings)).
+ *
+ * **WHY basic-capabilities-only:** Adapter factories run *before* the database is connected. They
+ * cannot read runtime settings from the DB. Only settings available from character config
+ * and process.env (e.g. POSTGRES_URL, PGLITE_DATA_DIR, MONGODB_URI) are valid here. Runtime
+ * settings (API keys, model prefs, etc.) are merged later from the DB via mergeSettingsInto.
+ *
+ * **Merge order:** env first, then character.settings (excluding nested secrets object),
+ * then character.settings.secrets, then character.secrets. Later sources override earlier
+ * (character overrides env). WHY: Allows env defaults while letting character config override.
+ *
+ * @param character - Character to read settings and secrets from
+ * @param env - Environment record (defaults to process.env)
+ * @returns String-only record suitable for adapter factories
+ */
+export declare function getBasicCapabilitiesSettings(character: Character, env?: NodeJS.ProcessEnv): Record<string, string>;
+/**
+ * Minimal shape of an agent record as returned from the database (e.g. getAgentsByIds).
+ * Used by mergeSettingsInto so callers can pass either a full Agent or a subset with
+ * settings/secrets. WHY loose type: Custom hosts (e.g. cloud) may have their own
+ * agent-like structures; this keeps the merge logic reusable.
+ */
+export interface AgentRecordForMerge {
+    settings?: Record<string, unknown>;
+    secrets?: Record<string, unknown>;
+}
+/**
+ * Merge DB-backed agent settings and secrets into a character (pure, no DB call).
+ * Same merge order as mergeDbSettings in provisioning.ts: DB base, character overrides.
+ *
+ * **WHY exported:** Custom hosts (e.g. cloud with its own adapter pool and caching) may
+ * load agent records themselves and need to apply the same merge semantics without
+ * calling mergeDbSettings (which takes an adapter and does the DB fetch). This function
+ * is the pure merge step only.
+ *
+ * @param character - Character to merge into (not mutated)
+ * @param agentRecord - Agent record from DB (e.g. getAgentsByIds result item), or null
+ * @returns New character with merged settings and secrets
+ */
+export declare function mergeSettingsInto(character: Character, agentRecord: AgentRecordForMerge | null): Character;
+/** Options for {@link loadCharacters}. */
+export interface LoadCharactersOptions {
+    /**
+     * Base directory for resolving relative file paths in `sources`.
+     * Defaults to `process.cwd()`.
+     */
+    cwd?: string;
+}
+/**
+ * Load characters from file paths and/or inline character objects.
+ * String entries are UTF-8 JSON files (`.json`). Uses `parseCharacter` and `importSecretsFromEnv`.
+ *
+ * **WHY accept mixed sources:** Daemons often load from files; programmatic hosts (e.g. cloud,
+ * serverless) may build character config in code. One API supports both.
+ *
+ * @param sources - Relative or absolute JSON file paths, or CharacterInput objects
+ * @param options - Optional `cwd` for relative paths
+ * @returns Validated Character[] (empty array if sources is empty)
+ * @throws If a file path fails to load or an object fails validation (message includes path/details)
+ */
+export declare function loadCharacters(sources: Array<CharacterInput | string>, options?: LoadCharactersOptions): Promise<Character[]>;
+/** Options for {@link createRuntimes} (second argument). */
+export interface CreateRuntimesOptions {
+    /** Override: use this adapter for all characters (skip adapter discovery). WHY: Cloud/custom hosts may manage their own adapter pool. */
+    adapter?: IDatabaseAdapter;
+    /** Extra plugins to include for all characters (merged with character.plugins). WHY: Hosts like milaidy add their own plugin without putting it in every character file. */
+    sharedPlugins?: Plugin[];
+    /** Run provisioning after init: migrations once per unique adapter, then ensureAgentInfrastructure + ensureEmbeddingDimension per runtime. Default false. WHY: Daemons need it once at boot; serverless/ephemeral usually skip. */
+    provision?: boolean;
+    /** Log level for created runtimes. */
+    logLevel?: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+    /** Extra settings applied to each runtime (e.g. MODEL_PROVIDER override). */
+    settings?: Record<string, string | boolean | number>;
+    /** When false, the runtime always responds (e.g. direct chat / harness). Passed to AgentRuntime. */
+    checkShouldRespond?: boolean;
+}
+/**
+ * Create runtimes from characters: resolve plugins once (batch), create adapters from
+ * plugin adapter factory, init adapters (deduped), batch merge DB settings per unique
+ * adapter, create AgentRuntime instances, initialize them, optionally provision.
+ *
+ * **WHY batch where possible:** Resolving plugins once for all characters avoids duplicate
+ * work and keeps dependency order consistent. getAgentsByIds is called once per unique
+ * adapter with all agent IDs for that adapter (not once per character). WHY: Fewer DB
+ * round-trips when multiple characters share the same DB.
+ *
+ * **Adapter discovery:** The first resolved plugin that defines an adapter factory
+ * (Plugin.adapter) is used. If options.adapter is set, that overrides and is used for
+ * all characters. WHY: One adapter per character is the common case; shared override
+ * supports custom pooling. Plugins that only attach the DB in `init` (some `@elizaos/plugin-sql`
+ * builds) expose no `adapter` factory — pass `options.adapter` from `createDatabaseAdapter`
+ * (or equivalent) instead.
+ *
+ * @param characters - Validated characters (e.g. from loadCharacters)
+ * @param options - Optional adapter override, sharedPlugins, provision, logLevel, settings
+ * @returns Initialized IAgentRuntime[] (empty if characters is empty)
+ */
+export declare function createRuntimes(characters: Character[], options?: CreateRuntimesOptions): Promise<IAgentRuntime[]>;
+//# sourceMappingURL=runtime-composition.d.ts.map

package/packages/typescript/src/runtime-composition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-composition.d.ts","sourceRoot":"","sources":["../../../../../typescript/src/runtime-composition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAUlD,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,KAAK,EAAkB,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAQ7D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,4BAA4B,CAC3C,SAAS,EAAE,SAAS,EACpB,GAAG,GAAE,MAAM,CAAC,UAAwB,GAClC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA0CxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAChC,SAAS,EAAE,SAAS,EACpB,WAAW,EAAE,mBAAmB,GAAG,IAAI,GACrC,SAAS,CAuDX;AAeD,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACrC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CACnC,OAAO,EAAE,KAAK,CAAC,cAAc,GAAG,MAAM,CAAC,EACvC,OAAO,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,SAAS,EAAE,CAAC,CAkCtB;AAED,4DAA4D;AAC5D,MAAM,WAAW,qBAAqB;IACrC,yIAAyI;IACzI,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,4KAA4K;IAC5K,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,mOAAmO;IACnO,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IACnE,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC,CAAC;IACrD,oGAAoG;IACpG,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,cAAc,CACnC,UAAU,EAAE,SAAS,EAAE,EACvB,OAAO,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,aAAa,EAAE,CAAC,CA+H1B"}