@voltagent/core 1.1.36 → 1.1.38

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { ModelMessage, DataContent as DataContent$1, UserContent, AssistantContent, ToolContent, ProviderOptions as ProviderOptions$1 } from '@ai-sdk/provider-utils';
+import { ModelMessage, ToolCallOptions, DataContent as DataContent$1, UserContent, AssistantContent, ToolContent, ProviderOptions as ProviderOptions$1 } from '@ai-sdk/provider-utils';
 export { AssistantContent, FilePart, ImagePart, TextPart, ToolContent, UserContent } from '@ai-sdk/provider-utils';
 import { Tool as Tool$1, TextStreamPart, generateText, UIMessage, StreamTextResult, LanguageModel, CallSettings, Output, ToolSet, GenerateTextResult, GenerateObjectResult, AsyncIterableStream as AsyncIterableStream$1, CallWarning, LanguageModelUsage, FinishReason, EmbeddingModel } from 'ai';
 export { LanguageModel, Tool as VercelTool, hasToolCall, stepCountIs } from 'ai';
@@ -58,95 +58,164 @@ type Toolkit = {
  */
 declare const createToolkit: (options: Toolkit) => Toolkit;
 
-/**
- * Status of a tool at any given time
- */
-type ToolStatus = "idle" | "working" | "error" | "completed";
-/**
- * Tool status information
- */
-type ToolStatusInfo = {
-    name: string;
-    status: ToolStatus;
-    result?: any;
-    error?: any;
-    input?: any;
-    output?: any;
-    timestamp: Date;
-    parameters?: any;
-};
-/**
- * Manager class to handle all tool-related operations, including Toolkits.
- */
-declare class ToolManager {
+declare abstract class BaseToolManager<TItems extends AgentTool | Tool$1 | Toolkit = AgentTool | Tool$1 | Toolkit, TToolkitManager extends BaseToolManager<TItems, never> | never = BaseToolManager<TItems, never>> {
     /**
      * User tools managed by this manager.
      * Includes server-side and client-side tools (no server execute) managed separately from server-executable tools.
      */
-    private baseTools;
+    protected baseTools: Map<string, BaseTool>;
     /**
      * Provider-defined tools managed by providers
      */
-    private providerTools;
+    protected providerTools: Map<string, ProviderTool>;
     /**
      * Toolkits managed by this manager.
      */
-    private toolkits;
+    protected toolkits: Map<string, TToolkitManager>;
     /**
      * Logger instance
      */
-    private logger;
+    protected logger: Logger;
     /**
      * Creates a new ToolManager.
      * Accepts individual tools, provider-defined tools, and toolkits.
      */
-    constructor(items?: (AgentTool | Tool$1 | Toolkit)[], logger?: Logger);
+    protected constructor(items?: TItems[], logger?: Logger);
+    /** Not all inheritances of BaseToolManager support toolkits - thus this is abstract */
+    abstract addToolkit(toolkit: Toolkit): boolean;
+    /**
+     * Add multiple tools or toolkits to the manager.
+     */
+    addItems(items: TItems[]): void;
+    addStandaloneTool(tool: AgentTool | Tool$1): boolean;
+    /**
+     * Remove a standalone tool by name. Does not remove tools from toolkits.
+     * @returns true if the tool was removed, false if it wasn't found.
+     */
+    removeTool(toolName: string): boolean;
+    /**
+     * Remove a toolkit by name.
+     * @returns true if the toolkit was removed, false if it wasn't found.
+     */
+    removeToolkit(toolkitName: string): boolean;
     /**
      * Get all toolkits managed by this manager.
      */
-    getToolkits(): Toolkit[];
+    getToolkits(): TToolkitManager[];
+    /**
+     * Get standalone tools and standalone tools within toolkits as a flattened list.
+     */
+    getAllBaseTools(): BaseTool[];
     /**
      * Get provider-defined tools managed externally by providers.
      */
-    getProviderTools(): ProviderTool[];
-    addTool(tool: AgentTool | Tool$1): boolean;
-    hasTool(toolName: string): boolean;
+    getAllProviderTools(): ProviderTool[];
     /**
-     * Add multiple tools or toolkits to the manager.
+     * Get all kinds of tools, owned by this manager and inside toolkits as a flattened list.
+     * */
+    getAllTools(): (BaseTool | ProviderTool)[];
+    /**
+     * Get names of all tools (standalone and inside toolkits), deduplicated.
      */
-    addItems(items: (AgentTool | Tool$1 | Toolkit)[]): void;
+    getAllToolNames(): string[];
     /**
-     * Get all individual tools and tools within toolkits as a flattened list.
+     * Returns tools owned directly by this manager (standalone tools), excluding tools inside toolkits.
      */
-    getTools(): BaseTool[];
+    protected getStandaloneTools(): (BaseTool | ProviderTool)[];
     /**
-     * Add a toolkit to the manager.
-     * If a toolkit with the same name already exists, it will be replaced.
-     * Also checks if any tool within the toolkit conflicts with existing standalone tools or tools in other toolkits.
-     * @returns true if the toolkit was successfully added or replaced.
+     * Check if any tool with the given name exists in this manager or nested toolkits.
      */
-    addToolkit(toolkit: Toolkit): boolean;
-    findInToolkits(toolName: string): Tool | ProviderTool | false;
+    hasToolInAny(toolName: string): boolean;
+}
+
+declare class ToolkitManager extends BaseToolManager<AgentTool | Tool$1, never> {
+    readonly name: string;
     /**
-     * Remove a standalone tool by name. Does not remove tools from toolkits.
-     * @returns true if the tool was removed, false if it wasn't found.
+     * A brief description of what the toolkit does or what tools it contains.
+     * Optional.
      */
-    removeTool(toolName: string): boolean;
+    readonly description?: string | undefined;
     /**
-     * Remove a toolkit by name.
-     * @returns true if the toolkit was removed, false if it wasn't found.
+     * Shared instructions for the LLM on how to use the tools within this toolkit.
+     * These instructions are intended to be added to the system prompt if `addInstructions` is true.
+     * Optional.
      */
-    removeToolkit(toolkitName: string): boolean;
+    readonly instructions?: string | undefined;
+    /**
+     * Whether to automatically add the toolkit's `instructions` to the agent's system prompt.
+     * If true, the instructions from individual tools within this toolkit might be ignored
+     * by the Agent's system message generation logic to avoid redundancy.
+     * Defaults to false.
+     */
+    readonly addInstructions: boolean;
+    /**
+     * Constructor does not accept toolkits - only tools
+     * */
+    constructor(name: string, items?: (AgentTool | Tool$1)[], 
+    /**
+     * A brief description of what the toolkit does or what tools it contains.
+     * Optional.
+     */
+    description?: string | undefined, 
+    /**
+     * Shared instructions for the LLM on how to use the tools within this toolkit.
+     * These instructions are intended to be added to the system prompt if `addInstructions` is true.
+     * Optional.
+     */
+    instructions?: string | undefined, 
+    /**
+     * Whether to automatically add the toolkit's `instructions` to the agent's system prompt.
+     * If true, the instructions from individual tools within this toolkit might be ignored
+     * by the Agent's system message generation logic to avoid redundancy.
+     * Defaults to false.
+     */
+    addInstructions?: boolean, logger?: Logger);
+    /**
+     * Toolkits are not supported inside a ToolkitManager (toolkits contain tools only).
+     * Keep the same signature as BaseToolManager.addToolkit to preserve type compatibility,
+     * but implement as a no-op (or warn) so callers won't crash.
+     */
+    addToolkit(toolkit: Toolkit): boolean;
+}
+
+declare class ToolManager extends BaseToolManager<AgentTool | Tool$1 | Toolkit, ToolkitManager> {
     /**
-     * Combine static base tools with runtime tools (includes tools from toolkits).
+     * Creates a new ToolManager.
+     * Accepts individual tools, provider-defined tools, and toolkits.
      */
-    combineStaticAndRuntimeBaseTools(runtimeTools?: (BaseTool | Toolkit)[]): BaseTool[];
+    constructor(items?: (AgentTool | Tool$1 | Toolkit)[], logger?: Logger);
+    /**
+     * Add a toolkit to the manager.
+     * If a toolkit with the same name already exists, it will be replaced.
+     * Also checks if any tool within the toolkit conflicts with existing standalone tools or tools in other toolkits.
+     * @returns true if the toolkit was successfully added or replaced.
+     */
+    addToolkit(toolkit: Toolkit): boolean;
+    prepareToolsForExecution(createToolExecuteFunction: (tool: AgentTool) => (args: any, options?: ToolExecuteOptions) => Promise<any>): Record<string, any>;
     /**
      * Get agent's tools (including those in toolkits) for API exposure.
      */
     getToolsForApi(): ApiToolInfo[];
 }
 
+/**
+ * Status of a tool at any given time
+ */
+type ToolStatus = "idle" | "working" | "error" | "completed";
+/**
+ * Tool status information
+ */
+type ToolStatusInfo = {
+    name: string;
+    status: ToolStatus;
+    result?: any;
+    error?: any;
+    input?: any;
+    output?: any;
+    timestamp: Date;
+    parameters?: any;
+};
+
 /**
  * Tool definition compatible with Vercel AI SDK
  */
@@ -184,7 +253,7 @@ type ToolOptions<T extends ToolSchema = ToolSchema, O extends ToolSchema | undef
     /**
      * Function to execute when the tool is called
      */
-    execute?: (args: z.infer<T>, context?: OperationContext) => Promise<O extends ToolSchema ? z.infer<O> : unknown>;
+    execute?: (args: z.infer<T>, context?: OperationContext, options?: ToolExecuteOptions) => Promise<O extends ToolSchema ? z.infer<O> : unknown>;
 };
 /**
  * Tool class for defining tools that agents can use
@@ -218,7 +287,7 @@ declare class Tool<T extends ToolSchema = ToolSchema, O extends ToolSchema | und
     /**
      * Function to execute when the tool is called
      */
-    readonly execute?: (args: z.infer<T>, context?: OperationContext) => Promise<O extends ToolSchema ? z.infer<O> : unknown>;
+    readonly execute?: (args: z.infer<T>, context?: OperationContext, options?: ToolExecuteOptions) => Promise<O extends ToolSchema ? z.infer<O> : unknown>;
     /**
      * Whether this tool should be executed on the client side.
      * Returns true when no server-side execute handler is provided.
@@ -416,24 +485,23 @@ type MessageRole = "user" | "assistant" | "system" | "tool";
  */
 type BaseMessage = ModelMessage;
 type ToolSchema = z.ZodType;
-type ToolExecuteOptions = {
+type ToolExecuteOptions = ToolCallOptions & {
     /**
-     * Optional AbortController for cancelling the execution and accessing the signal
+     * Optional AbortController for cancelling the execution and accessing the signal.
+     * Prefer using the provided abortSignal, but we keep this for backward compatibility.
      */
     abortController?: AbortController;
     /**
-     * @deprecated Use abortController.signal instead. This field will be removed in a future version.
-     * Optional AbortSignal to abort the execution
+     * @deprecated Use abortController.signal or options.abortSignal instead. This field will be removed in a future version.
      */
     signal?: AbortSignal;
     /**
      * The operation context associated with the agent invocation triggering this tool execution.
-     * Provides access to operation-specific state like context.
-     * The context includes a logger with full execution context (userId, conversationId, executionId).
+     * Provides access to operation-specific state like context and logging metadata.
      */
     operationContext?: OperationContext;
     /**
-     * Additional options can be added in the future
+     * Additional options can be added in the future.
      */
     [key: string]: any;
 };
@@ -666,6 +734,30 @@ interface WorkflowStateEntry {
         };
         suspendData?: any;
     };
+    /**
+     * Stream events collected during execution
+     * Used for timeline visualization in UI
+     */
+    events?: Array<{
+        id: string;
+        type: string;
+        name?: string;
+        from?: string;
+        startTime: string;
+        endTime?: string;
+        status?: string;
+        input?: any;
+        output?: any;
+        metadata?: Record<string, unknown>;
+        context?: Record<string, unknown>;
+    }>;
+    /** Final output of the workflow execution */
+    output?: unknown;
+    /** Cancellation metadata */
+    cancellation?: {
+        cancelledAt: Date;
+        reason?: string;
+    };
     /** User ID if applicable */
     userId?: string;
     /** Conversation ID if applicable */
@@ -809,10 +901,10 @@ interface VectorItem$1 {
  * Handles persistence of conversations and messages
  */
 interface StorageAdapter {
-    addMessage(message: UIMessage, userId: string, conversationId: string): Promise<void>;
-    addMessages(messages: UIMessage[], userId: string, conversationId: string): Promise<void>;
-    getMessages(userId: string, conversationId: string, options?: GetMessagesOptions): Promise<UIMessage[]>;
-    clearMessages(userId: string, conversationId?: string): Promise<void>;
+    addMessage(message: UIMessage, userId: string, conversationId: string, context?: OperationContext): Promise<void>;
+    addMessages(messages: UIMessage[], userId: string, conversationId: string, context?: OperationContext): Promise<void>;
+    getMessages(userId: string, conversationId: string, options?: GetMessagesOptions, context?: OperationContext): Promise<UIMessage[]>;
+    clearMessages(userId: string, conversationId?: string, context?: OperationContext): Promise<void>;
     createConversation(input: CreateConversationInput): Promise<Conversation>;
     getConversation(id: string): Promise<Conversation | null>;
     getConversations(resourceId: string): Promise<Conversation[]>;
@@ -1071,7 +1163,7 @@ declare class Memory {
     /**
      * Get messages from a conversation
      */
-    getMessages(userId: string, conversationId: string, options?: GetMessagesOptions): Promise<UIMessage[]>;
+    getMessages(userId: string, conversationId: string, options?: GetMessagesOptions, context?: OperationContext): Promise<UIMessage[]>;
     /**
      * Save a single message
      */
@@ -1079,15 +1171,15 @@ declare class Memory {
     /**
      * Add a single message (alias for consistency with existing API)
      */
-    addMessage(message: UIMessage, userId: string, conversationId: string): Promise<void>;
+    addMessage(message: UIMessage, userId: string, conversationId: string, context?: OperationContext): Promise<void>;
     /**
      * Add multiple messages in batch
      */
-    addMessages(messages: UIMessage[], userId: string, conversationId: string): Promise<void>;
+    addMessages(messages: UIMessage[], userId: string, conversationId: string, context?: OperationContext): Promise<void>;
     /**
      * Clear messages for a user
      */
-    clearMessages(userId: string, conversationId?: string): Promise<void>;
+    clearMessages(userId: string, conversationId?: string, context?: OperationContext): Promise<void>;
     /**
      * Get a conversation by ID
      */
@@ -1235,7 +1327,7 @@ declare class Memory {
      */
     saveMessageWithContext(message: UIMessage, userId: string, conversationId: string, context?: {
         logger?: Logger;
-    }): Promise<void>;
+    }, operationContext?: OperationContext): Promise<void>;
     /**
      * Get messages with semantic search support
      * Simple version without event publishing (handled by MemoryManagerV2)
@@ -1249,7 +1341,7 @@ declare class Memory {
         semanticLimit?: number;
         semanticThreshold?: number;
         mergeStrategy?: "prepend" | "append" | "interleave";
-    }): Promise<UIMessage[]>;
+    }, operationContext?: OperationContext): Promise<UIMessage[]>;
     /**
      * Internal: Set resource ID (agent ID)
      */
@@ -3366,6 +3458,7 @@ interface OnToolStartHookArgs {
     tool: AgentTool;
     context: OperationContext;
     args: any;
+    options?: ToolExecuteOptions;
 }
 interface OnToolEndHookArgs {
     agent: Agent;
@@ -3375,6 +3468,7 @@ interface OnToolEndHookArgs {
     /** The error if the tool execution failed. */
     error: VoltAgentError | AbortError | undefined;
     context: OperationContext;
+    options?: ToolExecuteOptions;
 }
 interface OnPrepareMessagesHookArgs {
     /** The messages that will be sent to the LLM (AI SDK UIMessage). */
@@ -4505,10 +4599,7 @@ declare class Agent {
      * Validate tool output against optional output schema.
      */
     private validateToolOutput;
-    /**
-     * Convert VoltAgent tools to AI SDK format with context injection
-     */
-    private convertTools;
+    private createToolExecutionFactory;
     /**
      * Create step handler for memory and hooks
      */
@@ -6598,9 +6689,9 @@ declare const ReasoningStepSchema: z.ZodObject<{
     agentId: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     type: "thought" | "analysis";
-    title: string;
     id: string;
     reasoning: string;
+    title: string;
     historyEntryId: string;
     agentId: string;
     timestamp: string;
@@ -6610,9 +6701,9 @@ declare const ReasoningStepSchema: z.ZodObject<{
     next_action?: NextAction | undefined;
 }, {
     type: "thought" | "analysis";
-    title: string;
     id: string;
     reasoning: string;
+    title: string;
     historyEntryId: string;
     agentId: string;
     timestamp: string;
@@ -6769,19 +6860,19 @@ declare class InMemoryStorageAdapter implements StorageAdapter {
     /**
      * Add a single message
      */
-    addMessage(message: UIMessage, userId: string, conversationId: string): Promise<void>;
+    addMessage(message: UIMessage, userId: string, conversationId: string, _context?: OperationContext): Promise<void>;
     /**
      * Add multiple messages
      */
-    addMessages(messages: UIMessage[], userId: string, conversationId: string): Promise<void>;
+    addMessages(messages: UIMessage[], userId: string, conversationId: string, context?: OperationContext): Promise<void>;
     /**
      * Get messages with optional filtering
      */
-    getMessages(userId: string, conversationId: string, options?: GetMessagesOptions): Promise<UIMessage[]>;
+    getMessages(userId: string, conversationId: string, options?: GetMessagesOptions, _context?: OperationContext): Promise<UIMessage[]>;
     /**
      * Clear messages for a user
      */
-    clearMessages(userId: string, conversationId?: string): Promise<void>;
+    clearMessages(userId: string, conversationId?: string, _context?: OperationContext): Promise<void>;
     /**
      * Create a new conversation
      */