@elizaos/core 2.0.0-alpha.52 → 2.0.0-alpha.53

package/dist/types/memory.d.ts

@@ -0,0 +1,426 @@
+import type { Content, MetadataValue, UUID } from "./primitives";
+import type { BaseMetadata as ProtoBaseMetadata, CustomMetadata as ProtoCustomMetadata, DescriptionMetadata as ProtoDescriptionMetadata, DocumentMetadata as ProtoDocumentMetadata, FragmentMetadata as ProtoFragmentMetadata, Memory as ProtoMemory, MemoryMetadata as ProtoMemoryMetadataType, MessageMetadata as ProtoMessageMetadata } from "./proto.js";
+/**
+ * Memory type enumeration for built-in memory types
+ */
+export type MemoryTypeAlias = string;
+/**
+ * Enumerates the built-in types of memories that can be stored and retrieved.
+ * - `DOCUMENT`: Represents a whole document or a large piece of text.
+ * - `FRAGMENT`: A chunk or segment of a `DOCUMENT`, often created for embedding and search.
+ * - `MESSAGE`: A conversational message, typically from a user or the agent.
+ * - `DESCRIPTION`: A descriptive piece of information, perhaps about an entity or concept.
+ * - `CUSTOM`: For any other type of memory not covered by the built-in types.
+ * This enum is used in `MemoryMetadata` to categorize memories and influences how they are processed or queried.
+ */
+export declare const MemoryType: {
+    readonly DOCUMENT: "document";
+    readonly FRAGMENT: "fragment";
+    readonly MESSAGE: "message";
+    readonly DESCRIPTION: "description";
+    readonly CUSTOM: "custom";
+};
+export type MemoryType = (typeof MemoryType)[keyof typeof MemoryType];
+/**
+ * Defines the scope of a memory, indicating its visibility and accessibility.
+ * - `shared`: The memory is accessible to multiple entities or across different contexts (e.g., a public fact).
+ * - `private`: The memory is specific to a single entity or a private context (e.g., a user's personal preference).
+ * - `room`: The memory is scoped to a specific room or channel.
+ * This is used in `MemoryMetadata` to control how memories are stored and retrieved based on context.
+ */
+export type MemoryScope = "shared" | "private" | "room";
+/**
+ * Base interface for all memory metadata types.
+ * It includes common properties for all memories, such as:
+ * - `type`: The kind of memory (e.g., `MemoryType.MESSAGE`, `MemoryType.DOCUMENT`).
+ * - `source`: An optional string indicating the origin of the memory (e.g., 'discord', 'user_input').
+ * - `sourceId`: An optional UUID linking to a source entity or object.
+ * - `scope`: The visibility scope of the memory (`shared`, `private`, or `room`).
+ * - `timestamp`: An optional numerical timestamp (e.g., milliseconds since epoch) of when the memory was created or relevant.
+ * - `tags`: Optional array of strings for categorizing or filtering memories.
+ * Specific metadata types like `DocumentMetadata` or `MessageMetadata` extend this base.
+ */
+export interface BaseMetadata extends Omit<ProtoBaseMetadata, "$typeName" | "$unknown" | "type" | "scope" | "timestamp"> {
+    type: MemoryTypeAlias;
+    scope?: MemoryScope;
+    timestamp?: number;
+}
+export interface DocumentMetadata extends Omit<ProtoDocumentMetadata, "$typeName" | "$unknown" | "base"> {
+    base?: BaseMetadata;
+    type?: "document";
+}
+export interface FragmentMetadata extends Omit<ProtoFragmentMetadata, "$typeName" | "$unknown" | "base"> {
+    base?: BaseMetadata;
+    documentId: UUID;
+    position: number;
+    type?: "fragment";
+}
+/**
+ * Chat type for message context.
+ */
+export type MessageChatType = "dm" | "private" | "direct" | "group" | "supergroup" | "channel" | "thread" | "forum" | string;
+/**
+ * Sender identity information.
+ */
+export interface SenderIdentity {
+    /** Platform-specific sender ID */
+    id?: string;
+    /** Display name */
+    name?: string;
+    /** Username (without @ prefix) */
+    username?: string;
+    /** User tag (e.g., user#1234 for Discord) */
+    tag?: string;
+    /** E.164 phone number */
+    e164?: string;
+}
+/**
+ * Thread context for threaded conversations.
+ */
+export interface ThreadContext {
+    /** Thread/topic ID */
+    id?: string | number;
+    /** Thread label/name */
+    label?: string;
+    /** Whether this is a forum topic */
+    isForum?: boolean;
+    /** Thread starter message body */
+    starterBody?: string;
+}
+/**
+ * Group context for group chats.
+ */
+export interface GroupContext {
+    /** Group ID */
+    id?: string;
+    /** Group name/subject */
+    name?: string;
+    /** Channel within the group (e.g., #general) */
+    channel?: string;
+    /** Workspace/space name */
+    space?: string;
+    /** Group members (comma-separated or count) */
+    members?: string;
+    /** Group-specific system prompt */
+    systemPrompt?: string;
+}
+/**
+ * Reply context for reply messages.
+ */
+export interface ReplyContext {
+    /** ID of message being replied to (also in Content.inReplyTo) */
+    id?: string;
+    /** Full platform-specific ID */
+    idFull?: string;
+    /** Body of message being replied to */
+    body?: string;
+    /** Sender of message being replied to */
+    sender?: string;
+    /** Whether this is a quote reply */
+    isQuote?: boolean;
+}
+/**
+ * Forwarded message context.
+ */
+export interface ForwardedContext {
+    /** Original sender name */
+    fromName?: string;
+    /** Original sender ID */
+    fromId?: string;
+    /** Original sender username */
+    fromUsername?: string;
+    /** Original sender type */
+    fromType?: string;
+    /** Original chat/channel title */
+    fromTitle?: string;
+    /** Original signature */
+    fromSignature?: string;
+    /** Original chat type */
+    fromChatType?: string;
+    /** Original message ID */
+    originalMessageId?: number;
+    /** Forward date timestamp */
+    date?: number;
+}
+/**
+ * Delivery context for message routing.
+ */
+export interface DeliveryContext {
+    /** Channel/provider for delivery */
+    channel?: string;
+    /** Destination address */
+    to?: string;
+    /** Account ID for multi-account channels */
+    accountId?: string;
+    /** Thread ID for threaded replies */
+    threadId?: string | number;
+}
+/**
+ * Session origin information.
+ */
+export interface SessionOrigin {
+    /** Human-readable label */
+    label?: string;
+    /** Provider name */
+    provider?: string;
+    /** Surface type */
+    surface?: string;
+    /** Chat type */
+    chatType?: MessageChatType;
+    /** Original sender */
+    from?: string;
+    /** Original recipient */
+    to?: string;
+    /** Account ID */
+    accountId?: string;
+    /** Thread ID */
+    threadId?: string | number;
+}
+/**
+ * Model override configuration for a session.
+ */
+export interface SessionModelOverride {
+    /** Provider name override (e.g., "anthropic", "openai") */
+    provider?: string;
+    /** Model name override (e.g., "claude-3-opus", "gpt-5") */
+    model?: string;
+    /** Authentication profile override */
+    authProfile?: string;
+    /** Source of auth profile override */
+    authProfileSource?: "auto" | "user";
+}
+/**
+ * Token usage tracking for a session.
+ */
+export interface SessionUsage {
+    /** Total input tokens consumed */
+    inputTokens: number;
+    /** Total output tokens generated */
+    outputTokens: number;
+    /** Combined total tokens */
+    totalTokens: number;
+    /** Number of context compactions performed */
+    compactionCount: number;
+}
+/**
+ * Skill snapshot for a session.
+ */
+export interface SessionSkillEntry {
+    /** Skill name */
+    name: string;
+    /** Primary environment for the skill */
+    primaryEnv?: string;
+}
+/**
+ * Skills configuration snapshot for a session.
+ */
+export interface SessionSkillsSnapshot {
+    /** Prompt text for skills */
+    prompt: string;
+    /** List of available skills */
+    skills: SessionSkillEntry[];
+}
+/**
+ * Session context providing first-class session state access.
+ * This enables filtering memories by session and accessing session configuration
+ * from within the Eliza runtime pipeline (providers, evaluators, actions).
+ */
+export interface SessionContext {
+    /** Session ID (UUID) - used for transcript files and filtering */
+    sessionId: string;
+    /** Session key for conversation routing (e.g., "agent:123:telegram:+1234567890") */
+    sessionKey: string;
+    /** Parent session key if this session was spawned from another */
+    parentSessionKey?: string;
+    /** Whether this is a newly created session */
+    isNewSession: boolean;
+    /** Timestamp of last session activity */
+    updatedAt: number;
+    /** Human-readable session label */
+    label?: string;
+    /** Model and provider overrides for this session */
+    modelOverride?: SessionModelOverride;
+    /** Thinking level setting ("low", "medium", "high") */
+    thinkingLevel?: string;
+    /** Verbose level setting ("on", "off") */
+    verboseLevel?: string;
+    /** Reasoning level setting */
+    reasoningLevel?: string;
+    /** Send policy for outbound messages */
+    sendPolicy?: "allow" | "deny";
+    /** Token usage tracking */
+    usage?: SessionUsage;
+    /** Skills snapshot for this session */
+    skillsSnapshot?: SessionSkillsSnapshot;
+    /** Chat type for the session */
+    chatType?: MessageChatType;
+    /** Channel identifier */
+    channel?: string;
+    /** Group ID if in a group context */
+    groupId?: string;
+    /** Group channel name */
+    groupChannel?: string;
+    /** Workspace/space identifier */
+    space?: string;
+    /** Session spawned by this key (for sandbox scoping) */
+    spawnedBy?: string;
+    /** Response usage display mode */
+    responseUsage?: "on" | "off" | "tokens" | "full";
+    /** Execution host configuration */
+    execHost?: string;
+    /** Execution security mode */
+    execSecurity?: string;
+    /** Group activation mode */
+    groupActivation?: "mention" | "always";
+}
+export interface MessageMetadata extends Omit<ProtoMessageMetadata, "$typeName" | "$unknown" | "base"> {
+    base?: BaseMetadata;
+    type?: "message";
+    trajectoryStepId?: string;
+    benchmarkContext?: string;
+    /** Session key for conversation routing */
+    sessionKey?: string;
+    /** Parent session key (for spawned/subagent sessions) */
+    parentSessionKey?: string;
+    /** Sender identity */
+    sender?: SenderIdentity;
+    /** Platform/provider name (e.g., "telegram", "discord", "slack") */
+    provider?: string;
+    /** Chat type */
+    chatType?: MessageChatType;
+    /** Account ID for multi-account channels */
+    accountId?: string;
+    /** Thread context */
+    thread?: ThreadContext;
+    /** Group context */
+    group?: GroupContext;
+    /** Reply context (supplements Content.inReplyTo) */
+    reply?: ReplyContext;
+    /** Forwarded message context */
+    forwarded?: ForwardedContext;
+    /** Delivery context for routing responses */
+    delivery?: DeliveryContext;
+    /** Session origin (where the conversation started) */
+    origin?: SessionOrigin;
+    /** Full session context for session-aware processing */
+    session?: SessionContext;
+    /** Whether the agent was mentioned */
+    wasMentioned?: boolean;
+    /** Full platform-specific message ID */
+    messageIdFull?: string;
+    /** Multiple message IDs (for batched messages) */
+    messageIds?: string[];
+    /** First message ID in a batch */
+    messageIdFirst?: string;
+    /** Last message ID in a batch */
+    messageIdLast?: string;
+    /** Telegram-specific metadata */
+    telegram?: {
+        chatId?: string | number;
+        messageId?: string;
+        threadId?: string | number;
+    };
+    /** Discord-specific metadata */
+    discord?: {
+        guildId?: string;
+        channelId?: string;
+        messageId?: string;
+    };
+    /** Slack-specific metadata */
+    slack?: {
+        teamId?: string;
+        channelId?: string;
+        messageTs?: string;
+        threadTs?: string;
+    };
+    /** WhatsApp-specific metadata */
+    whatsapp?: {
+        phoneNumberId?: string;
+        contactId?: string;
+        messageId?: string;
+    };
+    /** Signal-specific metadata */
+    signal?: {
+        groupId?: string;
+        senderId?: string;
+        timestamp?: number;
+    };
+    /** Sticker metadata (Telegram) */
+    sticker?: {
+        emoji?: string;
+        setName?: string;
+        fileId?: string;
+        fileUniqueId?: string;
+        description?: string;
+    };
+    /** Media transcription result */
+    transcript?: string;
+    /** Command source type */
+    commandSource?: string;
+    /** Command target session key */
+    commandTargetSessionKey?: string;
+    /** Gateway client scopes */
+    gatewayClientScopes?: string[];
+    /** Untrusted user-provided context */
+    untrustedContext?: string[];
+    /** Hook-injected messages */
+    hookMessages?: string[];
+}
+export interface DescriptionMetadata extends Omit<ProtoDescriptionMetadata, "$typeName" | "$unknown" | "base"> {
+    base?: BaseMetadata;
+    type?: "description";
+}
+/**
+ * Custom metadata with typed dynamic properties
+ */
+export interface CustomMetadata extends Omit<ProtoCustomMetadata, "$typeName" | "$unknown" | "base"> {
+    base?: BaseMetadata;
+    type?: "custom";
+    /** Custom metadata values - must be JSON-serializable */
+    [key: string]: MetadataValue | MemoryTypeAlias | BaseMetadata | undefined;
+}
+interface MemoryMetadataBase {
+    type?: MemoryTypeAlias;
+    source?: string;
+    scope?: MemoryScope;
+    timestamp?: number;
+}
+export type MemoryMetadata = (DocumentMetadata | FragmentMetadata | MessageMetadata | DescriptionMetadata | CustomMetadata) & MemoryMetadataBase;
+export type ProtoMemoryMetadata = ProtoMemoryMetadataType;
+/**
+ * Represents a stored memory/message
+ */
+export interface Memory extends Omit<ProtoMemory, "$typeName" | "$unknown" | "id" | "createdAt" | "embedding" | "metadata" | "content"> {
+    id?: UUID;
+    createdAt?: number;
+    embedding?: number[];
+    metadata?: MemoryMetadata;
+    content: Content;
+    /**
+     * Session ID for filtering and grouping memories by conversation session.
+     * This is a first-class field to enable efficient querying by session.
+     * Optional for backwards compatibility - memories without sessionId
+     * will continue to work as before.
+     *
+     * Format: UUID string (e.g., "550e8400-e29b-41d4-a716-446655440000")
+     */
+    sessionId?: string;
+    /**
+     * Session key for routing and identification.
+     * This is the full session key used for conversation routing.
+     * Optional for backwards compatibility.
+     *
+     * Format: "agent:<agentId>:<channel>:<destination>" or similar patterns
+     * Examples:
+     *   - "agent:123:telegram:+14155551234"
+     *   - "agent:123:discord:channel:987654321"
+     *   - "cron:daily-summary"
+     */
+    sessionKey?: string;
+}
+/**
+ * Specialized memory type for messages with enhanced type checking
+ */
+export type MessageMemory = Memory;
+export {};
+//# sourceMappingURL=memory.d.ts.map

package/dist/types/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/types/memory.ts"],"names":[],"mappings":"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"}

package/dist/types/message-service.d.ts

@@ -0,0 +1,136 @@
+import type { HandlerCallback } from "./components";
+import type { Room } from "./environment";
+import type { Memory } from "./memory";
+import type { Content, Media, MentionContext, UUID } from "./primitives";
+import type { MessageProcessingMode as ProtoMessageProcessingMode, MessageProcessingOptions as ProtoMessageProcessingOptions, ShouldRespondModelType as ProtoShouldRespondModelType } from "./proto.js";
+import type { IAgentRuntime } from "./runtime";
+import type { State } from "./state";
+/**
+ * Configuration options for message processing
+ */
+export interface MessageProcessingOptions extends Omit<ProtoMessageProcessingOptions, "$typeName" | "$unknown" | "maxRetries" | "timeoutDuration" | "useMultiStep" | "maxMultiStepIterations" | "shouldRespondModel"> {
+    maxRetries?: number;
+    timeoutDuration?: number;
+    useMultiStep?: boolean;
+    maxMultiStepIterations?: number;
+    shouldRespondModel?: ShouldRespondModelType;
+    onStreamChunk?: (chunk: string, messageId?: string) => Promise<void>;
+    /** Signal to abort message processing */
+    abortSignal?: AbortSignal;
+    /**
+     * When true, do not discard responses when a newer message is being processed (same as BOOTSTRAP_KEEP_RESP).
+     * @default resolved from runtime.getSetting("BOOTSTRAP_KEEP_RESP") if not set
+     */
+    keepExistingResponses?: boolean;
+}
+/**
+ * Result of message processing
+ */
+export interface MessageProcessingResult {
+    didRespond: boolean;
+    responseContent?: Content | null;
+    responseMessages: Memory[];
+    state?: State;
+    mode?: MessageProcessingMode;
+    skipEvaluation?: boolean;
+    reason?: string;
+}
+/**
+ * Response decision from the shouldRespond logic
+ */
+export interface ResponseDecision {
+    shouldRespond: boolean;
+    skipEvaluation: boolean;
+    reason: string;
+}
+export type ShouldRespondModelType = ProtoShouldRespondModelType | "small" | "large";
+export type MessageProcessingMode = ProtoMessageProcessingMode | "simple" | "actions" | "none";
+/**
+ * Core interface for message handling service.
+ * This service is responsible for processing incoming messages and generating responses.
+ *
+ * Implementations of this interface control the entire message processing pipeline,
+ * including:
+ * - Message validation and memory creation
+ * - Response decision logic (shouldRespond)
+ * - Single-shot or multi-step processing
+ * - Action execution and evaluation
+ *
+ * @example
+ * ```typescript
+ * // Custom implementation
+ * class CustomMessageService implements IMessageService {
+ *   async handleMessage(runtime, message, callback) {
+ *     // Your custom message handling logic
+ *     return {
+ *       didRespond: true,
+ *       responseContent: { text: "Custom response" },
+ *       responseMessages: [],
+ *       state: {},
+ *       mode: 'simple'
+ *     };
+ *   }
+ *
+ *   shouldRespond(runtime, message, room, mentionContext) {
+ *     // Your custom response decision logic
+ *     return { shouldRespond: true, skipEvaluation: true, reason: "custom" };
+ *   }
+ * }
+ *
+ * // Register in runtime
+ * await runtime.registerService(CustomMessageService);
+ * ```
+ */
+export interface IMessageService {
+    /**
+     * Main entry point for message processing.
+     * This method orchestrates the entire message handling flow.
+     *
+     * @param runtime - The agent runtime instance
+     * @param message - The incoming message to process
+     * @param callback - Callback function to send responses
+     * @param options - Optional processing options
+     * @returns Promise resolving to the processing result
+     */
+    handleMessage(runtime: IAgentRuntime, message: Memory, callback?: HandlerCallback, options?: MessageProcessingOptions): Promise<MessageProcessingResult>;
+    /**
+     * Determines whether the agent should respond to a message.
+     * Uses simple rules for obvious cases (DM, mentions) and defers to LLM for ambiguous cases.
+     *
+     * @param runtime - The agent runtime instance
+     * @param message - The message to evaluate
+     * @param room - The room context (optional)
+     * @param mentionContext - Platform mention/reply context (optional)
+     * @returns Response decision with reasoning
+     */
+    shouldRespond(runtime: IAgentRuntime, message: Memory, room?: Room, mentionContext?: MentionContext): ResponseDecision;
+    /**
+     * Processes attachments in a message (images, documents, etc.)
+     * Generates descriptions for images and extracts text from documents.
+     *
+     * @param runtime - The agent runtime instance
+     * @param attachments - Array of media attachments to process
+     * @returns Promise resolving to processed attachments with descriptions
+     */
+    processAttachments?(runtime: IAgentRuntime, attachments: Media[]): Promise<Media[]>;
+    /**
+     * Deletes a message from the agent's memory.
+     * This method handles the actual deletion logic that was previously in event handlers.
+     *
+     * @param runtime - The agent runtime instance
+     * @param message - The message memory to delete
+     * @returns Promise resolving when deletion is complete
+     */
+    deleteMessage(runtime: IAgentRuntime, message: Memory): Promise<void>;
+    /**
+     * Clears all messages from a channel/room.
+     * This method handles bulk deletion of all message memories in a room.
+     *
+     * @param runtime - The agent runtime instance
+     * @param roomId - The room ID to clear messages from
+     * @param channelId - The original channel ID (for logging)
+     * @returns Promise resolving when channel is cleared
+     */
+    clearChannel(runtime: IAgentRuntime, roomId: UUID, channelId: string): Promise<void>;
+}
+//# sourceMappingURL=message-service.d.ts.map

package/dist/types/message-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-service.d.ts","sourceRoot":"","sources":["../../src/types/message-service.ts"],"names":[],"mappings":"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"}