@voltagent/core 0.1.41 → 0.1.43

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { Span } from '@opentelemetry/api';
+import { Simplify, LiteralUnion } from 'type-fest';
 import { Context } from 'hono';
 import { SpanExporter } from '@opentelemetry/sdk-trace-base';
 import { ClientCapabilities } from '@modelcontextprotocol/sdk/types.js';
@@ -554,6 +555,11 @@ declare class HistoryManager {
      * Optional VoltAgentExporter for sending telemetry data.
      */
     private voltAgentExporter?;
+    /**
+     * Background queue for non-blocking history operations
+     * Uses lower concurrency to preserve operation order when telemetryExporter is enabled
+     */
+    private historyQueue;
     /**
      * Create a new history manager
      *
@@ -572,11 +578,22 @@ declare class HistoryManager {
      * This allows the exporter to be set after the HistoryManager is created.
      */
     setExporter(exporter: VoltAgentExporter): void;
+    /**
+     * Get the VoltAgentExporter instance
+     * @returns The VoltAgentExporter instance or undefined if not configured
+     */
+    getExporter(): VoltAgentExporter | undefined;
     /**
      * Checks if a VoltAgentExporter is configured for this history manager.
      * @returns True if an exporter is configured, false otherwise.
      */
     isExporterConfigured(): boolean;
+    /**
+     * Queue a history operation for background processing
+     * @param operationId Unique identifier for the operation
+     * @param operation The async operation to execute
+     */
+    private queueHistoryOperation;
     /**
      * Add a new history entry
      *
@@ -591,7 +608,7 @@ declare class HistoryManager {
      * @param steps - Steps to add
      * @returns The updated entry or undefined if not found
      */
-    addStepsToEntry(entryId: string, steps: StepWithContent[]): Promise<AgentHistoryEntry | undefined>;
+    addStepsToEntry(entryId: string, steps: StepWithContent[]): void;
     /**
      * Get history entry by ID
      *
@@ -618,11 +635,12 @@ declare class HistoryManager {
      */
     updateEntry(id: string, updates: Partial<Omit<AgentHistoryEntry, "id" | "timestamp"> & {
         metadata?: Record<string, unknown>;
-    }>): Promise<AgentHistoryEntry | undefined>;
+    }>): void;
     /**
      * 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 event - The NewTimelineEvent object to persist
      * @returns A promise that resolves to the updated entry or undefined if an error occurs
@@ -691,46 +709,104 @@ interface VoltAgentExporterOptions {
 declare class VoltAgentExporter {
     private apiClient;
     readonly publicKey: string;
+    /**
+     * Internal queue for all telemetry export operations
+     * Ensures non-blocking exports that don't interfere with event ordering
+     */
+    private telemetryQueue;
     constructor(options: VoltAgentExporterOptions);
     /**
      * Exports a single agent history entry.
      * @param historyEntryData - The agent history data to export.
-     *                           This should conform to ExportAgentHistoryPayload.
-     * @returns A promise that resolves with the response from the telemetry service,
-     *          typically including the ID of the created history entry.
+     * @returns A promise that resolves with the response from the telemetry service.
      */
     exportHistoryEntry(historyEntryData: ExportAgentHistoryPayload): Promise<{
         historyEntryId: string;
     }>;
+    /**
+     * Exports a single agent history entry asynchronously (non-blocking).
+     * Queues the export operation to avoid blocking the calling thread.
+     * @param historyEntryData - The agent history data to export.
+     */
+    exportHistoryEntryAsync(historyEntryData: ExportAgentHistoryPayload): void;
     /**
      * Exports a single timeline event.
-     * (Placeholder for when the 'export-timeline-event' Edge Function is ready)
      * @param timelineEventData - The timeline event data to export.
-     *                            This should conform to ExportTimelineEventPayload.
      * @returns A promise that resolves with the response from the telemetry service.
      */
     exportTimelineEvent(timelineEventData: ExportTimelineEventPayload): Promise<{
         timelineEventId: string;
     }>;
+    /**
+     * Exports a single timeline event asynchronously (non-blocking).
+     * Queues the export operation to avoid blocking the calling thread.
+     * @param timelineEventData - The timeline event data to export.
+     */
+    exportTimelineEventAsync(timelineEventData: ExportTimelineEventPayload): void;
     /**
      * Exports history steps for a specific agent history entry.
-     * @param project_id - The project ID associated with the history entry.
      * @param history_id - The ID of the history entry to export steps for.
      * @param steps - The steps data to export.
-     * @returns A promise that resolves with the response from the telemetry service.
+     * @returns A promise that resolves when the export is complete.
      */
     exportHistorySteps(history_id: string, steps: HistoryStep[]): Promise<void>;
+    /**
+     * Exports history steps for a specific agent history entry asynchronously (non-blocking).
+     * @param history_id - The ID of the history entry to export steps for.
+     * @param steps - The steps data to export.
+     */
+    exportHistoryStepsAsync(history_id: string, steps: HistoryStep[]): void;
     /**
      * Updates specific fields of an agent history entry.
-     * @param project_id - The project ID associated with the history entry.
      * @param history_id - The ID of the history entry to update.
      * @param updates - An object containing the fields to update.
-     *                  Should conform to Partial<AgentHistoryUpdatableFields>.
-     * @returns A promise that resolves with the response from the telemetry service.
+     * @returns A promise that resolves when the update is complete.
      */
     updateHistoryEntry(history_id: string, updates: Partial<AgentHistoryUpdatableFields>): Promise<void>;
+    /**
+     * Updates specific fields of an agent history entry asynchronously (non-blocking).
+     * @param history_id - The ID of the history entry to update.
+     * @param updates - An object containing the fields to update.
+     */
+    updateHistoryEntryAsync(history_id: string, updates: Partial<AgentHistoryUpdatableFields>): void;
 }
 
+type StreamEventType = StreamEvent["type"];
+type StreamEvent = StreamEventTextDelta | StreamEventReasoning | StreamEventSource | StreamEventToolCall | StreamEventToolResult | StreamEventFinish | StreamEventError;
+type StreamEventTextDelta = InferStreamEventBase<TextDeltaStreamPart>;
+type StreamEventReasoning = InferStreamEventBase<ReasoningStreamPart>;
+type StreamEventSource = InferStreamEventBase<SourceStreamPart>;
+type StreamEventToolCall = InferStreamEventBase<ToolCallStreamPart>;
+type StreamEventToolResult = InferStreamEventBase<ToolResultStreamPart>;
+type StreamEventFinish = InferStreamEventBase<FinishStreamPart>;
+type StreamEventError = InferStreamEventBase<ErrorStreamPart>;
+type InferStreamEventBase<TStreamPart extends StreamPart> = {
+    type: TStreamPart["type"];
+    data: InferStreamEventData<TStreamPart> | null;
+    timestamp: string;
+    subAgentId: string;
+    subAgentName: string;
+};
+type InferStreamEventData<TStreamPart extends StreamPart> = Simplify<Omit<TStreamPart, "type" | "subAgentId" | "subAgentName">>;
+
+interface StreamEventForwarderOptions {
+    forwarder?: (event: StreamEvent) => Promise<void>;
+    filterTypes?: LiteralUnion<StreamEventType, string>[];
+    addSubAgentPrefix?: boolean;
+}
+/**
+ * Forwards SubAgent events to a stream with optional filtering and prefixing
+ * @param event - The SubAgent event to forward
+ * @param options - Configuration options for forwarding
+ */
+declare function streamEventForwarder(event: StreamEvent, options?: StreamEventForwarderOptions): Promise<void>;
+/**
+ * Creates a configured streamEventForwarder function
+ * @param options - Configuration options
+ * @returns A configured forwarder function
+ */
+declare function createStreamEventForwarder(options?: StreamEventForwarderOptions): (event: StreamEvent) => Promise<void>;
+
 /**
  * Options object for dynamic value resolution
  */
@@ -983,13 +1059,7 @@ type AgentHandoffOptions = {
      * Optional real-time event forwarder function
      * Used to forward SubAgent events to parent stream in real-time
      */
-    forwardEvent?: (event: {
-        type: string;
-        data: any;
-        timestamp: string;
-        subAgentId: string;
-        subAgentName: string;
-    }) => Promise<void>;
+    forwardEvent?: (event: StreamEvent) => Promise<void>;
 };
 /**
  * Result of a handoff to another agent
@@ -2370,16 +2440,19 @@ declare class MemoryManager {
      * The ID of the resource (agent) that owns this memory manager
      */
     private resourceId;
+    /**
+     * Background queue for memory operations
+     */
+    private backgroundQueue;
     /**
      * Creates a new MemoryManager
      */
     constructor(resourceId: string, memory?: Memory | false, options?: MemoryOptions);
     /**
-     * Create and publish a timeline event for memory operations
+     * Create and publish a timeline event for memory operations using the queue
      *
      * @param context - Operation context with history entry info
      * @param event - Timeline event to publish
-     * @returns A promise that resolves when the event is published
      */
     private publishTimelineEvent;
     /**
@@ -2391,12 +2464,26 @@ declare class MemoryManager {
      */
     createStepFinishHandler(context: OperationContext, userId?: string, conversationId?: string): (() => void) | ((step: StepWithContent) => Promise<void>);
     /**
-     * Prepare conversation context for message generation
+     * Prepare conversation context for message generation (CONTEXT-FIRST OPTIMIZED)
+     * Ensures context is always loaded, optimizes non-critical operations in background
      */
     prepareConversationContext(context: OperationContext, input: string | BaseMessage[], userId?: string, conversationIdParam?: string, contextLimit?: number): Promise<{
         messages: BaseMessage[];
         conversationId: string;
     }>;
+    /**
+     * Handle sequential background operations using the queue
+     * Setup conversation and save input in a single atomic operation
+     */
+    private handleSequentialBackgroundOperations;
+    /**
+     * Ensure conversation exists (background task)
+     */
+    private ensureConversationExists;
+    /**
+     * Save current input (background task)
+     */
+    private saveCurrentInput;
     /**
      * Get the memory instance
      */
@@ -2993,6 +3080,7 @@ declare class Agent<TProvider extends {
      * Helper method to enrich and end an OpenTelemetry span associated with a tool call.
      */
     private _endOtelToolSpan;
+    private publishTimelineEvent;
     /**
      * Create an enhanced fullStream with real-time SubAgent event injection
      */
@@ -3203,23 +3291,23 @@ declare const ReasoningStepSchema: z.ZodObject<{
     title: string;
     id: string;
     historyEntryId: string;
-    agentId: string;
     reasoning: string;
     timestamp: string;
+    agentId: string;
     confidence: number;
-    action?: string | undefined;
     result?: string | undefined;
+    action?: string | undefined;
     next_action?: NextAction | undefined;
 }, {
     type: "thought" | "analysis";
     title: string;
     id: string;
     historyEntryId: string;
-    agentId: string;
     reasoning: string;
     timestamp: string;
-    action?: string | undefined;
+    agentId: string;
     result?: string | undefined;
+    action?: string | undefined;
     next_action?: NextAction | undefined;
     confidence?: number | undefined;
 }>;
@@ -3373,31 +3461,6 @@ declare const updateSinglePackage: (packageName: string, packagePath?: string) =
 declare function safeJsonParse(value: string | null | undefined): any;
 declare function serializeValueForDebug(value: unknown): unknown;
 
-interface SubAgentEvent {
-    type: string;
-    data: any;
-    timestamp: string;
-    subAgentId: string;
-    subAgentName: string;
-}
-interface StreamEventForwarderOptions {
-    forwarder?: (event: any) => Promise<void>;
-    filterTypes?: string[];
-    addSubAgentPrefix?: boolean;
-}
-/**
- * Forwards SubAgent events to a stream with optional filtering and prefixing
- * @param event - The SubAgent event to forward
- * @param options - Configuration options for forwarding
- */
-declare function streamEventForwarder(event: SubAgentEvent, options?: StreamEventForwarderOptions): Promise<void>;
-/**
- * Creates a configured streamEventForwarder function
- * @param options - Configuration options
- * @returns A configured forwarder function
- */
-declare function createStreamEventForwarder(options?: StreamEventForwarderOptions): (event: SubAgentEvent) => Promise<void>;
-
 /**
  * Creates an AgentTool from a retriever, allowing it to be used as a tool in an agent.
  * This is the preferred way to use a retriever as a tool, as it properly maintains the 'this' context.
@@ -3999,4 +4062,4 @@ declare class VoltAgent {
     shutdownTelemetry(): Promise<void>;
 }
 
-export { Agent, AgentErrorEvent, AgentHistoryEntry, AgentHookOnEnd, AgentHookOnHandoff, AgentHookOnStart, AgentHookOnToolEnd, AgentHookOnToolStart, AgentHooks, AgentOptions, AgentRegistry, AgentResponse, AgentStartEvent, AgentStartEventMetadata, AgentSuccessEvent, AgentSuccessEventMetadata, AgentTool, AllowedVariableValue, AnyToolConfig, AsyncIterableStream, BaseEventMetadata, BaseLLMOptions, BaseMessage, BaseRetriever, BaseTimelineEvent, BaseTool, BaseToolCall, ClientInfo, Conversation, ConversationQueryOptions, CreateConversationInput, CreateReasoningToolsOptions, CustomEndpointDefinition, CustomEndpointError, CustomEndpointHandler, DEFAULT_INSTRUCTIONS, DataContent, DynamicValueOptions, ErrorStreamPart, EventStatus, ExtractVariableNames, FEW_SHOT_EXAMPLES, FilePart, FinishStreamPart, GenerateObjectOptions, GenerateTextOptions, HTTPServerConfig, HistoryStatus, HttpMethod, ImagePart, InMemoryStorage, InferGenerateObjectResponse, InferGenerateTextResponse, InferMessage, InferModel, InferProviderParams, InferStreamResponse, InferTool, LLMProvider, LibSQLStorage, MCPClient, MCPClientConfig, MCPClientEvents, MCPConfiguration, MCPOptions, MCPServerConfig, MCPToolCall, MCPToolResult, Memory, MemoryEventMetadata, 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, ReasoningStreamPart, ReasoningToolExecuteOptions, RetrieveOptions, Retriever, RetrieverErrorEvent, RetrieverOptions, RetrieverStartEvent, RetrieverSuccessEvent, SSEServerConfig, ServerOptions, SourceStreamPart, StandardEventData, StandardTimelineEvent, StdioServerConfig, StepChunkCallback, StepFinishCallback, StepWithContent, StreamEventForwarderOptions, StreamObjectFinishResult, StreamObjectOnFinishCallback, StreamObjectOptions, StreamPart, StreamTextFinishResult, StreamTextOnFinishCallback, StreamTextOptions, StreamableHTTPServerConfig, SubAgentEvent, TemplateVariables, TextDeltaStreamPart, TextPart, TimelineEventCoreLevel, TimelineEventCoreStatus, TimelineEventCoreType, Tool, ToolCall, ToolCallStreamPart, ToolErrorEvent, ToolErrorInfo, ToolExecuteOptions, ToolExecutionContext, ToolManager, ToolOptions, ToolResultStreamPart, ToolSchema, ToolStartEvent, ToolStatus, ToolStatusInfo, ToolSuccessEvent, Toolkit, ToolsetMap, ToolsetWithTools, TransportError, Usage, UsageInfo, Voice, VoiceEventData, VoiceEventType, VoiceMetadata, VoiceOptions, VoltAgent, VoltAgentError, VoltAgentExporter, VoltAgentExporterOptions, VoltAgentOptions, checkForUpdates, createAsyncIterableStream, createHooks, createNodeId, createPrompt, createReasoningTools, createRetrieverTool, createStreamEventForwarder, createTool, createToolkit, VoltAgent as default, getNodeTypeFromNodeId, registerCustomEndpoint, registerCustomEndpoints, safeJsonParse, serializeValueForDebug, streamEventForwarder, tool, updateAllPackages, updateSinglePackage, zodSchemaToJsonUI };
+export { Agent, AgentErrorEvent, AgentHistoryEntry, AgentHookOnEnd, AgentHookOnHandoff, AgentHookOnStart, AgentHookOnToolEnd, AgentHookOnToolStart, AgentHooks, AgentOptions, AgentRegistry, AgentResponse, AgentStartEvent, AgentStartEventMetadata, AgentSuccessEvent, AgentSuccessEventMetadata, AgentTool, AllowedVariableValue, AnyToolConfig, AsyncIterableStream, BaseEventMetadata, BaseLLMOptions, BaseMessage, BaseRetriever, BaseTimelineEvent, BaseTool, BaseToolCall, ClientInfo, Conversation, ConversationQueryOptions, CreateConversationInput, CreateReasoningToolsOptions, CustomEndpointDefinition, CustomEndpointError, CustomEndpointHandler, DEFAULT_INSTRUCTIONS, DataContent, DynamicValueOptions, ErrorStreamPart, EventStatus, ExtractVariableNames, FEW_SHOT_EXAMPLES, FilePart, FinishStreamPart, GenerateObjectOptions, GenerateTextOptions, HTTPServerConfig, HistoryStatus, HttpMethod, ImagePart, InMemoryStorage, InferGenerateObjectResponse, InferGenerateTextResponse, InferMessage, InferModel, InferProviderParams, InferStreamResponse, InferTool, LLMProvider, LibSQLStorage, MCPClient, MCPClientConfig, MCPClientEvents, MCPConfiguration, MCPOptions, MCPServerConfig, MCPToolCall, MCPToolResult, Memory, MemoryEventMetadata, 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, ReasoningStreamPart, ReasoningToolExecuteOptions, RetrieveOptions, Retriever, RetrieverErrorEvent, RetrieverOptions, RetrieverStartEvent, RetrieverSuccessEvent, SSEServerConfig, ServerOptions, SourceStreamPart, StandardEventData, StandardTimelineEvent, StdioServerConfig, StepChunkCallback, StepFinishCallback, StepWithContent, StreamEventForwarderOptions, StreamObjectFinishResult, StreamObjectOnFinishCallback, StreamObjectOptions, StreamPart, StreamTextFinishResult, StreamTextOnFinishCallback, StreamTextOptions, StreamableHTTPServerConfig, TemplateVariables, TextDeltaStreamPart, TextPart, TimelineEventCoreLevel, TimelineEventCoreStatus, TimelineEventCoreType, Tool, ToolCall, ToolCallStreamPart, ToolErrorEvent, ToolErrorInfo, ToolExecuteOptions, ToolExecutionContext, ToolManager, ToolOptions, ToolResultStreamPart, ToolSchema, ToolStartEvent, ToolStatus, ToolStatusInfo, ToolSuccessEvent, Toolkit, ToolsetMap, ToolsetWithTools, TransportError, Usage, UsageInfo, Voice, VoiceEventData, VoiceEventType, VoiceMetadata, VoiceOptions, VoltAgent, VoltAgentError, VoltAgentExporter, VoltAgentExporterOptions, VoltAgentOptions, checkForUpdates, createAsyncIterableStream, createHooks, createNodeId, createPrompt, createReasoningTools, createRetrieverTool, createStreamEventForwarder, createTool, createToolkit, VoltAgent as default, getNodeTypeFromNodeId, registerCustomEndpoint, registerCustomEndpoints, safeJsonParse, serializeValueForDebug, streamEventForwarder, tool, updateAllPackages, updateSinglePackage, zodSchemaToJsonUI };