@voltagent/core 0.1.35 → 0.1.37

package/dist/index.d.ts

@@ -520,6 +520,14 @@ interface AgentHistoryEntry {
      */
     usage?: UsageInfo;
     metadata?: Record<string, unknown>;
+    /**
+     * User ID associated with this history entry
+     */
+    userId?: string;
+    /**
+     * Conversation ID associated with this history entry
+     */
+    conversationId?: string;
     /**
      * Sequence number for the history entry
      */
@@ -957,6 +965,17 @@ type AgentHandoffOptions = {
      * Optional user-defined context to be passed from the supervisor agent
      */
     userContext?: Map<string | symbol, unknown>;
+    /**
+     * 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>;
 };
 /**
  * Result of a handoff to another agent
@@ -982,6 +1001,16 @@ interface AgentHandoffResult {
      * Error information if the handoff failed
      */
     error?: Error | string;
+    /**
+     * Stream events captured from sub-agent for forwarding to parent
+     */
+    streamEvents?: Array<{
+        type: string;
+        data: any;
+        timestamp: string;
+        subAgentId: string;
+        subAgentName: string;
+    }>;
 }
 /**
  * Context for a specific agent operation (e.g., one generateText call)
@@ -1195,6 +1224,54 @@ type ProviderTextResponse<TOriginalResponse> = {
      */
     finishReason?: string;
 };
+type TextDeltaStreamPart = {
+    type: "text-delta";
+    textDelta: string;
+    subAgentId?: string;
+    subAgentName?: string;
+};
+type ReasoningStreamPart = {
+    type: "reasoning";
+    reasoning: string;
+    subAgentId?: string;
+    subAgentName?: string;
+};
+type SourceStreamPart = {
+    type: "source";
+    source: string;
+    subAgentId?: string;
+    subAgentName?: string;
+};
+type ToolCallStreamPart = {
+    type: "tool-call";
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, any>;
+    subAgentId?: string;
+    subAgentName?: string;
+};
+type ToolResultStreamPart = {
+    type: "tool-result";
+    toolCallId: string;
+    toolName: string;
+    result: any;
+    subAgentId?: string;
+    subAgentName?: string;
+};
+type FinishStreamPart = {
+    type: "finish";
+    finishReason?: string;
+    usage?: UsageInfo;
+    subAgentId?: string;
+    subAgentName?: string;
+};
+type ErrorStreamPart = {
+    type: "error";
+    error: Error;
+    subAgentId?: string;
+    subAgentName?: string;
+};
+type StreamPart = TextDeltaStreamPart | ReasoningStreamPart | SourceStreamPart | ToolCallStreamPart | ToolResultStreamPart | FinishStreamPart | ErrorStreamPart;
 /**
  * Response type for text streaming operations
  */
@@ -1207,6 +1284,12 @@ type ProviderTextStreamResponse<TOriginalResponse> = {
      * Text stream for consuming the response
      */
     textStream: AsyncIterableStream<string>;
+    /**
+     * Full stream for consuming all events (text, tool calls, reasoning, etc.)
+     * This provides access to the complete stream of events from the provider
+     * Optional - only available in providers that support it
+     */
+    fullStream?: AsyncIterable<StreamPart>;
 };
 /**
  * Response type for object generation operations
@@ -2251,6 +2334,10 @@ declare class LibSQLStorage implements Memory {
      * @param migratedCount Number of records migrated
      */
     private setMigrationFlag;
+    /**
+     * Migrate agent history schema to add userId and conversationId columns
+     */
+    private migrateAgentHistorySchema;
 }
 
 /**
@@ -2868,6 +2955,10 @@ declare class Agent<TProvider extends {
      * Helper method to enrich and end an OpenTelemetry span associated with a tool call.
      */
     private _endOtelToolSpan;
+    /**
+     * Create an enhanced fullStream that includes SubAgent events
+     */
+    private createEnhancedFullStream;
     /**
      * Generate a text response without streaming
      */
@@ -2980,6 +3071,72 @@ declare class CustomEndpointError extends Error {
     constructor(message: string);
 }
 
+/**
+ * Basic type definitions for VoltAgent Core
+ */
+
+/**
+ * Server configuration options for VoltAgent
+ */
+type ServerOptions = {
+    /**
+     * Whether to automatically start the server
+     * @default true
+     */
+    autoStart?: boolean;
+    /**
+     * Port number for the server
+     * @default 3141 (or next available port)
+     */
+    port?: number;
+    /**
+     * Optional flag to enable/disable Swagger UI
+     * By default:
+     * - In development (NODE_ENV !== 'production'): Swagger UI is enabled
+     * - In production (NODE_ENV === 'production'): Swagger UI is disabled
+     */
+    enableSwaggerUI?: boolean;
+    /**
+     * Optional array of custom endpoint definitions to register with the API server
+     */
+    customEndpoints?: CustomEndpointDefinition[];
+};
+/**
+ * VoltAgent constructor options
+ */
+type VoltAgentOptions = {
+    agents: Record<string, Agent<any>>;
+    /**
+     * Server configuration options
+     */
+    server?: ServerOptions;
+    /**
+     * @deprecated Use `server.port` instead
+     */
+    port?: number;
+    /**
+     * @deprecated Use `server.autoStart` instead
+     */
+    autoStart?: boolean;
+    checkDependencies?: boolean;
+    /**
+     * @deprecated Use `server.customEndpoints` instead
+     */
+    customEndpoints?: CustomEndpointDefinition[];
+    /**
+     * @deprecated Use `server.enableSwaggerUI` instead
+     */
+    enableSwaggerUI?: boolean;
+    /**
+     * Optional OpenTelemetry SpanExporter instance or array of instances.
+     * or a VoltAgentExporter instance or array of instances.
+     * If provided, VoltAgent will attempt to initialize and register
+     * a NodeTracerProvider with a BatchSpanProcessor for the given exporter(s).
+     * It's recommended to only provide this in one VoltAgent instance per application process.
+     */
+    telemetryExporter?: (SpanExporter | VoltAgentExporter) | (SpanExporter | VoltAgentExporter)[];
+};
+
 /**
  * Enum defining the next action to take after a reasoning step.
  */
@@ -3009,8 +3166,8 @@ declare const ReasoningStepSchema: z.ZodObject<{
     id: string;
     historyEntryId: string;
     agentId: string;
-    timestamp: string;
     reasoning: string;
+    timestamp: string;
     confidence: number;
     action?: string | undefined;
     result?: string | undefined;
@@ -3021,8 +3178,8 @@ declare const ReasoningStepSchema: z.ZodObject<{
     id: string;
     historyEntryId: string;
     agentId: string;
-    timestamp: string;
     reasoning: string;
+    timestamp: string;
     action?: string | undefined;
     result?: string | undefined;
     next_action?: NextAction | undefined;
@@ -3054,44 +3211,6 @@ type CreateReasoningToolsOptions = {
  */
 declare const createReasoningTools: (options?: CreateReasoningToolsOptions) => Toolkit;
 
-/**
- * Basic type definitions for VoltAgent Core
- */
-/**
- * Retry configuration for error handling
- */
-interface RetryConfig {
-    /**
-     * Maximum number of retry attempts
-     * @default 3
-     */
-    maxRetries?: number;
-    /**
-     * Initial delay between retries in milliseconds
-     * @default 1000
-     */
-    initialDelay?: number;
-    /**
-     * Backoff multiplier for exponential backoff
-     * @default 2
-     */
-    backoffMultiplier?: number;
-    /**
-     * Maximum delay between retries in milliseconds
-     * @default 30000
-     */
-    maxDelay?: number;
-    /**
-     * Callback function called when an error occurs
-     * Return true to retry, false to abort
-     * @param error The error that occurred
-     * @param attempt Current attempt number (1-based)
-     * @param maxRetries Maximum number of retries
-     * @returns Boolean indicating whether to retry
-     */
-    onError?: ((error: Error, attempt: number, maxRetries: number) => boolean | Promise<boolean>) | null;
-}
-
 /**
  * Prompt management utilities for agent prompt tuning
  */
@@ -3216,6 +3335,42 @@ declare const updateSinglePackage: (packageName: string, packagePath?: string) =
 declare function safeJsonParse(value: string | null | undefined): any;
 declare function serializeValueForDebug(value: unknown): unknown;
 
+/**
+ * Utility for merging multiple async streams with event queue integration
+ */
+interface StreamMergerOptions {
+    /**
+     * Polling interval for checking events (in milliseconds)
+     * Default: 16ms (~60fps for smooth UI updates)
+     */
+    pollingInterval?: number;
+    /**
+     * Post-stream polling interval when main stream is finished (in milliseconds)
+     * Default: 10ms
+     */
+    postStreamInterval?: number;
+}
+/**
+ * Creates an enhanced stream that merges an original async iterable with events
+ * from a shared queue, ensuring chronological order and smooth UI updates.
+ *
+ * @param originalStream - The main stream to merge with
+ * @param eventsQueue - Shared array that other sources push events to
+ * @param options - Configuration options for polling intervals
+ * @returns Enhanced async iterable that yields events from both sources
+ */
+declare function createMergedStream<T>(originalStream: AsyncIterable<T>, eventsQueue: T[], options?: StreamMergerOptions): AsyncIterable<T>;
+/**
+ * Helper type for SubAgent events that can be merged into a main stream
+ */
+interface SubAgentEvent {
+    type: string;
+    data: any;
+    timestamp: string;
+    subAgentId: string;
+    subAgentName: string;
+}
+
 /**
  * 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.
@@ -3325,9 +3480,10 @@ type MCPClientConfig = {
 /**
  * MCP server configuration options
  */
-type MCPServerConfig = HTTPServerConfig | StdioServerConfig;
+type MCPServerConfig = HTTPServerConfig | SSEServerConfig | StreamableHTTPServerConfig | StdioServerConfig;
 /**
- * HTTP-based MCP server configuration via SSE
+ * HTTP-based MCP server configuration with automatic fallback
+ * Tries streamable HTTP first, falls back to SSE if not supported
  */
 type HTTPServerConfig = {
     /**
@@ -3342,11 +3498,53 @@ type HTTPServerConfig = {
      * Request initialization options
      */
     requestInit?: RequestInit;
+    /**
+     * Event source initialization options (used for SSE fallback)
+     */
+    eventSourceInit?: EventSourceInit;
+};
+/**
+ * SSE-based MCP server configuration (explicit SSE transport)
+ */
+type SSEServerConfig = {
+    /**
+     * Type of server connection
+     */
+    type: "sse";
+    /**
+     * URL of the MCP server
+     */
+    url: string;
+    /**
+     * Request initialization options
+     */
+    requestInit?: RequestInit;
     /**
      * Event source initialization options
      */
     eventSourceInit?: EventSourceInit;
 };
+/**
+ * Streamable HTTP-based MCP server configuration (no fallback)
+ */
+type StreamableHTTPServerConfig = {
+    /**
+     * Type of server connection
+     */
+    type: "streamable-http";
+    /**
+     * URL of the MCP server
+     */
+    url: string;
+    /**
+     * Request initialization options
+     */
+    requestInit?: RequestInit;
+    /**
+     * Session ID for the connection
+     */
+    sessionId?: string;
+};
 /**
  * Stdio-based MCP server configuration
  */
@@ -3459,6 +3657,18 @@ declare class MCPClient extends EventEmitter {
      * Information identifying this client to the server.
      */
     private readonly clientInfo;
+    /**
+     * Server configuration for fallback attempts.
+     */
+    private readonly serverConfig;
+    /**
+     * Whether to attempt SSE fallback if streamable HTTP fails.
+     */
+    private shouldAttemptFallback;
+    /**
+     * Client capabilities for re-initialization.
+     */
+    private readonly capabilities;
     /**
      * Creates a new MCP client instance.
      * @param config Configuration for the client, including server details and client identity.
@@ -3473,6 +3683,11 @@ declare class MCPClient extends EventEmitter {
      * Idempotent: does nothing if already connected.
      */
     connect(): Promise<void>;
+    /**
+     * Attempts to connect using SSE transport as a fallback.
+     * @param originalError The error from the initial connection attempt.
+     */
+    private attemptSSEFallback;
     /**
      * Closes the connection to the MCP server.
      * Idempotent: does nothing if not connected.
@@ -3517,6 +3732,18 @@ declare class MCPClient extends EventEmitter {
      * @returns True if the configuration type is 'http', false otherwise.
      */
     private isHTTPServer;
+    /**
+     * Type guard to check if a server configuration is for an SSE server.
+     * @param server The server configuration object.
+     * @returns True if the configuration type is 'sse', false otherwise.
+     */
+    private isSSEServer;
+    /**
+     * Type guard to check if a server configuration is for a Streamable HTTP server.
+     * @param server The server configuration object.
+     * @returns True if the configuration type is 'streamable-http', false otherwise.
+     */
+    private isStreamableHTTPServer;
     /**
      * Type guard to check if a server configuration is for a Stdio server.
      * @param server The server configuration object.
@@ -3691,24 +3918,6 @@ declare function registerCustomEndpoint(endpoint: CustomEndpointDefinition): voi
  */
 declare function registerCustomEndpoints(endpoints: CustomEndpointDefinition[]): void;
 
-type VoltAgentOptions = {
-    agents: Record<string, Agent<any>>;
-    port?: number;
-    autoStart?: boolean;
-    checkDependencies?: boolean;
-    /**
-     * Optional array of custom endpoint definitions to register with the API server
-     */
-    customEndpoints?: CustomEndpointDefinition[];
-    /**
-     * Optional OpenTelemetry SpanExporter instance or array of instances.
-     * or a VoltAgentExporter instance or array of instances.
-     * If provided, VoltAgent will attempt to initialize and register
-     * a NodeTracerProvider with a BatchSpanProcessor for the given exporter(s).
-     * It's recommended to only provide this in one VoltAgent instance per application process.
-     */
-    telemetryExporter?: (SpanExporter | VoltAgentExporter) | (SpanExporter | VoltAgentExporter)[];
-};
 /**
  * Main VoltAgent class for managing agents and server
  */
@@ -3716,6 +3925,8 @@ declare class VoltAgent {
     private registry;
     private serverStarted;
     private customEndpoints;
+    private serverConfig;
+    private serverOptions;
     constructor(options: VoltAgentOptions);
     /**
      * Check for dependency updates
@@ -3761,4 +3972,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, EventStatus, ExtractVariableNames, FEW_SHOT_EXAMPLES, FilePart, 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, ReasoningToolExecuteOptions, RetrieveOptions, 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, createAsyncIterableStream, createHooks, createNodeId, createPrompt, createReasoningTools, createRetrieverTool, createTool, createToolkit, VoltAgent as default, getNodeTypeFromNodeId, registerCustomEndpoint, registerCustomEndpoints, safeJsonParse, serializeValueForDebug, 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, 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, StreamMergerOptions, 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, createMergedStream, createNodeId, createPrompt, createReasoningTools, createRetrieverTool, createTool, createToolkit, VoltAgent as default, getNodeTypeFromNodeId, registerCustomEndpoint, registerCustomEndpoints, safeJsonParse, serializeValueForDebug, tool, updateAllPackages, updateSinglePackage, zodSchemaToJsonUI };