@mcp-use/agent 2.0.0-beta.2 → 2.0.0-beta.21

package/dist/index.js

@@ -16,6 +16,9 @@ var BaseAdapter = class {
    * generated for it.
    */
   connectorToolMap = /* @__PURE__ */ new Map();
+  /**
+   * @param disallowedTools - MCP tool names to omit during conversion.
+   */
   constructor(disallowedTools) {
     this.disallowedTools = disallowedTools ?? [];
   }
@@ -25,9 +28,9 @@ var BaseAdapter = class {
    * This is the recommended way to create tools from an MCPClient, as it handles
    * session creation and connector extraction automatically.
    *
-   * @param client          The MCPClient to extract tools from.
-   * @param disallowedTools Optional list of tool names to exclude.
-   * @returns               A promise that resolves with a list of converted tools.
+   * @param client - The MCPClient to extract tools from.
+   * @param disallowedTools - Optional list of tool names to exclude.
+   * @returns A promise that resolves with a list of converted tools.
    */
   static async createTools(client, disallowedTools) {
     const adapter = new this(disallowedTools);
@@ -44,8 +47,8 @@ var BaseAdapter = class {
   /**
    * Dynamically load tools for a specific connector.
    *
-   * @param connector The connector to load tools for.
-   * @returns         The list of tools that were loaded in the target framework's format.
+   * @param connector - The connector to load tools for.
+   * @returns The list of tools that were loaded in the target framework's format.
    */
   async loadToolsForConnector(connector) {
     if (this.connectorToolMap.has(connector)) {
@@ -73,8 +76,8 @@ var BaseAdapter = class {
   /**
    * Create tools from MCP tools in all provided connectors.
    *
-   * @param connectors List of MCP connectors to create tools from.
-   * @returns         A promise that resolves with all converted tools.
+   * @param connectors - List of MCP connectors to create tools from.
+   * @returns A promise that resolves with all converted tools.
    */
   async createToolsFromConnectors(connectors) {
     const tools = [];
@@ -88,8 +91,8 @@ var BaseAdapter = class {
   /**
    * Dynamically load resources for a specific connector.
    *
-   * @param connector The connector to load resources for.
-   * @returns         The list of resources that were loaded in the target framework's format.
+   * @param connector - The connector to load resources for.
+   * @returns The list of resources that were loaded in the target framework's format.
    */
   async loadResourcesForConnector(connector) {
     const connectorResources = [];
@@ -119,8 +122,8 @@ var BaseAdapter = class {
   /**
    * Dynamically load prompts for a specific connector.
    *
-   * @param connector The connector to load prompts for.
-   * @returns         The list of prompts that were loaded in the target framework's format.
+   * @param connector - The connector to load prompts for.
+   * @returns The list of prompts that were loaded in the target framework's format.
    */
   async loadPromptsForConnector(connector) {
     const connectorPrompts = [];
@@ -150,8 +153,8 @@ var BaseAdapter = class {
   /**
    * Create resources from MCP resources in all provided connectors.
    *
-   * @param connectors List of MCP connectors to create resources from.
-   * @returns         A promise that resolves with all converted resources.
+   * @param connectors - List of MCP connectors to create resources from.
+   * @returns A promise that resolves with all converted resources.
    */
   async createResourcesFromConnectors(connectors) {
     const resources = [];
@@ -165,8 +168,8 @@ var BaseAdapter = class {
   /**
    * Create prompts from MCP prompts in all provided connectors.
    *
-   * @param connectors List of MCP connectors to create prompts from.
-   * @returns         A promise that resolves with all converted prompts.
+   * @param connectors - List of MCP connectors to create prompts from.
+   * @returns A promise that resolves with all converted prompts.
    */
   async createPromptsFromConnectors(connectors) {
     const prompts = [];
@@ -180,8 +183,8 @@ var BaseAdapter = class {
   /**
    * Check if a connector is initialized and has tools.
    *
-   * @param connector The connector to check.
-   * @returns         True if the connector is initialized and has tools, false otherwise.
+   * @param connector - The connector to check.
+   * @returns True if the connector is initialized and has tools, false otherwise.
    */
   checkConnectorInitialized(connector) {
     return Boolean(connector.tools && connector.tools.length);
@@ -189,8 +192,8 @@ var BaseAdapter = class {
   /**
    * Ensure a connector is initialized.
    *
-   * @param connector The connector to initialize.
-   * @returns         True if initialization succeeded, false otherwise.
+   * @param connector - The connector to initialize.
+   * @returns True if initialization succeeded, false otherwise.
    */
   async ensureConnectorInitialized(connector) {
     if (!this.checkConnectorInitialized(connector)) {
@@ -214,14 +217,29 @@ function sanitizeToolName(name) {
 var NativeAdapter = class extends BaseAdapter {
   usedToolNames = /* @__PURE__ */ new Set();
   handlers = /* @__PURE__ */ new Map();
+  /**
+   * @param disallowedTools - MCP tool names to omit during conversion.
+   */
   constructor(disallowedTools = []) {
     super(disallowedTools);
   }
+  /**
+   * Converts MCP tools from all connectors and resets the dispatch table.
+   *
+   * @param connectors - Connected MCP connectors.
+   * @returns Provider-neutral tool entries.
+   */
   async createToolsFromConnectors(connectors) {
     this.usedToolNames.clear();
     this.handlers.clear();
     return super.createToolsFromConnectors(connectors);
   }
+  /**
+   * Creates a dispatcher for the entries loaded by this adapter.
+   *
+   * @returns A function that invokes tools, reads resources, or gets prompts.
+   * @throws Error if the requested exposed tool name is unknown.
+   */
   createCallTool() {
     const handlers = this.handlers;
     return async (name, args) => {
@@ -244,6 +262,12 @@ var NativeAdapter = class extends BaseAdapter {
       }
     };
   }
+  /**
+   * Removes internal dispatch metadata from native tool entries.
+   *
+   * @param entries - Entries created by this adapter.
+   * @returns Provider-neutral definitions safe to send to an LLM provider.
+   */
   toProviderTools(entries) {
     return entries.map(({ name, description, inputSchema }) => ({
       name,
@@ -478,6 +502,62 @@ function toolImageFollowupHeader(toolName, count) {
 }
 
 // src/llm/messageFormat.ts
+function messageText(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content.map(
+      (part) => part && typeof part === "object" && "text" in part && typeof part.text === "string" ? part.text : ""
+    ).join("");
+  }
+  return JSON.stringify(content ?? "");
+}
+function langChainMessageType(message) {
+  try {
+    if (typeof message._getType === "function") return message._getType();
+    if (typeof message.getType === "function") return message.getType();
+  } catch {
+  }
+  return message.type ?? "";
+}
+function convertExternalHistoryToProvider(messages) {
+  return messages.map((raw, index) => {
+    const message = raw;
+    const type = langChainMessageType(message);
+    const content = messageText(message.content);
+    if (type === "human" || type === "user") {
+      return { role: "user", content };
+    }
+    if (type === "system") {
+      return { role: "system", content };
+    }
+    if (type === "ai" || type === "assistant") {
+      const toolCalls = message.tool_calls?.map((call, callIndex) => ({
+        id: call.id ?? `external_${index}_${callIndex}`,
+        name: call.name,
+        args: call.args ?? {}
+      }));
+      return {
+        role: "assistant",
+        content,
+        ...toolCalls?.length ? { toolCalls } : {}
+      };
+    }
+    if (type === "tool") {
+      const toolIsError = message.status === "error" || isToolResultError(message.content);
+      return {
+        role: "tool",
+        content,
+        toolCallId: message.tool_call_id ?? `external_${index}`,
+        ...message.name ? { toolName: message.name } : {},
+        toolResult: message.content,
+        ...toolIsError ? { toolIsError: true } : {}
+      };
+    }
+    throw new TypeError(
+      `Unsupported external history message type at index ${index}: ${type || "unknown"}`
+    );
+  });
+}
 function extractText(m) {
   const raw = typeof m.content === "string" ? m.content : Array.isArray(m.content) ? m.content.map((x) => x?.text ?? "").join("\n") : JSON.stringify(m.content ?? "");
   if (raw.trim()) return raw.trim();
@@ -781,7 +861,13 @@ function buildBody(params, stream) {
     body.tools = tools.map((t) => ({
       name: t.name,
       description: t.description,
-      input_schema: t.inputSchema
+      input_schema: t.inputSchema,
+      // Anthropic buffers each parameter value by default. That makes a tool
+      // with one large string argument (code, SVG, a document, etc.) appear to
+      // have no input until the whole value has finished generating. Request
+      // eager input only for streaming calls so input_json_delta events arrive
+      // while the model is still writing the value.
+      ...stream ? { eager_input_streaming: true } : {}
     }));
   }
   return body;
@@ -872,7 +958,11 @@ async function* streamChat(params) {
           try {
             args = JSON.parse(entry.argsJson);
           } catch {
-            args = {};
+            yield {
+              type: "error",
+              message: `Anthropic returned invalid JSON arguments for tool "${entry.name}".`
+            };
+            return;
           }
         }
         yield {
@@ -1283,6 +1373,9 @@ function buildOllamaApiUrl(baseUrl, path) {
   return `${normalizeOllamaBaseUrl(baseUrl)}${path}`;
 }
 var OllamaCorsError = class extends Error {
+  /**
+   * @param cause - Original network error.
+   */
   constructor(cause) {
     super(
       "Could not reach Ollama. If it's running, allow this origin by starting Ollama with `OLLAMA_ORIGINS=*` (or your inspector origin) and try again."
@@ -1488,8 +1581,15 @@ async function chat3(params) {
 
 // src/llm/providers/openai-chat-completions.ts
 var LlmRequestError = class extends Error {
+  /** HTTP response status. */
   status;
+  /** Parsed JSON response body, or the raw response text. */
   body;
+  /**
+   * @param status - HTTP response status.
+   * @param message - Error message.
+   * @param body - Parsed or raw provider response body.
+   */
   constructor(status, message, body) {
     super(message);
     this.name = "LlmRequestError";
@@ -1935,14 +2035,21 @@ function appendToolOutputsToInput(input, callId, toolName, result) {
     });
   }
 }
+function responsesReasoningFields(config) {
+  const effort = config.reasoningEffort;
+  if (!effort || effort === "none") return {};
+  return {
+    include: ["reasoning.encrypted_content"],
+    reasoning: { effort }
+  };
+}
 function buildResponsesBody(params, stream) {
   const body = {
     model: params.config.model,
     input: params.input,
     store: false,
-    include: ["reasoning.encrypted_content"],
-    reasoning: { effort: params.config.reasoningEffort ?? "low" },
-    stream
+    stream,
+    ...responsesReasoningFields(params.config)
   };
   if (params.instructions) body.instructions = params.instructions;
   if (params.tools && params.tools.length > 0) {
@@ -2449,12 +2556,12 @@ async function* streamNativeAgent(driver, options) {
 }
 async function* streamNativeAgentSteps(driver, options) {
   let finalText = "";
-  let pendingStep = null;
+  const pendingSteps = /* @__PURE__ */ new Map();
   for await (const ev of streamNativeAgent(driver, options)) {
     if (ev.type === "text-delta") {
       finalText += ev.delta;
     } else if (ev.type === "tool-call-ready") {
-      pendingStep = {
+      const pendingStep = {
         action: {
           tool: ev.toolName,
           toolInput: ev.args,
@@ -2462,14 +2569,17 @@ async function* streamNativeAgentSteps(driver, options) {
         },
         observation: ""
       };
+      pendingSteps.set(ev.toolCallId, pendingStep);
       yield pendingStep;
-    } else if (ev.type === "tool-result" && pendingStep) {
+    } else if (ev.type === "tool-result") {
+      const pendingStep = pendingSteps.get(ev.toolCallId);
+      if (!pendingStep) continue;
       const observation = typeof ev.result === "string" ? ev.result : JSON.stringify(ev.result ?? "");
       yield {
         action: pendingStep.action,
         observation
       };
-      pendingStep = null;
+      pendingSteps.delete(ev.toolCallId);
     } else if (ev.type === "error") {
       throw new Error(ev.message);
     }
@@ -2561,27 +2671,34 @@ function providerConfigFromOptions(provider, model, config) {
 }
 
 // src/version.ts
-var VERSION = "2.0.0-beta.1";
+var VERSION = "2.0.0-beta.21";
 function getPackageVersion() {
   return VERSION;
 }
 
 // src/agents/normalize_run_options.ts
-function normalizeRunOptions(queryOrOptions, maxSteps, manageConnector, _externalHistory, outputSchema, signal) {
+function normalizeRunOptions(queryOrOptions, maxSteps, manageConnector, externalHistory, outputSchema, signal) {
   if (typeof queryOrOptions === "object" && queryOrOptions !== null) {
     return {
       prompt: queryOrOptions.prompt,
       maxSteps: queryOrOptions.maxSteps,
       manageConnector: queryOrOptions.manageConnector,
+      externalHistory: queryOrOptions.externalHistory,
       messages: queryOrOptions.messages,
       schema: queryOrOptions.schema,
       signal: queryOrOptions.signal
     };
   }
+  if (externalHistory !== void 0 && !Array.isArray(externalHistory)) {
+    throw new TypeError(
+      "externalHistory must be an array of LangChain messages"
+    );
+  }
   return {
     prompt: queryOrOptions,
     maxSteps,
     manageConnector,
+    externalHistory,
     schema: outputSchema,
     signal
   };
@@ -2616,6 +2733,11 @@ var RemoteAgent = class {
   apiKey;
   baseUrl;
   chatId = null;
+  /**
+   * @param options - Hosted agent identifier and API connection settings.
+   * @throws Error if no API key is supplied or available from
+   * `MCP_USE_API_KEY`.
+   */
   constructor(options) {
     this.agentId = options.agentId;
     this.baseUrl = options.baseUrl ?? "https://cloud.manufact.com";
@@ -2841,6 +2963,7 @@ Raw error: ${result}`
     );
     return result;
   }
+  /** Releases local remote-agent state. */
   async close() {
     logger4.debug("\u{1F50C} Remote agent client closed");
   }
@@ -2848,6 +2971,7 @@ Raw error: ${result}`
 
 // src/agents/mcp_agent.ts
 var MCPAgent = class {
+  /** @returns The installed `@mcp-use/agent` package version. */
   static getPackageVersion() {
     return getPackageVersion();
   }
@@ -2875,6 +2999,15 @@ var MCPAgent = class {
   conversationMessages = [];
   memoryEnabled;
   boundConnections;
+  /**
+   * Creates an MCP agent.
+   *
+   * Call {@link initialize} before the first local run unless
+   * `autoInitialize` is enabled. Setting `agentId` creates a remote agent.
+   *
+   * @param options - Model, MCP connection, and execution settings.
+   * @throws Error if local execution has no MCP servers, client, or connectors.
+   */
   constructor(options) {
     if (options.agentId) {
       this.isRemote = true;
@@ -2894,7 +3027,6 @@ var MCPAgent = class {
       return;
     }
     this.maxSteps = options.maxSteps ?? 10;
-    this.autoInitialize = options.autoInitialize ?? false;
     this.systemPrompt = options.systemPrompt ?? "You are a helpful assistant with access to MCP tools.";
     this.disallowedTools = options.disallowedTools ?? [];
     this.exposeResourcesAsTools = options.exposeResourcesAsTools ?? true;
@@ -2934,6 +3066,7 @@ var MCPAgent = class {
         parseLLMStringToProviderConfig(this.llmString, this.llmConfig)
       );
     }
+    this.autoInitialize = options.autoInitialize ?? this.isSimplifiedMode;
   }
   resolveMcpServers(mcpServers) {
     if (!mcpServers) return;
@@ -2946,6 +3079,14 @@ var MCPAgent = class {
   hasLiveConnections() {
     return (this.boundConnections?.length ?? 0) > 0;
   }
+  /**
+   * Resolves the model configuration, connects MCP servers, and loads tools.
+   *
+   * Calling this method more than once has no effect until {@link close}.
+   *
+   * @throws Error if the model configuration is incomplete or no driver can
+   * be created.
+   */
   async initialize() {
     if (this.isRemote) {
       this.initialized = true;
@@ -2953,11 +3094,6 @@ var MCPAgent = class {
     }
     if (this.initialized) return;
     if (this.isSimplifiedMode) {
-      if (!this.client && this.mcpServersConfig) {
-        const { MCPClient } = await import("@mcp-use/client");
-        this.client = new MCPClient({ mcpServers: this.mcpServersConfig });
-        this.clientOwnedByAgent = true;
-      }
       if (this.llmString) {
         this.driver = createLlmDriver(
           parseLLMStringToProviderConfig(this.llmString, this.llmConfig)
@@ -2966,6 +3102,11 @@ var MCPAgent = class {
     } else if (this.explicitProviderConfig) {
       this.driver = createLlmDriver(this.explicitProviderConfig);
     }
+    if (!this.client && this.mcpServersConfig && !this.hasLiveConnections()) {
+      const { MCPClient } = await import("@mcp-use/client");
+      this.client = new MCPClient({ mcpServers: this.mcpServersConfig });
+      this.clientOwnedByAgent = true;
+    }
     if (!this.driver) {
       throw new Error("LLM driver not configured.");
     }
@@ -3072,6 +3213,11 @@ var MCPAgent = class {
     if (this.memoryEnabled && this.conversationMessages.length > 0) {
       messages.push(...this.conversationMessages);
     }
+    if (options.externalHistory?.length) {
+      messages.push(
+        ...convertExternalHistoryToProvider(options.externalHistory)
+      );
+    }
     if (options.messages?.length) {
       messages.push(...options.messages);
     }
@@ -3080,12 +3226,21 @@ var MCPAgent = class {
     }
     return messages;
   }
+  /**
+   * @returns A shallow copy of stored provider-neutral conversation history.
+   */
   getConversationHistory() {
     return [...this.conversationMessages];
   }
+  /** Removes all stored user and assistant messages. */
   clearConversationHistory() {
     this.conversationMessages = [];
   }
+  /**
+   * Replaces the system instruction used by subsequent runs.
+   *
+   * @param message - New system instruction.
+   */
   setSystemMessage(message) {
     this.systemPrompt = message;
   }
@@ -3197,7 +3352,13 @@ var MCPAgent = class {
     await this.ensureReady(options.manageConnector ?? true);
     yield* streamNativeAgent(this.driver, this.nativeRunParams(options));
   }
-  /** Single-shot completion without tools (sampling, props generation). */
+  /**
+   * Runs a single model completion without MCP tools.
+   *
+   * @param options - Provider-neutral messages and optional cancellation
+   * signal.
+   * @returns Final assistant text.
+   */
   async chat(options) {
     await this.ensureReady();
     const result = await this.driver.complete({
@@ -3207,6 +3368,11 @@ var MCPAgent = class {
     });
     return result.text;
   }
+  /**
+   * Closes MCP sessions created by this agent and resets initialization state.
+   *
+   * Existing clients supplied by the caller remain open.
+   */
   async close() {
     if (this.clientOwnedByAgent && this.client) {
       await this.client.closeAllSessions?.();
@@ -3229,6 +3395,7 @@ async function completeChat(params) {
 // src/agents/prompts/index.ts
 var CODE_MODE_PROMPT = "Use code execution mode to discover and call MCP tools programmatically.";
 var PROMPTS = {
+  /** Instruction used to enable code-based MCP tool discovery and calls. */
   CODE_MODE: CODE_MODE_PROMPT
 };
 export {