@agentforge/core 0.10.6 → 0.11.0

package/dist/index.cjs

@@ -421,7 +421,7 @@ function getMissingDescriptions(schema) {
 }
 
 // src/tools/helpers.ts
-function createTool(metadata, schema, execute) {
+function createTool(metadata, schema, invoke) {
   const metadataResult = validateToolMetadata(metadata);
   if (!metadataResult.success) {
     const errors = metadataResult.error.errors.map((err) => `  - ${err.path.join(".")}: ${err.message}`).join("\n");
@@ -432,12 +432,12 @@ ${errors}`);
   const tool = {
     metadata: metadataResult.data,
     schema,
-    execute
+    invoke
   };
-  tool.invoke = execute;
+  tool.execute = invoke;
   return tool;
 }
-function createToolUnsafe(metadata, schema, execute) {
+function createToolUnsafe(metadata, schema, invoke) {
   const metadataResult = validateToolMetadata(metadata);
   if (!metadataResult.success) {
     const errors = metadataResult.error.errors.map((err) => `  - ${err.path.join(".")}: ${err.message}`).join("\n");
@@ -447,9 +447,9 @@ ${errors}`);
   const tool = {
     metadata: metadataResult.data,
     schema,
-    execute
+    invoke
   };
-  tool.invoke = execute;
+  tool.execute = invoke;
   return tool;
 }
 function validateTool(tool) {
@@ -477,7 +477,7 @@ function validateTool(tool) {
 var ToolBuilder = class {
   metadata = {};
   _schema;
-  _execute;
+  _invoke;
   /**
    * Set the tool name (required)
    * 
@@ -689,10 +689,10 @@ var ToolBuilder = class {
   /**
    * Set the implementation function (required)
    *
-   * @param execute - Async function that implements the tool
+   * @param invoke - Async function that implements the tool
    */
-  implement(execute) {
-    this._execute = execute;
+  implement(invoke) {
+    this._invoke = invoke;
     return this;
   }
   /**
@@ -701,7 +701,7 @@ var ToolBuilder = class {
    * Wraps the implementation in a try-catch block and returns a standardized
    * result object with success/error information.
    *
-   * @param execute - Async function that implements the tool
+   * @param invoke - Async function that implements the tool
    * @returns ToolBuilder with safe result type { success: boolean; data?: T; error?: string }
    *
    * @example
@@ -718,10 +718,10 @@ var ToolBuilder = class {
    * // Or on error: { success: false, error: "ENOENT: no such file..." }
    * ```
    */
-  implementSafe(execute) {
-    const safeExecute = async (input) => {
+  implementSafe(invoke) {
+    const safeInvoke = async (input) => {
       try {
-        const data = await execute(input);
+        const data = await invoke(input);
         return { success: true, data };
       } catch (error) {
         return {
@@ -730,17 +730,17 @@ var ToolBuilder = class {
         };
       }
     };
-    this._execute = safeExecute;
+    this._invoke = safeInvoke;
     return this;
   }
   /**
    * Build the tool with validation
-   * 
+   *
    * Validates:
    * - All required fields are present
    * - Metadata is valid
    * - Schema has descriptions on all fields
-   * 
+   *
    * @returns The validated tool
    * @throws {Error} If validation fails
    */
@@ -757,13 +757,13 @@ var ToolBuilder = class {
     if (!this._schema) {
       throw new Error("Tool schema is required. Use .schema() to set it.");
     }
-    if (!this._execute) {
+    if (!this._invoke) {
       throw new Error("Tool implementation is required. Use .implement() to set it.");
     }
     return createTool(
       this.metadata,
       this._schema,
-      this._execute
+      this._invoke
     );
   }
 };
@@ -780,7 +780,7 @@ function toLangChainTool(tool) {
     description: tool.metadata.description,
     schema: tool.schema,
     func: async (input) => {
-      const result = await tool.execute(input);
+      const result = await tool.invoke(input);
       if (typeof result === "string") {
         return result;
       }
@@ -1509,13 +1509,17 @@ function createToolExecutor(config = {}) {
     return Math.min(delay, maxDelay);
   }
   async function executeWithRetry(tool, input, policy) {
+    const executeFn = tool.invoke || tool.execute;
+    if (!executeFn) {
+      throw new Error("Tool must implement either invoke() or execute() method");
+    }
     if (!policy) {
-      return await tool.invoke(input);
+      return await executeFn.call(tool, input);
     }
     let lastError;
     for (let attempt = 1; attempt <= policy.maxAttempts; attempt++) {
       try {
-        return await tool.invoke(input);
+        return await executeFn.call(tool, input);
       } catch (error) {
         lastError = error;
         if (policy.retryableErrors && policy.retryableErrors.length > 0) {

package/dist/index.d.cts

@@ -309,7 +309,7 @@ interface Tool<TInput = unknown, TOutput = unknown> {
      */
     schema: z.ZodSchema<TInput>;
     /**
-     * Tool implementation
+     * Tool implementation (primary method)
      *
      * Why async?
      * - Most tools do I/O (files, network, database)
@@ -317,22 +317,33 @@ interface Tool<TInput = unknown, TOutput = unknown> {
      *
      * The input is automatically validated against the schema
      * before this function is called.
+     *
+     * This is the industry standard method name used by LangChain.
+     *
+     * @example
+     * ```ts
+     * const result = await tool.invoke({ input: 'hello' });
+     * ```
      */
-    execute: (input: TInput) => Promise<TOutput>;
+    invoke: (input: TInput) => Promise<TOutput>;
     /**
-     * LangChain-compatible alias for execute
+     * Deprecated alias for invoke()
+     *
+     * @deprecated Use invoke() instead. This method will be removed in v1.0.0.
      *
-     * This allows developers familiar with LangChain to use .invoke()
-     * instead of .execute(). Both methods do exactly the same thing.
+     * Both methods do exactly the same thing, but invoke() is the industry
+     * standard used by LangChain and should be preferred.
      *
      * @example
      * ```ts
-     * // Both of these work:
+     * // ❌ Deprecated (still works, but will be removed in v1.0.0):
      * const result1 = await tool.execute({ input: 'hello' });
+     *
+     * // ✅ Preferred (industry standard):
      * const result2 = await tool.invoke({ input: 'hello' });
      * ```
      */
-    invoke?: (input: TInput) => Promise<TOutput>;
+    execute?: (input: TInput) => Promise<TOutput>;
 }
 
 /**
@@ -832,7 +843,7 @@ declare function getMissingDescriptions(schema: z.ZodTypeAny): string[];
  *
  * @param metadata - Tool metadata
  * @param schema - Zod schema for input validation (must have descriptions!)
- * @param execute - Tool implementation
+ * @param invoke - Tool implementation (primary method, industry standard)
  * @returns Validated tool
  * @throws {Error} If metadata is invalid or schema is missing descriptions
  *
@@ -863,7 +874,7 @@ declare function getMissingDescriptions(schema: z.ZodTypeAny): string[];
  * );
  * ```
  */
-declare function createTool<TInput = unknown, TOutput = unknown>(metadata: ToolMetadata, schema: z.ZodSchema<TInput>, execute: (input: TInput) => Promise<TOutput>): Tool<TInput, TOutput>;
+declare function createTool<TInput = unknown, TOutput = unknown>(metadata: ToolMetadata, schema: z.ZodSchema<TInput>, invoke: (input: TInput) => Promise<TOutput>): Tool<TInput, TOutput>;
 /**
  * Create a tool without enforcing schema descriptions
  *
@@ -877,10 +888,10 @@ declare function createTool<TInput = unknown, TOutput = unknown>(metadata: ToolM
  *
  * @param metadata - Tool metadata
  * @param schema - Zod schema for input validation
- * @param execute - Tool implementation
+ * @param invoke - Tool implementation (primary method, industry standard)
  * @returns Tool (without schema validation)
  */
-declare function createToolUnsafe<TInput = unknown, TOutput = unknown>(metadata: ToolMetadata, schema: z.ZodSchema<TInput>, execute: (input: TInput) => Promise<TOutput>): Tool<TInput, TOutput>;
+declare function createToolUnsafe<TInput = unknown, TOutput = unknown>(metadata: ToolMetadata, schema: z.ZodSchema<TInput>, invoke: (input: TInput) => Promise<TOutput>): Tool<TInput, TOutput>;
 /**
  * Validate an existing tool
  *
@@ -933,7 +944,7 @@ declare function validateTool(tool: Tool): {
 declare class ToolBuilder<TInput = unknown, TOutput = unknown> {
     private metadata;
     private _schema?;
-    private _execute?;
+    private _invoke?;
     /**
      * Set the tool name (required)
      *
@@ -1067,16 +1078,16 @@ declare class ToolBuilder<TInput = unknown, TOutput = unknown> {
     /**
      * Set the implementation function (required)
      *
-     * @param execute - Async function that implements the tool
+     * @param invoke - Async function that implements the tool
      */
-    implement<T>(execute: (input: TInput) => Promise<T>): ToolBuilder<TInput, T>;
+    implement<T>(invoke: (input: TInput) => Promise<T>): ToolBuilder<TInput, T>;
     /**
      * Set the implementation function with automatic error handling
      *
      * Wraps the implementation in a try-catch block and returns a standardized
      * result object with success/error information.
      *
-     * @param execute - Async function that implements the tool
+     * @param invoke - Async function that implements the tool
      * @returns ToolBuilder with safe result type { success: boolean; data?: T; error?: string }
      *
      * @example
@@ -1093,7 +1104,7 @@ declare class ToolBuilder<TInput = unknown, TOutput = unknown> {
      * // Or on error: { success: false, error: "ENOENT: no such file..." }
      * ```
      */
-    implementSafe<T>(execute: (input: TInput) => Promise<T>): ToolBuilder<TInput, {
+    implementSafe<T>(invoke: (input: TInput) => Promise<T>): ToolBuilder<TInput, {
         success: boolean;
         data?: T;
         error?: string;

package/dist/index.d.ts

@@ -309,7 +309,7 @@ interface Tool<TInput = unknown, TOutput = unknown> {
      */
     schema: z.ZodSchema<TInput>;
     /**
-     * Tool implementation
+     * Tool implementation (primary method)
      *
      * Why async?
      * - Most tools do I/O (files, network, database)
@@ -317,22 +317,33 @@ interface Tool<TInput = unknown, TOutput = unknown> {
      *
      * The input is automatically validated against the schema
      * before this function is called.
+     *
+     * This is the industry standard method name used by LangChain.
+     *
+     * @example
+     * ```ts
+     * const result = await tool.invoke({ input: 'hello' });
+     * ```
      */
-    execute: (input: TInput) => Promise<TOutput>;
+    invoke: (input: TInput) => Promise<TOutput>;
     /**
-     * LangChain-compatible alias for execute
+     * Deprecated alias for invoke()
+     *
+     * @deprecated Use invoke() instead. This method will be removed in v1.0.0.
      *
-     * This allows developers familiar with LangChain to use .invoke()
-     * instead of .execute(). Both methods do exactly the same thing.
+     * Both methods do exactly the same thing, but invoke() is the industry
+     * standard used by LangChain and should be preferred.
      *
      * @example
      * ```ts
-     * // Both of these work:
+     * // ❌ Deprecated (still works, but will be removed in v1.0.0):
      * const result1 = await tool.execute({ input: 'hello' });
+     *
+     * // ✅ Preferred (industry standard):
      * const result2 = await tool.invoke({ input: 'hello' });
      * ```
      */
-    invoke?: (input: TInput) => Promise<TOutput>;
+    execute?: (input: TInput) => Promise<TOutput>;
 }
 
 /**
@@ -832,7 +843,7 @@ declare function getMissingDescriptions(schema: z.ZodTypeAny): string[];
  *
  * @param metadata - Tool metadata
  * @param schema - Zod schema for input validation (must have descriptions!)
- * @param execute - Tool implementation
+ * @param invoke - Tool implementation (primary method, industry standard)
  * @returns Validated tool
  * @throws {Error} If metadata is invalid or schema is missing descriptions
  *
@@ -863,7 +874,7 @@ declare function getMissingDescriptions(schema: z.ZodTypeAny): string[];
  * );
  * ```
  */
-declare function createTool<TInput = unknown, TOutput = unknown>(metadata: ToolMetadata, schema: z.ZodSchema<TInput>, execute: (input: TInput) => Promise<TOutput>): Tool<TInput, TOutput>;
+declare function createTool<TInput = unknown, TOutput = unknown>(metadata: ToolMetadata, schema: z.ZodSchema<TInput>, invoke: (input: TInput) => Promise<TOutput>): Tool<TInput, TOutput>;
 /**
  * Create a tool without enforcing schema descriptions
  *
@@ -877,10 +888,10 @@ declare function createTool<TInput = unknown, TOutput = unknown>(metadata: ToolM
  *
  * @param metadata - Tool metadata
  * @param schema - Zod schema for input validation
- * @param execute - Tool implementation
+ * @param invoke - Tool implementation (primary method, industry standard)
  * @returns Tool (without schema validation)
  */
-declare function createToolUnsafe<TInput = unknown, TOutput = unknown>(metadata: ToolMetadata, schema: z.ZodSchema<TInput>, execute: (input: TInput) => Promise<TOutput>): Tool<TInput, TOutput>;
+declare function createToolUnsafe<TInput = unknown, TOutput = unknown>(metadata: ToolMetadata, schema: z.ZodSchema<TInput>, invoke: (input: TInput) => Promise<TOutput>): Tool<TInput, TOutput>;
 /**
  * Validate an existing tool
  *
@@ -933,7 +944,7 @@ declare function validateTool(tool: Tool): {
 declare class ToolBuilder<TInput = unknown, TOutput = unknown> {
     private metadata;
     private _schema?;
-    private _execute?;
+    private _invoke?;
     /**
      * Set the tool name (required)
      *
@@ -1067,16 +1078,16 @@ declare class ToolBuilder<TInput = unknown, TOutput = unknown> {
     /**
      * Set the implementation function (required)
      *
-     * @param execute - Async function that implements the tool
+     * @param invoke - Async function that implements the tool
      */
-    implement<T>(execute: (input: TInput) => Promise<T>): ToolBuilder<TInput, T>;
+    implement<T>(invoke: (input: TInput) => Promise<T>): ToolBuilder<TInput, T>;
     /**
      * Set the implementation function with automatic error handling
      *
      * Wraps the implementation in a try-catch block and returns a standardized
      * result object with success/error information.
      *
-     * @param execute - Async function that implements the tool
+     * @param invoke - Async function that implements the tool
      * @returns ToolBuilder with safe result type { success: boolean; data?: T; error?: string }
      *
      * @example
@@ -1093,7 +1104,7 @@ declare class ToolBuilder<TInput = unknown, TOutput = unknown> {
      * // Or on error: { success: false, error: "ENOENT: no such file..." }
      * ```
      */
-    implementSafe<T>(execute: (input: TInput) => Promise<T>): ToolBuilder<TInput, {
+    implementSafe<T>(invoke: (input: TInput) => Promise<T>): ToolBuilder<TInput, {
         success: boolean;
         data?: T;
         error?: string;

package/dist/index.js

@@ -265,7 +265,7 @@ function getMissingDescriptions(schema) {
 }
 
 // src/tools/helpers.ts
-function createTool(metadata, schema, execute) {
+function createTool(metadata, schema, invoke) {
   const metadataResult = validateToolMetadata(metadata);
   if (!metadataResult.success) {
     const errors = metadataResult.error.errors.map((err) => `  - ${err.path.join(".")}: ${err.message}`).join("\n");
@@ -276,12 +276,12 @@ ${errors}`);
   const tool = {
     metadata: metadataResult.data,
     schema,
-    execute
+    invoke
   };
-  tool.invoke = execute;
+  tool.execute = invoke;
   return tool;
 }
-function createToolUnsafe(metadata, schema, execute) {
+function createToolUnsafe(metadata, schema, invoke) {
   const metadataResult = validateToolMetadata(metadata);
   if (!metadataResult.success) {
     const errors = metadataResult.error.errors.map((err) => `  - ${err.path.join(".")}: ${err.message}`).join("\n");
@@ -291,9 +291,9 @@ ${errors}`);
   const tool = {
     metadata: metadataResult.data,
     schema,
-    execute
+    invoke
   };
-  tool.invoke = execute;
+  tool.execute = invoke;
   return tool;
 }
 function validateTool(tool) {
@@ -321,7 +321,7 @@ function validateTool(tool) {
 var ToolBuilder = class {
   metadata = {};
   _schema;
-  _execute;
+  _invoke;
   /**
    * Set the tool name (required)
    * 
@@ -533,10 +533,10 @@ var ToolBuilder = class {
   /**
    * Set the implementation function (required)
    *
-   * @param execute - Async function that implements the tool
+   * @param invoke - Async function that implements the tool
    */
-  implement(execute) {
-    this._execute = execute;
+  implement(invoke) {
+    this._invoke = invoke;
     return this;
   }
   /**
@@ -545,7 +545,7 @@ var ToolBuilder = class {
    * Wraps the implementation in a try-catch block and returns a standardized
    * result object with success/error information.
    *
-   * @param execute - Async function that implements the tool
+   * @param invoke - Async function that implements the tool
    * @returns ToolBuilder with safe result type { success: boolean; data?: T; error?: string }
    *
    * @example
@@ -562,10 +562,10 @@ var ToolBuilder = class {
    * // Or on error: { success: false, error: "ENOENT: no such file..." }
    * ```
    */
-  implementSafe(execute) {
-    const safeExecute = async (input) => {
+  implementSafe(invoke) {
+    const safeInvoke = async (input) => {
       try {
-        const data = await execute(input);
+        const data = await invoke(input);
         return { success: true, data };
       } catch (error) {
         return {
@@ -574,17 +574,17 @@ var ToolBuilder = class {
         };
       }
     };
-    this._execute = safeExecute;
+    this._invoke = safeInvoke;
     return this;
   }
   /**
    * Build the tool with validation
-   * 
+   *
    * Validates:
    * - All required fields are present
    * - Metadata is valid
    * - Schema has descriptions on all fields
-   * 
+   *
    * @returns The validated tool
    * @throws {Error} If validation fails
    */
@@ -601,13 +601,13 @@ var ToolBuilder = class {
     if (!this._schema) {
       throw new Error("Tool schema is required. Use .schema() to set it.");
     }
-    if (!this._execute) {
+    if (!this._invoke) {
       throw new Error("Tool implementation is required. Use .implement() to set it.");
     }
     return createTool(
       this.metadata,
       this._schema,
-      this._execute
+      this._invoke
     );
   }
 };
@@ -624,7 +624,7 @@ function toLangChainTool(tool) {
     description: tool.metadata.description,
     schema: tool.schema,
     func: async (input) => {
-      const result = await tool.execute(input);
+      const result = await tool.invoke(input);
       if (typeof result === "string") {
         return result;
       }
@@ -1353,13 +1353,17 @@ function createToolExecutor(config = {}) {
     return Math.min(delay, maxDelay);
   }
   async function executeWithRetry(tool, input, policy) {
+    const executeFn = tool.invoke || tool.execute;
+    if (!executeFn) {
+      throw new Error("Tool must implement either invoke() or execute() method");
+    }
     if (!policy) {
-      return await tool.invoke(input);
+      return await executeFn.call(tool, input);
     }
     let lastError;
     for (let attempt = 1; attempt <= policy.maxAttempts; attempt++) {
       try {
-        return await tool.invoke(input);
+        return await executeFn.call(tool, input);
       } catch (error) {
         lastError = error;
         if (policy.retryableErrors && policy.retryableErrors.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge/core",
-  "version": "0.10.6",
+  "version": "0.11.0",
   "description": "Core abstractions for AgentForge - production-ready deep agents framework",
   "type": "module",
   "main": "./dist/index.cjs",