@voltagent/core 0.1.6 → 0.1.7

package/dist/index.d.ts

@@ -2111,8 +2111,8 @@ interface ReasoningToolExecuteOptions extends ToolExecuteOptions {
     historyEntryId: string;
 }
 
-declare const DEFAULT_INSTRUCTIONS = "\nYou have access to the 'think' and 'analyze' tools to work through problems step-by-step and structure your thought process. You should ALWAYS 'think' before making tool calls or generating a response.\n\n1.  **Think** (scratchpad):\n    *   Purpose: Use the 'think' tool as a scratchpad to break down complex problems, outline steps, and decide on immediate actions within your reasoning flow. Use this to structure your internal monologue.\n    *   Usage: Call 'think' multiple times if needed to break down the problem. Explain your reasoning and specify the intended action (e.g., \"make a tool call\", \"perform calculation\", \"ask clarifying question\").\n\n2.  **Analyze** (evaluation):\n    *   Purpose: Evaluate the result of a think step or a set of tool calls. Assess if the result is expected, sufficient, or requires further investigation.\n    *   Usage: Call 'analyze' AFTER a set of tool calls or a thought process. Determine the 'next_action' based on your analysis: 'continue' (more reasoning needed), 'validate' (seek external confirmation/validation if possible), or 'final_answer' (ready to conclude).\n    *   Explain your reasoning highlighting whether the result is correct/sufficient.\n\n## IMPORTANT GUIDELINES\n*   **Always Think First:** You MUST use the 'think' tool before making other tool calls or generating a response, unless the request is extremely simple. Use 'think' multiple times to break down complex problems.\n*   **Iterate to Solve:** Use the 'think' and 'analyze' tools iteratively to build a clear reasoning path. The typical flow is Think -> [Think -> ...] -> [Tool Calls if needed] -> [Analyze if needed] -> ... -> final_answer. Repeat this cycle until you reach a satisfactory conclusion.\n*   **Make multiple tool calls in parallel:** After a 'think' step, you can make multiple tool calls in parallel if needed.\n*   **Keep Thoughts Internal:** The reasoning steps (thoughts and analyses) are for your internal process only. Do not share them directly with the user unless asked to explain your reasoning.\n*   **Conclude Clearly:** When your analysis determines the 'next_action' is 'final_answer', provide a concise and accurate final answer to the user based on your reasoning steps.\n";
-declare const FEW_SHOT_EXAMPLES = "\n## Examples\n\n**Example 1: Simple Fact Retrieval**\n\n*User Request:* How many continents are there on Earth?\n\n*Agent's Internal Process:*\n```json\n{\n  \"tool_call\": {\n    \"name\": \"think\",\n    \"arguments\": {\n      \"title\": \"Understand Request\",\n      \"thought\": \"The user wants to know the standard number of continents on Earth. This is a common piece of knowledge.\",\n      \"action\": \"Recall or verify the number of continents.\",\n      \"confidence\": 0.95\n    }\n  }\n}\n```\n*--(Agent internally recalls the fact)--*\n```json\n{\n  \"tool_call\": {\n    \"name\": \"analyze\",\n    \"arguments\": {\n      \"title\": \"Evaluate Fact\",\n      \"result\": \"Standard geographical models list 7 continents: Africa, Antarctica, Asia, Australia, Europe, North America, South America.\",\n      \"analysis\": \"The recalled information directly answers the user's question accurately.\",\n      \"next_action\": \"final_answer\",\n      \"confidence\": 1.0\n    }\n  }\n}\n```\n\n*Agent's Final Answer to User:*\nThere are 7 continents on Earth: Africa, Antarctica, Asia, Australia, Europe, North America, and South America.\n\n**Example 2: Multi-Step Information Gathering**\n\n*User Request:* What is the capital of France and its current population?\n\n*Agent's Internal Process:*\n```json\n{\n  \"tool_call\": {\n    \"name\": \"think\",\n    \"arguments\": {\n      \"title\": \"Plan Information Retrieval\",\n      \"thought\": \"The user needs two pieces of information: the capital of France and its current population. I should break this down. First, find the capital.\",\n      \"action\": \"Search for the capital of France.\",\n      \"confidence\": 0.95\n    }\n  }\n}\n```\n*--(Tool call: search(query=\"capital of France\"))--*\n*--(Tool Result: \"Paris\")--*\n```json\n{\n  \"tool_call\": {\n    \"name\": \"analyze\",\n    \"arguments\": {\n      \"title\": \"Analyze Capital Search Result\",\n      \"result\": \"The search result indicates Paris is the capital of France.\",\n      \"analysis\": \"This provides the first piece of requested information. Now I need to find the population of Paris.\",\n      \"next_action\": \"continue\",\n      \"confidence\": 1.0\n    }\n  }\n}\n```\n```json\n{\n  \"tool_call\": {\n    \"name\": \"think\",\n    \"arguments\": {\n      \"title\": \"Plan Population Retrieval\",\n      \"thought\": \"The next step is to find the current population of Paris.\",\n      \"action\": \"Search for the population of Paris.\",\n      \"confidence\": 0.95\n    }\n  }\n}\n```\n*--(Tool call: search(query=\"population of Paris current\"))--*\n*--(Tool Result: \"Approximately 2.1 million (city proper, estimate for early 2024)\")--*\n```json\n{\n  \"tool_call\": {\n    \"name\": \"analyze\",\n    \"arguments\": {\n      \"title\": \"Analyze Population Search Result\",\n      \"result\": \"The search provided an estimated population figure for Paris.\",\n      \"analysis\": \"I now have both the capital and its estimated population. I can provide the final answer.\",\n      \"next_action\": \"final_answer\",\n      \"confidence\": 0.9\n    }\n  }\n}\n```\n\n*Agent's Final Answer to User:*\nThe capital of France is Paris. Its estimated population (city proper) is approximately 2.1 million as of early 2024.\n";
+declare const DEFAULT_INSTRUCTIONS = "\nYou are equipped with 'think' and 'analyze' capabilities to methodically tackle problems and organize your reasoning process. ALWAYS utilize 'think' before initiating any tool calls or formulating a response.\n\n1.  **Think** (Internal Workspace):\n    *   Objective: Employ the 'think' tool as an internal workspace to dissect complex issues, chart out solution paths, and determine the next steps in your reasoning. Use this to organize your internal thought process.\n    *   Method: Invoke 'think' repeatedly if necessary for problem decomposition. Articulate your rationale and specify the planned next step (e.g., \"initiate tool call,\" \"compute value,\" \"request clarification\").\n\n2.  **Analyze** (Assessment):\n    *   Objective: Assess the outcome of a thinking phase or a sequence of tool interactions. Determine if the outcome aligns with expectations, is adequate, or necessitates further exploration.\n    *   Method: Call 'analyze' following a series of tool uses or a completed thought sequence. Define the 'next_action' based on your assessment: 'continue' (further reasoning is required), 'validate' (if possible, seek external verification), or 'final_answer' (prepared to deliver the conclusion).\n    *   Justify your assessment, indicating whether the result is accurate/sufficient.\n\n## Core Principles\n*   **Initiate with Thought:** It is MANDATORY to use the 'think' tool prior to other tool interactions or response generation, except for trivial requests. Use 'think' multiple times for intricate problems.\n*   **Iterative Problem Solving:** Employ 'think' and 'analyze' in cycles to construct a transparent reasoning trajectory. The standard sequence is Think -> [Think -> ...] -> [Tool Calls if needed] -> [Analyze if needed] -> ... -> final_answer. Repeat this loop until a satisfactory resolution is achieved.\n*   **Parallel Tool Execution:** Following a 'think' step, multiple tool calls can be executed concurrently if required.\n*   **Maintain Internal Reasoning:** The steps involving 'think' and 'analyze' constitute your internal cognitive process. Do not expose these steps directly to the user unless specifically asked to elaborate on your reasoning.\n*   **Deliver Concise Conclusions:** Once your analysis concludes with 'next_action: final_answer', present a clear and precise final answer to the user, synthesized from your reasoning steps.\n";
+declare const FEW_SHOT_EXAMPLES = "\n## Illustrations\n\n**Illustration 1: Basic Knowledge Retrieval**\n\n*User Query:* What is the tallest mountain in the world?\n\n*Agent's Internal Processing:*\n```json\n{\n  \"tool_call\": {\n    \"name\": \"think\",\n    \"arguments\": {\n      \"title\": \"Parse Request\",\n      \"thought\": \"The user is asking for the name of the world's highest peak. This is well-known geographical data.\",\n      \"action\": \"Recall or look up the tallest mountain.\",\n      \"confidence\": 0.98\n    }\n  }\n}\n```\n*--(Agent internally accesses the information)--*\n```json\n{\n  \"tool_call\": {\n    \"name\": \"analyze\",\n    \"arguments\": {\n      \"title\": \"Assess Information\",\n      \"result\": \"Mount Everest is recognized as the tallest mountain above sea level.\",\n      \"analysis\": \"The retrieved data directly answers the user's query accurately.\",\n      \"next_action\": \"final_answer\",\n      \"confidence\": 1.0\n    }\n  }\n}\n```\n\n*Agent's Final Response to User:*\nThe tallest mountain in the world is Mount Everest.\n\n**Illustration 2: Sequential Information Gathering**\n\n*User Query:* Who directed the movie 'Inception' and what year was it released?\n\n*Agent's Internal Processing:*\n```json\n{\n  \"tool_call\": {\n    \"name\": \"think\",\n    \"arguments\": {\n      \"title\": \"Outline Information Needs\",\n      \"thought\": \"The request asks for two specific details about the movie 'Inception': its director and release year. I'll handle these sequentially. First, find the director.\",\n      \"action\": \"Search for the director of 'Inception'.\",\n      \"confidence\": 0.95\n    }\n  }\n}\n```\n*--(Tool interaction: search(query=\"director of Inception\"))--*\n*--(Tool Outcome: \"Christopher Nolan\")--*\n```json\n{\n  \"tool_call\": {\n    \"name\": \"analyze\",\n    \"arguments\": {\n      \"title\": \"Evaluate Director Search\",\n      \"result\": \"The search identified Christopher Nolan as the director.\",\n      \"analysis\": \"This fulfills the first part of the request. Next, I need the release year.\",\n      \"next_action\": \"continue\",\n      \"confidence\": 1.0\n    }\n  }\n}\n```\n```json\n{\n  \"tool_call\": {\n    \"name\": \"think\",\n    \"arguments\": {\n      \"title\": \"Plan Release Year Retrieval\",\n      \"thought\": \"The subsequent step is to determine the release year for 'Inception'.\",\n      \"action\": \"Search for the release year of 'Inception'.\",\n      \"confidence\": 0.95\n    }\n  }\n}\n```\n*--(Tool interaction: search(query=\"release year of Inception\"))--*\n*--(Tool Outcome: \"2010\")--*\n```json\n{\n  \"tool_call\": {\n    \"name\": \"analyze\",\n    \"arguments\": {\n      \"title\": \"Evaluate Release Year Search\",\n      \"result\": \"The search indicated the release year was 2010.\",\n      \"analysis\": \"I have now obtained both the director's name and the release year. I am ready to formulate the final response.\",\n      \"next_action\": \"final_answer\",\n      \"confidence\": 1.0\n    }\n  }\n}\n```\n\n*Agent's Final Response to User:*\nThe movie 'Inception' was directed by Christopher Nolan and released in 2010.\n";
 type CreateReasoningToolsOptions = {
     addInstructions?: boolean;
     think?: boolean;
@@ -2448,85 +2448,103 @@ type ToolsetWithTools = Record<string, AnyToolConfig> & {
 type AnyToolConfig = Tool<any>;
 
 /**
- * Client for interacting with Model Context Protocol (MCP) servers
- * Implements MCP specification using the official SDK
+ * Client for interacting with Model Context Protocol (MCP) servers.
+ * Wraps the official MCP SDK client to provide a higher-level interface.
+ * Internal implementation differs from original source.
  */
 declare class MCPClient extends EventEmitter {
     /**
-     * Underlying MCP client instance from SDK
+     * Underlying MCP client instance from the SDK.
      */
     private client;
     /**
-     * Transport layer for MCP communication
+     * Communication channel (transport layer) for MCP interactions.
      */
     private transport;
     /**
-     * Whether the client is connected to the server
+     * Tracks the connection status to the server.
      */
     private connected;
     /**
-     * Request timeout in milliseconds
+     * Maximum time allowed for requests in milliseconds.
      */
     private readonly timeout;
     /**
-     * Client information used for identification
+     * Information identifying this client to the server.
      */
     private readonly clientInfo;
     /**
-     * Creates a new MCP client
+     * Creates a new MCP client instance.
+     * @param config Configuration for the client, including server details and client identity.
      */
     constructor(config: MCPClientConfig);
     /**
-     * Set up MCP client event handlers
+     * Sets up handlers for events from the underlying SDK client.
      */
     private setupEventHandlers;
     /**
-     * Connect to the MCP server
+     * Establishes a connection to the configured MCP server.
+     * Idempotent: does nothing if already connected.
      */
     connect(): Promise<void>;
     /**
-     * Disconnect from the MCP server
+     * Closes the connection to the MCP server.
+     * Idempotent: does nothing if not connected.
      */
     disconnect(): Promise<void>;
     /**
-     * List available tools from the MCP server
+     * Fetches the definitions of available tools from the server.
+     * @returns A record mapping tool names to their definitions (schema, description).
      */
     listTools(): Promise<Record<string, unknown>>;
     /**
-     * Get tools converted to AgentTools with execute functions
-     * This method transforms MCP tool definitions into AgentTools that can be used directly by an Agent
+     * Builds executable Tool objects from the server's tool definitions.
+     * These tools include an `execute` method for calling the remote tool.
+     * @returns A record mapping namespaced tool names (`clientName_toolName`) to executable Tool objects.
      */
     getAgentTools(): Promise<Record<string, Tool<any>>>;
     /**
-     * Call a tool on the MCP server
+     * Executes a specified tool on the remote MCP server.
+     * @param toolCall Details of the tool to call, including name and arguments.
+     * @returns The result content returned by the tool.
      */
     callTool(toolCall: MCPToolCall): Promise<MCPToolResult>;
     /**
-     * Get the list of available resources from the MCP server
+     * Retrieves a list of resource identifiers available on the server.
+     * @returns A promise resolving to an array of resource ID strings.
      */
     listResources(): Promise<string[]>;
     /**
-     * Ensure the client is connected before making requests
+     * Ensures the client is connected before proceeding with an operation.
+     * Attempts to connect if not currently connected.
+     * @throws Error if connection attempt fails.
      */
     private ensureConnected;
     /**
-     * Convert and emit error events in a type-safe way
+     * Emits an 'error' event, ensuring the payload is always an Error object.
+     * @param error The error encountered, can be of any type.
      */
     private emitError;
     /**
-     * Check if the server config is HTTP-based
+     * Type guard to check if a server configuration is for an HTTP server.
+     * @param server The server configuration object.
+     * @returns True if the configuration type is 'http', false otherwise.
      */
     private isHTTPServer;
     /**
-     * Type guard to check if the server config is stdio-based
+     * Type guard to check if a server configuration is for a Stdio server.
+     * @param server The server configuration object.
+     * @returns True if the configuration type is 'stdio', false otherwise.
      */
     private isStdioServer;
     /**
-     * Override EventEmitter's on method to provide type safety
+     * Overrides EventEmitter's 'on' method for type-safe event listening.
+     * Uses the original `MCPClientEvents` for event types.
      */
     on<E extends keyof MCPClientEvents>(event: E, listener: MCPClientEvents[E]): this;
     /**
-     * Override EventEmitter's emit method to provide type safety
+     * Overrides EventEmitter's 'emit' method for type-safe event emission.
+     * Uses the original `MCPClientEvents` for event types.
      */
     emit<E extends keyof MCPClientEvents>(event: E, ...args: Parameters<MCPClientEvents[E]>): boolean;
 }
@@ -2534,96 +2552,65 @@ declare class MCPClient extends EventEmitter {
 /**
  * Configuration manager for Model Context Protocol (MCP).
  * Handles multiple MCP server connections and tool management.
- * Ensures unique configuration instances based on server settings or provided ID.
+ * NOTE: This version does NOT manage singleton instances automatically.
  */
 declare class MCPConfiguration<TServerKeys extends string = string> {
-    /**
-     * Unique identifier for this configuration, generated based on server configurations.
-     */
-    private readonly id;
     /**
      * Map of server configurations keyed by server names.
      */
     private readonly serverConfigs;
     /**
-     * Map of connected MCP clients keyed by server names.
+     * Map of connected MCP clients keyed by server names (local cache).
      */
     private readonly mcpClientsById;
     /**
-     * Creates a new MCP configuration or returns an existing one if configuration matches.
-     * @param options Configuration options including server definitions and an optional unique ID.
-     * @throws Error if initialized multiple times with the same configuration without a unique ID.
+     * Creates a new, independent MCP configuration instance.
+     * @param options Configuration options including server definitions.
      */
     constructor(options: {
-        id?: string;
         servers: Record<TServerKeys, MCPServerConfig>;
     });
     /**
-     * Generates a unique ID for the configuration based on server settings.
-     * Uses UUIDv5 to create a deterministic ID from the JSON representation of servers.
-     * @returns A unique string identifier.
+     * Type guard to check if an object conforms to the basic structure of AnyToolConfig.
      */
-    private generateId;
+    private isAnyToolConfigStructure;
     /**
-     * Adds the current instance to the global cache if not already present.
-     */
-    private addToInstanceCache;
-    /**
-     * Disconnects all associated MCP clients and removes this configuration instance from the cache.
-     * Ensures cleanup of resources.
+     * Disconnects all associated MCP clients for THIS instance.
      */
     disconnect(): Promise<void>;
     /**
-     * Retrieves agent-ready tools from all configured MCP servers.
-     * Tools are namespaced with their server name (e.g., "serverName.toolName").
-     * Agent-ready tools include executable functions.
+     * Retrieves agent-ready tools from all configured MCP servers for this instance.
      * @returns A flat array of all agent-ready tools.
      */
     getTools(): Promise<Tool<any>[]>;
     /**
-     * Retrieves raw tool definitions (without execute functions) from all configured MCP servers.
-     * Tools are namespaced with their server name (e.g., "serverName.toolName").
+     * Retrieves raw tool definitions from all configured MCP servers for this instance.
      * @returns A flat record of all raw tools keyed by their namespaced name.
      */
     getRawTools(): Promise<Record<string, AnyToolConfig>>;
     /**
-     * Retrieves agent-ready toolsets grouped by server name.
-     * Each toolset contains tools with executable functions for a specific server.
-     * @returns A record where keys are server names and values are records of agent-ready tools for that server.
+     * Retrieves agent-ready toolsets grouped by server name for this instance.
+     * @returns A record where keys are server names and values are agent-ready toolsets.
      */
     getToolsets(): Promise<Record<TServerKeys, ToolsetWithTools>>;
     /**
-     * Retrieves raw tool definitions (without execute functions) grouped by server name.
-     * @returns A record where keys are server names and values are records of raw tools for that server.
+     * Retrieves raw tool definitions grouped by server name for this instance.
+     * @returns A record where keys are server names and values are records of raw tools.
      */
     getRawToolsets(): Promise<Record<TServerKeys, Record<string, AnyToolConfig>>>;
     /**
-     * Retrieves a specific connected MCP client by its server name.
-     * Connects the client if it's not already connected.
-     * @param serverName The name of the server/client to retrieve.
-     * @returns The connected MCPClient instance or undefined if the server name is not configured.
+     * Retrieves a specific connected MCP client by its server name for this instance.
      */
     getClient(serverName: TServerKeys): Promise<MCPClient | undefined>;
     /**
-     * Retrieves all configured MCP clients, ensuring they are connected.
-     * @returns A record of connected MCPClient instances keyed by server name.
+     * Retrieves all configured MCP clients for this instance, ensuring they are connected.
      */
     getClients(): Promise<Record<TServerKeys, MCPClient>>;
     /**
-     * Gets or creates an MCP client connection for a given server configuration.
-     * Ensures the client is connected before returning. Handles connection errors.
-     * @param name The server name (key).
-     * @param config The server configuration.
-     * @returns A promise resolving to the connected MCPClient.
-     * @throws Error if connection fails.
+     * Internal helper to get/create/connect a client for this instance.
+     * Manages the local mcpClientsById cache.
      */
     private getConnectedClient;
-    /**
-     * Executes a callback for each configured server, providing the raw tools listed by the client.
-     * Handles connection and tool listing errors internally.
-     * @param callback Async function to execute for each server's raw tools.
-     */
-    private forEachClientRawTools;
 }
 
 /**