@elizaos/core 1.5.0 → 1.5.2

package/src/types/browser.ts

@@ -0,0 +1,145 @@
+import { Service, ServiceType } from './service';
+
+export interface BrowserNavigationOptions {
+  timeout?: number;
+  waitUntil?: 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
+  viewport?: {
+    width: number;
+    height: number;
+  };
+  userAgent?: string;
+  headers?: Record<string, string>;
+}
+
+export interface ScreenshotOptions {
+  fullPage?: boolean;
+  clip?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  format?: 'png' | 'jpeg' | 'webp';
+  quality?: number;
+  omitBackground?: boolean;
+}
+
+export interface ElementSelector {
+  selector: string;
+  text?: string;
+  timeout?: number;
+}
+
+export interface ExtractedContent {
+  text: string;
+  html: string;
+  links: Array<{
+    url: string;
+    text: string;
+  }>;
+  images: Array<{
+    src: string;
+    alt?: string;
+  }>;
+  title?: string;
+  metadata?: Record<string, string>;
+}
+
+export interface ClickOptions {
+  timeout?: number;
+  force?: boolean;
+  waitForNavigation?: boolean;
+}
+
+export interface TypeOptions {
+  delay?: number;
+  timeout?: number;
+  clear?: boolean;
+}
+
+/**
+ * Interface for browser automation services
+ */
+export abstract class IBrowserService extends Service {
+  static override readonly serviceType = ServiceType.BROWSER;
+
+  public readonly capabilityDescription = 'Web browser automation and scraping capabilities';
+
+  /**
+   * Navigate to a URL
+   * @param url - URL to navigate to
+   * @param options - Navigation options
+   * @returns Promise resolving when navigation completes
+   */
+  abstract navigate(url: string, options?: BrowserNavigationOptions): Promise<void>;
+
+  /**
+   * Take a screenshot of the current page
+   * @param options - Screenshot options
+   * @returns Promise resolving to screenshot buffer
+   */
+  abstract screenshot(options?: ScreenshotOptions): Promise<Buffer>;
+
+  /**
+   * Extract text and content from the current page
+   * @param selector - Optional CSS selector to extract from specific element
+   * @returns Promise resolving to extracted content
+   */
+  abstract extractContent(selector?: string): Promise<ExtractedContent>;
+
+  /**
+   * Click on an element
+   * @param selector - CSS selector or element selector
+   * @param options - Click options
+   * @returns Promise resolving when click completes
+   */
+  abstract click(selector: string | ElementSelector, options?: ClickOptions): Promise<void>;
+
+  /**
+   * Type text into an input field
+   * @param selector - CSS selector for input field
+   * @param text - Text to type
+   * @param options - Typing options
+   * @returns Promise resolving when typing completes
+   */
+  abstract type(selector: string, text: string, options?: TypeOptions): Promise<void>;
+
+  /**
+   * Wait for an element to appear
+   * @param selector - CSS selector or element selector
+   * @returns Promise resolving when element is found
+   */
+  abstract waitForElement(selector: string | ElementSelector): Promise<void>;
+
+  /**
+   * Evaluate JavaScript in the browser context
+   * @param script - JavaScript code to evaluate
+   * @param args - Arguments to pass to the script
+   * @returns Promise resolving to evaluation result
+   */
+  abstract evaluate<T = any>(script: string, ...args: any[]): Promise<T>;
+
+  /**
+   * Get the current page URL
+   * @returns Promise resolving to current URL
+   */
+  abstract getCurrentUrl(): Promise<string>;
+
+  /**
+   * Go back in browser history
+   * @returns Promise resolving when navigation completes
+   */
+  abstract goBack(): Promise<void>;
+
+  /**
+   * Go forward in browser history
+   * @returns Promise resolving when navigation completes
+   */
+  abstract goForward(): Promise<void>;
+
+  /**
+   * Refresh the current page
+   * @returns Promise resolving when refresh completes
+   */
+  abstract refresh(): Promise<void>;
+}

package/src/types/components.ts

@@ -0,0 +1,184 @@
+import type { Memory } from './memory';
+import type { Content } from './primitives';
+import type { IAgentRuntime } from './runtime';
+import type { State } from './state';
+
+/**
+ * Example content with associated user for demonstration purposes
+ */
+export interface ActionExample {
+  /** User associated with the example */
+  name: string;
+
+  /** Content of the example */
+  content: Content;
+}
+
+/**
+ * Callback function type for handlers
+ */
+export type HandlerCallback = (response: Content, files?: any) => Promise<Memory[]>;
+
+/**
+ * Handler function type for processing messages
+ */
+export type Handler = (
+  runtime: IAgentRuntime,
+  message: Memory,
+  state?: State,
+  options?: { [key: string]: unknown },
+  callback?: HandlerCallback,
+  responses?: Memory[]
+) => Promise<ActionResult | void | undefined>;
+
+/**
+ * Validator function type for actions/evaluators
+ */
+export type Validator = (
+  runtime: IAgentRuntime,
+  message: Memory,
+  state?: State
+) => Promise<boolean>;
+
+/**
+ * Represents an action the agent can perform
+ */
+export interface Action {
+  /** Similar action descriptions */
+  similes?: string[];
+
+  /** Detailed description */
+  description: string;
+
+  /** Example usages */
+  examples?: ActionExample[][];
+
+  /** Handler function */
+  handler: Handler;
+
+  /** Action name */
+  name: string;
+
+  /** Validation function */
+  validate: Validator;
+}
+
+/**
+ * Example for evaluating agent behavior
+ */
+export interface EvaluationExample {
+  /** Evaluation context */
+  prompt: string;
+
+  /** Example messages */
+  messages: Array<ActionExample>;
+
+  /** Expected outcome */
+  outcome: string;
+}
+
+/**
+ * Evaluator for assessing agent responses
+ */
+export interface Evaluator {
+  /** Whether to always run */
+  alwaysRun?: boolean;
+
+  /** Detailed description */
+  description: string;
+
+  /** Similar evaluator descriptions */
+  similes?: string[];
+
+  /** Example evaluations */
+  examples: EvaluationExample[];
+
+  /** Handler function */
+  handler: Handler;
+
+  /** Evaluator name */
+  name: string;
+
+  /** Validation function */
+  validate: Validator;
+}
+
+export interface ProviderResult {
+  values?: {
+    [key: string]: any;
+  };
+  data?: {
+    [key: string]: any;
+  };
+  text?: string;
+}
+
+/**
+ * Provider for external data/services
+ */
+export interface Provider {
+  /** Provider name */
+  name: string;
+
+  /** Description of the provider */
+  description?: string;
+
+  /** Whether the provider is dynamic */
+  dynamic?: boolean;
+
+  /** Position of the provider in the provider list, positive or negative */
+  position?: number;
+
+  /**
+   * Whether the provider is private
+   *
+   * Private providers are not displayed in the regular provider list, they have to be called explicitly
+   */
+  private?: boolean;
+
+  /** Data retrieval function */
+  get: (runtime: IAgentRuntime, message: Memory, state: State) => Promise<ProviderResult>;
+}
+
+/**
+ * Result returned by an action after execution
+ * Used for action chaining and state management
+ */
+export interface ActionResult {
+  /** Optional text description of the result */
+  text?: string;
+
+  /** Values to merge into the state */
+  values?: Record<string, any>;
+
+  /** Data payload containing action-specific results */
+  data?: Record<string, any>;
+
+  /** Whether the action succeeded - defaults to true */
+  success: boolean;
+
+  /** Error information if the action failed */
+  error?: string | Error;
+}
+
+/**
+ * Context provided to actions during execution
+ * Allows actions to access previous results and update state
+ */
+export interface ActionContext {
+  /** Results from previously executed actions in this run */
+  previousResults: ActionResult[];
+
+  /** Get a specific previous result by action name */
+  getPreviousResult?: (actionName: string) => ActionResult | undefined;
+}
+
+/**
+ * Helper function to create ActionResult with proper defaults
+ */
+export function createActionResult(partial: Partial<ActionResult> = {}): ActionResult {
+  return {
+    success: true, // Default to success
+    ...partial,
+  };
+}

package/src/types/database.ts

@@ -0,0 +1,348 @@
+import type { Agent } from './agent';
+import type { Component, Entity, Participant, Relationship, Room, World } from './environment';
+import type { Memory, MemoryMetadata } from './memory';
+import type { Metadata, UUID } from './primitives';
+import type { Task } from './task';
+
+/**
+ * Represents a log entry
+ */
+export interface Log {
+  /** Optional unique identifier */
+  id?: UUID;
+
+  /** Associated entity ID */
+  entityId: UUID;
+
+  /** Associated room ID */
+  roomId?: UUID;
+
+  /** Log body */
+  body: { [key: string]: unknown };
+
+  /** Log type */
+  type: string;
+
+  /** Log creation timestamp */
+  createdAt: Date;
+}
+
+/**
+ * Interface for database operations
+ */
+export interface IDatabaseAdapter {
+  /** Database instance */
+  db: any;
+
+  /** Initialize database connection */
+  initialize(config?: any): Promise<void>;
+
+  /** Initialize database connection */
+  init(): Promise<void>;
+
+  /** Run database migrations */
+  runMigrations(schema?: any, pluginName?: string): Promise<void>;
+
+  /** Check if the database connection is ready */
+  isReady(): Promise<boolean>;
+
+  /** Close database connection */
+  close(): Promise<void>;
+
+  getConnection(): Promise<any>;
+
+  getAgent(agentId: UUID): Promise<Agent | null>;
+
+  /** Get all agents */
+  getAgents(): Promise<Partial<Agent>[]>;
+
+  createAgent(agent: Partial<Agent>): Promise<boolean>;
+
+  updateAgent(agentId: UUID, agent: Partial<Agent>): Promise<boolean>;
+
+  deleteAgent(agentId: UUID): Promise<boolean>;
+
+  ensureEmbeddingDimension(dimension: number): Promise<void>;
+
+  /** Get entity by IDs */
+  getEntitiesByIds(entityIds: UUID[]): Promise<Entity[] | null>;
+
+  /** Get entities for room */
+  getEntitiesForRoom(roomId: UUID, includeComponents?: boolean): Promise<Entity[]>;
+
+  /** Create new entities */
+  createEntities(entities: Entity[]): Promise<boolean>;
+
+  /** Update entity */
+  updateEntity(entity: Entity): Promise<void>;
+
+  /** Get component by ID */
+  getComponent(
+    entityId: UUID,
+    type: string,
+    worldId?: UUID,
+    sourceEntityId?: UUID
+  ): Promise<Component | null>;
+
+  /** Get all components for an entity */
+  getComponents(entityId: UUID, worldId?: UUID, sourceEntityId?: UUID): Promise<Component[]>;
+
+  /** Create component */
+  createComponent(component: Component): Promise<boolean>;
+
+  /** Update component */
+  updateComponent(component: Component): Promise<void>;
+
+  /** Delete component */
+  deleteComponent(componentId: UUID): Promise<void>;
+
+  /** Get memories matching criteria */
+  getMemories(params: {
+    entityId?: UUID;
+    agentId?: UUID;
+    count?: number;
+    unique?: boolean;
+    tableName: string;
+    start?: number;
+    end?: number;
+    roomId?: UUID;
+    worldId?: UUID;
+  }): Promise<Memory[]>;
+
+  getMemoryById(id: UUID): Promise<Memory | null>;
+
+  getMemoriesByIds(ids: UUID[], tableName?: string): Promise<Memory[]>;
+
+  getMemoriesByRoomIds(params: {
+    tableName: string;
+    roomIds: UUID[];
+    limit?: number;
+  }): Promise<Memory[]>;
+
+  getCachedEmbeddings(params: {
+    query_table_name: string;
+    query_threshold: number;
+    query_input: string;
+    query_field_name: string;
+    query_field_sub_name: string;
+    query_match_count: number;
+  }): Promise<{ embedding: number[]; levenshtein_score: number }[]>;
+
+  log(params: {
+    body: { [key: string]: unknown };
+    entityId: UUID;
+    roomId: UUID;
+    type: string;
+  }): Promise<void>;
+
+  getLogs(params: {
+    entityId: UUID;
+    roomId?: UUID;
+    type?: string;
+    count?: number;
+    offset?: number;
+  }): Promise<Log[]>;
+
+  deleteLog(logId: UUID): Promise<void>;
+
+  searchMemories(params: {
+    embedding: number[];
+    match_threshold?: number;
+    count?: number;
+    unique?: boolean;
+    tableName: string;
+    query?: string;
+    roomId?: UUID;
+    worldId?: UUID;
+    entityId?: UUID;
+  }): Promise<Memory[]>;
+
+  createMemory(memory: Memory, tableName: string, unique?: boolean): Promise<UUID>;
+
+  updateMemory(memory: Partial<Memory> & { id: UUID; metadata?: MemoryMetadata }): Promise<boolean>;
+
+  deleteMemory(memoryId: UUID): Promise<void>;
+
+  deleteManyMemories(memoryIds: UUID[]): Promise<void>;
+
+  deleteAllMemories(roomId: UUID, tableName: string): Promise<void>;
+
+  countMemories(roomId: UUID, unique?: boolean, tableName?: string): Promise<number>;
+
+  createWorld(world: World): Promise<UUID>;
+
+  getWorld(id: UUID): Promise<World | null>;
+
+  removeWorld(id: UUID): Promise<void>;
+
+  getAllWorlds(): Promise<World[]>;
+
+  updateWorld(world: World): Promise<void>;
+
+  getRoomsByIds(roomIds: UUID[]): Promise<Room[] | null>;
+
+  createRooms(rooms: Room[]): Promise<UUID[]>;
+
+  deleteRoom(roomId: UUID): Promise<void>;
+
+  deleteRoomsByWorldId(worldId: UUID): Promise<void>;
+
+  updateRoom(room: Room): Promise<void>;
+
+  getRoomsForParticipant(entityId: UUID): Promise<UUID[]>;
+
+  getRoomsForParticipants(userIds: UUID[]): Promise<UUID[]>;
+
+  getRoomsByWorld(worldId: UUID): Promise<Room[]>;
+
+  removeParticipant(entityId: UUID, roomId: UUID): Promise<boolean>;
+
+  getParticipantsForEntity(entityId: UUID): Promise<Participant[]>;
+
+  getParticipantsForRoom(roomId: UUID): Promise<UUID[]>;
+
+  addParticipantsRoom(entityIds: UUID[], roomId: UUID): Promise<boolean>;
+
+  getParticipantUserState(roomId: UUID, entityId: UUID): Promise<'FOLLOWED' | 'MUTED' | null>;
+
+  setParticipantUserState(
+    roomId: UUID,
+    entityId: UUID,
+    state: 'FOLLOWED' | 'MUTED' | null
+  ): Promise<void>;
+
+  /**
+   * Creates a new relationship between two entities.
+   * @param params Object containing the relationship details
+   * @returns Promise resolving to boolean indicating success
+   */
+  createRelationship(params: {
+    sourceEntityId: UUID;
+    targetEntityId: UUID;
+    tags?: string[];
+    metadata?: Metadata;
+  }): Promise<boolean>;
+
+  /**
+   * Updates an existing relationship between two entities.
+   * @param relationship The relationship object with updated data
+   * @returns Promise resolving to void
+   */
+  updateRelationship(relationship: Relationship): Promise<void>;
+
+  /**
+   * Retrieves a relationship between two entities if it exists.
+   * @param params Object containing the entity IDs and agent ID
+   * @returns Promise resolving to the Relationship object or null if not found
+   */
+  getRelationship(params: {
+    sourceEntityId: UUID;
+    targetEntityId: UUID;
+  }): Promise<Relationship | null>;
+
+  /**
+   * Retrieves all relationships for a specific entity.
+   * @param params Object containing the user ID, agent ID and optional tags to filter by
+   * @returns Promise resolving to an array of Relationship objects
+   */
+  getRelationships(params: { entityId: UUID; tags?: string[] }): Promise<Relationship[]>;
+
+  getCache<T>(key: string): Promise<T | undefined>;
+  setCache<T>(key: string, value: T): Promise<boolean>;
+  deleteCache(key: string): Promise<boolean>;
+
+  // Only task instance methods - definitions are in-memory
+  createTask(task: Task): Promise<UUID>;
+  getTasks(params: { roomId?: UUID; tags?: string[]; entityId?: UUID }): Promise<Task[]>;
+  getTask(id: UUID): Promise<Task | null>;
+  getTasksByName(name: string): Promise<Task[]>;
+  updateTask(id: UUID, task: Partial<Task>): Promise<void>;
+  deleteTask(id: UUID): Promise<void>;
+
+  getMemoriesByWorldId(params: {
+    worldId: UUID;
+    count?: number;
+    tableName?: string;
+  }): Promise<Memory[]>;
+}
+
+/**
+ * Result interface for embedding similarity searches
+ */
+export interface EmbeddingSearchResult {
+  embedding: number[];
+  levenshtein_score: number;
+}
+
+/**
+ * Options for memory retrieval operations
+ */
+export interface MemoryRetrievalOptions {
+  roomId: UUID;
+  count?: number;
+  unique?: boolean;
+  start?: number;
+  end?: number;
+  agentId?: UUID;
+}
+
+/**
+ * Options for memory search operations
+ */
+export interface MemorySearchOptions {
+  embedding: number[];
+  match_threshold?: number;
+  count?: number;
+  roomId: UUID;
+  agentId?: UUID;
+  unique?: boolean;
+  metadata?: Partial<MemoryMetadata>;
+}
+
+/**
+ * Options for multi-room memory retrieval
+ */
+export interface MultiRoomMemoryOptions {
+  roomIds: UUID[];
+  limit?: number;
+  agentId?: UUID;
+}
+
+/**
+ * Unified options pattern for memory operations
+ * Provides a simpler, more consistent interface
+ */
+export interface UnifiedMemoryOptions {
+  roomId: UUID;
+  limit?: number; // Unified naming (replacing 'count')
+  agentId?: UUID; // Common optional parameter
+  unique?: boolean; // Common flag for duplication control
+  start?: number; // Pagination start
+  end?: number; // Pagination end
+}
+
+/**
+ * Specialized memory search options
+ */
+export interface UnifiedSearchOptions extends UnifiedMemoryOptions {
+  embedding: number[];
+  similarity?: number; // Clearer name than 'match_threshold'
+}
+
+/**
+ * Represents a generic database connection object.
+ * The actual type of this connection will depend on the specific database adapter implementation
+ * (e.g., a connection pool object for PostgreSQL, a client instance for a NoSQL database).
+ * This `unknown` type serves as a placeholder in the abstract `IDatabaseAdapter`.
+ */
+export type DbConnection = unknown;
+
+// Allowable vector dimensions
+export const VECTOR_DIMS = {
+  SMALL: 384,
+  MEDIUM: 512,
+  LARGE: 768,
+  XL: 1024,
+  XXL: 1536,
+  XXXL: 3072,
+} as const;