@elizaos/core 1.5.1 → 1.5.2

package/src/types/email.ts

@@ -0,0 +1,162 @@
+import { Service, ServiceType } from './service';
+
+export interface EmailAddress {
+  email: string;
+  name?: string;
+}
+
+export interface EmailAttachment {
+  filename: string;
+  content: Buffer | string;
+  contentType?: string;
+  contentDisposition?: 'attachment' | 'inline';
+  cid?: string;
+}
+
+export interface EmailMessage {
+  from: EmailAddress;
+  to: EmailAddress[];
+  cc?: EmailAddress[];
+  bcc?: EmailAddress[];
+  subject: string;
+  text?: string;
+  html?: string;
+  attachments?: EmailAttachment[];
+  replyTo?: EmailAddress;
+  date?: Date;
+  messageId?: string;
+  references?: string[];
+  inReplyTo?: string;
+  priority?: 'high' | 'normal' | 'low';
+}
+
+export interface EmailSendOptions {
+  retry?: number;
+  timeout?: number;
+  trackOpens?: boolean;
+  trackClicks?: boolean;
+  tags?: string[];
+}
+
+export interface EmailSearchOptions {
+  query?: string;
+  from?: string;
+  to?: string;
+  subject?: string;
+  folder?: string;
+  since?: Date;
+  before?: Date;
+  limit?: number;
+  offset?: number;
+  unread?: boolean;
+  flagged?: boolean;
+  hasAttachments?: boolean;
+}
+
+export interface EmailFolder {
+  name: string;
+  path: string;
+  type: 'inbox' | 'sent' | 'drafts' | 'trash' | 'spam' | 'custom';
+  messageCount?: number;
+  unreadCount?: number;
+  children?: EmailFolder[];
+}
+
+export interface EmailAccount {
+  email: string;
+  name?: string;
+  provider?: string;
+  folders?: EmailFolder[];
+  quotaUsed?: number;
+  quotaLimit?: number;
+}
+
+/**
+ * Interface for email services
+ */
+export abstract class IEmailService extends Service {
+  static override readonly serviceType = ServiceType.EMAIL;
+
+  public readonly capabilityDescription = 'Email sending, receiving, and management capabilities';
+
+  /**
+   * Send an email
+   * @param message - Email message to send
+   * @param options - Send options
+   * @returns Promise resolving to message ID
+   */
+  abstract sendEmail(message: EmailMessage, options?: EmailSendOptions): Promise<string>;
+
+  /**
+   * Get emails from a folder
+   * @param options - Search options
+   * @returns Promise resolving to array of emails
+   */
+  abstract getEmails(options?: EmailSearchOptions): Promise<EmailMessage[]>;
+
+  /**
+   * Get a specific email by ID
+   * @param messageId - Message ID
+   * @returns Promise resolving to email message
+   */
+  abstract getEmail(messageId: string): Promise<EmailMessage>;
+
+  /**
+   * Delete an email
+   * @param messageId - Message ID
+   * @returns Promise resolving when deletion completes
+   */
+  abstract deleteEmail(messageId: string): Promise<void>;
+
+  /**
+   * Mark an email as read/unread
+   * @param messageId - Message ID
+   * @param read - True to mark as read, false for unread
+   * @returns Promise resolving when operation completes
+   */
+  abstract markEmailAsRead(messageId: string, read: boolean): Promise<void>;
+
+  /**
+   * Flag/unflag an email
+   * @param messageId - Message ID
+   * @param flagged - True to flag, false to unflag
+   * @returns Promise resolving when operation completes
+   */
+  abstract flagEmail(messageId: string, flagged: boolean): Promise<void>;
+
+  /**
+   * Move email to a different folder
+   * @param messageId - Message ID
+   * @param folderPath - Destination folder path
+   * @returns Promise resolving when move completes
+   */
+  abstract moveEmail(messageId: string, folderPath: string): Promise<void>;
+
+  /**
+   * Get available folders
+   * @returns Promise resolving to array of folders
+   */
+  abstract getFolders(): Promise<EmailFolder[]>;
+
+  /**
+   * Create a new folder
+   * @param folderName - Name of the folder
+   * @param parentPath - Optional parent folder path
+   * @returns Promise resolving when folder is created
+   */
+  abstract createFolder(folderName: string, parentPath?: string): Promise<void>;
+
+  /**
+   * Get account information
+   * @returns Promise resolving to account details
+   */
+  abstract getAccountInfo(): Promise<EmailAccount>;
+
+  /**
+   * Search emails
+   * @param query - Search query
+   * @param options - Search options
+   * @returns Promise resolving to search results
+   */
+  abstract searchEmails(query: string, options?: EmailSearchOptions): Promise<EmailMessage[]>;
+}

package/src/types/environment.ts

@@ -0,0 +1,129 @@
+import type { Metadata, UUID } from './primitives';
+
+export interface Component {
+  id: UUID;
+  entityId: UUID;
+  agentId: UUID;
+  roomId: UUID;
+  worldId: UUID;
+  sourceEntityId: UUID;
+  type: string;
+  createdAt: number;
+  data: Metadata;
+}
+
+/**
+ * Represents a user account
+ */
+export interface Entity {
+  /** Unique identifier, optional on creation */
+  id?: UUID;
+
+  /** Names of the entity */
+  names: string[];
+
+  /** Additional metadata */
+  metadata: Metadata;
+
+  /** Agent ID this account is related to, for agents should be themselves */
+  agentId: UUID;
+
+  /** Optional array of components */
+  components?: Component[];
+}
+
+/**
+ * Defines roles within a system, typically for access control or permissions, often within a `World`.
+ * - `OWNER`: Represents the highest level of control, typically the creator or primary administrator.
+ * - `ADMIN`: Represents administrative privileges, usually a subset of owner capabilities.
+ * - `NONE`: Indicates no specific role or default, minimal permissions.
+ * These roles are often used in `World.metadata.roles` to assign roles to entities.
+ */
+export enum Role {
+  OWNER = 'OWNER',
+  ADMIN = 'ADMIN',
+  NONE = 'NONE',
+}
+
+export type World = {
+  id: UUID;
+  name?: string;
+  agentId: UUID;
+  serverId: string;
+  metadata?: {
+    ownership?: {
+      ownerId: string;
+    };
+    roles?: {
+      [entityId: UUID]: Role;
+    };
+    [key: string]: unknown;
+  };
+};
+
+export enum ChannelType {
+  SELF = 'SELF', // Messages to self
+  DM = 'DM', // Direct messages between two participants
+  GROUP = 'GROUP', // Group messages with multiple participants
+  VOICE_DM = 'VOICE_DM', // Voice direct messages
+  VOICE_GROUP = 'VOICE_GROUP', // Voice channels with multiple participants
+  FEED = 'FEED', // Social media feed
+  THREAD = 'THREAD', // Threaded conversation
+  WORLD = 'WORLD', // World channel
+  FORUM = 'FORUM', // Forum discussion
+  // Legacy types - kept for backward compatibility but should be replaced
+  API = 'API', // @deprecated - Use DM or GROUP instead
+}
+
+export type Room = {
+  id: UUID;
+  name?: string;
+  agentId?: UUID;
+  source: string;
+  type: ChannelType;
+  channelId?: string;
+  serverId?: string;
+  worldId?: UUID;
+  metadata?: Metadata;
+};
+
+export type RoomMetadata = {
+  [key: string]: unknown;
+};
+
+/**
+ * Room participant with account details
+ */
+export interface Participant {
+  /** Unique identifier */
+  id: UUID;
+
+  /** Associated account */
+  entity: Entity;
+}
+
+/**
+ * Represents a relationship between users
+ */
+export interface Relationship {
+  /** Unique identifier */
+  id: UUID;
+
+  /** First user ID */
+  sourceEntityId: UUID;
+
+  /** Second user ID */
+  targetEntityId: UUID;
+
+  /** Agent ID */
+  agentId: UUID;
+
+  /** Tags for filtering/categorizing relationships */
+  tags: string[];
+
+  /** Additional metadata about the relationship */
+  metadata: Metadata;
+
+  /** Optional creation timestamp */
+  createdAt?: string;
+}

package/src/types/events.ts

@@ -0,0 +1,249 @@
+import type { HandlerCallback } from './components';
+import type { Entity, Room, World } from './environment';
+import type { Memory } from './memory';
+import type { ModelTypeName } from './model';
+import type { Metadata, UUID } from './primitives';
+import type { IAgentRuntime } from './runtime';
+
+/**
+ * Standard event types across all platforms
+ */
+export enum EventType {
+  // World events
+  WORLD_JOINED = 'WORLD_JOINED',
+  WORLD_CONNECTED = 'WORLD_CONNECTED',
+  WORLD_LEFT = 'WORLD_LEFT',
+
+  // Entity events
+  ENTITY_JOINED = 'ENTITY_JOINED',
+  ENTITY_LEFT = 'ENTITY_LEFT',
+  ENTITY_UPDATED = 'ENTITY_UPDATED',
+
+  // Room events
+  ROOM_JOINED = 'ROOM_JOINED',
+  ROOM_LEFT = 'ROOM_LEFT',
+
+  // Message events
+  MESSAGE_RECEIVED = 'MESSAGE_RECEIVED',
+  MESSAGE_SENT = 'MESSAGE_SENT',
+  MESSAGE_DELETED = 'MESSAGE_DELETED',
+
+  // Channel events
+  CHANNEL_CLEARED = 'CHANNEL_CLEARED',
+
+  // Voice events
+  VOICE_MESSAGE_RECEIVED = 'VOICE_MESSAGE_RECEIVED',
+  VOICE_MESSAGE_SENT = 'VOICE_MESSAGE_SENT',
+
+  // Interaction events
+  REACTION_RECEIVED = 'REACTION_RECEIVED',
+  POST_GENERATED = 'POST_GENERATED',
+  INTERACTION_RECEIVED = 'INTERACTION_RECEIVED',
+
+  // Run events
+  RUN_STARTED = 'RUN_STARTED',
+  RUN_ENDED = 'RUN_ENDED',
+  RUN_TIMEOUT = 'RUN_TIMEOUT',
+
+  // Action events
+  ACTION_STARTED = 'ACTION_STARTED',
+  ACTION_COMPLETED = 'ACTION_COMPLETED',
+
+  // Evaluator events
+  EVALUATOR_STARTED = 'EVALUATOR_STARTED',
+  EVALUATOR_COMPLETED = 'EVALUATOR_COMPLETED',
+
+  // Model events
+  MODEL_USED = 'MODEL_USED',
+
+  // Embedding events
+  EMBEDDING_GENERATION_REQUESTED = 'EMBEDDING_GENERATION_REQUESTED',
+  EMBEDDING_GENERATION_COMPLETED = 'EMBEDDING_GENERATION_COMPLETED',
+  EMBEDDING_GENERATION_FAILED = 'EMBEDDING_GENERATION_FAILED',
+}
+
+/**
+ * Platform-specific event type prefix
+ */
+export enum PlatformPrefix {
+  DISCORD = 'DISCORD',
+  TELEGRAM = 'TELEGRAM',
+  TWITTER = 'TWITTER',
+}
+
+/**
+ * Base payload interface for all events
+ */
+export interface EventPayload {
+  runtime: IAgentRuntime;
+  source: string;
+  onComplete?: () => void;
+}
+
+/**
+ * Payload for world-related events
+ */
+export interface WorldPayload extends EventPayload {
+  world: World;
+  rooms: Room[];
+  entities: Entity[];
+}
+
+/**
+ * Payload for entity-related events
+ */
+export interface EntityPayload extends EventPayload {
+  entityId: UUID;
+  worldId?: UUID;
+  roomId?: UUID;
+  metadata?: {
+    orginalId: string;
+    username: string;
+    displayName?: string;
+    [key: string]: any;
+  };
+}
+
+/**
+ * Payload for reaction-related events
+ */
+export interface MessagePayload extends EventPayload {
+  message: Memory;
+  callback?: HandlerCallback;
+  onComplete?: () => void;
+}
+
+/**
+ * Payload for channel cleared events
+ */
+export interface ChannelClearedPayload extends EventPayload {
+  roomId: UUID;
+  channelId: string;
+  memoryCount: number;
+}
+
+/**
+ * Payload for events that are invoked without a message
+ */
+export interface InvokePayload extends EventPayload {
+  worldId: UUID;
+  userId: string;
+  roomId: UUID;
+  callback?: HandlerCallback;
+  source: string;
+}
+
+/**
+ * Run event payload type
+ */
+export interface RunEventPayload extends EventPayload {
+  runId: UUID;
+  messageId: UUID;
+  roomId: UUID;
+  entityId: UUID;
+  startTime: number;
+  status: 'started' | 'completed' | 'timeout';
+  endTime?: number;
+  duration?: number;
+  error?: string;
+}
+
+/**
+ * Action event payload type
+ */
+export interface ActionEventPayload extends EventPayload {
+  actionId: UUID;
+  actionName: string;
+  startTime?: number;
+  completed?: boolean;
+  error?: Error;
+}
+
+/**
+ * Evaluator event payload type
+ */
+export interface EvaluatorEventPayload extends EventPayload {
+  evaluatorId: UUID;
+  evaluatorName: string;
+  startTime?: number;
+  completed?: boolean;
+  error?: Error;
+}
+
+/**
+ * Model event payload type
+ */
+export interface ModelEventPayload extends EventPayload {
+  provider: string;
+  type: ModelTypeName;
+  prompt: string;
+  tokens?: {
+    prompt: number;
+    completion: number;
+    total: number;
+  };
+}
+
+/**
+ * Payload for embedding generation events
+ */
+export interface EmbeddingGenerationPayload extends EventPayload {
+  memory: Memory;
+  priority?: 'high' | 'normal' | 'low';
+  retryCount?: number;
+  maxRetries?: number;
+  embedding?: number[];
+  error?: any;
+}
+
+export type MessageReceivedHandlerParams = {
+  runtime: IAgentRuntime;
+  message: Memory;
+  callback: HandlerCallback;
+  onComplete?: () => void;
+};
+
+/**
+ * Maps event types to their corresponding payload types
+ */
+export interface EventPayloadMap {
+  [EventType.WORLD_JOINED]: WorldPayload;
+  [EventType.WORLD_CONNECTED]: WorldPayload;
+  [EventType.WORLD_LEFT]: WorldPayload;
+  [EventType.ENTITY_JOINED]: EntityPayload;
+  [EventType.ENTITY_LEFT]: EntityPayload;
+  [EventType.ENTITY_UPDATED]: EntityPayload;
+  [EventType.MESSAGE_RECEIVED]: MessagePayload;
+  [EventType.MESSAGE_SENT]: MessagePayload;
+  [EventType.MESSAGE_DELETED]: MessagePayload;
+  [EventType.CHANNEL_CLEARED]: ChannelClearedPayload;
+  [EventType.REACTION_RECEIVED]: MessagePayload;
+  [EventType.POST_GENERATED]: InvokePayload;
+  [EventType.INTERACTION_RECEIVED]: MessagePayload;
+  [EventType.RUN_STARTED]: RunEventPayload;
+  [EventType.RUN_ENDED]: RunEventPayload;
+  [EventType.RUN_TIMEOUT]: RunEventPayload;
+  [EventType.ACTION_STARTED]: ActionEventPayload;
+  [EventType.ACTION_COMPLETED]: ActionEventPayload;
+  [EventType.EVALUATOR_STARTED]: EvaluatorEventPayload;
+  [EventType.EVALUATOR_COMPLETED]: EvaluatorEventPayload;
+  [EventType.MODEL_USED]: ModelEventPayload;
+  [EventType.EMBEDDING_GENERATION_REQUESTED]: EmbeddingGenerationPayload;
+  [EventType.EMBEDDING_GENERATION_COMPLETED]: EmbeddingGenerationPayload;
+  [EventType.EMBEDDING_GENERATION_FAILED]: EmbeddingGenerationPayload;
+}
+
+/**
+ * Event handler function type
+ */
+export type EventHandler<T extends keyof EventPayloadMap> = (
+  payload: EventPayloadMap[T]
+) => Promise<void>;
+
+/**
+ * Defines a more specific type for event handlers, expecting an `Metadata`.
+ * This aims to improve upon generic 'any' type handlers, providing a clearer contract
+ * for functions that respond to events emitted within the agent runtime (see `emitEvent` in `AgentRuntime`).
+ * Handlers can be synchronous or asynchronous.
+ */
+export type TypedEventHandler = (data: Metadata) => Promise<void> | void;

package/src/types/index.ts

@@ -0,0 +1,29 @@
+export * from './primitives';
+export * from './state';
+export * from './memory';
+export * from './knowledge';
+export * from './environment';
+export * from './agent';
+export * from './components';
+export * from './plugin';
+export * from './service';
+export * from './model';
+export * from './database';
+export * from './events';
+export * from './task';
+export * from './tee';
+export * from './runtime';
+export * from './token';
+export * from './messaging';
+export * from './testing';
+export * from './settings';
+export * from './wallet';
+export * from './lp';
+export * from './pdf';
+export * from './video';
+export * from './browser';
+export * from './transcription';
+export * from './web-search';
+export * from './email';
+export * from './message';
+export * from './post';

package/src/types/knowledge.ts

@@ -0,0 +1,65 @@
+import type { MemoryMetadata } from './memory';
+import type { Content, UUID } from './primitives';
+
+/**
+ * Represents a single item of knowledge that can be processed and stored by the agent.
+ * Knowledge items consist of content (text and optional structured data) and metadata.
+ * These items are typically added to the agent's knowledge base via `AgentRuntime.addKnowledge`
+ * and retrieved using `AgentRuntime.getKnowledge`.
+ * The `id` is a unique identifier for the knowledge item, often derived from its source or content.
+ */
+export type KnowledgeItem = {
+  /** A Universally Unique Identifier for this specific knowledge item. */
+  id: UUID;
+  /** The actual content of the knowledge item, which must include text and can have other fields. */
+  content: Content;
+  /** Optional metadata associated with this knowledge item, conforming to `MemoryMetadata`. */
+  metadata?: MemoryMetadata;
+};
+
+/**
+ * Defines the scope or visibility of knowledge items within the agent's system.
+ * - `SHARED`: Indicates knowledge that is broadly accessible, potentially across different agents or users if the system architecture permits.
+ * - `PRIVATE`: Indicates knowledge that is restricted, typically to the specific agent or user context it belongs to.
+ * This enum is used to manage access and retrieval of knowledge items, often in conjunction with `AgentRuntime.addKnowledge` or `AgentRuntime.getKnowledge` scopes.
+ */
+export enum KnowledgeScope {
+  SHARED = 'shared',
+  PRIVATE = 'private',
+}
+
+/**
+ * Specifies prefixes for keys used in caching mechanisms, helping to namespace cached data.
+ * For example, `KNOWLEDGE` might be used to prefix keys for cached knowledge embeddings or processed documents.
+ * This helps in organizing the cache and avoiding key collisions.
+ * Used internally by caching strategies, potentially within `IDatabaseAdapter` cache methods or runtime caching layers.
+ */
+export enum CacheKeyPrefix {
+  KNOWLEDGE = 'knowledge',
+}
+
+/**
+ * Represents an item within a directory listing, specifically for knowledge loading.
+ * When an agent's `Character.knowledge` configuration includes a directory, this type
+ * is used to specify the path to that directory and whether its contents should be treated as shared.
+ * - `directory`: The path to the directory containing knowledge files.
+ * - `shared`: An optional boolean (defaults to false) indicating if the knowledge from this directory is considered shared or private.
+ */
+export interface DirectoryItem {
+  /** The path to the directory containing knowledge files. */
+  directory: string;
+  /** If true, knowledge from this directory is considered shared; otherwise, it's private. Defaults to false. */
+  shared?: boolean;
+}
+
+/**
+ * Represents a row structure, typically from a database query related to text chunking or processing.
+ * This interface is quite minimal and seems to be a placeholder or a base for more specific chunk-related types.
+ * The `id` would be the unique identifier for the chunk.
+ * It might be used when splitting large documents into smaller, manageable pieces for embedding or analysis.
+ */
+export interface ChunkRow {
+  /** The unique identifier for this chunk of text. */
+  id: string;
+  // Add other properties if needed
+}