Update JSDoc documentation across 62 files

packages/core/__tests__/database.test.ts

@@ -19,6 +19,29 @@ import type {
  * MockDatabaseAdapter class extends DatabaseAdapter class and provides mock implementations for various database operations.
  * @extends {DatabaseAdapter}
  */
+/**
+ * MockDatabaseAdapter class extends DatabaseAdapter class and provides mock implementations for various database operations.
+ * @extends {DatabaseAdapter}
+ */
+/**
+ * Mock Database Adapter class that extends DatabaseAdapter.
+ * 
+ * @class
+ * 
+ * @method init
+ * @returns {Promise<void>} Promise that resolves with void
+ * @description Initializes the database adapter
+ * 
+ * @method close
+ * @returns {Promise<void>} Promise that resolves with void
+ * @description Closes the database adapter
+ * 
+ * @method getEntitiesForRoom
+ * @param {UUID} roomId - The UUID of the room
+ * @param {boolean} [includeComponents] - Optional parameter to include components
+ * @returns {Promise<Entity[]>} Promise that resolves with an array of entities
+ * @description Gets entities for a specific room
+ */
 class MockDatabaseAdapter extends DatabaseAdapter {
   init(): Promise<void> {
     throw new Error('Method not implemented.');
@@ -155,6 +178,200 @@ class MockDatabaseAdapter extends DatabaseAdapter {
    * @throws {Error} - If the method is not implemented.
    */
 
+  getMemoryById(_id: UUID): Promise<Memory | null> {
+    throw new Error('Method not implemented.');
+  }
+  /**
+   * Retrieve memories by their IDs.
+   *
+   * @param {UUID[]} memoryIds - An array of memory IDs to fetch.
+   * @param {string} [_tableName] - Optional table name parameter.
+   * @returns {Promise<Memory[]>} - A Promise that resolves to an array of Memory objects.
+   */
+  async getMemoriesByIds(memoryIds: UUID[], _tableName?: string): Promise<Memory[]> {
+    return memoryIds.map((id) => ({
+      id: id,
+      content: { text: 'Test Memory' },
+      roomId: 'room-id' as UUID,
+      entityId: 'user-id' as UUID,
+    })) as Memory[];
+  }
+  /**
+   * Logs an event for a specific user in a specific room.
+   *
+   * @param {object} _params - The parameters for the log function.
+   * @param {object} _params.body - The data object containing the event details.
+   * @param {string} _params.entityId - The unique identifier of the user performing the event.
+   * @param {string} _params.roomId - The unique identifier of the room where the event occurred.
+   * @param {string} _params.type - The type of event being logged.
+   * @returns {Promise<void>}
+   */
+  log(_params: {
+    body: { [key: string]: unknown };
+    entityId: UUID;
+    roomId: UUID;
+    type: string;
+  }): Promise<void> {
+    throw new Error('Method not implemented.');
+  }
+  /**
+   * Retrieve details of entities in a specific room.
+   *
+   * @param {Object} _params - The parameters for the method.
+   * @param {UUID} _params.roomId - The UUID of the room to retrieve actor details from.
+   * @returns {Promise<Entity[]>} - A promise that resolves to an array of Entity objects representing the details of entities in the specified room.
+   * @throws {Error} - If the method is not implemented.
+   */
+  getEntityDetails(_params: { roomId: UUID }): Promise<Entity[]> {
+    throw new Error('Method not implemented.');
+  }
+  /**
+   * Creates a new memory in the specified table.
+   * @param _memory The memory object to be created.
+   * @param _tableName The name of the table where the memory should be created.
+   * @param _unique... (truncated) 
+class MockDatabaseAdapter extends DatabaseAdapter {
+/**
+ * Initializes the function.
+ * 
+ * @returns A Promise that resolves when the function is initialized.
+ * @throws {Error} If the method is not implemented.
+ */
+  init(): Promise<void> {
+    throw new Error('Method not implemented.');
+  }
+  close(): Promise<void> {
+    throw new Error('Method not implemented.');
+  }
+  getEntitiesForRoom(roomId: UUID, includeComponents?: boolean): Promise<Entity[]> {
+    throw new Error('Method not implemented.');
+  }
+  updateEntity(entity: Entity): Promise<void> {
+    throw new Error('Method not implemented.');
+  }
+  getComponent(
+    entityId: UUID,
+    type: string,
+    worldId?: UUID,
+    sourceEntityId?: UUID
+  ): Promise<Component | null> {
+    throw new Error('Method not implemented.');
+  }
+  getComponents(entityId: UUID, worldId?: UUID, sourceEntityId?: UUID): Promise<Component[]> {
+    throw new Error('Method not implemented.');
+  }
+  createComponent(component: Component): Promise<boolean> {
+    throw new Error('Method not implemented.');
+  }
+  updateComponent(component: Component): Promise<void> {
+    throw new Error('Method not implemented.');
+  }
+  deleteComponent(componentId: UUID): Promise<void> {
+    throw new Error('Method not implemented.');
+  }
+  getLogs(params: {
+    entityId: UUID;
+    roomId?: UUID;
+    type?: string;
+    count?: number;
+    offset?: number;
+  }): Promise<Log[]> {
+    throw new Error('Method not implemented.');
+  }
+  deleteLog(logId: UUID): Promise<void> {
+    throw new Error('Method not implemented.');
+  }
+  getWorld(id: UUID): Promise<World | null> {
+    throw new Error('Method not implemented.');
+  }
+  getAllWorlds(): Promise<World[]> {
+    throw new Error('Method not implemented.');
+  }
+  createWorld(world: World): Promise<UUID> {
+    throw new Error('Method not implemented.');
+  }
+  updateWorld(world: World): Promise<void> {
+    throw new Error('Method not implemented.');
+  }
+  removeWorld(id: UUID): Promise<void> {
+    throw new Error('Method not implemented.');
+  }
+  getRooms(worldId: UUID): Promise<Room[]> {
+    throw new Error('Method not implemented.');
+  }
+  updateRoom(room: Room): Promise<void> {
+    throw new Error('Method not implemented.');
+  }
+  deleteRoom(roomId: UUID): Promise<void> {
+    throw new Error('Method not implemented.');
+  }
+  getParticipantsForEntity(entityId: UUID): Promise<Participant[]> {
+    throw new Error('Method not implemented.');
+  }
+  updateRelationship(params: {
+    sourceEntityId: UUID;
+    targetEntityId: UUID;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+  }): Promise<void> {
+    throw new Error('Method not implemented.');
+  }
+  getAgent(agentId: UUID): Promise<Agent | null> {
+    throw new Error('Method not implemented.');
+  }
+  getAgents(): Promise<Agent[]> {
+    throw new Error('Method not implemented.');
+  }
+  createAgent(agent: Partial<Agent>): Promise<boolean> {
+    throw new Error('Method not implemented.');
+  }
+  updateAgent(agentId: UUID, agent: Partial<Agent>): Promise<boolean> {
+    throw new Error('Method not implemented.');
+  }
+  deleteAgent(agentId: UUID): Promise<boolean> {
+    throw new Error('Method not implemented.');
+  }
+  ensureAgentExists(agent: Partial<Agent>): Promise<void> {
+    throw new Error('Method not implemented.');
+  }
+  ensureEmbeddingDimension(dimension: number): Promise<void> {
+    throw new Error('Method not implemented.');
+  }
+  getCache<T>(key: string): Promise<T | undefined> {
+    throw new Error('Method not implemented.');
+  }
+  setCache<T>(key: string, value: T): Promise<boolean> {
+    throw new Error('Method not implemented.');
+  }
+  deleteCache(key: string): Promise<boolean> {
+    throw new Error('Method not implemented.');
+  }
+  createTask(task: Task): Promise<UUID> {
+    throw new Error('Method not implemented.');
+  }
+  getTasks(params: { roomId?: UUID; tags?: string[] }): Promise<Task[]> {
+    throw new Error('Method not implemented.');
+  }
+  getTask(id: UUID): Promise<Task | null> {
+    throw new Error('Method not implemented.');
+  }
+  getTasksByName(name: string): Promise<Task[]> {
+    throw new Error('Method not implemented.');
+  }
+  updateTask(id: UUID, task: Partial<Task>): Promise<void> {
+    throw new Error('Method not implemented.');
+  }
+  deleteTask(id: UUID): Promise<void> {
+    throw new Error('Method not implemented.');
+  }
+  /**
+   * Asynchronous function to retrieve a Memory object by its unique ID.
+   *
+   * @param {UUID} _id - The unique identifier of the Memory object to retrieve.
+   * @returns {Promise<Memory | null>} - A Promise that resolves to the retrieved Memory object, or null if not found.
+   * @throws {Error} - If the method is not implemented.
+   */
+
   getMemoryById(_id: UUID): Promise<Memory | null> {
     throw new Error('Method not implemented.');
   }

packages/core/__tests__/evaluators.test.ts

@@ -11,6 +11,10 @@ import type { Evaluator, HandlerCallback, IAgentRuntime, Memory, State } from '.
  * Array of mock evaluators.
  * @type {Evaluator[]}
  */
+/**
+ * Array of mock evaluators for testing purposes.
+ * @type {Evaluator[]}
+ */
 const mockEvaluators: Evaluator[] = [
   {
     name: 'Evaluator1',

packages/core/__tests__/mockCharacter.ts

@@ -5,6 +5,18 @@ import type { Character } from '@elizaos/core';
  *
  * @type {Character}
  */
+/**
+ * Mock character object for testing purposes.
+ * 
+ * @type {Character}
+ * @property {string} name - The name of the character.
+ * @property {string} username - The username of the character.
+ * @property {Array} plugins - An array of plugins associated with the character.
+ * @property {object} settings - Object containing character settings.
+ * @property {object} settings.secrets - Object containing any secret settings.
+ * @property {object} settings.voice - Object containing voice settings.
+ * @property {string} settings.voice.model - The voice model used for the character.
+ */
 export const mockCharacter: Character = {
   name: 'Eliza',
   username: 'eliza',

packages/core/__tests__/runtime.test.ts

@@ -7,6 +7,10 @@ import type { Action, IDatabaseAdapter, Memory, UUID } from '../src/types';
  * Mock database adapter for testing purposes.
  * @type {IDatabaseAdapter}
  */
+/**
+ * Mock database adapter for testing purposes.
+ * Implements the IDatabaseAdapter interface with mock functions that return predefined values.
+ */
 const mockDatabaseAdapter: IDatabaseAdapter = {
   db: {},
   init: vi.fn().mockResolvedValue(undefined),

packages/core/src/actions/choice.ts

@@ -43,6 +43,39 @@ import {
  *
  * Make sure to include the ```json``` tags around the JSON object.
  */
+/**
+ * Task: Extract selected task and option from user message
+ *
+ * Available Tasks:
+ * {{#each tasks}}
+ * Task ID: {{taskId}} - {{name}}
+ * Available options:
+ * {{#each options}}
+ * - {{name}}: {{description}}
+ * {{/each}}
+ * - ABORT: Cancel this task
+ * 
+ * {{/each}}
+ *
+ * Recent Messages:
+ * {{recentMessages}}
+ *
+ * Instructions:
+ * 1. Review the user's message and identify which task and option they are selecting
+ * 2. Match against the available tasks and their options, including ABORT
+ * 3. Return the task ID (shortened UUID) and selected option name exactly as listed above
+ * 4. If no clear selection is made, return null for both fields
+ *
+ * Return in JSON format:
+ * ```json
+ * {
+ *   "taskId": "string" | null,
+ *   "selectedOption": "OPTION_NAME" | null
+ * }
+ * ```
+ * 
+ * Make sure to include the ```json``` tags around the JSON object.
+ */
 const optionExtractionTemplate = `# Task: Extract selected task and option from user message
 
 # Available Tasks:

packages/core/src/actions/followRoom.ts

@@ -20,6 +20,10 @@ import {
  * - {{agentName}} has unique insights to contribute and users seem receptive
  * Otherwise, respond with NO.
  */
+/**
+ * Template for determining if the agent should start following a room
+ * @type {string}
+ */
 export const shouldFollowTemplate = `# Task: Decide if {{agentName}} should start following this room, i.e. eagerly participating without explicit mentions.
 
 {{recentMessages}}

packages/core/src/actions/ignore.ts

@@ -11,6 +11,18 @@ import type { Action, ActionExample, IAgentRuntime, Memory } from '../types';
  * @property {Function} handler - Asynchronous function that handles the action logic.
  * @property {ActionExample[][]} examples - Array of examples demonstrating the usage of the IGNORE action.
  */
+/**
+ * Represents an action called 'IGNORE'.
+ *
+ * This action is used to ignore the user in a conversation. It should be used when the user is aggressive, creepy, or when the conversation has naturally ended. 
+ * Avoid using this action if the user has engaged directly or if there is a need to communicate with them. Use IGNORE only when the user should be ignored.
+ *
+ * The action includes a validation function that always returns true and a handler function that also returns true.
+ *
+ * Examples of using the IGNORE action are provided in the 'examples' array. Each example includes messages between two parties and the use of the IGNORE action.
+ *
+ * @typedef {Action} ignoreAction
+ */
 export const ignoreAction: Action = {
   name: 'IGNORE',
   similes: ['STOP_TALKING', 'STOP_CHATTING', 'STOP_CONVERSATION'],

packages/core/src/actions/muteRoom.ts

@@ -16,6 +16,11 @@ import {
  *
  * @type {string}
  */
+/**
+ * Template for deciding if agent should mute a room and stop responding unless explicitly mentioned.
+ * 
+ * @type {string}
+ */
 export const shouldMuteTemplate = `# Task: Decide if {{agentName}} should mute this room and stop responding unless explicitly mentioned.
 
 {{recentMessages}}

packages/core/src/actions/none.ts

@@ -7,6 +7,11 @@ import type { Action, ActionExample, IAgentRuntime, Memory } from '../types';
  *
  * @type {Action}
  */
+/**
+ * Represents an action that responds but performs no additional action.
+ * This is the default behavior if the agent is speaking and not doing anything additional.
+ * @type {Action}
+ */
 export const noneAction: Action = {
   name: 'NONE',
   similes: ['NO_ACTION', 'NO_RESPONSE', 'NO_REACTION'],

packages/core/src/actions/reply.ts

@@ -15,6 +15,11 @@ import {
  *
  * @type {string}
  */
+/**
+ * Template for generating dialog and actions for a character.
+ * 
+ * @type {string}
+ */
 const replyTemplate = `# Task: Generate dialog and actions for the character {{agentName}}.
 {{providers}}
 # Instructions: Write the next message for {{agentName}}.

packages/core/src/actions/roles.ts

@@ -24,6 +24,13 @@ import dedent from 'dedent';
  * @param newRole The new role to assign
  * @returns Whether the role change is allowed
  */
+/**
+ * Determines if a user with a given current role can modify the role of another user to a new role.
+ * @param {Role} currentRole - The current role of the user attempting to modify the other user's role.
+ * @param {Role | null} targetRole - The target user's current role. Can be null if the user does not exist.
+ * @param {Role} newRole - The new role that the current user is attempting to set for the target user.
+ * @returns {boolean} Returns true if the user can modify the role, false otherwise.
+ */
 const canModifyRole = (currentRole: Role, targetRole: Role | null, newRole: Role): boolean => {
   // User's can't change their own role
   if (targetRole === currentRole) return false;