@voltagent/core 0.1.20 → 0.1.22

package/dist/index.d.ts

@@ -4,6 +4,171 @@ import { SpanExporter } from '@opentelemetry/sdk-trace-base';
 import { ClientCapabilities } from '@modelcontextprotocol/sdk/types.js';
 import { EventEmitter } from 'node:events';
 
+/**
+ * Memory options
+ */
+type MemoryOptions = {
+    /**
+     * Maximum number of messages to store in the database
+     * @default 100
+     */
+    storageLimit?: number;
+};
+/**
+ * Options for filtering messages when retrieving from memory
+ */
+type MessageFilterOptions = {
+    /**
+     * User identifier
+     */
+    userId?: string;
+    /**
+     * Conversation identifier
+     */
+    conversationId?: string;
+    /**
+     * Maximum number of messages to retrieve
+     */
+    limit?: number;
+    /**
+     * Only retrieve messages before this timestamp
+     */
+    before?: number;
+    /**
+     * Only retrieve messages after this timestamp
+     */
+    after?: number;
+    /**
+     * Only retrieve messages with this role
+     */
+    role?: BaseMessage["role"];
+};
+/**
+ * Conversation type
+ */
+type Conversation = {
+    id: string;
+    resourceId: string;
+    title: string;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+};
+/**
+ * Input type for creating a conversation
+ */
+type CreateConversationInput = {
+    id: string;
+    resourceId: string;
+    title: string;
+    metadata: Record<string, unknown>;
+};
+/**
+ * Memory interface for storing and retrieving messages
+ */
+type Memory = {
+    /**
+     * Add a message to memory
+     */
+    addMessage(message: BaseMessage, userId: string, conversationId?: string): Promise<void>;
+    /**
+     * Get messages from memory
+     */
+    getMessages(options: MessageFilterOptions): Promise<BaseMessage[]>;
+    /**
+     * Clear messages from memory
+     */
+    clearMessages(options: {
+        userId: string;
+        conversationId?: string;
+    }): Promise<void>;
+    /**
+     * Create a new conversation
+     */
+    createConversation(conversation: CreateConversationInput): Promise<Conversation>;
+    /**
+     * Get a conversation by ID
+     */
+    getConversation(id: string): Promise<Conversation | null>;
+    /**
+     * Get conversations for a resource
+     */
+    getConversations(resourceId: string): Promise<Conversation[]>;
+    /**
+     * Update a conversation
+     */
+    updateConversation(id: string, updates: Partial<Omit<Conversation, "id" | "createdAt" | "updatedAt">>): Promise<Conversation>;
+    /**
+     * Delete a conversation
+     */
+    deleteConversation(id: string): Promise<void>;
+    /**
+     * Add or update a history entry
+     * @param key Entry ID
+     * @param value Entry data
+     * @param agentId Agent ID for filtering
+     */
+    addHistoryEntry(key: string, value: any, agentId: string): Promise<void>;
+    /**
+     * Update an existing history entry
+     * @param key Entry ID
+     * @param value Updated entry data
+     * @param agentId Agent ID for filtering
+     */
+    updateHistoryEntry(key: string, value: any, agentId: string): Promise<void>;
+    /**
+     * Add a history step
+     * @param key Step ID
+     * @param value Step data
+     * @param historyId Related history entry ID
+     * @param agentId Agent ID for filtering
+     */
+    addHistoryStep(key: string, value: any, historyId: string, agentId: string): Promise<void>;
+    /**
+     * Update a history step
+     * @param key Step ID
+     * @param value Updated step data
+     * @param historyId Related history entry ID
+     * @param agentId Agent ID for filtering
+     */
+    updateHistoryStep(key: string, value: any, historyId: string, agentId: string): Promise<void>;
+    /**
+     * Get a history entry by ID
+     * @param key Entry ID
+     * @returns The history entry or undefined if not found
+     */
+    getHistoryEntry(key: string): Promise<any | undefined>;
+    /**
+     * Get a history step by ID
+     * @param key Step ID
+     * @returns The history step or undefined if not found
+     */
+    getHistoryStep(key: string): Promise<any | undefined>;
+    /**
+     * Get all history entries for an agent
+     * @param agentId Agent ID
+     * @returns Array of all history entries for the agent
+     */
+    getAllHistoryEntriesByAgent(agentId: string): Promise<any[]>;
+    /**
+     * Add a timeline event
+     * This is part of the new immutable event system.
+     * @param key Event ID (UUID)
+     * @param value Timeline event data with immutable structure
+     * @param historyId Related history entry ID
+     * @param agentId Agent ID for filtering
+     */
+    addTimelineEvent(key: string, value: NewTimelineEvent, historyId: string, agentId: string): Promise<void>;
+};
+/**
+ * Memory-specific message type
+ */
+type MemoryMessage = BaseMessage & {
+    id: string;
+    type: "text" | "tool-call" | "tool-result";
+    createdAt: string;
+};
+
 /**
  * Represents a collection of related tools with optional shared instructions.
  */
@@ -214,52 +379,36 @@ declare const createTool: <T extends ToolSchema>(options: ToolOptions<T>) => Too
  */
 declare const tool: <T extends ToolSchema>(options: ToolOptions<T>) => Tool<T>;
 
-type EventStatus = AgentStatus;
-type TimelineEventType = "memory" | "tool" | "agent" | "retriever";
-/**
- * Types for tracked event functionality
- */
-type EventUpdater = (updateOptions: {
-    status?: AgentStatus;
-    data?: Record<string, any>;
-}) => Promise<AgentHistoryEntry | undefined>;
-
 interface ExportAgentHistoryPayload {
     agent_id: string;
     project_id: string;
     history_id: string;
-    timestamp: string;
-    type: string;
+    startTime: string;
+    endTime?: string;
     status: string;
     input: Record<string, unknown>;
     output?: Record<string, unknown>;
     error?: Record<string, unknown>;
     usage?: Record<string, unknown>;
-    agent_snapshot?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
     steps?: HistoryStep[];
     userId?: string;
     conversationId?: string;
+    model?: string;
 }
 interface ExportTimelineEventPayload {
     history_id: string;
     event_id: string;
-    event: TimelineEvent;
+    agent_id: string;
+    event: NewTimelineEvent;
 }
 interface AgentHistoryUpdatableFields {
     input?: AgentHistoryEntry["input"];
     output?: string;
     status?: AgentStatus;
     usage?: UsageInfo;
-    agent_snapshot?: Record<string, unknown>;
-}
-interface TimelineEventUpdatableFields {
-    timestamp?: string;
-    type?: TimelineEventType;
-    name?: string;
-    status?: EventStatus;
-    error?: Record<string, unknown>;
-    input?: Record<string, unknown>;
-    output?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    endTime?: string;
 }
 
 /**
@@ -319,7 +468,7 @@ declare class VoltAgentExporter {
      * @param steps - The steps data to export.
      * @returns A promise that resolves with the response from the telemetry service.
      */
-    exportHistorySteps(project_id: string, history_id: string, steps: HistoryStep[]): Promise<void>;
+    exportHistorySteps(history_id: string, steps: HistoryStep[]): Promise<void>;
     /**
      * Updates specific fields of an agent history entry.
      * @param project_id - The project ID associated with the history entry.
@@ -328,15 +477,7 @@ declare class VoltAgentExporter {
      *                  Should conform to Partial<AgentHistoryUpdatableFields>.
      * @returns A promise that resolves with the response from the telemetry service.
      */
-    updateHistoryEntry(project_id: string, history_id: string, updates: Partial<AgentHistoryUpdatableFields>): Promise<void>;
-    /**
-     * Updates specific fields of a timeline event.
-     * @param history_id - The ID of the parent history entry.
-     * @param event_id - The ID of the timeline event to update.
-     * @param updates - An object containing the fields to update.
-     * @returns A promise that resolves when the operation is complete.
-     */
-    updateTimelineEvent(history_id: string, event_id: string, updates: TimelineEventUpdatableFields): Promise<void>;
+    updateHistoryEntry(history_id: string, updates: Partial<AgentHistoryUpdatableFields>): Promise<void>;
 }
 
 /**
@@ -349,40 +490,41 @@ interface HistoryStep {
     arguments?: Record<string, unknown>;
 }
 /**
- * Timeline event for detailed history
+ * Parameters for adding a history entry
  */
-interface TimelineEvent {
+interface AddEntryParams {
     /**
-     * Unique identifier for the event
+     * Input to the agent
      */
-    id?: string;
+    input: string | Record<string, unknown> | BaseMessage[];
     /**
-     * Timestamp when the event occurred
+     * Output from the agent
      */
-    timestamp: string;
+    output: string;
     /**
-     * Name of the event (e.g., "generating", "tool_calling", "tool_result", etc.)
-     * In the new format, "componentName:operationName" style (e.g.: "memory:getMessages")
+     * Status of the entry
      */
-    name: string;
+    status: AgentStatus;
     /**
-     * ID of the affected Flow node
-     * Added with the new format
+     * Steps taken during generation
      */
-    affectedNodeId?: string;
+    steps?: HistoryStep[];
     /**
-     * Optional additional data specific to the event type
-     * In the new format: { status, input, output, updatedAt etc. }
+     * Additional options for the entry
      */
-    data?: Record<string, unknown>;
+    options?: Partial<Omit<AgentHistoryEntry, "id" | "timestamp" | "input" | "output" | "status" | "steps">>;
     /**
-     * Optional timestamp for when the event was last updated
+     * Optional userId for telemetry
      */
-    updatedAt?: string;
+    userId?: string;
+    /**
+     * Optional conversationId for telemetry
+     */
+    conversationId?: string;
     /**
-     * Type of the event
+     * Optional model name for telemetry
      */
-    type: "memory" | "tool" | "agent" | "retriever";
+    model?: string;
 }
 /**
  * Agent history entry
@@ -395,7 +537,8 @@ interface AgentHistoryEntry {
     /**
      * Timestamp of the entry
      */
-    timestamp: Date;
+    startTime: Date;
+    endTime?: Date;
     /**
      * Original input to the agent
      */
@@ -416,10 +559,7 @@ interface AgentHistoryEntry {
      * Usage information returned by the LLM
      */
     usage?: UsageInfo;
-    /**
-     * Timeline events for detailed agent state history
-     */
-    events?: TimelineEvent[];
+    metadata?: Record<string, unknown>;
     /**
      * Sequence number for the history entry
      */
@@ -472,25 +612,10 @@ declare class HistoryManager {
     /**
      * Add a new history entry
      *
-     * @param input - Input to the agent
-     * @param output - Output from the agent
-     * @param status - Status of the entry
-     * @param steps - Steps taken during generation
-     * @param options - Additional options for the entry
-     * @param agentSnapshot - Optional agent snapshot for telemetry
-     * @param userId - Optional userId for telemetry
-     * @param conversationId - Optional conversationId for telemetry
+     * @param params - Parameters for adding a history entry
      * @returns The new history entry
      */
-    addEntry(input: string | Record<string, unknown> | BaseMessage[], output: string, status: AgentStatus, steps?: HistoryStep[], options?: Partial<Omit<AgentHistoryEntry, "id" | "timestamp" | "input" | "output" | "status" | "steps">>, agentSnapshot?: Record<string, unknown>, userId?: string, conversationId?: string): Promise<AgentHistoryEntry>;
-    /**
-     * Add a timeline event to an existing history entry
-     *
-     * @param entryId - ID of the entry to update
-     * @param event - Timeline event to add
-     * @returns The updated entry or undefined if not found
-     */
-    addEventToEntry(entryId: string, event: TimelineEvent): Promise<AgentHistoryEntry | undefined>;
+    addEntry(params: AddEntryParams): Promise<AgentHistoryEntry>;
     /**
      * Add steps to an existing history entry
      *
@@ -512,12 +637,6 @@ declare class HistoryManager {
      * @returns Array of history entries
      */
     getEntries(): Promise<AgentHistoryEntry[]>;
-    /**
-     * Get the latest history entry
-     *
-     * @returns The latest history entry or undefined if no entries
-     */
-    getLatestEntry(): Promise<AgentHistoryEntry | undefined>;
     /**
      * Clear all history entries
      */
@@ -530,28 +649,17 @@ declare class HistoryManager {
      * @returns The updated entry or undefined if not found
      */
     updateEntry(id: string, updates: Partial<Omit<AgentHistoryEntry, "id" | "timestamp"> & {
-        agent_snapshot?: Record<string, unknown>;
+        metadata?: Record<string, unknown>;
     }>): Promise<AgentHistoryEntry | undefined>;
     /**
-     * Get a tracked event by ID
+     * Persists a timeline event for a history entry.
+     * This is used by the new immutable event system.
      *
      * @param historyId - ID of the history entry
-     * @param eventId - ID of the event or _trackedEventId
-     * @returns The tracked event or undefined if not found
+     * @param event - The NewTimelineEvent object to persist
+     * @returns A promise that resolves to the updated entry or undefined if an error occurs
      */
-    getTrackedEvent(historyId: string, eventId: string): Promise<TimelineEvent | undefined>;
-    /**
-     * Update a tracked event by ID
-     *
-     * @param historyId - ID of the history entry
-     * @param eventId - ID of the event or _trackedEventId
-     * @param updates - Updates to apply to the event
-     * @returns The updated history entry or undefined if not found
-     */
-    updateTrackedEvent(historyId: string, eventId: string, updates: {
-        status?: AgentStatus;
-        data?: Record<string, unknown>;
-    }): Promise<AgentHistoryEntry | undefined>;
+    persistTimelineEvent(historyId: string, event: NewTimelineEvent): Promise<AgentHistoryEntry | undefined>;
 }
 
 /**
@@ -818,8 +926,6 @@ type OperationContext = {
     readonly userContext: Map<string | symbol, any>;
     /** The history entry associated with this operation */
     historyEntry: AgentHistoryEntry;
-    /** Map to store tool event updaters using tool call ID as key */
-    eventUpdaters: Map<string, EventUpdater>;
     /** Whether this operation is still active */
     isActive: boolean;
     /** Parent agent ID if part of a delegation chain */
@@ -1258,182 +1364,180 @@ type LLMProvider<TProvider> = {
 };
 
 /**
- * Memory options
+ * Event statuses
  */
-type MemoryOptions = {
-    /**
-     * Maximum number of messages to store in the database
-     * @default 100
-     */
-    storageLimit?: number;
-};
+type EventStatus = "idle" | "working" | "completed" | "error";
 /**
- * Options for filtering messages when retrieving from memory
+ * Standard event data interface
  */
-type MessageFilterOptions = {
-    /**
-     * User identifier
-     */
-    userId?: string;
-    /**
-     * Conversation identifier
-     */
-    conversationId?: string;
-    /**
-     * Maximum number of messages to retrieve
-     */
-    limit?: number;
-    /**
-     * Only retrieve messages before this timestamp
-     */
-    before?: number;
-    /**
-     * Only retrieve messages after this timestamp
-     */
-    after?: number;
-    /**
-     * Only retrieve messages with this role
-     */
-    role?: BaseMessage["role"];
-};
+interface StandardEventData {
+    status: EventStatus;
+    timestamp: string;
+    input?: unknown;
+    output?: unknown;
+    error?: unknown;
+    errorMessage?: string;
+    metadata?: Record<string, unknown>;
+    sourceAgentId?: string;
+    userContext?: Record<string, unknown>;
+}
 /**
- * Conversation type
+ * Standard timeline event
  */
-type Conversation = {
+interface StandardTimelineEvent {
     id: string;
-    resourceId: string;
-    title: string;
-    metadata: Record<string, unknown>;
-    createdAt: string;
-    updatedAt: string;
-};
+    timestamp: Date;
+    name: string;
+    data: StandardEventData;
+    agentId: string;
+    historyId: string;
+}
 /**
- * Input type for creating a conversation
+ * Defines the main category of a TimelineEvent.
  */
-type CreateConversationInput = {
-    id: string;
-    resourceId: string;
-    title: string;
-    metadata: Record<string, unknown>;
-};
+type TimelineEventCoreType = "agent" | "tool" | "memory" | "retriever";
 /**
- * Memory interface for storing and retrieving messages
+ * Defines the operational status of a TimelineEvent.
+ * 'idle' is added for consistency with frontend initial states.
  */
-type Memory = {
-    /**
-     * Add a message to memory
-     */
-    addMessage(message: BaseMessage, userId: string, conversationId?: string): Promise<void>;
-    /**
-     * Get messages from memory
-     */
-    getMessages(options: MessageFilterOptions): Promise<BaseMessage[]>;
-    /**
-     * Clear messages from memory
-     */
-    clearMessages(options: {
-        userId: string;
-        conversationId?: string;
-    }): Promise<void>;
-    /**
-     * Create a new conversation
-     */
-    createConversation(conversation: CreateConversationInput): Promise<Conversation>;
-    /**
-     * Get a conversation by ID
-     */
-    getConversation(id: string): Promise<Conversation | null>;
-    /**
-     * Get conversations for a resource
-     */
-    getConversations(resourceId: string): Promise<Conversation[]>;
-    /**
-     * Update a conversation
-     */
-    updateConversation(id: string, updates: Partial<Omit<Conversation, "id" | "createdAt" | "updatedAt">>): Promise<Conversation>;
-    /**
-     * Delete a conversation
-     */
-    deleteConversation(id: string): Promise<void>;
-    /**
-     * Add or update a history entry
-     * @param key Entry ID
-     * @param value Entry data
-     * @param agentId Agent ID for filtering
-     */
-    addHistoryEntry(key: string, value: any, agentId: string): Promise<void>;
-    /**
-     * Update an existing history entry
-     * @param key Entry ID
-     * @param value Updated entry data
-     * @param agentId Agent ID for filtering
-     */
-    updateHistoryEntry(key: string, value: any, agentId: string): Promise<void>;
-    /**
-     * Add a history event
-     * @param key Event ID
-     * @param value Event data
-     * @param historyId Related history entry ID
-     * @param agentId Agent ID for filtering
-     */
-    addHistoryEvent(key: string, value: any, historyId: string, agentId: string): Promise<void>;
-    /**
-     * Update a history event
-     * @param key Event ID
-     * @param value Updated event data
-     * @param historyId Related history entry ID
-     * @param agentId Agent ID for filtering
-     */
-    updateHistoryEvent(key: string, value: any, historyId: string, agentId: string): Promise<void>;
-    /**
-     * Add a history step
-     * @param key Step ID
-     * @param value Step data
-     * @param historyId Related history entry ID
-     * @param agentId Agent ID for filtering
-     */
-    addHistoryStep(key: string, value: any, historyId: string, agentId: string): Promise<void>;
-    /**
-     * Update a history step
-     * @param key Step ID
-     * @param value Updated step data
-     * @param historyId Related history entry ID
-     * @param agentId Agent ID for filtering
-     */
-    updateHistoryStep(key: string, value: any, historyId: string, agentId: string): Promise<void>;
-    /**
-     * Get a history entry by ID
-     * @param key Entry ID
-     * @returns The history entry or undefined if not found
-     */
-    getHistoryEntry(key: string): Promise<any | undefined>;
-    /**
-     * Get a history event by ID
-     * @param key Event ID
-     * @returns The history event or undefined if not found
-     */
-    getHistoryEvent(key: string): Promise<any | undefined>;
-    /**
-     * Get a history step by ID
-     * @param key Step ID
-     * @returns The history step or undefined if not found
-     */
-    getHistoryStep(key: string): Promise<any | undefined>;
-    /**
-     * Get all history entries for an agent
-     * @param agentId Agent ID
-     * @returns Array of all history entries for the agent
-     */
-    getAllHistoryEntriesByAgent(agentId: string): Promise<any[]>;
-};
+type TimelineEventCoreStatus = "idle" | "running" | "completed" | "error";
 /**
- * Memory-specific message type
+ * Defines the severity level of a TimelineEvent.
  */
-type MemoryMessage = BaseMessage & {
+type TimelineEventCoreLevel = "DEBUG" | "INFO" | "WARNING" | "ERROR" | "CRITICAL";
+/**
+ * Usage information for tracking resource consumption
+ */
+interface Usage {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+    input?: number;
+    output?: number;
+    total?: number;
+    unit?: "TOKENS" | "CHARACTERS" | "MILLISECONDS" | "SECONDS" | "IMAGES";
+    inputCost?: number;
+    outputCost?: number;
+    totalCost?: number;
+    [key: string]: unknown;
+}
+/**
+ * Base metadata interface with common fields for all timeline events
+ */
+interface BaseEventMetadata {
+    displayName?: string;
     id: string;
-    type: "text" | "tool-call" | "tool-result";
-    createdAt: string;
+    agentId?: string;
+    usage?: Usage;
+}
+interface AgentStartEventMetadata extends BaseEventMetadata {
+    instructions?: string;
+}
+/**
+ * Base interface for all Timeline Events.
+ * The `metadata` field will be typed more specifically using a discriminated union based on `type` and `name`.
+ */
+interface BaseTimelineEvent<M = BaseEventMetadata | null> {
+    id: string;
+    name: string;
+    type: TimelineEventCoreType;
+    startTime: string;
+    endTime?: string | null;
+    status?: TimelineEventCoreStatus;
+    statusMessage?: string | null;
+    level?: TimelineEventCoreLevel;
+    input?: Record<string, unknown> | null;
+    output?: Record<string, unknown> | null;
+    metadata: M;
+    error?: {
+        message: string;
+        stack?: string;
+        code?: string | number;
+        [key: string]: unknown;
+    } | null;
+    version?: string | null;
+    parentEventId?: string | null;
+    traceId: string;
+    tags?: string[] | null;
+}
+type ToolStartEvent = BaseTimelineEvent<BaseEventMetadata> & {
+    name: "tool:start";
+    type: "tool";
+};
+type ToolSuccessEvent = BaseTimelineEvent<BaseEventMetadata> & {
+    name: "tool:success";
+    type: "tool";
+};
+type ToolErrorEvent = BaseTimelineEvent<BaseEventMetadata> & {
+    name: "tool:error";
+    type: "tool";
+    status: "error";
+    level: "ERROR" | "CRITICAL";
+};
+type AgentStartEvent = BaseTimelineEvent<AgentStartEventMetadata> & {
+    name: "agent:start";
+    type: "agent";
+    input: {
+        input: string | BaseMessage[];
+    };
+};
+type AgentSuccessEvent = BaseTimelineEvent<BaseEventMetadata> & {
+    name: "agent:success";
+    type: "agent";
+    status: "completed";
+};
+type AgentErrorEvent = BaseTimelineEvent<BaseEventMetadata> & {
+    name: "agent:error";
+    type: "agent";
+    status: "error";
+    level: "ERROR" | "CRITICAL";
+};
+type MemoryReadStartEvent = BaseTimelineEvent<BaseEventMetadata> & {
+    name: "memory:read_start";
+    type: "memory";
+};
+type MemoryReadSuccessEvent = BaseTimelineEvent<BaseEventMetadata> & {
+    name: "memory:read_success";
+    type: "memory";
+    status: "completed";
+};
+type MemoryReadErrorEvent = BaseTimelineEvent<BaseEventMetadata> & {
+    name: "memory:read_error";
+    type: "memory";
+    status: "error";
+    level: "ERROR" | "CRITICAL";
+};
+type MemoryWriteStartEvent = BaseTimelineEvent<BaseEventMetadata> & {
+    name: "memory:write_start";
+    type: "memory";
 };
+type MemoryWriteSuccessEvent = BaseTimelineEvent<BaseEventMetadata> & {
+    name: "memory:write_success";
+    type: "memory";
+    status: "completed";
+};
+type MemoryWriteErrorEvent = BaseTimelineEvent<BaseEventMetadata> & {
+    name: "memory:write_error";
+    type: "memory";
+    status: "error";
+    level: "ERROR" | "CRITICAL";
+};
+type RetrieverStartEvent = BaseTimelineEvent<BaseEventMetadata> & {
+    name: "retriever:start";
+    type: "retriever";
+};
+type RetrieverSuccessEvent = BaseTimelineEvent<BaseEventMetadata> & {
+    name: "retriever:success";
+    type: "retriever";
+    status: "completed";
+};
+type RetrieverErrorEvent = BaseTimelineEvent<BaseEventMetadata> & {
+    name: "retriever:error";
+    type: "retriever";
+    status: "error";
+    level: "ERROR" | "CRITICAL";
+};
+type NewTimelineEvent = ToolStartEvent | ToolSuccessEvent | ToolErrorEvent | AgentStartEvent | AgentSuccessEvent | AgentErrorEvent | MemoryReadStartEvent | MemoryReadSuccessEvent | MemoryReadErrorEvent | MemoryWriteStartEvent | MemoryWriteSuccessEvent | MemoryWriteErrorEvent | RetrieverStartEvent | RetrieverSuccessEvent | RetrieverErrorEvent;
 
 /**
  * Options for configuring the InMemoryStorage
@@ -1453,6 +1557,8 @@ declare class InMemoryStorage implements Memory {
     private storage;
     private conversations;
     private historyEntries;
+    private historySteps;
+    private timelineEvents;
     private agentHistory;
     private options;
     /**
@@ -1461,15 +1567,19 @@ declare class InMemoryStorage implements Memory {
      */
     constructor(options?: InMemoryStorageOptions);
     /**
-     * Get a history entry by ID
+     * Add a timeline event
+     * @param key Event ID (UUID)
+     * @param value Timeline event data
+     * @param historyId Related history entry ID
+     * @param agentId Agent ID for filtering
      */
-    getHistoryEntry(key: string): Promise<any | undefined>;
+    addTimelineEvent(key: string, value: NewTimelineEvent, historyId: string, agentId: string): Promise<void>;
     /**
-     * Get a history event (not needed for in-memory, but required by interface)
+     * Get a history entry by ID
      */
-    getHistoryEvent(key: string): Promise<any | undefined>;
+    getHistoryEntry(key: string): Promise<any | undefined>;
     /**
-     * Get a history step (not needed for in-memory, but required by interface)
+     * Get a history step by ID
      */
     getHistoryStep(key: string): Promise<any | undefined>;
     /**
@@ -1480,14 +1590,6 @@ declare class InMemoryStorage implements Memory {
      * Update a history entry
      */
     updateHistoryEntry(key: string, value: any, agentId?: string): Promise<void>;
-    /**
-     * Add a history event
-     */
-    addHistoryEvent(key: string, value: any, historyId: string, agentId: string): Promise<void>;
-    /**
-     * Update a history event
-     */
-    updateHistoryEvent(key: string, value: any, historyId: string, agentId: string): Promise<void>;
     /**
      * Add a history step
      */
@@ -1669,22 +1771,6 @@ declare class LibSQLStorage implements Memory {
      * @param agentId Agent ID for filtering
      */
     updateHistoryEntry(key: string, value: any, agentId: string): Promise<void>;
-    /**
-     * Add a history event
-     * @param key Event ID
-     * @param value Event data
-     * @param historyId Related history entry ID
-     * @param agentId Agent ID for filtering
-     */
-    addHistoryEvent(key: string, value: any, historyId: string, agentId: string): Promise<void>;
-    /**
-     * Update a history event
-     * @param key Event ID
-     * @param value Updated event data
-     * @param historyId Related history entry ID
-     * @param agentId Agent ID for filtering
-     */
-    updateHistoryEvent(key: string, value: any, historyId: string, agentId: string): Promise<void>;
     /**
      * Add a history step
      * @param key Step ID
@@ -1701,18 +1787,20 @@ declare class LibSQLStorage implements Memory {
      * @param agentId Agent ID for filtering
      */
     updateHistoryStep(key: string, value: any, historyId: string, agentId: string): Promise<void>;
+    /**
+     * Add a timeline event
+     * @param key Event ID (UUID)
+     * @param value Timeline event data
+     * @param historyId Related history entry ID
+     * @param agentId Agent ID for filtering
+     */
+    addTimelineEvent(key: string, value: NewTimelineEvent, historyId: string, agentId: string): Promise<void>;
     /**
      * Get a history entry by ID
      * @param key Entry ID
      * @returns The history entry or undefined if not found
      */
     getHistoryEntry(key: string): Promise<any | undefined>;
-    /**
-     * Get a history event by ID
-     * @param key Event ID
-     * @returns The history event or undefined if not found
-     */
-    getHistoryEvent(key: string): Promise<any | undefined>;
     /**
      * Get a history step by ID
      * @param key Step ID
@@ -1730,6 +1818,27 @@ declare class LibSQLStorage implements Memory {
      * @returns Array of all history entries for the agent
      */
     getAllHistoryEntriesByAgent(agentId: string): Promise<any[]>;
+    /**
+     * Migrates agent history data from old structure to new structure.
+     * If migration fails, it can be rolled back using the backup mechanism.
+     *
+     * Old database structure:
+     * CREATE TABLE voltagent_memory_agent_history (
+     *   key TEXT PRIMARY KEY,
+     *   value TEXT NOT NULL,
+     *   agent_id TEXT
+     * );
+     */
+    migrateAgentHistoryData(options?: {
+        createBackup?: boolean;
+        restoreFromBackup?: boolean;
+        deleteBackupAfterSuccess?: boolean;
+    }): Promise<{
+        success: boolean;
+        migratedCount?: number;
+        error?: Error;
+        backupCreated?: boolean;
+    }>;
 }
 
 /**
@@ -1753,23 +1862,17 @@ declare class MemoryManager {
      */
     constructor(resourceId: string, memory?: Memory | false, options?: MemoryOptions);
     /**
-     * Create a tracked event for a memory operation
+     * Create and publish a timeline event for memory operations
      *
      * @param context - Operation context with history entry info
-     * @param operationName - Name of the memory operation
-     * @param status - Current status of the memory operation
-     * @param initialData - Initial data for the event
-     * @returns An event updater function
+     * @param event - Timeline event to publish
+     * @returns A promise that resolves when the event is published
      */
-    private createMemoryEvent;
+    private publishTimelineEvent;
     /**
      * Save a message to memory
      */
     saveMessage(context: OperationContext, message: BaseMessage, userId?: string, conversationId?: string, type?: "text" | "tool-call" | "tool-result"): Promise<void>;
-    /**
-     * Get messages from memory
-     */
-    getMessages(context: OperationContext, userId?: string, conversationId?: string, limit?: number): Promise<BaseMessage[]>;
     /**
      * Create a step finish handler to save messages during generation
      */
@@ -1825,16 +1928,6 @@ declare class MemoryManager {
      * @returns A promise that resolves to the updated entry or undefined
      */
     updateHistoryEntry(agentId: string, entryId: string, updates: any): Promise<any | undefined>;
-    /**
-     * Update an existing event in a history entry
-     *
-     * @param agentId - The ID of the agent
-     * @param entryId - The ID of the history entry
-     * @param eventId - The ID of the event to update
-     * @param event - Updated event data
-     * @returns A promise that resolves when the update is complete
-     */
-    updateEventInHistoryEntry(agentId: string, entryId: string, eventId: string, event: any): Promise<any | undefined>;
     /**
      * Add steps to a history entry
      *
@@ -1845,14 +1938,16 @@ declare class MemoryManager {
      */
     addStepsToHistoryEntry(agentId: string, entryId: string, steps: any[]): Promise<any | undefined>;
     /**
-     * Add an event to a history entry
+     * Add a timeline event to a history entry
+     * This method is part of the new immutable event system
      *
      * @param agentId - The ID of the agent
-     * @param entryId - The ID of the entry to update
-     * @param event - Timeline event to add
+     * @param historyId - The ID of the history entry
+     * @param eventId - The ID of the timeline event
+     * @param event - The NewTimelineEvent object
      * @returns A promise that resolves to the updated entry or undefined
      */
-    addEventToHistoryEntry(agentId: string, entryId: string, event: any): Promise<any | undefined>;
+    addTimelineEvent(agentId: string, historyId: string, eventId: string, event: NewTimelineEvent): Promise<any | undefined>;
 }
 
 interface OnStartHookArgs {
@@ -2322,10 +2417,6 @@ declare class Agent<TProvider extends {
      * Update history entry
      */
     private updateHistoryEntry;
-    /**
-     * Standard timeline event creator
-     */
-    private createStandardTimelineEvent;
     /**
      * Fix delete operator usage for better performance
      */
@@ -2440,9 +2531,9 @@ declare const ReasoningStepSchema: z.ZodObject<{
     id: string;
     title: string;
     type: "thought" | "analysis";
-    timestamp: string;
     historyEntryId: string;
     agentId: string;
+    timestamp: string;
     reasoning: string;
     confidence: number;
     action?: string | undefined;
@@ -2452,9 +2543,9 @@ declare const ReasoningStepSchema: z.ZodObject<{
     id: string;
     title: string;
     type: "thought" | "analysis";
-    timestamp: string;
     historyEntryId: string;
     agentId: string;
+    timestamp: string;
     reasoning: string;
     action?: string | undefined;
     result?: string | undefined;
@@ -3158,4 +3249,4 @@ declare class VoltAgent {
     shutdownTelemetry(): Promise<void>;
 }
 
-export { Agent, AgentHistoryEntry, AgentHookOnEnd, AgentHookOnHandoff, AgentHookOnStart, AgentHookOnToolEnd, AgentHookOnToolStart, AgentHooks, AgentOptions, AgentRegistry, AgentResponse, AgentTool, AllowedVariableValue, AnyToolConfig, BaseLLMOptions, BaseMessage, BaseRetriever, BaseTool, BaseToolCall, ClientInfo, Conversation, CreateConversationInput, CreateReasoningToolsOptions, DEFAULT_INSTRUCTIONS, DataContent, ExtractVariableNames, FEW_SHOT_EXAMPLES, FilePart, GenerateObjectOptions, GenerateTextOptions, HTTPServerConfig, ImagePart, InMemoryStorage, InferGenerateObjectResponse, InferGenerateTextResponse, InferMessage, InferModel, InferProviderParams, InferStreamResponse, InferTool, LLMProvider, LibSQLStorage, MCPClient, MCPClientConfig, MCPClientEvents, MCPConfiguration, MCPOptions, MCPServerConfig, MCPToolCall, MCPToolResult, Memory, MemoryManager, MemoryMessage, MemoryOptions, MessageContent, MessageFilterOptions, MessageRole, ModelToolCall, NextAction, NodeType, OnEndHookArgs, OnHandoffHookArgs, OnStartHookArgs, OnToolEndHookArgs, OnToolStartHookArgs, OperationContext, PackageUpdateInfo, PromptCreator, PromptTemplate, ProviderObjectResponse, ProviderObjectStreamResponse, ProviderParams, ProviderResponse, ProviderTextResponse, ProviderTextStreamResponse, ReadableStreamType, ReasoningStep, ReasoningStepSchema, ReasoningToolExecuteOptions, Retriever, RetrieverOptions, RetryConfig, StdioServerConfig, StepChunkCallback, StepFinishCallback, StepWithContent, StreamObjectFinishResult, StreamObjectOnFinishCallback, StreamObjectOptions, StreamTextFinishResult, StreamTextOnFinishCallback, StreamTextOptions, TemplateVariables, TextPart, Tool, ToolCall, ToolErrorInfo, ToolExecuteOptions, ToolExecutionContext, ToolManager, ToolOptions, ToolSchema, ToolStatus, ToolStatusInfo, Toolkit, ToolsetMap, ToolsetWithTools, TransportError, UsageInfo, Voice, VoiceEventData, VoiceEventType, VoiceMetadata, VoiceOptions, VoltAgent, VoltAgentError, VoltAgentExporter, VoltAgentExporterOptions, checkForUpdates, createHooks, createNodeId, createPrompt, createReasoningTools, createRetrieverTool, createTool, createToolkit, VoltAgent as default, getNodeTypeFromNodeId, serializeValueForDebug, tool, updateAllPackages, updateSinglePackage, zodSchemaToJsonUI };
+export { Agent, AgentErrorEvent, AgentHistoryEntry, AgentHookOnEnd, AgentHookOnHandoff, AgentHookOnStart, AgentHookOnToolEnd, AgentHookOnToolStart, AgentHooks, AgentOptions, AgentRegistry, AgentResponse, AgentStartEvent, AgentStartEventMetadata, AgentSuccessEvent, AgentTool, AllowedVariableValue, AnyToolConfig, BaseEventMetadata, BaseLLMOptions, BaseMessage, BaseRetriever, BaseTimelineEvent, BaseTool, BaseToolCall, ClientInfo, Conversation, CreateConversationInput, CreateReasoningToolsOptions, DEFAULT_INSTRUCTIONS, DataContent, EventStatus, ExtractVariableNames, FEW_SHOT_EXAMPLES, FilePart, GenerateObjectOptions, GenerateTextOptions, HTTPServerConfig, ImagePart, InMemoryStorage, InferGenerateObjectResponse, InferGenerateTextResponse, InferMessage, InferModel, InferProviderParams, InferStreamResponse, InferTool, LLMProvider, LibSQLStorage, MCPClient, MCPClientConfig, MCPClientEvents, MCPConfiguration, MCPOptions, MCPServerConfig, MCPToolCall, MCPToolResult, Memory, MemoryManager, MemoryMessage, MemoryOptions, MemoryReadErrorEvent, MemoryReadStartEvent, MemoryReadSuccessEvent, MemoryWriteErrorEvent, MemoryWriteStartEvent, MemoryWriteSuccessEvent, MessageContent, MessageFilterOptions, MessageRole, ModelToolCall, NewTimelineEvent, NextAction, NodeType, OnEndHookArgs, OnHandoffHookArgs, OnStartHookArgs, OnToolEndHookArgs, OnToolStartHookArgs, OperationContext, PackageUpdateInfo, PromptCreator, PromptTemplate, ProviderObjectResponse, ProviderObjectStreamResponse, ProviderParams, ProviderResponse, ProviderTextResponse, ProviderTextStreamResponse, ReadableStreamType, ReasoningStep, ReasoningStepSchema, ReasoningToolExecuteOptions, Retriever, RetrieverErrorEvent, RetrieverOptions, RetrieverStartEvent, RetrieverSuccessEvent, RetryConfig, StandardEventData, StandardTimelineEvent, StdioServerConfig, StepChunkCallback, StepFinishCallback, StepWithContent, StreamObjectFinishResult, StreamObjectOnFinishCallback, StreamObjectOptions, StreamTextFinishResult, StreamTextOnFinishCallback, StreamTextOptions, TemplateVariables, TextPart, TimelineEventCoreLevel, TimelineEventCoreStatus, TimelineEventCoreType, Tool, ToolCall, ToolErrorEvent, ToolErrorInfo, ToolExecuteOptions, ToolExecutionContext, ToolManager, ToolOptions, ToolSchema, ToolStartEvent, ToolStatus, ToolStatusInfo, ToolSuccessEvent, Toolkit, ToolsetMap, ToolsetWithTools, TransportError, Usage, UsageInfo, Voice, VoiceEventData, VoiceEventType, VoiceMetadata, VoiceOptions, VoltAgent, VoltAgentError, VoltAgentExporter, VoltAgentExporterOptions, checkForUpdates, createHooks, createNodeId, createPrompt, createReasoningTools, createRetrieverTool, createTool, createToolkit, VoltAgent as default, getNodeTypeFromNodeId, serializeValueForDebug, tool, updateAllPackages, updateSinglePackage, zodSchemaToJsonUI };