@agentforge/core 0.10.7 → 0.11.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.cjs CHANGED
@@ -421,7 +421,7 @@ function getMissingDescriptions(schema) {
421
421
  }
422
422
 
423
423
  // src/tools/helpers.ts
424
- function createTool(metadata, schema, execute) {
424
+ function createTool(metadata, schema, invoke) {
425
425
  const metadataResult = validateToolMetadata(metadata);
426
426
  if (!metadataResult.success) {
427
427
  const errors = metadataResult.error.errors.map((err) => ` - ${err.path.join(".")}: ${err.message}`).join("\n");
@@ -432,12 +432,12 @@ ${errors}`);
432
432
  const tool = {
433
433
  metadata: metadataResult.data,
434
434
  schema,
435
- execute
435
+ invoke
436
436
  };
437
- tool.invoke = execute;
437
+ tool.execute = invoke;
438
438
  return tool;
439
439
  }
440
- function createToolUnsafe(metadata, schema, execute) {
440
+ function createToolUnsafe(metadata, schema, invoke) {
441
441
  const metadataResult = validateToolMetadata(metadata);
442
442
  if (!metadataResult.success) {
443
443
  const errors = metadataResult.error.errors.map((err) => ` - ${err.path.join(".")}: ${err.message}`).join("\n");
@@ -447,9 +447,9 @@ ${errors}`);
447
447
  const tool = {
448
448
  metadata: metadataResult.data,
449
449
  schema,
450
- execute
450
+ invoke
451
451
  };
452
- tool.invoke = execute;
452
+ tool.execute = invoke;
453
453
  return tool;
454
454
  }
455
455
  function validateTool(tool) {
@@ -477,7 +477,7 @@ function validateTool(tool) {
477
477
  var ToolBuilder = class {
478
478
  metadata = {};
479
479
  _schema;
480
- _execute;
480
+ _invoke;
481
481
  /**
482
482
  * Set the tool name (required)
483
483
  *
@@ -689,10 +689,10 @@ var ToolBuilder = class {
689
689
  /**
690
690
  * Set the implementation function (required)
691
691
  *
692
- * @param execute - Async function that implements the tool
692
+ * @param invoke - Async function that implements the tool
693
693
  */
694
- implement(execute) {
695
- this._execute = execute;
694
+ implement(invoke) {
695
+ this._invoke = invoke;
696
696
  return this;
697
697
  }
698
698
  /**
@@ -701,7 +701,7 @@ var ToolBuilder = class {
701
701
  * Wraps the implementation in a try-catch block and returns a standardized
702
702
  * result object with success/error information.
703
703
  *
704
- * @param execute - Async function that implements the tool
704
+ * @param invoke - Async function that implements the tool
705
705
  * @returns ToolBuilder with safe result type { success: boolean; data?: T; error?: string }
706
706
  *
707
707
  * @example
@@ -718,10 +718,10 @@ var ToolBuilder = class {
718
718
  * // Or on error: { success: false, error: "ENOENT: no such file..." }
719
719
  * ```
720
720
  */
721
- implementSafe(execute) {
722
- const safeExecute = async (input) => {
721
+ implementSafe(invoke) {
722
+ const safeInvoke = async (input) => {
723
723
  try {
724
- const data = await execute(input);
724
+ const data = await invoke(input);
725
725
  return { success: true, data };
726
726
  } catch (error) {
727
727
  return {
@@ -730,17 +730,17 @@ var ToolBuilder = class {
730
730
  };
731
731
  }
732
732
  };
733
- this._execute = safeExecute;
733
+ this._invoke = safeInvoke;
734
734
  return this;
735
735
  }
736
736
  /**
737
737
  * Build the tool with validation
738
- *
738
+ *
739
739
  * Validates:
740
740
  * - All required fields are present
741
741
  * - Metadata is valid
742
742
  * - Schema has descriptions on all fields
743
- *
743
+ *
744
744
  * @returns The validated tool
745
745
  * @throws {Error} If validation fails
746
746
  */
@@ -757,13 +757,13 @@ var ToolBuilder = class {
757
757
  if (!this._schema) {
758
758
  throw new Error("Tool schema is required. Use .schema() to set it.");
759
759
  }
760
- if (!this._execute) {
760
+ if (!this._invoke) {
761
761
  throw new Error("Tool implementation is required. Use .implement() to set it.");
762
762
  }
763
763
  return createTool(
764
764
  this.metadata,
765
765
  this._schema,
766
- this._execute
766
+ this._invoke
767
767
  );
768
768
  }
769
769
  };
@@ -780,7 +780,7 @@ function toLangChainTool(tool) {
780
780
  description: tool.metadata.description,
781
781
  schema: tool.schema,
782
782
  func: async (input) => {
783
- const result = await tool.execute(input);
783
+ const result = await tool.invoke(input);
784
784
  if (typeof result === "string") {
785
785
  return result;
786
786
  }
@@ -1465,6 +1465,7 @@ var ToolRegistry = class {
1465
1465
  };
1466
1466
 
1467
1467
  // src/tools/executor.ts
1468
+ var logger2 = createLogger("agentforge:tools:executor");
1468
1469
  var PRIORITY_ORDER = {
1469
1470
  critical: 0,
1470
1471
  high: 1,
@@ -1511,7 +1512,14 @@ function createToolExecutor(config = {}) {
1511
1512
  async function executeWithRetry(tool, input, policy) {
1512
1513
  const executeFn = tool.invoke || tool.execute;
1513
1514
  if (!executeFn) {
1514
- throw new Error("Tool must implement either invoke() or execute() method");
1515
+ throw new Error(
1516
+ "Tool must implement invoke() method. Tools created with createTool() or toolBuilder automatically have this method. If you are manually constructing a tool, ensure it has an invoke() method."
1517
+ );
1518
+ }
1519
+ if (!tool.invoke && tool.execute) {
1520
+ logger2.warn(
1521
+ `Tool "${tool.metadata?.name || "unknown"}" only implements execute() which is deprecated. Please update to implement invoke() as the primary method. execute() will be removed in v1.0.0.`
1522
+ );
1515
1523
  }
1516
1524
  if (!policy) {
1517
1525
  return await executeFn.call(tool, input);
@@ -1635,7 +1643,7 @@ function createToolExecutor(config = {}) {
1635
1643
  }
1636
1644
 
1637
1645
  // src/tools/lifecycle.ts
1638
- var logger2 = createLogger("agentforge:core:tools:lifecycle", { level: "info" /* INFO */ });
1646
+ var logger3 = createLogger("agentforge:core:tools:lifecycle", { level: "info" /* INFO */ });
1639
1647
  var ManagedTool = class {
1640
1648
  name;
1641
1649
  description;
@@ -1667,7 +1675,7 @@ var ManagedTool = class {
1667
1675
  if (this.autoCleanup) {
1668
1676
  process.on("beforeExit", () => {
1669
1677
  this.cleanup().catch(
1670
- (err) => logger2.error("Cleanup failed", {
1678
+ (err) => logger3.error("Cleanup failed", {
1671
1679
  toolName: this.name,
1672
1680
  error: err instanceof Error ? err.message : String(err),
1673
1681
  stack: err instanceof Error ? err.stack : void 0
@@ -2636,14 +2644,14 @@ var withLogging = (options) => {
2636
2644
  onComplete,
2637
2645
  onError
2638
2646
  } = options;
2639
- const logger3 = providedLogger || createLogger(name, { level });
2647
+ const logger4 = providedLogger || createLogger(name, { level });
2640
2648
  return (node) => {
2641
2649
  return async (state) => {
2642
2650
  const startTime = Date.now();
2643
2651
  try {
2644
2652
  if (logInput) {
2645
2653
  const data = extractData ? extractData(state) : { state };
2646
- logger3.info("Node execution started", data);
2654
+ logger4.info("Node execution started", data);
2647
2655
  }
2648
2656
  if (onStart) {
2649
2657
  onStart(state);
@@ -2653,9 +2661,9 @@ var withLogging = (options) => {
2653
2661
  if (logOutput) {
2654
2662
  const data = extractData ? extractData(result) : { result };
2655
2663
  if (logDuration) {
2656
- logger3.info(`Node execution completed (${duration}ms)`, data);
2664
+ logger4.info(`Node execution completed (${duration}ms)`, data);
2657
2665
  } else {
2658
- logger3.info("Node execution completed", data);
2666
+ logger4.info("Node execution completed", data);
2659
2667
  }
2660
2668
  }
2661
2669
  if (onComplete) {
@@ -2666,7 +2674,7 @@ var withLogging = (options) => {
2666
2674
  const duration = Date.now() - startTime;
2667
2675
  const err = error instanceof Error ? error : new Error(String(error));
2668
2676
  if (logErrors) {
2669
- logger3.error(`Node execution failed (${duration}ms)`, {
2677
+ logger4.error(`Node execution failed (${duration}ms)`, {
2670
2678
  error: err.message,
2671
2679
  stack: err.stack
2672
2680
  });
@@ -2702,7 +2710,7 @@ function withLogging2(options) {
2702
2710
  function production(node, options) {
2703
2711
  const {
2704
2712
  nodeName,
2705
- logger: logger3,
2713
+ logger: logger4,
2706
2714
  enableMetrics = true,
2707
2715
  enableTracing = true,
2708
2716
  enableRetry = true,
@@ -2710,7 +2718,7 @@ function production(node, options) {
2710
2718
  retryOptions = {},
2711
2719
  errorOptions = {}
2712
2720
  } = options;
2713
- const actualLogger = logger3 || createLogger(nodeName, { level: "info" /* INFO */ });
2721
+ const actualLogger = logger4 || createLogger(nodeName, { level: "info" /* INFO */ });
2714
2722
  const middleware = [];
2715
2723
  middleware.push(
2716
2724
  withLogging2({
@@ -2774,9 +2782,9 @@ function development(node, options) {
2774
2782
  const {
2775
2783
  nodeName,
2776
2784
  verbose = true,
2777
- logger: logger3
2785
+ logger: logger4
2778
2786
  } = options;
2779
- const actualLogger = logger3 || createLogger(nodeName, { level: "debug" /* DEBUG */ });
2787
+ const actualLogger = logger4 || createLogger(nodeName, { level: "debug" /* DEBUG */ });
2780
2788
  return withLogging2({
2781
2789
  logger: actualLogger,
2782
2790
  name: nodeName,
package/dist/index.d.cts CHANGED
@@ -309,7 +309,7 @@ interface Tool<TInput = unknown, TOutput = unknown> {
309
309
  */
310
310
  schema: z.ZodSchema<TInput>;
311
311
  /**
312
- * Tool implementation
312
+ * Tool implementation (primary method)
313
313
  *
314
314
  * Why async?
315
315
  * - Most tools do I/O (files, network, database)
@@ -317,22 +317,33 @@ interface Tool<TInput = unknown, TOutput = unknown> {
317
317
  *
318
318
  * The input is automatically validated against the schema
319
319
  * before this function is called.
320
+ *
321
+ * This is the industry standard method name used by LangChain.
322
+ *
323
+ * @example
324
+ * ```ts
325
+ * const result = await tool.invoke({ input: 'hello' });
326
+ * ```
320
327
  */
321
- execute: (input: TInput) => Promise<TOutput>;
328
+ invoke: (input: TInput) => Promise<TOutput>;
322
329
  /**
323
- * LangChain-compatible alias for execute
330
+ * Deprecated alias for invoke()
331
+ *
332
+ * @deprecated Use invoke() instead. This method will be removed in v1.0.0.
324
333
  *
325
- * This allows developers familiar with LangChain to use .invoke()
326
- * instead of .execute(). Both methods do exactly the same thing.
334
+ * Both methods do exactly the same thing, but invoke() is the industry
335
+ * standard used by LangChain and should be preferred.
327
336
  *
328
337
  * @example
329
338
  * ```ts
330
- * // Both of these work:
339
+ * // Deprecated (still works, but will be removed in v1.0.0):
331
340
  * const result1 = await tool.execute({ input: 'hello' });
341
+ *
342
+ * // ✅ Preferred (industry standard):
332
343
  * const result2 = await tool.invoke({ input: 'hello' });
333
344
  * ```
334
345
  */
335
- invoke?: (input: TInput) => Promise<TOutput>;
346
+ execute?: (input: TInput) => Promise<TOutput>;
336
347
  }
337
348
 
338
349
  /**
@@ -832,7 +843,7 @@ declare function getMissingDescriptions(schema: z.ZodTypeAny): string[];
832
843
  *
833
844
  * @param metadata - Tool metadata
834
845
  * @param schema - Zod schema for input validation (must have descriptions!)
835
- * @param execute - Tool implementation
846
+ * @param invoke - Tool implementation (primary method, industry standard)
836
847
  * @returns Validated tool
837
848
  * @throws {Error} If metadata is invalid or schema is missing descriptions
838
849
  *
@@ -863,7 +874,7 @@ declare function getMissingDescriptions(schema: z.ZodTypeAny): string[];
863
874
  * );
864
875
  * ```
865
876
  */
866
- declare function createTool<TInput = unknown, TOutput = unknown>(metadata: ToolMetadata, schema: z.ZodSchema<TInput>, execute: (input: TInput) => Promise<TOutput>): Tool<TInput, TOutput>;
877
+ declare function createTool<TInput = unknown, TOutput = unknown>(metadata: ToolMetadata, schema: z.ZodSchema<TInput>, invoke: (input: TInput) => Promise<TOutput>): Tool<TInput, TOutput>;
867
878
  /**
868
879
  * Create a tool without enforcing schema descriptions
869
880
  *
@@ -877,10 +888,10 @@ declare function createTool<TInput = unknown, TOutput = unknown>(metadata: ToolM
877
888
  *
878
889
  * @param metadata - Tool metadata
879
890
  * @param schema - Zod schema for input validation
880
- * @param execute - Tool implementation
891
+ * @param invoke - Tool implementation (primary method, industry standard)
881
892
  * @returns Tool (without schema validation)
882
893
  */
883
- declare function createToolUnsafe<TInput = unknown, TOutput = unknown>(metadata: ToolMetadata, schema: z.ZodSchema<TInput>, execute: (input: TInput) => Promise<TOutput>): Tool<TInput, TOutput>;
894
+ declare function createToolUnsafe<TInput = unknown, TOutput = unknown>(metadata: ToolMetadata, schema: z.ZodSchema<TInput>, invoke: (input: TInput) => Promise<TOutput>): Tool<TInput, TOutput>;
884
895
  /**
885
896
  * Validate an existing tool
886
897
  *
@@ -933,7 +944,7 @@ declare function validateTool(tool: Tool): {
933
944
  declare class ToolBuilder<TInput = unknown, TOutput = unknown> {
934
945
  private metadata;
935
946
  private _schema?;
936
- private _execute?;
947
+ private _invoke?;
937
948
  /**
938
949
  * Set the tool name (required)
939
950
  *
@@ -1067,16 +1078,16 @@ declare class ToolBuilder<TInput = unknown, TOutput = unknown> {
1067
1078
  /**
1068
1079
  * Set the implementation function (required)
1069
1080
  *
1070
- * @param execute - Async function that implements the tool
1081
+ * @param invoke - Async function that implements the tool
1071
1082
  */
1072
- implement<T>(execute: (input: TInput) => Promise<T>): ToolBuilder<TInput, T>;
1083
+ implement<T>(invoke: (input: TInput) => Promise<T>): ToolBuilder<TInput, T>;
1073
1084
  /**
1074
1085
  * Set the implementation function with automatic error handling
1075
1086
  *
1076
1087
  * Wraps the implementation in a try-catch block and returns a standardized
1077
1088
  * result object with success/error information.
1078
1089
  *
1079
- * @param execute - Async function that implements the tool
1090
+ * @param invoke - Async function that implements the tool
1080
1091
  * @returns ToolBuilder with safe result type { success: boolean; data?: T; error?: string }
1081
1092
  *
1082
1093
  * @example
@@ -1093,7 +1104,7 @@ declare class ToolBuilder<TInput = unknown, TOutput = unknown> {
1093
1104
  * // Or on error: { success: false, error: "ENOENT: no such file..." }
1094
1105
  * ```
1095
1106
  */
1096
- implementSafe<T>(execute: (input: TInput) => Promise<T>): ToolBuilder<TInput, {
1107
+ implementSafe<T>(invoke: (input: TInput) => Promise<T>): ToolBuilder<TInput, {
1097
1108
  success: boolean;
1098
1109
  data?: T;
1099
1110
  error?: string;
package/dist/index.d.ts CHANGED
@@ -309,7 +309,7 @@ interface Tool<TInput = unknown, TOutput = unknown> {
309
309
  */
310
310
  schema: z.ZodSchema<TInput>;
311
311
  /**
312
- * Tool implementation
312
+ * Tool implementation (primary method)
313
313
  *
314
314
  * Why async?
315
315
  * - Most tools do I/O (files, network, database)
@@ -317,22 +317,33 @@ interface Tool<TInput = unknown, TOutput = unknown> {
317
317
  *
318
318
  * The input is automatically validated against the schema
319
319
  * before this function is called.
320
+ *
321
+ * This is the industry standard method name used by LangChain.
322
+ *
323
+ * @example
324
+ * ```ts
325
+ * const result = await tool.invoke({ input: 'hello' });
326
+ * ```
320
327
  */
321
- execute: (input: TInput) => Promise<TOutput>;
328
+ invoke: (input: TInput) => Promise<TOutput>;
322
329
  /**
323
- * LangChain-compatible alias for execute
330
+ * Deprecated alias for invoke()
331
+ *
332
+ * @deprecated Use invoke() instead. This method will be removed in v1.0.0.
324
333
  *
325
- * This allows developers familiar with LangChain to use .invoke()
326
- * instead of .execute(). Both methods do exactly the same thing.
334
+ * Both methods do exactly the same thing, but invoke() is the industry
335
+ * standard used by LangChain and should be preferred.
327
336
  *
328
337
  * @example
329
338
  * ```ts
330
- * // Both of these work:
339
+ * // Deprecated (still works, but will be removed in v1.0.0):
331
340
  * const result1 = await tool.execute({ input: 'hello' });
341
+ *
342
+ * // ✅ Preferred (industry standard):
332
343
  * const result2 = await tool.invoke({ input: 'hello' });
333
344
  * ```
334
345
  */
335
- invoke?: (input: TInput) => Promise<TOutput>;
346
+ execute?: (input: TInput) => Promise<TOutput>;
336
347
  }
337
348
 
338
349
  /**
@@ -832,7 +843,7 @@ declare function getMissingDescriptions(schema: z.ZodTypeAny): string[];
832
843
  *
833
844
  * @param metadata - Tool metadata
834
845
  * @param schema - Zod schema for input validation (must have descriptions!)
835
- * @param execute - Tool implementation
846
+ * @param invoke - Tool implementation (primary method, industry standard)
836
847
  * @returns Validated tool
837
848
  * @throws {Error} If metadata is invalid or schema is missing descriptions
838
849
  *
@@ -863,7 +874,7 @@ declare function getMissingDescriptions(schema: z.ZodTypeAny): string[];
863
874
  * );
864
875
  * ```
865
876
  */
866
- declare function createTool<TInput = unknown, TOutput = unknown>(metadata: ToolMetadata, schema: z.ZodSchema<TInput>, execute: (input: TInput) => Promise<TOutput>): Tool<TInput, TOutput>;
877
+ declare function createTool<TInput = unknown, TOutput = unknown>(metadata: ToolMetadata, schema: z.ZodSchema<TInput>, invoke: (input: TInput) => Promise<TOutput>): Tool<TInput, TOutput>;
867
878
  /**
868
879
  * Create a tool without enforcing schema descriptions
869
880
  *
@@ -877,10 +888,10 @@ declare function createTool<TInput = unknown, TOutput = unknown>(metadata: ToolM
877
888
  *
878
889
  * @param metadata - Tool metadata
879
890
  * @param schema - Zod schema for input validation
880
- * @param execute - Tool implementation
891
+ * @param invoke - Tool implementation (primary method, industry standard)
881
892
  * @returns Tool (without schema validation)
882
893
  */
883
- declare function createToolUnsafe<TInput = unknown, TOutput = unknown>(metadata: ToolMetadata, schema: z.ZodSchema<TInput>, execute: (input: TInput) => Promise<TOutput>): Tool<TInput, TOutput>;
894
+ declare function createToolUnsafe<TInput = unknown, TOutput = unknown>(metadata: ToolMetadata, schema: z.ZodSchema<TInput>, invoke: (input: TInput) => Promise<TOutput>): Tool<TInput, TOutput>;
884
895
  /**
885
896
  * Validate an existing tool
886
897
  *
@@ -933,7 +944,7 @@ declare function validateTool(tool: Tool): {
933
944
  declare class ToolBuilder<TInput = unknown, TOutput = unknown> {
934
945
  private metadata;
935
946
  private _schema?;
936
- private _execute?;
947
+ private _invoke?;
937
948
  /**
938
949
  * Set the tool name (required)
939
950
  *
@@ -1067,16 +1078,16 @@ declare class ToolBuilder<TInput = unknown, TOutput = unknown> {
1067
1078
  /**
1068
1079
  * Set the implementation function (required)
1069
1080
  *
1070
- * @param execute - Async function that implements the tool
1081
+ * @param invoke - Async function that implements the tool
1071
1082
  */
1072
- implement<T>(execute: (input: TInput) => Promise<T>): ToolBuilder<TInput, T>;
1083
+ implement<T>(invoke: (input: TInput) => Promise<T>): ToolBuilder<TInput, T>;
1073
1084
  /**
1074
1085
  * Set the implementation function with automatic error handling
1075
1086
  *
1076
1087
  * Wraps the implementation in a try-catch block and returns a standardized
1077
1088
  * result object with success/error information.
1078
1089
  *
1079
- * @param execute - Async function that implements the tool
1090
+ * @param invoke - Async function that implements the tool
1080
1091
  * @returns ToolBuilder with safe result type { success: boolean; data?: T; error?: string }
1081
1092
  *
1082
1093
  * @example
@@ -1093,7 +1104,7 @@ declare class ToolBuilder<TInput = unknown, TOutput = unknown> {
1093
1104
  * // Or on error: { success: false, error: "ENOENT: no such file..." }
1094
1105
  * ```
1095
1106
  */
1096
- implementSafe<T>(execute: (input: TInput) => Promise<T>): ToolBuilder<TInput, {
1107
+ implementSafe<T>(invoke: (input: TInput) => Promise<T>): ToolBuilder<TInput, {
1097
1108
  success: boolean;
1098
1109
  data?: T;
1099
1110
  error?: string;
package/dist/index.js CHANGED
@@ -265,7 +265,7 @@ function getMissingDescriptions(schema) {
265
265
  }
266
266
 
267
267
  // src/tools/helpers.ts
268
- function createTool(metadata, schema, execute) {
268
+ function createTool(metadata, schema, invoke) {
269
269
  const metadataResult = validateToolMetadata(metadata);
270
270
  if (!metadataResult.success) {
271
271
  const errors = metadataResult.error.errors.map((err) => ` - ${err.path.join(".")}: ${err.message}`).join("\n");
@@ -276,12 +276,12 @@ ${errors}`);
276
276
  const tool = {
277
277
  metadata: metadataResult.data,
278
278
  schema,
279
- execute
279
+ invoke
280
280
  };
281
- tool.invoke = execute;
281
+ tool.execute = invoke;
282
282
  return tool;
283
283
  }
284
- function createToolUnsafe(metadata, schema, execute) {
284
+ function createToolUnsafe(metadata, schema, invoke) {
285
285
  const metadataResult = validateToolMetadata(metadata);
286
286
  if (!metadataResult.success) {
287
287
  const errors = metadataResult.error.errors.map((err) => ` - ${err.path.join(".")}: ${err.message}`).join("\n");
@@ -291,9 +291,9 @@ ${errors}`);
291
291
  const tool = {
292
292
  metadata: metadataResult.data,
293
293
  schema,
294
- execute
294
+ invoke
295
295
  };
296
- tool.invoke = execute;
296
+ tool.execute = invoke;
297
297
  return tool;
298
298
  }
299
299
  function validateTool(tool) {
@@ -321,7 +321,7 @@ function validateTool(tool) {
321
321
  var ToolBuilder = class {
322
322
  metadata = {};
323
323
  _schema;
324
- _execute;
324
+ _invoke;
325
325
  /**
326
326
  * Set the tool name (required)
327
327
  *
@@ -533,10 +533,10 @@ var ToolBuilder = class {
533
533
  /**
534
534
  * Set the implementation function (required)
535
535
  *
536
- * @param execute - Async function that implements the tool
536
+ * @param invoke - Async function that implements the tool
537
537
  */
538
- implement(execute) {
539
- this._execute = execute;
538
+ implement(invoke) {
539
+ this._invoke = invoke;
540
540
  return this;
541
541
  }
542
542
  /**
@@ -545,7 +545,7 @@ var ToolBuilder = class {
545
545
  * Wraps the implementation in a try-catch block and returns a standardized
546
546
  * result object with success/error information.
547
547
  *
548
- * @param execute - Async function that implements the tool
548
+ * @param invoke - Async function that implements the tool
549
549
  * @returns ToolBuilder with safe result type { success: boolean; data?: T; error?: string }
550
550
  *
551
551
  * @example
@@ -562,10 +562,10 @@ var ToolBuilder = class {
562
562
  * // Or on error: { success: false, error: "ENOENT: no such file..." }
563
563
  * ```
564
564
  */
565
- implementSafe(execute) {
566
- const safeExecute = async (input) => {
565
+ implementSafe(invoke) {
566
+ const safeInvoke = async (input) => {
567
567
  try {
568
- const data = await execute(input);
568
+ const data = await invoke(input);
569
569
  return { success: true, data };
570
570
  } catch (error) {
571
571
  return {
@@ -574,17 +574,17 @@ var ToolBuilder = class {
574
574
  };
575
575
  }
576
576
  };
577
- this._execute = safeExecute;
577
+ this._invoke = safeInvoke;
578
578
  return this;
579
579
  }
580
580
  /**
581
581
  * Build the tool with validation
582
- *
582
+ *
583
583
  * Validates:
584
584
  * - All required fields are present
585
585
  * - Metadata is valid
586
586
  * - Schema has descriptions on all fields
587
- *
587
+ *
588
588
  * @returns The validated tool
589
589
  * @throws {Error} If validation fails
590
590
  */
@@ -601,13 +601,13 @@ var ToolBuilder = class {
601
601
  if (!this._schema) {
602
602
  throw new Error("Tool schema is required. Use .schema() to set it.");
603
603
  }
604
- if (!this._execute) {
604
+ if (!this._invoke) {
605
605
  throw new Error("Tool implementation is required. Use .implement() to set it.");
606
606
  }
607
607
  return createTool(
608
608
  this.metadata,
609
609
  this._schema,
610
- this._execute
610
+ this._invoke
611
611
  );
612
612
  }
613
613
  };
@@ -624,7 +624,7 @@ function toLangChainTool(tool) {
624
624
  description: tool.metadata.description,
625
625
  schema: tool.schema,
626
626
  func: async (input) => {
627
- const result = await tool.execute(input);
627
+ const result = await tool.invoke(input);
628
628
  if (typeof result === "string") {
629
629
  return result;
630
630
  }
@@ -1309,6 +1309,7 @@ var ToolRegistry = class {
1309
1309
  };
1310
1310
 
1311
1311
  // src/tools/executor.ts
1312
+ var logger2 = createLogger("agentforge:tools:executor");
1312
1313
  var PRIORITY_ORDER = {
1313
1314
  critical: 0,
1314
1315
  high: 1,
@@ -1355,7 +1356,14 @@ function createToolExecutor(config = {}) {
1355
1356
  async function executeWithRetry(tool, input, policy) {
1356
1357
  const executeFn = tool.invoke || tool.execute;
1357
1358
  if (!executeFn) {
1358
- throw new Error("Tool must implement either invoke() or execute() method");
1359
+ throw new Error(
1360
+ "Tool must implement invoke() method. Tools created with createTool() or toolBuilder automatically have this method. If you are manually constructing a tool, ensure it has an invoke() method."
1361
+ );
1362
+ }
1363
+ if (!tool.invoke && tool.execute) {
1364
+ logger2.warn(
1365
+ `Tool "${tool.metadata?.name || "unknown"}" only implements execute() which is deprecated. Please update to implement invoke() as the primary method. execute() will be removed in v1.0.0.`
1366
+ );
1359
1367
  }
1360
1368
  if (!policy) {
1361
1369
  return await executeFn.call(tool, input);
@@ -1479,7 +1487,7 @@ function createToolExecutor(config = {}) {
1479
1487
  }
1480
1488
 
1481
1489
  // src/tools/lifecycle.ts
1482
- var logger2 = createLogger("agentforge:core:tools:lifecycle", { level: "info" /* INFO */ });
1490
+ var logger3 = createLogger("agentforge:core:tools:lifecycle", { level: "info" /* INFO */ });
1483
1491
  var ManagedTool = class {
1484
1492
  name;
1485
1493
  description;
@@ -1511,7 +1519,7 @@ var ManagedTool = class {
1511
1519
  if (this.autoCleanup) {
1512
1520
  process.on("beforeExit", () => {
1513
1521
  this.cleanup().catch(
1514
- (err) => logger2.error("Cleanup failed", {
1522
+ (err) => logger3.error("Cleanup failed", {
1515
1523
  toolName: this.name,
1516
1524
  error: err instanceof Error ? err.message : String(err),
1517
1525
  stack: err instanceof Error ? err.stack : void 0
@@ -2480,14 +2488,14 @@ var withLogging = (options) => {
2480
2488
  onComplete,
2481
2489
  onError
2482
2490
  } = options;
2483
- const logger3 = providedLogger || createLogger(name, { level });
2491
+ const logger4 = providedLogger || createLogger(name, { level });
2484
2492
  return (node) => {
2485
2493
  return async (state) => {
2486
2494
  const startTime = Date.now();
2487
2495
  try {
2488
2496
  if (logInput) {
2489
2497
  const data = extractData ? extractData(state) : { state };
2490
- logger3.info("Node execution started", data);
2498
+ logger4.info("Node execution started", data);
2491
2499
  }
2492
2500
  if (onStart) {
2493
2501
  onStart(state);
@@ -2497,9 +2505,9 @@ var withLogging = (options) => {
2497
2505
  if (logOutput) {
2498
2506
  const data = extractData ? extractData(result) : { result };
2499
2507
  if (logDuration) {
2500
- logger3.info(`Node execution completed (${duration}ms)`, data);
2508
+ logger4.info(`Node execution completed (${duration}ms)`, data);
2501
2509
  } else {
2502
- logger3.info("Node execution completed", data);
2510
+ logger4.info("Node execution completed", data);
2503
2511
  }
2504
2512
  }
2505
2513
  if (onComplete) {
@@ -2510,7 +2518,7 @@ var withLogging = (options) => {
2510
2518
  const duration = Date.now() - startTime;
2511
2519
  const err = error instanceof Error ? error : new Error(String(error));
2512
2520
  if (logErrors) {
2513
- logger3.error(`Node execution failed (${duration}ms)`, {
2521
+ logger4.error(`Node execution failed (${duration}ms)`, {
2514
2522
  error: err.message,
2515
2523
  stack: err.stack
2516
2524
  });
@@ -2546,7 +2554,7 @@ function withLogging2(options) {
2546
2554
  function production(node, options) {
2547
2555
  const {
2548
2556
  nodeName,
2549
- logger: logger3,
2557
+ logger: logger4,
2550
2558
  enableMetrics = true,
2551
2559
  enableTracing = true,
2552
2560
  enableRetry = true,
@@ -2554,7 +2562,7 @@ function production(node, options) {
2554
2562
  retryOptions = {},
2555
2563
  errorOptions = {}
2556
2564
  } = options;
2557
- const actualLogger = logger3 || createLogger(nodeName, { level: "info" /* INFO */ });
2565
+ const actualLogger = logger4 || createLogger(nodeName, { level: "info" /* INFO */ });
2558
2566
  const middleware = [];
2559
2567
  middleware.push(
2560
2568
  withLogging2({
@@ -2618,9 +2626,9 @@ function development(node, options) {
2618
2626
  const {
2619
2627
  nodeName,
2620
2628
  verbose = true,
2621
- logger: logger3
2629
+ logger: logger4
2622
2630
  } = options;
2623
- const actualLogger = logger3 || createLogger(nodeName, { level: "debug" /* DEBUG */ });
2631
+ const actualLogger = logger4 || createLogger(nodeName, { level: "debug" /* DEBUG */ });
2624
2632
  return withLogging2({
2625
2633
  logger: actualLogger,
2626
2634
  name: nodeName,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agentforge/core",
3
- "version": "0.10.7",
3
+ "version": "0.11.1",
4
4
  "description": "Core abstractions for AgentForge - production-ready deep agents framework",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",